123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502 |
- ---
- 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):: 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 [literal]#++@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 a project-specific widget set, it must be compiled in
- the [filename]#VAADIN/widgetset/# directory.
-
-
-
-
- [[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 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="normal"]
- ----
- <?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>**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.MyWidgetSet**</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 [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
-
- If the UI uses add-on components or custom widgets, it needs a custom widget
- set, which can be specified with the [parameter]#widgetset# parameter for the
- servlet. Alternatively, you can defined it with the [classname]#@WidgetSet#
- annotation for the UI class. The parameter is a class name with the same path
- but without the [filename]#.gwt.xml# extension as the widget set definition
- file. If the parameter is not given, the
- [classname]#com.vaadin.DefaultWidgetSet# is used, which contains all the widgets
- for the built-in Vaadin components.
-
- Unless using the default widget set (which is included in the
- [filename]#vaadin-client-compiled# JAR), the widget set must be compiled, as
- described in
- <<dummy/../../../framework/addons/addons-overview.asciidoc#addons.overview,"Using
- Vaadin Add-ons">> or
- <<dummy/../../../framework/clientside/clientside-compiling#clientside.compiling,"Compiling
- a Client-Side Module">>, 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]#++<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#, or in [filename]#web.xml#:
-
-
- ----
- <context-param>
- <param-name>productionMode</param-name>
- <param-value>true</param-value>
- <description>Vaadin production mode</description>
- </context-param>
- ----
-
- 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#.
-
- 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
- <<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).
-
- In a [filename]#web.xml#:
-
-
- ----
- <context-param>
- <param-name>heartbeatInterval</param-name>
- <param-value>300</param-value>
- </context-param>
- ----
-
-
- [[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]#++<web-app>++# with:
-
- In a [filename]#web.xml#:
-
- ((("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# parameter expires after the last non-heartbeat
- request.
-
- In a [filename]#web.xml#:
-
-
- ----
- <servlet>
- ...
- <init-param>
- <param-name>closeIdleSessions</param-name>
- <param-value>true</param-value>
- </init-param>
- ----
-
-
- [[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# 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#:
-
-
- ----
- <context-param>
- <param-name>disable-xsrf-protection</param-name>
- <param-value>true</param-value>
- </context-param>
- ----
-
-
-
- [[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.
-
-
-
|