123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387 |
- ---
- 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 <<../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"]
- ----
- <?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>[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.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 <<../addons/addons-overview.asciidoc#addons.overview,"Using Vaadin Add-ons">> (for add-ons) or <<../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
- <<../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
- <<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
- <<../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.
|