From 2af72ba9636bec70046394c41744f89ce4572e35 Mon Sep 17 00:00:00 2001
From: Ilia Motornyi <elmot@vaadin.com>
Date: Thu, 3 Dec 2015 14:59:05 +0000
Subject: Revert "Merge branch 'documentation'"

This reverts commit f6874bde3d945c8b2d1b5c17ab50e2d0f1f8ff00.

Change-Id: I67ee1c30ba3e3bcc3c43a1dd2e73a822791514bf
---
 .../application/application-environment.asciidoc   | 502 ---------------------
 1 file changed, 502 deletions(-)
 delete 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
deleted file mode 100644
index 5a2bf7ecbf..0000000000
--- a/documentation/application/application-environment.asciidoc
+++ /dev/null
@@ -1,502 +0,0 @@
----
-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

