Docs

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Docs

Deploying an Application

Vaadin Framework 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 .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.

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.

  1. Select File › Export and then Web › WAR File. Or, right-click the project in the Project Explorer and select Web › WAR File.

  2. Select the Web project to export. Enter Destination file name (.war).

  3. Make any other settings in the dialog, and click Finish.

Web Application Contents

The following files are required in a web application in order to run it.

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 @WebServlet annotation in Servlet API 3.0.

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.

Your UI classes

You must include your UI classes either in a JAR file in WEB-INF/lib or as classes in WEB-INF/classes

Your own theme files (OPTIONAL)

If your application uses a special theme (look and feel), you must include it in VAADIN/themes/themename directory.

Widget sets (OPTIONAL)

If your application uses add-ons or custom widgets, they must be compiled to the VAADIN/widgetset/ directory. When using add-ons, this is done automatically in Maven projects. See "Using Add-ons in a Maven Project" for more information.

Web Servlet Class

When using the Servlet 3.0 API, you normally declare the Vaadin servlet classes with the @WebServlet annotation. The Vaadin UI associated with the servlet and other Vaadin-specific parameters are declared with a separate @VaadinServletConfiguration annotation.

@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 value parameter is the URL pattern for mapping request URLs to the servlet, as described in Servlet Mapping with URL Patterns. The 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 web.xml deployment descriptor in Servlet 3.0 projects.

Using a web.xml Deployment Descriptor

A deployment descriptor is an XML file with the name web.xml in the 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 @WebServlet annotation as decribed earlier, as web fragments, or programmatically. You can use both a web.xml and WebServlet in the same application. Settings in the web.xml override the ones given in annotations.

The following example shows the basic contents of a deployment descriptor. You simply specify the UI class with the UI parameter for the com.vaadin.server.VaadinServlet. The servlet is then mapped to a URL path in a standard way for Java Servlets.

<?xml version="1.0" encoding="UTF-8"?>
<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">

  <servlet>
    <servlet-name>myservlet</servlet-name>
    <servlet-class>
        com.vaadin.server.VaadinServlet
    </servlet-class>

    <init-param>
      <param-name>UI</param-name>
      <param-value>com.ex.myprj.MyUI</param-value>
    </init-param>

    <!-- If not using the default widget set-->
    <init-param>
      <param-name>widgetset</param-name>
      <param-value>com.ex.myprj.AppWidgetSet</param-value>
    </init-param>
  </servlet>

  <servlet-mapping>
    <servlet-name>myservlet</servlet-name>
    <url-pattern>/*</url-pattern>
  </servlet-mapping>
</web-app>

The descriptor defines a servlet with the name myservlet. The servlet class, 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 VaadinServlet. The class name must include the full package path.

Widget Set

The widget set is normally defined and compiled automatically in Maven projects. It may be necessary to define it manually in some cases, such as when developing custom widgets or if you need to include special rules in the widget set definition file (.gwt.xml module descriptor).

The widget set of a UI can be defined with the @WidgetSet annotation for the UI class.

@WidgetSet("com.example.myproject.MyWidgetSet")
class MyUI extends UI {
    …​

You can also define it with the widgetset init parameter for the servlet.

The name of a widget set is technically a Java class name with the same path as the widget set definition file, but without the .gwt.xml extension.

If a widget set is not specified, the default is used. In a project that does not use add-ons or custom widgets, the com.vaadin.DefaultWidgetSet is used. It contains all the widgets for the built-in Vaadin components. When using add-ons, the Vaadin Maven Plugin automatically defines an AppWidgetSet that includes all the add-on widget sets.

The widget set must be compiled, as described in "Using Vaadin Add-ons" (for add-ons) or "Compiling a Client-Side Module" (for custom widgets and client-side modules), and properly deployed with the application.

Servlet Mapping with URL Patterns

The servlet needs to be mapped to an URL path, which requests it is to handle.

With @WebServlet annotation for the servlet class:

@WebServlet(value = "/*", asyncSupported = true)

The URL pattern is defined in the above examples as /*. This matches any URL under the project context. We defined above the project context as myproject so the URL for the page of the UI will be http://localhost:8080/myproject/.

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 /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 /VAADIN/* to a servlet (unless you are serving it statically as noted below).

With a @WebServlet annotation for a servlet class, you can define multiple mappings as a list enclosed in curly braces as follows:

@WebServlet(value = {"/myui/*", "/VAADIN/*"},
            asyncSupported = true)

If you have multiple servlets, you should specify only one /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 /VAADIN/* mapping if you serve both the widget sets and (custom and default) themes statically in the /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 /* for the Vaadin servlet, as then all the requests would be mapped to the servlet.

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 Java Servlet Specification.

@VaadinServletConfiguration accepts a number of special parameters, as described below.

In a web.xml, you can set most parameters either as a <context-param> for the entire web application, in which case they apply to all Vaadin servlets, or as an <init-param> for an individual servlet. If both are defined, servlet parameters override context parameters.

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 productionMode=true setting in the @VaadinServletConfiguration.

The parameter and the debug and production modes are described in more detail in "Debug Mode and Window".

Custom UI Provider

Vaadin normally uses the DefaultUIProvider for creating UI class instances. If you need to use a custom UI provider, you can define its class with the UIProvider parameter. The provider is registered in the VaadinSession.

The parameter is logically associated with a particular servlet, but can be defined in the context as well.

UI Heartbeat

Vaadin monitors UIs by using a heartbeat, as explained in "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 UI instance.

The interval of the heartbeat requests can be specified in seconds with the 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).

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. There is no way to programmatically set the global session timeout, but you can set it in the deployment descriptor with: 

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

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.

However, having a shorter heartbeat interval than the session timeout, which is the normal case, prevents the sessions from expiring. If the closeIdleSessions parameter for the servlet is enabled (disabled by default), Vaadin closes the UIs and the session after the time specified in the session-timeout init parameter expires after the last non-heartbeat request.

Push Mode

You can enable server push, as described in "Server Push", for a UI either with a @Push annotation for the UI or in the descriptor. The push mode is defined with a pushmode init parameter. The automatic mode pushes changes to the browser automatically after access() finishes. With manual mode, you need to do the push explicitly with push(). You can enable asynchronous processing with the async-supported init parameter.

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 disable-xsrf-protection context parameter to true.

Deployment Configuration

The Vaadin-specific parameters defined in the deployment configuration are available from the DeploymentConfiguration object managed by the VaadinSession.

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 HttpSession or PortletSession object, which are wrapped in a WrappedSession in Vaadin. You can access the low-level session wrapper with getSession() of the VaadinSession.

WrappedSession session = getSession().getSession();
int sessionTimeout = session.getMaxInactiveInterval();

You can also access other HttpSession and 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.