Book of Vaadin - vaadin.com

4.8. Setting Up the Application Environment
Prev	Chapter 4. Writing a Web Application	Next

4.8. Setting Up the Application Environment

While more and more server based frameworks, libraries, standards, and architectures for Java are invented to make the programmer's life easier, software deployment seems to get harder and harder. For example, Java Enterprise Beans tried to make the creation of persistent and networked objects easy and somewhat automatic, but the number of deployment descriptions got enormous. As Vaadin lives in a Java Servlet container, it must follow the rules, but it tries to avoid adding extra complexity.

All Vaadin applications are deployed as Java web applications, which can be packaged as WAR files. For a detailed tutorial on how web applications are packaged, please refer to any Java book that discusses Servlets. Sun has an excellent reference online at http://java.sun.com/j2ee/tutorial/1_3-fcs/doc/WCC3.html .

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

Open project properties and first set the name and destination of the WAR file in Tomcat Export to WAR settings tab. Exporting to WAR is done by selecting Export to WAR from Tomcat Project in project context menu (just click calc with the right mouse button on Package contents tree).

4.8.2. Web Application Contents

The following files are required in a web application in order to run it.

Web application organization

WEB-INF/web.xml: This is the standard web application descriptor that defines how the application is organized. You can refer to any Java book about the contents of this file. Also see an example in Example 4.1, “web.xml”.
WEB-INF/lib/vaadin-6.2.0.jar: This is the Vaadin library. It is included in the product package in lib directory.
Your application classes: You must include your application classes either in a JAR file in WEB-INF/lib or as classes in WEB-INF/classes
Your own theme files (OPTIONAL): If your application uses a special theme (look and feel), you must include it in WEB-INF/lib/themes/themename directory.

4.8.3. Deployment Descriptor `web.xml`

The deployment descriptor is an XML file with the name web.xml in the WEB-INF directory of a web application. It is a standard component in Java EE describing how a web application should be deployed. The structure of the deployment descriptor is illustrated by the following example. You simply deploy applications as servlets implemented by the special com.vaadin.terminal.gwt.server.ApplicationServlet wrapper class. The class of the actual application is specified by giving the application parameter with the name of the specific application class to the servlet. The servlet is then connected to a URL in a standard way for Java Servlets.

Example 4.1. web.xml

<?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.terminal.gwt.server.ApplicationServlet
    </servlet-class>
    <init-param>
      <param-name>application</param-name>
      <param-value>MyApplicationClass</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 name myservlet. The servlet class, com.vaadin.terminal.gwt.server.ApplicationServlet, is provided by Vaadin framework and it should be the same for all Vaadin projects. The servlet takes the class name Calc of the user application class as a parameter, including the full package path to the class. If the class is in the default package the package path is obviously not used.

The url-pattern is defined above as /*. This matches to any URL under the project context. We defined above the project context as myproject so the application URL will be http://localhost:8080/myproject/. If the project were to have multiple applications or servlets, they would have to be given different names to distinguish them. For example, url-pattern /myapp/* would match a URL such as http://localhost:8080/myproject/myapp/. Notice that the slash and the asterisk must be included at the end of the pattern.

Notice also that if the URL pattern is other than root /* (such as /myapp/*), you will also need to make a servlet mapping to /VAADIN/* (unless you are serving it statically as noted below). For example:

    ...
    <servlet-mapping>
        <servlet-name>myservlet</servlet-name>
        <url-pattern>/myurl/*</url-pattern>
    </servlet-mapping>
    <servlet-mapping>
        <servlet-name>myservlet</servlet-name>
        <url-pattern>/VAADIN/*</url-pattern>
    </servlet-mapping>

You do not have to provide the above /VAADIN/* mapping if you serve both the widget sets and (custom and default) themes statically in WebContent/VAADIN/ directory. The mapping simply allows serving them dynamically from the Vaadin JAR. Serving them statically is recommended for production environments as it is much faster.

For a complete example on how to deploy applications, see the demos included in the Vaadin installation package, especially the WebContent/WEB-INF directory.

Deployment Descriptor Parameters

Deployment descriptor can have many parameters and options that control the execution of a servlet. You can find a complete documentation of the deployment descriptor in Java Servlet Specification at http://java.sun.com/products/servlet/.

By default, Vaadin applications run in debug mode, which should be used during development. This enables various debugging features. For production use, you should have put in your web.xml the following parameter:

<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 detail in Section 11.4, “Debug and Production Mode”.

One often needed option is the session timeout. Different servlet containers use varying defaults for timeouts, such as 30 minutes for Apache Tomcat. You can set the timeout with:

<session-config>
    <session-timeout>30</session-timeout>
</session-config>

After the timeout expires, the close() method of the Application class will be called. You should implement it if you wish to handle timeout situations.