path: root/documentation/application/application-environment.asciidoc

---
title: Deploying an Application
order: 9
layout: page
---

[[application.environment]]
= 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 [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.

[[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 [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.

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 <<dummy/../../../framework/addons/addons-maven#addons.maven, "Using Add-ons in a Maven Project">> 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 <<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. 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"]
----
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&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;

  &lt;servlet&gt;
    &lt;servlet-name&gt;[replaceable]##myservlet##&lt;/servlet-name&gt;
    &lt;servlet-class&gt;
        [replaceable]##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;[replaceable]##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;[replaceable]##com.ex.myprj.AppWidgetSet##&lt;/param-value&gt;
    &lt;/init-param&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;[replaceable]##myservlet##&lt;/servlet-name&gt;
    &lt;url-pattern&gt;[replaceable]##/*##&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.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 with the [parameter]#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 [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 <<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">> (for add-ons) or <<dummy/../../../framework/clientside/clientside-compiling#clientside.compiling,"Compiling a Client-Side Module">> (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)
----

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)
----

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#.

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#.

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).


[[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. There is no way to
programmatically set the global session timeout, but you can set it in the
deployment descriptor with:
((("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# init parameter expires after the last non-heartbeat
request.


[[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# init 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()#. You can enable asynchronous processing with the
[literal]#++async-supported++# init parameter.


[[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# context parameter to
[literal]#++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.