From a1b265c318dbda4a213cec930785b81e4c0f7d2b Mon Sep 17 00:00:00 2001
From: elmot <elmot@vaadin.com>
Date: Fri, 25 Sep 2015 16:40:44 +0300
Subject: Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581
---
 .../application/application-environment.asciidoc   | 502 +++++++++++++++++++++
 1 file changed, 502 insertions(+)
 create mode 100644 documentation/application/application-environment.asciidoc

(limited to 'documentation/application/application-environment.asciidoc')

diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc
new file mode 100644
index 0000000000..5a2bf7ecbf
--- /dev/null
+++ b/documentation/application/application-environment.asciidoc
@@ -0,0 +1,502 @@
+---
+title: Deploying an Application
+order: 9
+layout: page
+---
+
+[[application.environment]]
+= Deploying an Application
+
+Vaadin applications are deployed as __Java web applications__, which can contain
+a number of servlets, each of which can be a Vaadin application or some other
+servlet, and static resources such as HTML files. Such a web application is
+normally packaged as a WAR (Web application ARchive) file, which can be deployed
+to a Java application server (or a servlet container to be exact). A WAR file,
+which has the [filename]#.war# extension, is a subtype of JAR (Java ARchive),
+and like a regular JAR, is a ZIP-compressed file with a special content
+structure.
+
+For a detailed tutorial on how web applications are packaged, please refer to
+any Java book that discusses Java Servlets.
+
+In the Java Servlet parlance, a "web application" means a collection of Java
+servlets or portlets, JSP and static HTML pages, and various other resources
+that form an application. Such a Java web application is typically packaged as a
+WAR package for deployment. Server-side Vaadin UIs run as servlets within such a
+Java web application. There exists also other kinds of web applications. To
+avoid confusion with the general meaning of "web application", we often refer to
+Java web applications with the slight misnomer "WAR" in this book.//TODO Vaadin
+7: What is the relationship between servlet and
+application?
+
+[[application.environment.war-eclipse]]
+== Creating Deployable WAR in Eclipse
+
+To deploy an application to a web server, you need to create a WAR package. Here
+we give the instructions for Eclipse.
+
+. Select "File > Export" and then "Web > WAR File". Or, right-click the project in
+the Project Explorer and select "Web > WAR File".
+
+. Select the [guilabel]#Web project# to export. Enter [guilabel]#Destination# file
+name ( [filename]#.war#).
+
+. Make any other settings in the dialog, and click [guibutton]#Finish#.
+
+
+
+[[application.environment.war]]
+== Web Application Contents
+
+The following files are required in a web application in order to run it.
+
+[filename]#WEB-INF/web.xml# (optional with Servlet 3.0):: This is the web application descriptor that defines how the application is
+organized, that is, what servlets and such it has. You can refer to any Java
+book about the contents of this file. It is not needed if you define the Vaadin
+servlet with the [literal]#++@WebServlet++# annotation in Servlet API 3.0.
+
+[filename]#WEB-INF/lib/*.jar# :: These are the Vaadin libraries and their dependencies. They can be found in the
+installation package or as loaded by a dependency management system such as
+Maven or Ivy.
+
+Your UI classes:: You must include your UI classes either in a JAR file in [filename]#WEB-INF/lib#
+or as classes in [filename]#WEB-INF/classes#
+
+Your own theme files (OPTIONAL):: If your application uses a special theme (look and feel), you must include it in
+[filename]#VAADIN/themes/themename# directory.
+
+Widget sets (OPTIONAL):: If your application uses a project-specific widget set, it must be compiled in
+the [filename]#VAADIN/widgetset/# directory.
+
+
+
+
+[[application.environment.webservlet]]
+== Web Servlet Class
+
+When using the Servlet 3.0 API, you normally declare the Vaadin servlet classes
+with the [literal]#++@WebServlet++# annotation. The Vaadin UI associated with
+the servlet and other Vaadin-specific parameters are declared with a separate
+[literal]#++@VaadinServletConfiguration++# annotation.
+
+[subs="normal"]
+----
+@WebServlet(value = "**/++*++**",
+            asyncSupported = true)
+@VaadinServletConfiguration(
+        productionMode = **false**,
+        ui = **MyProjectUI**.class)
+public class **MyProjectServlet** extends VaadinServlet {
+}
+----
+The Vaadin Plugin for Eclipse creates the servlet class as a static inner class
+of the UI class. Normally, you may want to have it as a separate regular class.
+
+The [parameter]#value# parameter is the URL pattern for mapping request URLs to
+the servlet, as described in <<application.environment.servlet-mapping>>. The
+[parameter]#ui# parameter is the UI class. Production mode is disabled by
+default, which enabled on-the-fly theme compilation, debug window, and other
+such development features. See the subsequent sections for details on the
+different servlet and Vaadin configuration parameters.
+
+You can also use a [filename]#web.xml# deployment descriptor in Servlet 3.0
+projects.
+
+
+[[application.environment.web-xml]]
+== Using a [filename]#web.xml# Deployment Descriptor
+
+A deployment descriptor is an XML file with the name [filename]#web.xml# in the
+[filename]#WEB-INF# sub-directory of a web application. It is a standard
+component in Java EE describing how a web application should be deployed. The
+descriptor is not required with Servlet API 3.0, where you can also define
+servlets with the [classname]#@WebServlet# annotation as decribed earlier, as
+web fragments, or programmatically. You can use both a [filename]#web.xml# and
+WebServlet in the same application. Settings in the [filename]#web.xml# override
+the ones given in annotations.
+
+The following example shows the basic contents of a deployment descriptor for a
+Servlet 2.4 application. You simply specify the UI class with the
+[parameter]#UI# parameter for the [classname]#com.vaadin.server.VaadinServlet#.
+The servlet is then mapped to a URL path in a standard way for Java Servlets.
+
+[subs="normal"]
+----
+&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;web-app
+  id="WebApp_ID" version="2.4"
+  xmlns="http://java.sun.com/xml/ns/j2ee" 
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
+     http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"&gt;
+
+  &lt;servlet&gt;
+    &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+    &lt;servlet-class&gt;
+        com.vaadin.server.VaadinServlet
+    &lt;/servlet-class&gt;
+
+    &lt;init-param&gt;
+      &lt;param-name&gt;UI&lt;/param-name&gt;
+      &lt;param-value&gt;**com.ex.myprj.MyUI**&lt;/param-value&gt;
+    &lt;/init-param&gt;
+
+    &lt;!-- If not using the default widget set--&gt;
+    &lt;init-param&gt;
+      &lt;param-name&gt;widgetset&lt;/param-name&gt;
+      &lt;param-value&gt;**com.ex.myprj.MyWidgetSet**&lt;/param-value&gt;
+    &lt;/init-param&gt;
+  &lt;/servlet&gt;
+
+  &lt;servlet-mapping&gt;
+    &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+  &lt;/servlet-mapping&gt;
+&lt;/web-app&gt;
+----
+The descriptor defines a servlet with the name [filename]#myservlet#. The
+servlet class, [classname]#com.vaadin.server.VaadinServlet#, is provided by
+Vaadin framework and is normally the same for all Vaadin projects. For some
+purposes, you may need to use a custom servlet class that extends the
+[classname]#VaadinServlet#. The class name must include the full package path.
+
+[[application.environment.web-xml.servlet]]
+=== Servlet API Version
+
+The descriptor example given above was for Servlet 2.4. For a later version,
+such as Servlet 3.0, you should use:
+
+[subs="normal"]
+----
+&lt;web-app
+  id="WebApp_ID" version="**3.0**"
+  xmlns="http://java.sun.com/xml/ns/j2ee" 
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+  xsi:schemaLocation="**http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd**"&gt;
+----
+Servlet 3.0 support is useful for at least server push.
+
+
+[[application.environment.web-xml.widgetset]]
+=== Widget Set
+
+If the UI uses add-on components or custom widgets, it needs a custom widget
+set, which can be specified with the [parameter]#widgetset# parameter for the
+servlet. Alternatively, you can defined it with the [classname]#@WidgetSet#
+annotation for the UI class. The parameter is a class name with the same path
+but without the [filename]#.gwt.xml# extension as the widget set definition
+file. If the parameter is not given, the
+[classname]#com.vaadin.DefaultWidgetSet# is used, which contains all the widgets
+for the built-in Vaadin components.
+
+Unless using the default widget set (which is included in the
+[filename]#vaadin-client-compiled# JAR), the widget set must be compiled, as
+described in
+<<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using
+Vaadin Add-ons">> or
+<<dummy/../../../framework/clientside/clientside-compiling#clientside.compiling,"Compiling
+a Client-Side Module">>, and properly deployed with the application.
+
+
+
+[[application.environment.servlet-mapping]]
+== Servlet Mapping with URL Patterns
+
+The servlet needs to be mapped to an URL path, which requests it is to handle.
+
+With [classname]#@WebServlet# annotation for the servlet class:
+
+[subs="normal"]
+----
+@WebServlet(value = "**/++*++**", asyncSupported = true)
+----
+In a [filename]#web.xml#:
+
+[subs="normal"]
+----
+  &lt;servlet-mapping&gt;
+    &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
+  &lt;/servlet-mapping&gt;
+----
+The URL pattern is defined in the above examples as [literal]#++/*++#. This
+matches any URL under the project context. We defined above the project context
+as [literal]#++myproject++# so the URL for the page of the UI will be
+http://localhost:8080/myproject/.
+
+[[application.environment.servlet-mapping.sub-paths]]
+=== Mapping Sub-Paths
+
+If an application has multiple UIs or servlets, they have to be given different
+paths in the URL, matched by a different URL pattern. Also, you may need to have
+statically served content under some path. Having an URL pattern
+[literal]#++/myui/*++# would match a URL such as
+http://localhost:8080/myproject/myui/. Notice that the slash and the asterisk
+__must__ be included at the end of the pattern. In such case, you also need to
+map URLs with [literal]#++/VAADIN/*++# to a servlet (unless you are serving it
+statically as noted below).
+
+With a [classname]#@WebServlet# annotation for a servlet class, you can define
+multiple mappings as a list enclosed in curly braces as follows:
+
+[subs="normal"]
+----
+@WebServlet(value = {"**/myui/++*++**", "/VAADIN/*"},
+            asyncSupported = true)
+----
+In a [filename]#web.xml#:
+
+[subs="normal"]
+----
+    ...
+    &lt;servlet-mapping&gt;
+        &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+        &lt;url-pattern&gt;**/myui/++*++**&lt;/url-pattern&gt;
+    &lt;/servlet-mapping&gt;
+
+    &lt;servlet-mapping&gt;
+        &lt;servlet-name&gt;**myservlet**&lt;/servlet-name&gt;
+        &lt;url-pattern&gt;/VAADIN/*&lt;/url-pattern&gt;
+    &lt;/servlet-mapping&gt;
+----
+If you have multiple servlets, you should specify only one
+[literal]#++/VAADIN/*++# mapping.It does not matter which servlet you map the
+pattern to, as long as it is a Vaadin servlet.
+
+You do not have to provide the above [literal]#++/VAADIN/*++# mapping if you
+serve both the widget sets and (custom and default) themes statically in the
+[filename]#/VAADIN# directory in the web application. The mapping simply allows
+serving them dynamically from the Vaadin JAR. Serving them statically is
+recommended for production environments as it is faster. If you serve the
+content from within the same web application, you may not have the root pattern
+[literal]#++/*++# for the Vaadin servlet, as then all the requests would be
+mapped to the servlet.
+
+
+
+[[application.environment.parameters]]
+== Other Servlet Configuration Parameters
+
+The servlet class or deployment descriptor can have many parameters and options
+that control the execution of a servlet. You can find complete documentation of
+the basic servlet parameters in the appropriate
+link:http://wiki.apache.org/tomcat/Specifications[Java Servlet Specification].
+////
+JCP or Oracle don't seem to have a proper index
+URL.
+////
+[classname]#@VaadinServletConfiguration# accepts a number of special parameters,
+as described below.
+
+In a [filename]#web.xml#, you can set most parameters either as a
+[literal]#++<context-param>++# for the entire web application, in which case
+they apply to all Vaadin servlets, or as an [literal]#++<init-param>++# for an
+individual servlet. If both are defined, servlet parameters override context
+parameters.
+
+[[application.environment.parameters.production-mode]]
+=== Production Mode
+
+By default, Vaadin applications run in __debug mode__ (or __development mode__),
+which should be used during development. This enables various debugging
+features. For production use, you should have the
+[literal]#++productionMode=true++# setting in the
+[classname]#@VaadinServletConfiguration#, or in [filename]#web.xml#:
+
+
+----
+<context-param>
+  <param-name>productionMode</param-name>
+  <param-value>true</param-value>
+  <description>Vaadin production mode</description>
+</context-param>
+----
+
+The parameter and the debug and production modes are described in more detail in
+<<dummy/../../../framework/advanced/advanced-debug#advanced.debug,"Debug Mode
+and Window">>.
+
+
+[[application.environment.parameters.uiprovider]]
+=== Custom UI Provider
+
+Vaadin normally uses the [classname]#DefaultUIProvider# for creating
+[classname]#UI# class instances. If you need to use a custom UI provider, you
+can define its class with the [parameter]#UIProvider# parameter. The provider is
+registered in the [classname]#VaadinSession#.
+
+In a [filename]#web.xml#:
+
+[subs="normal"]
+----
+  &lt;servlet&gt;
+    ...
+    &lt;init-param&gt;
+      &lt;param-name&gt;UIProvider&lt;/param-name&gt;
+      &lt;param-value&gt;**com.ex.my.MyUIProvider**&lt;/param-value&gt;
+    &lt;/init-param&gt;
+----
+The parameter is logically associated with a particular servlet, but can be
+defined in the context as well.
+
+
+[[application.environment.parameters.heartbeat]]
+=== UI Heartbeat
+
+Vaadin monitors UIs by using a heartbeat, as explained in
+<<dummy/../../../framework/application/application-lifecycle#application.lifecycle.ui-expiration,"UI
+Expiration">>. If the user closes the browser window of a Vaadin application or
+navigates to another page, the Client-Side Engine running in the page stops
+sending heartbeat to the server, and the server eventually cleans up the
+[classname]#UI# instance.
+
+The interval of the heartbeat requests can be specified in seconds with the
+[parameter]#heartbeatInterval# parameter either as a context parameter for the
+entire web application or an init parameter for the individual servlet. The
+default value is 300 seconds (5 minutes).
+
+In a [filename]#web.xml#:
+
+
+----
+<context-param>
+  <param-name>heartbeatInterval</param-name>
+  <param-value>300</param-value>
+</context-param>
+----
+
+
+[[application.environment.parameters.session-timeout]]
+=== Session Timeout After User Inactivity
+
+In normal servlet operation, the session timeout defines the allowed time of
+inactivity after which the server should clean up the session. The inactivity is
+measured from the last server request. Different servlet containers use varying
+defaults for timeouts, such as 30 minutes for Apache Tomcat. You can set the
+timeout under [literal]#++<web-app>++# with:
+
+In a [filename]#web.xml#:
+
+((("session-timeout")))
+
+----
+<session-config>
+    <session-timeout>30</session-timeout>
+</session-config>
+----
+
+((("Out of
+Sync")))
+The session timeout should be longer than the heartbeat interval or otherwise
+sessions are closed before the heartbeat can keep them alive. As the session
+expiration leaves the UIs in a state where they assume that the session still
+exists, this would cause an Out Of Sync error notification in the browser.
+
+((("closeIdleSessions")))
+However, having a shorter heartbeat interval than the session timeout, which is
+the normal case, prevents the sessions from expiring. If the
+[parameter]#closeIdleSessions# parameter for the servlet is enabled (disabled by
+default), Vaadin closes the UIs and the session after the time specified in the
+[parameter]#session-timeout# parameter expires after the last non-heartbeat
+request.
+
+In a [filename]#web.xml#:
+
+
+----
+  <servlet>
+    ...
+    <init-param>
+      <param-name>closeIdleSessions</param-name>
+      <param-value>true</param-value>
+    </init-param>
+----
+
+
+[[application.environment.parameters.push]]
+=== Push Mode
+
+You can enable server push, as described in
+<<dummy/../../../framework/advanced/advanced-push#advanced.push,"Server Push">>,
+for a UI either with a [classname]#@Push# annotation for the UI or in the
+descriptor. The push mode is defined with a [parameter]#pushmode# parameter. The
+[literal]#++automatic++# mode pushes changes to the browser automatically after
+__access()__ finishes. With [literal]#++manual++# mode, you need to do the push
+explicitly with [methodname]#push()#. If you use a Servlet 3.0 compatible
+server, you also want to enable asynchronous processing with the
+[literal]#++async-supported++# parameter.
+
+In a [filename]#web.xml#:
+
+[subs="normal"]
+----
+&lt;servlet&gt;
+  ...
+  &lt;init-param&gt;
+    &lt;param-name&gt;pushmode&lt;/param-name&gt;
+    &lt;param-value&gt;**automatic**&lt;/param-value&gt;
+  &lt;/init-param&gt;
+  &lt;async-supported&gt;**true**&lt;/async-supported&gt;
+----
+
+[[application.environment.parameters.xsrf]]
+=== Cross-Site Request Forgery Prevention
+
+Vaadin uses a protection mechanism to prevent malicious cross-site request
+forgery (XSRF or CSRF), also called one-click attacks or session riding, which
+is a security exploit for executing unauthorized commands in a web server. This
+protection is normally enabled. However, it prevents some forms of testing of
+Vaadin applications, such as with JMeter. In such cases, you can disable the
+protection by setting the [parameter]#disable-xsrf-protection# parameter to
+[literal]#++true++#.
+
+In a [filename]#web.xml#:
+
+
+----
+<context-param>
+  <param-name>disable-xsrf-protection</param-name>
+  <param-value>true</param-value>
+</context-param>
+----
+
+
+
+[[application.environment.configuration]]
+== Deployment Configuration
+
+The Vaadin-specific parameters defined in the deployment configuration are
+available from the [classname]#DeploymentConfiguration# object managed by the
+[classname]#VaadinSession#.
+
+
+[source, java]
+----
+DeploymentConfiguration conf =
+        getSession().getConfiguration();
+
+// Heartbeat interval in seconds
+int heartbeatInterval = conf.getHeartbeatInterval();
+----
+
+Parameters defined in the Java Servlet definition, such as the session timeout,
+are available from the low-level [classname]#HttpSession# or
+[classname]#PortletSession# object, which are wrapped in a
+[classname]#WrappedSession# in Vaadin. You can access the low-level session
+wrapper with [methodname]#getSession()# of the [classname]#VaadinSession#.
+
+
+[source, java]
+----
+WrappedSession session = getSession().getSession();
+int sessionTimeout = session.getMaxInactiveInterval();
+----
+
+You can also access other [classname]#HttpSession# and
+[classname]#PortletSession# session properties through the interface, such as
+set and read session attributes that are shared by all servlets belonging to a
+particular servlet or portlet session.
+
+
+
+
-- 
cgit v1.2.3

