--- 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):: his is the web application descriptor that defines how the application is rganized, 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 [classname]#@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 add-ons or custom widgets, they must be compiled to the [filename]#VAADIN/widgetset/# directory. When using add-ons, this is done automatically in Maven projects. See <> for more information. [[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 <>. 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="verbatim,replacements,quotes"] ---- <?xml version="1.0" encoding="UTF-8"?> <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"> <servlet> <servlet-name>[replaceable]##myservlet##</servlet-name> <servlet-class> [replaceable]##com.vaadin.server.VaadinServlet## </servlet-class> <init-param> <param-name>UI</param-name> <param-value>[replaceable]##com.ex.myprj.MyUI##</param-value> </init-param> <!-- If not using the default widget set--> <init-param> <param-name>widgetset</param-name> <param-value>[replaceable]##com.ex.myprj.AppWidgetSet##</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>[replaceable]##myservlet##</servlet-name> <url-pattern>[replaceable]##/*##</url-pattern> </servlet-mapping> </web-app> ---- 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"] ---- <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 3.0 support is useful for at least server push. [[application.environment.web-xml.widgetset]] === 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 ([filename]#.gwt.xml# module descriptor). The widget set of a UI can be defined with the [classname]#@WidgetSet# annotation for the UI class. [source, Java, subs="normal"] ---- @WidgetSet("[replaceable]#com.example.myproject.MyWidgetSet#") class MyUI extends UI { ... ---- You can also define it in the [filename]#web.xml# descriptor for the servlet: [source, xml, subs="normal"] ---- widgetset com.example.myproject.MyWidgetSet ---- 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 [filename]#.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 [classname]#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 [classname]#AppWidgetSet# that includes all the add-on widget sets. The widget set must be compiled, as described in <> (for add-ons) or <> (for custom widgets and client-side modules), 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"] ---- <servlet-mapping> <servlet-name>**myservlet**</servlet-name> <url-pattern>/*</url-pattern> </servlet-mapping> ---- 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"] ---- ... <servlet-mapping> <servlet-name>**myservlet**</servlet-name> <url-pattern>**/myui/++*++**</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>**myservlet**</servlet-name> <url-pattern>/VAADIN/*</url-pattern> </servlet-mapping> ---- 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]#++++# for the entire web application, in which case they apply to all Vaadin servlets, or as an [literal]#++++# 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#: ---- productionMode true Vaadin production mode ---- The parameter and the debug and production modes are described in more detail in <>. [[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"] ---- <servlet> ... <init-param> <param-name>UIProvider</param-name> <param-value>**com.ex.my.MyUIProvider**</param-value> </init-param> ---- 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 <>. 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#: ---- heartbeatInterval 300 ---- [[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]#++++# with: In a [filename]#web.xml#: ((("session-timeout"))) ---- 30 ---- ((("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#: ---- ... closeIdleSessions true ---- [[application.environment.parameters.push]] === Push Mode You can enable server push, as described in <>, 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"] ---- <servlet> ... <init-param> <param-name>pushmode</param-name> <param-value>**automatic**</param-value> </init-param> <async-supported>**true**</async-supported> ---- [[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#: ---- disable-xsrf-protection true ---- [[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.