Writing a Server-Side Web Application
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.
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 @PreserveOnRefresh, you may actually need to give the ?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 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, as described in Section 11.7, “Google App Engine Integration”.
4.7.2. Vaadin Servlet, Portlet, and Service
The VaadinServlet, or 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 VaadinService. It manages sessions, gives access to the deployment configuration information, handles system messages, and does various other tasks. Any servlet type specific tasks are handled in the corresponding VaadinServletService or VaadinPortletService. The service acts as the primary low-level customization layer for processing requests.
Customization
To customize VaadinService, you first need to extend the VaadinServlet or -Portlet class and override the createServletService() to create a custom service object.
4.7.3. User 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 UI. All server requests belonging to a particular UI class are processed by the VaadinServlet or VaadinPortlet class. When a new client connects, it creates a new user session, represented by an instance of VaadinSession. Sessions are tracked using cookies stored in the browser.
You can obtain the VaadinSession of an UI with getSession() or globally with VaadinSession.getCurrent(). It also provides access to the lower-level session objects, HttpSession and PortletSession, through a WrappedSession. You can also access the deployment configuration through VaadinSession, as described in Section 4.8.5, “Deployment Configuration”.
A session ends after the last UI instance expires or is closed, as described later.
80 |
Vaadin Servlet, Portlet, and Service |
Writing a Server-Side Web Application
4.7.4. Loading a UI
When a browser first accesses a URL mapped to the servlet of a particular UI, 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.
A UI instance is created when the client-side engine makes its first request. The servlet creates the UIs using a UIProvider registered in the VaadinSession instance. A session has at least a DefaultUIProvider for managing UIs opened by the user. If the application lets the user open popup windows with a BrowserWindowOpener, each of them has a dedicated special UI provider.
Once a new UI is created, its init() method is called. The method gets the request as a
VaadinRequest.
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 BootstrapListener that modifies the DOM object. To do so, you need to extend the VaadinServlet and add a SessionInitListener to the servlet with addSessionInitListener(). You can then add the bootstrap listener to a session with addBootstrapListener() when the session is initialized.
Loading the widget set is handled in the loader page with functions defined in a separate vaadinBootstrap.js script.
You can also use entirely custom loader code, such as in a static HTML page, as described in Section 11.2, “Embedding UIs in Web Pages”.
Custom UI Providers
You can create UI objects dynamically according to their request parameters, such as the URL path, by defining a custom 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 SessionInitListener.
You can find an example of custom UI providers in Section 22.6.1, “Providing a Fallback UI”.
Preserving UI on Refresh
Reloading a page in the browser normally spawns a new 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 @PreserveOnRefresh annotation for the UI class. You can also use a UIProvider with a custom implementation of isUiPreserved().
@PreserveOnRefresh
public class MyUI extends UI {
Adding the ?restartApplication parameter in the URL tells the Vaadin servlet to create a new UI instance when loading the page, even when the @PreserveOnRefresh is enabled. 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.
Loading a UI |
81 |
Writing a Server-Side Web Application
4.7.5. UI Expiration
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 heartbeatInterval parameter of the servlet. You can configure the parameter in web.xml as described in Section 4.8.4, “Other Deployment Parameters”.
When the UI cleanup happens, a DetachEvent is sent to all DetachListeners added to the UI. When the UI is detached from the session, detach() is called for it.
4.7.6. 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.
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. If the closeIdleSessions parameter of the servlet is set to true in the web.xml, as described in Section 4.8.3, “Deployment Descriptor web.xml”, the session and all of its UIs are closed when the timeout specified by the 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.To avoid the ugly message, you may want to set a redirect URL for the UIs as described in Section 4.5.2, “Customizing System Messages”.
The related configuration parameters are described in Section 4.8.4, “Other Deployment Parameters”.
4.7.7. Closing a Session
You can call the close() method in the VaadinSession to shut down the session and clean up any of the resources allocated for it.The session is closed immediately and any objects related to it are not available after calling the method. The UI that is still visible in the browser has no session to communicate with, but will still receive the response from the final request.You typically want to redirect the user to another URL at this point, using the setLocation() method in
Page.
In the following example, we display a logout button, which closes the user session.
Button logout = new Button("Logout"); logout.addClickListener(new Button.ClickListener() {
@Override
public void buttonClick(ClickEvent event) {
//Redirect from the page getUI().getPage().setLocation(
"/myapp/logoutpage.html");
//Close the VaadinSession getSession().close();
}
});
82 |
UI Expiration |