diff options
Diffstat (limited to 'documentation/application/application-environment.asciidoc')
| -rw-r--r-- | documentation/application/application-environment.asciidoc | 502 |
1 files changed, 502 insertions, 0 deletions
diff --git a/documentation/application/application-environment.asciidoc b/documentation/application/application-environment.asciidoc new file mode 100644 index 0000000000..5a2bf7ecbf --- /dev/null +++ b/documentation/application/application-environment.asciidoc @@ -0,0 +1,502 @@ +--- +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. + + + + |