Web Deployment Descriptor

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

Example 4.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>Tapestry Virtual Library Demo</display-name>
  <servlet>
    <servlet-name>vlib</servlet-name> 2
    <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class> 3
    <init-param>
    	<param-name>org.apache.tapestry.application-specification</param-name> 4
    	<param-value>/net/sf/tapestry/vlib/Vlib.application</param-value>
    </init-param>
    <load-on-startup>0</load-on-startup>
  </servlet>
  
  <!-- The single mapping used for the Virtual Library application -->

  <servlet-mapping>
    <servlet-name>vlib</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

The Virtual Library application stores its specification on the classpath, rather than under WEB-INF, so it is necessary to provide the complete path to the specification. Most applications can omit this <init-param>.

5

The servlet is mapped to /app within the context. The context itself has a path, determined by the application server, but typically /vlib. The client web browser will see the Tapestry application as http://host/vlib/app.

Using /app as the URL is a common convention when creating Tapestry applications, but is not a requirement.

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.

Prior to release 3.0, application specifications had to be stored on the classpath. This is maintained for backwards compatibility. In modern applications, the specification is 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 scenario.

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