Web deployment descriptor

All Tapestry applications make use of the ApplicationServlet class as their servlet; it is rarely necessary to create a subclass. A typical web.xml configuration maps the servlet to the /app path, and adds a servlet filter (discussed shortly):

<?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>
  <display-name>My Application</display-name>
  
  <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>

  <servlet>
    <servlet-name>myapp</servlet-name>
    <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class> 
    <load-on-startup>0</load-on-startup>
  </servlet>
  
  <session-config>
  	<session-timeout>15</session-timeout>
  </session-config>
    
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
  </welcome-file-list>
</web-app>

The servlet class should always be 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. If you choose an alternate URL, you must override the org.apache.tapestry.servlet-path configuration property.

The RedirectFilter 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.

Since Tapestry 4.0, the application specification is complemented and greatly extended by the HiveMind configurations.

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 property .
• 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.

Property Sources

• As a <meta> of the <application> (in the application specification, if the application uses one).
• As an <init-parameter> for the servlet, in the web application deployment descriptor.
• As an <init-parameter> for the servlet context, also in the web application deployment descriptor.
• As a JVM system property.
• Hard-coded "factory" defaults (for some properties). These are accessed as HiveMind symbols.

• The ComponentPropertySource serves the need of components, looking up properties starting at component-spec-level and working its way upwards
• The ApplicationPropertySource provides access to application-scoped properties where "application" means tapestry application as opposed to web application (see next item).
• The GlobalPropertySource provides access to much the same properties as the ApplicationPropertySource omitting the application-specification itself since there might be multiple tapestry applications living within the same web application.

1. writing a HiveMind service implementing the interface IPropertySource
2. contributing it to the tapestry.props.ApplicationPropertySource configuration point

Global Property Source

• As an <init-parameter> for the servlet, in the web application deployment descriptor.
• As an <init-parameter> for the servlet context, also in the web application deployment descriptor.
• As a JVM system property.
• Hard-coded "factory" defaults (for some properties). These are accessed as HiveMind symbols.

Configuration Properties

<application name="MyApplication">

<meta key="org.apache.tapestry.namespace-properties-name"
  value="Global" />

</application>

<h2 jwcid="@If" condition="true">
This is a header
</h2>

Application extensions

Tapestry is designed for flexibility; this extends beyond simply configuring the framework, and encompasses actually replacing or augmenting the implementation of the framework. If Tapestry doesn't do what you want it to, there are multiple paths for extending, changing and overriding its normal behavior. In some cases, it is necessary to subclass framework classes in order to alter behavior, but in many cases, it is possible to use an application extension.

Application extensions are JavaBeans declared in the application specification using the <extension> element. Each extension consists of a name, a Java class to instantiate, and an optional configuration (that is, properties of the bean may be set). The framework has a finite number of extension points. If an extension bean with the correct name exists, it will be used at that extension point.

Your application may have its own set of extensions not related to Tapestry framework extension points. For example, you might have an application extension referenced from multiple pages to perform common operations such as JNDI lookups.

You may access application extensions via the engine's specification property. For example:

IEngine engine = getEngine();
IApplicationSpecification specification = engine.getSpecification();
	
MyExtension myExtension = (MyExtension) specification.getExtension("myExtension");	

Each application extension used with an framework extension point must implement an interface particular to the extension point.