Web deployment descriptor

All Tapestry applications make use of the ApplicationServlet class as their servlet; it is rarely necessary to create a subclass.

Example 5.1. Virtual Library Deployment Descriptor

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
 "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">
<web-app>
  <distributable/> 1
  <display-name>My Application</display-name>
  <servlet>
    <servlet-name>myapp</servlet-name> 2
    <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class> 3
    <load-on-startup>0</load-on-startup> 4
  </servlet>
  
  <!-- The single mapping used for the Virtual Library application -->

  <servlet-mapping>
    <servlet-name>myapp</servlet-name>
    <url-pattern>/app</url-pattern> 5
  </servlet-mapping>
  
  <session-config>
  	<session-timeout>15</session-timeout>
  </session-config>
    
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
</web-app>
1

This indicates to the application server that the Tapestry application may be clustered. Most application servers ignore this element, but future servers may only distribute applications within a cluster if this element is present.

[Warning]JBoss is very literal!
JBoss 3.0.x appears to be very literal about the <distributable> element. If it appears, you had better be deploying into a clustered environment, otherwise HttpSession state management simply doesn't work.
2

The servlet name may be used when locating the application specification (though not in this example).

3

The servlet class is nearly always ApplicationServlet. There's rarely a need to create a subclass; Tapestry has many other hooks for extending the application.

4

It is generally a good idea to specify <load-on-startup>, this causes the servlet container to instantitate and initialize the the application servlet, which in turn, reads the Tapestry application specification. Many common development errors will be spotted immediately, rather than when the first application request arrives.

5

The servlet is mapped to /app within the context. The context itself has a path, determined by the application server and based on the name of the WAR file. The client web browser will see the Tapestry application as http://host/war-name/app.

Using /app as the URL is a common convention when creating Tapestry applications, but is not a requirement. The framework will adapt to whatever mapping you select.

On initialization, the Tapestry servlet will locate its application specification; a file that identifies details about the application, the pages and components within it, and any component libraries it uses. Tapestry provides a great deal of flexibility on where the specification is stored; trivial Tapestry applications can operate without an application specification.

The specification is normally stored under WEB-INF. In fact, Tapestry performs a search to find the specification:

  1. On the classpath, as defined by the org.apache.tapestry.application-specification configuration parameter.

  2. As /WEB-INF/name/name.application. The name is the servlet name. This location is only used in the rare case of a single WAR containing multiple Tapestry applications.

  3. As /WEB-INF/name.application. Again, name is the servlet name. This is the standard location.

If the application specification still can not be found, then an empty, "stand in" application specification is used.