Framework documentation IN

Change-Id: I767477c1fc3745f9e1f58075fe30c9ac8da63581

1 files changed, 502 insertions, 0 deletions

diff --git a/documentation/application/application-lifecycle.asciidoc b/documentation/application/application-lifecycle.asciidoc
new file mode 100644
index 0000000000..269f3d75b5
--- /dev/null
+++ b/documentation/application/application-lifecycle.asciidoc
@@ -0,0 +1,502 @@
+---
+title: Application Lifecycle
+order: 8
+layout: page
+---
+
+[[application.lifecycle]]
+= Application Lifecycle
+
+In this section, we look into more technical details of application deployment,
+user sessions, and UI instance lifecycle. These details are not generally needed
+for writing Vaadin applications, but may be useful for understanding how they
+actually work and, especially, in what circumstances their execution ends.
+
+[[application.lifecycle.deployment]]
+== Deployment
+
+Before a Vaadin application can be used, it has to be deployed to a Java web
+server, as described in
+<<dummy/../../../framework/application/application-environment#application.environment,"Deploying
+an Application">>. Deploying reads the servlet classes annotated with the
+[literal]#++@WebServlet++# annotation (Servlet 3.0) or the [filename]#web.xml#
+deployment descriptor (Servlet 2.4) in the application to register servlets for
+specific URL paths and loads the classes. Deployment does not yet normally run
+any code in the application, although static blocks in classes are executed when
+they are loaded.
+
+[[application.lifecycle.deployment.redeployment]]
+=== Undeploying and Redeploying
+
+Applications are undeployed when the server shuts down, during redeployment, and
+when they are explicitly undeployed. Undeploying a server-side Vaadin
+application ends its execution, all application classes are unloaded, and the
+heap space allocated by the application is freed for garbage-collection.
+
+If any user sessions are open at this point, the client-side state of the UIs is
+left hanging and an Out of Sync error is displayed on the next server request.
+
+
+[[application.lifecycle.deployment.serialization]]
+=== Redeployment and Serialization
+
+Some servers, such as Tomcat, support __hot deployment__, where the classes are
+reloaded while preserving the memory state of the application. This is done by
+serializing the application state and then deserializing it after the classes
+are reloaded. This is, in fact, done with the basic Eclipse setup with Tomcat
+and if a UI is marked as [classname]#@PreserveOnRefresh#, you may actually need
+to give the [literal]#++?restartApplication++# URL parameter to force it to
+restart when you reload the page. Tools such as JRebel go even further by
+reloading the code in place without need for serialization. The server can also
+serialize the application state when shutting down and restarting, thereby
+preserving sessions over restarts.
+
+Serialization requires that the applications are __serializable__, that is, all
+classes implement the [interfacename]#Serializable# interface. All Vaadin
+classes do. If you extend them or implement interfaces, you can provide an
+optional serialization key, which is automatically generated by Eclipse if you
+use it. Serialization is also used for clustering and cloud computing, such as
+with Google App Engine.
+
+ifdef::web[]
+For more about that topic, see
+<<dummy/../../../framework/advanced/advanced-gae#advanced.gae,"Google App Engine
+Integration">>.
+endif::web[]
+
+
+
+[[application.lifecycle.servlet-service]]
+== Vaadin Servlet, Portlet, and Service
+
+The [classname]#VaadinServlet#, or [classname]#VaadinPortlet# in a portal,
+receives all server requests mapped to it by its URL, as defined in the
+deployment configuration, and associates them with sessions. The sessions
+further associate the requests with particular UIs.
+
+When servicing requests, the Vaadin servlet or portlet handles all tasks common
+to both servlets and portlets in a [classname]#VaadinService#. It manages
+sessions, gives access to the deployment configuration information, handles
+system messages, and does various other tasks. Any further servlet or portlet
+specific tasks are handled in the corresponding
+[classname]#VaadinServletService# or [classname]#VaadinPortletService#. The
+service acts as the primary low-level customization layer for processing
+requests.
+
+[[application.lifecycle.servlet-service.servletcustomization]]
+=== Customizing Vaadin Servlet
+
+Many common configuration tasks need to be done in the servlet class, which you
+already have if you are using the [literal]#++@WebServlet++# annotation for
+Servlet 3.0 to deploy the application. You can handle most customization by
+overriding the [methodname]#servletInitialized()# method, where the
+[classname]#VaadinService# object is available with [methodname]#getService()#
+(it would not be available in a constructor). You should always call
+[methodname]#super.servletInitialized()# in the beginning.
+
+
+[source, java]
+----
+public class MyServlet extends VaadinServlet {
+    @Override
+    protected void servletInitialized()
+            throws ServletException {
+        super.servletInitialized();
+
+        ...
+    }
+}
+----
+
+To add custom functionality around request handling, you can override the
+[methodname]#service()# method.
+
+To use the custom servlet class in a Servlet 2.4 project, you need to define it
+in the [filename]#web.xml# deployment descriptor instead of the regular
+[classname]#VaadinServlet# class, as described in
+<<dummy/../../../framework/application/application-environment#application.environment.web-xml,"Using
+a web.xml Deployment Descriptor">>.
+
+
+ifdef::web[]
+[[application.lifecycle.servlet-service.portletcustomization]]
+=== Customizing Vaadin Portlet
+
+__To Be Done__
+
+endif::web[]
+
+ifdef::web[]
+[[application.lifecycle.servlet-service.servicecustomization]]
+=== Customizing Vaadin Service
+
+To customize [classname]#VaadinService#, you first need to extend the
+[classname]#VaadinServlet# or - [classname]#Portlet# class and override the
+[methodname]#createServletService()# to create a custom service object.
+
+endif::web[]
+
+
+[[application.lifecycle.session]]
+== User Session
+
+((("session")))
+A user session begins when a user first makes a request to a Vaadin servlet or
+portlet by opening the URL for a particular [classname]#UI#. All server requests
+belonging to a particular UI class are processed by the
+[classname]#VaadinServlet# or [classname]#VaadinPortlet# class. When a new
+client connects, it creates a new user session, represented by an instance of
+[classname]#VaadinSession#. Sessions are tracked using cookies stored in the
+browser.
+
+You can obtain the [classname]#VaadinSession# of a [classname]#UI# with
+[methodname]#getSession()# or globally with
+[methodname]#VaadinSession.getCurrent()#. It also provides access to the
+lower-level session objects, [interfacename]#HttpSession# and
+[interfacename]#PortletSession#, through a [classname]#WrappedSession#. You can
+also access the deployment configuration through [classname]#VaadinSession#, as
+described in
+<<dummy/../../../framework/application/application-environment#application.environment.configuration,"Deployment
+Configuration">>.
+
+A session ends after the last [classname]#UI# instance expires or is closed, as
+described later.
+
+[[application.lifecycle.session.init]]
+=== Handling Session Initialization and Destruction
+
+((("[classname]#SessionInitListener#")))
+((("[classname]#SessionDestroyListener#")))
+((("[classname]#VaadinService#")))
+You can handle session initialization and destruction by implementing a
+[interfacename]#SessionInitListener# or [interfacename]#SessionDestroyListener#,
+respectively, to the [classname]#VaadinService#.
+((("[methodname]#servletInitialized()#")))
+((("[classname]#VaadinServlet#")))
+You can do that best by extending [classname]#VaadinServlet# and overriding the
+[methodname]#servletInitialized()# method, as outlined in
+<<application.lifecycle.servlet-service>>.
+
+
+[source, java]
+----
+public class MyServlet extends VaadinServlet
+    implements SessionInitListener, SessionDestroyListener {
+
+    @Override
+    protected void servletInitialized() throws ServletException {
+        super.servletInitialized();
+        getService().addSessionInitListener(this);
+        getService().addSessionDestroyListener(this);
+    }
+
+    @Override
+    public void sessionInit(SessionInitEvent event)
+            throws ServiceException {
+        // Do session start stuff here
+    }
+
+    @Override
+    public void sessionDestroy(SessionDestroyEvent event) {
+        // Do session end stuff here
+    }
+}
+----
+
+If using Servlet 2.4, you need to configure the custom servlet class in the
+[parameter]#servlet-class# parameter in the [filename]#web.xml# descriptor
+instead of the [classname]#VaadinServlet#, as described in
+<<dummy/../../../framework/application/application-environment#application.environment.web-xml,"Using
+a web.xml Deployment Descriptor">>.
+
+
+
+[[application.lifecycle.ui]]
+== Loading a UI
+
+((("UI", "loading")))
+When a browser first accesses a URL mapped to the servlet of a particular UI
+class, the Vaadin servlet generates a loader page. The page loads the
+client-side engine (widget set), which in turn loads the UI in a separate
+request to the Vaadin servlet.
+
+((("[classname]#UIProvider#")))
+((("[classname]#DefaultUIProvider#")))
+((("[classname]#BrowserWindowOpener#")))
+A [classname]#UI# instance is created when the client-side engine makes its
+first request. The servlet creates the UIs using a [classname]#UIProvider#
+registered in the [classname]#VaadinSession# instance. A session has at least a
+[classname]#DefaultUIProvider# for managing UIs opened by the user. If the
+application lets the user open popup windows with a
+[classname]#BrowserWindowOpener#, each of them has a dedicated special UI
+provider.
+
+((("[classname]#VaadinRequest#")))
+((("[methodname]#init()#")))
+Once a new UI is created, its [methodname]#init()# method is called. The method
+gets the request as a [classname]#VaadinRequest#.
+
+[[application.lifecycle.ui.loaderpage]]
+=== Customizing the Loader Page
+
+The HTML content of the loader page is generated as an HTML DOM object, which
+can be customized by implementing a [interfacename]#BootstrapListener# that
+modifies the DOM object. To do so, you need to extend the
+[classname]#VaadinServlet# and add a [interfacename]#SessionInitListener# to the
+service object, as outlined in <<application.lifecycle.session>>. You can then
+add the bootstrap listener to a session with
+[methodname]#addBootstrapListener()# when the session is initialized.
+
+Loading the widget set is handled in the loader page with functions defined in a
+separate [filename]#vaadinBootstrap.js# script.
+
+You can also use entirely custom loader code, such as in a static HTML page, as
+described in
+<<dummy/../../../framework/advanced/advanced-embedding#advanced.embedding,"Embedding
+UIs in Web Pages">>.
+
+
+[[application.lifecycle.ui.uiprovider]]
+=== Custom UI Providers
+
+((("[interfacename]#UIProvider#", "custom")))
+You can create UI objects dynamically according to their request parameters,
+such as the URL path, by defining a custom [interfacename]#UIProvider#. You need
+to add custom UI providers to the session object which calls them. The providers
+are chained so that they are requested starting from the one added last, until
+one returns a UI (otherwise they return null). You can add a UI provider to a
+session most conveniently by implementing a custom servlet and adding the UI
+provider to sessions in a [interfacename]#SessionInitListener#.
+
+You can find an example of custom UI providers in
+<<dummy/../../../mobile/mobile-features#mobile.features.fallback,"Providing a
+Fallback UI">>.
+
+
+[[application.lifecycle.ui.preserving]]
+=== Preserving UI on Refresh
+
+((("UI", "preserving on refresh")))
+((("[classname]#@PreserveOnRefresh#")))
+Reloading a page in the browser normally spawns a new [classname]#UI# instance
+and the old UI is left hanging, until cleaned up after a while. This can be
+undesired as it resets the UI state for the user. To preserve the UI, you can
+use the [classname]#@PreserveOnRefresh# annotation for the UI class. You can
+also use a [classname]#UIProvider# with a custom implementation of
+[methodname]#isUiPreserved()#.
+
+
+[source, java]
+----
+@PreserveOnRefresh
+public class MyUI extends UI {
+----
+
+Adding the ?restartApplication parameter in the URL tells the Vaadin servlet to
+create a new [classname]#UI# instance when loading the page, thereby overriding
+the [classname]#@PreserveOnRefresh#. This is often necessary when developing
+such a UI in Eclipse, when you need to restart it after redeploying, because
+Eclipse likes to persist the application state between redeployments. If you
+also include a URI fragment, the parameter should be given before the fragment.
+
+
+
+[[application.lifecycle.ui-expiration]]
+== UI Expiration
+
+((("UI", "expiration")))
+[classname]#UI# instances are cleaned up if no communication is received from
+them after some time. If no other server requests are made, the client-side
+sends keep-alive heartbeat requests. A UI is kept alive for as long as requests
+or heartbeats are received from it. It expires if three consecutive heartbeats
+are missed.
+
+The heartbeats occur at an interval of 5 minutes, which can be changed with the
+[parameter]#heartbeatInterval# parameter of the servlet. You can configure the
+parameter in [classname]#@VaadinServletConfiguration# or in [filename]#web.xml#
+as described in
+<<dummy/../../../framework/application/application-environment#application.environment.parameters,"Other
+Servlet Configuration Parameters">>.
+
+When the UI cleanup happens, a [classname]#DetachEvent# is sent to all
+[classname]#DetachListener#s added to the UI. When the [classname]#UI# is
+detached from the session, [methodname]#detach()# is called for it.
+
+
+[[application.lifecycle.ui-closing]]
+== Closing UIs Explicitly
+
+((("UI", "closing")))
+((("[methodname]#close()#",
+"UI")))
+You can explicitly close a UI with [methodname]#close()#. The method marks the
+UI to be detached from the session after processing the current request.
+Therefore, the method does not invalidate the UI instance immediately and the
+response is sent as usual.
+
+Detaching a UI does not close the page or browser window in which the UI is
+running and further server request will cause error. Typically, you either want
+to close the window, reload it, or redirect it to another URL. If the page is a
+regular browser window or tab, browsers generally do not allow closing them
+programmatically, but redirection is possible. You can redirect the window to
+another URL with [methodname]#setLocation()#, as is done in the examples in
+<<application.lifecycle.session-closing>>. You can close popup windows by making
+JavaScript [methodname]#close()# call for them, as described in
+<<dummy/../../../framework/advanced/advanced-windows#advanced.windows.popup-closing,"Closing
+Popup Windows">>.
+
+If you close other UI than the one associated with the current request, they
+will not be detached at the end of the current request, but after next request
+from the particular UI. You can make that occur quicker by making the UI
+heartbeat faster or immediately by using server push.
+
+
+[[application.lifecycle.session-expiration]]
+== Session Expiration
+
+((("session", "expiration")))
+A session is kept alive by server requests caused by user interaction with the
+application as well as the heartbeat monitoring of the UIs. Once all UIs have
+expired, the session still remains. It is cleaned up from the server when the
+session timeout configured in the web application expires.
+
+((("closeIdleSessions")))
+If there are active UIs in an application, their heartbeat keeps the session
+alive indefinitely. You may want to have the sessions timeout if the user is
+inactive long enough, which is the original purpose of the session timeout
+setting. ((("session",
+"timeout")))
+((("closeIdleSessions")))
+If the [parameter]#closeIdleSessions# parameter of the servlet is set to
+[literal]#++true++# in the [filename]#web.xml#, as described in
+<<dummy/../../../framework/application/application-environment#application.environment.web-xml,"Using
+a web.xml Deployment Descriptor">>, the session and all of its UIs are closed
+when the timeout specified by the [parameter]#session-timeout# parameter of the
+servlet expires after the last non-heartbeat request. Once the session is gone,
+the browser will show an Out Of Sync error on the next server request.
+((("redirection")))
+To avoid the ugly message, you may want to set a redirect URL for the UIs
+
+ifdef::web[]
+, as described in
+<<dummy/../../../framework/application/application-errors#application.errors.systemmessages,"Customizing
+System
+Messages">>
+endif::web[]
+.
+
+The related configuration parameters are described in
+<<dummy/../../../framework/application/application-environment#application.environment.parameters,"Other
+Servlet Configuration Parameters">>.
+
+((("[interfacename]#SessionDestroyListener#")))
+You can handle session expiration on the server-side with a
+[interfacename]#SessionDestroyListener#, as described in
+<<application.lifecycle.session>>.
+
+
+[[application.lifecycle.session-closing]]
+== Closing a Session
+
+((("session", "closing")))
+((("[methodname]#close()#")))
+You can close a session by calling [methodname]#close()# on the
+[classname]#VaadinSession#. It is typically used when logging a user out and the
+session and all the UIs belonging to the session should be closed. The session
+is closed immediately and any objects related to it are not available after
+calling the method.
+
+When closing the session from a UI, you typically want to redirect the user to
+another URL.
+((("redirection")))
+((("[methodname]#setLocation()#")))
+((("Page",
+"[methodname]#setLocation()#")))
+You can do the redirect using the [methodname]#setLocation()# method in
+[classname]#Page#. This needs to be done before closing the session, as the UI
+or page are not available after that. In the following example, we display a
+logout button, which closes the user session.
+
+((("logout")))
+
+[source, java]
+----
+public class MyUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        setContent(new Button("Logout", event -> {// Java 8
+            // Redirect this page immediately
+            getPage().setLocation("/myapp/logout.html");
+            
+            // Close the session
+            getSession().close();
+        }));
+
+        // Notice quickly if other UIs are closed
+        setPollInterval(3000);
+    }
+}
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#application.lifecycle.closing[on-line example, window="_blank"].
+
+This is not enough. When a session is closed from one UI, any other UIs attached
+to it are left hanging. When the client-side engine notices that a UI and the
+session are gone on the server-side, it displays a "Session Expired" message
+and, by default, reloads the UI when the message is clicked. ((("session",
+"expiration")))
+((("redirection")))
+((("system
+messages")))
+You can customize the message and the redirect URL in the system messages
+
+ifdef::web[]
+, as described in
+<<dummy/../../../framework/application/application-errors#application.errors.systemmessages,"Customizing
+System
+Messages">>
+endif::web[]
+.
+
+((("heartbeat")))
+((("UI",
+"heartbeat")))
+((("push")))
+((("server
+push")))
+The client-side engine notices the expiration when user interaction causes a
+server request to be made or when the keep-alive heartbeat occurs. To make the
+UIs detect the situation faster, you need to make the heart beat faster, as was
+done in the example above. You can also use server push to close the other UIs
+immediately, as is done in the following example. Access to the UIs must be
+synchronized as described in
+<<dummy/../../../framework/advanced/advanced-push#advanced.push,"Server Push">>.
+
+
+[source, java]
+----
+@Push
+public class MyPushyUI extends UI {
+    @Override
+    protected void init(VaadinRequest request) {
+        setContent(new Button("Logout", event -> {// Java 8
+            for (UI ui: VaadinSession.getCurrent().getUIs())
+                ui.access(() -> {
+                    // Redirect from the page
+                    ui.getPage().setLocation("/logout.html");
+                });
+
+            getSession().close();
+        }));
+    }
+}
+----
+See the http://demo.vaadin.com/book-examples-vaadin7/book#application.lifecycle.closingall[on-line example, window="_blank"].
+
+In the above example, we assume that all UIs in the session have push enabled
+and that they should be redirected; popups you might want to close instead of
+redirecting. It is not necessary to call [methodname]#close()# for them
+individually, as we close the entire session afterwards.
+
+
+
+