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

Vaadin applications are deployed as Java web applications. A Java "web application" 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 WAR (Web application ARchive) file, which can be deployed to a Java application server (or a servlet container to be exact).

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

Remember that, in the Java Servlet parlance, "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. Vaadin applications, on the other hand, 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 application as "WAR" in this book.

To deploy an application to a web server, you need to create a WAR package. Here we give the instructions for Eclipse.

  1. Select File → Export and then Web → WAR File. Or, right-click the project in the Project Explorer and select Web → WAR File.

  2. Select the Web project to export. Enter Destination file name (.war).

  3. Make any other settings in the dialog, and click Finish.

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.x.x.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 VAADIN/themes/themename directory.

Widget sets (OPTIONAL)

If your application uses a project-specific widget set, it must be compiled in the VAADIN/widgetset/ directory.

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>

If you have multiple servlets, you should specify only one /VAADIN/* mapping . It doesn't matter which servlet you map the pattern to, as long as it is a Vaadin servlet.

You do not have to provide the above /VAADIN/* mapping if you serve both the widget sets and (custom and default) themes statically in the 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 faster. If you serve the content from within the same web application, you may not have the root pattern /* for the Vaadin servlet, as then all the requests would be mapped to the servlet.

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

Prev Up Next
4.7. Handling Errors Home Chapter 5. User Interface Components