Web deployment descriptor

Web deployment descriptor
	Chapter 5. Configuring Tapestry

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

Example 5.1. Web Deployment Descriptor

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
 "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <distributable/> 
  <display-name>My Application</display-name>
  <servlet>
    <servlet-name>myapp</servlet-name> 
    <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class> 
    <load-on-startup>0</load-on-startup> 
  </servlet>
  
  <servlet-mapping>
    <servlet-name>myapp</servlet-name>
    <url-pattern>/app</url-pattern> 
  </servlet-mapping>
  
  <filter> 
    <filter-name>redirect</filter-name>
    <filter-class>org.apache.tapestry.RedirectFilter</filter-class>
  </filter>
	
  <filter-mapping>
    <filter-name>redirect</filter-name>
    <url-pattern>/</url-pattern>
  </filter-mapping>

  <session-config>
  	<session-timeout>15</session-timeout>
  </session-config>
    
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
</web-app>

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.

	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.

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

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.

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.

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.

This filter sends a client redirect to the user when they access the web application context. The filter sends a client redirect to the user's browser, directing them to the application servlet. In this way, the "public" URL for an application can be http://myserver/mycontext/ when, in fact, the real address is http://myserver/mycontext/app.

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:

On the classpath, as defined by the org.apache.tapestry.application-specification configuration parameter.
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.
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. This is perfectly acceptible ... an application specification is typically needed only when an application makes use of component libraries, or requires some other kind of customization only possible with an application specification.


Requirements		Configuration Search Path