Configuring Tapestry


Configuration is the area of greatest change between Tapestry 3.0 and Tapestry 4.0. Tapestry 4.0 has been restructured around HiveMind , which includes a very rich environment for services and configurations.

Tapestry is designed to operate on a variety of different JVMs and versions of the Java Servlet API. Below you can find the list of supported and tested configurations:

Java 1.4.x
Operates correctly.
Java 1.5.x (recommended)
Operates correctly. Annotation-configuration can be used.
Java 1.6.x
Operates correctly.

Supported Java Servlet API Versions:

Java Servlet API 2.2
Operates correctly with minor exceptions related to character encoding of the requests due to the limitations of the Servlet API version.
Java Servlet API 2.3 (recommended)
Operates correctly.

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


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

Property Sources

Tapestry occasionally must obtain a value for a configuration property. These configuration properties are items that are frequently optional, and don't fit into any particular specification. Many are related to the runtime environment, such as which class to instantiate as the Visit object. Tapestry is very flexible about where values for such properties may be obtained. There are three kinds of property sources with different search paths which are used in different contexts; these are: global, application and component property sources. In general, the search path for configuration properties is:
  • 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.
It is expected that some configuration properties are not defined at any level; those will return null. Applications are free to leverage this lookup mechanism as well. Within the framework the following three services provide access to properties from the above-mentioned sources:
  • 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.
Applications may also want to change or augment the default search path; this is accomplished by
  1. writing a HiveMind service implementing the interface IPropertySource
  2. contributing it to the tapestry.props.ApplicationPropertySource configuration point
. For example, some configuration data could be drawn from a database.

Global Property Source

In some cases, a slightly different property source is used, the 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

The following are all the configuration values currently used in Tapestry:
Property Default Value Description
org.apache.tapestry.accepted-locales any/all Controls which locales are supported by the application; see the documentation on limiting accepted locales for details.
org.apache.tapestry.bean-class-packages A comma-seperated list, used when converting class names for managed beans (specified using the <bean> element) into fully qualified class names. This property is specified in the containing library or application specification.
org.apache.tapestry.component-class-packages A comma-seperated list of package names, used when searching for the component class . These must appear as <meta> tags in the application or library specification containing the component
org.apache.tapestry.default-binding-prefix ognl The default binding to use when no explicit binding prefix is provided. This is typically set inside a page or component specification, or within an application specification or library specification (to provide the default for all pages and components). If not otherwise specified, the default binding prefix is "ognl".
org.apache.tapestry.default-cookie-max-age 6123600 The default max age (in seconds) for cookies written by Tapestry, including the cookie used to track the user's locale. A value of -1 means the cookie is a session cookie, stored only until the user's browser exits. The default value is equivalent to one week.
org.apache.tapestry.default-property-persistence-strategy session The default property persistence strategy to use for page properties annotated with @Persist. The default is "session", which stores the properties in the HttpSession as a session attribute. Tapestry also provides a "client" strategy and additional strategies can be defined.
org.apache.tapestry.application-specification The alternate application specification path. This must be given as a servlet context parameter in your web.xml and must point to a resource in your applications classpath.
org.apache.tapestry.namespace-properties-name When specified in an application/library/page/component specification provides an alternate name to resolve .properties files. The default name is the name of the application/library/page/component specification file with .properties added onto it.

Example, change default global properties file to be instead of the typical default of
<application name="MyApplication">

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

org.apache.tapestry.default-page-class org.apache.tapestry. html.BasePage By default, any page that omits the class attribute (in its <page-specification> ) will be instantiated as BasePage . If this is not desired, the default may be overridden by specifying a fully qualified class name.
org.apache.tapestry.disable-caching false If specified (as "true"), then the framework will discard all cached data (specifications, templates, pooled objects, etc.) at the end of each request cycle. This slows down request handling by a noticable amount, but is very useful in development; it means that changes to templates and specifications are immediately visible to the application. It also helps identify any errors in managing persistent page state. This should never be enabled in production; the performance hit is too large. Unlike most other configuration values, this must be specified as a JVM system property.
org.apache.tapestry.enable-reset-service false If not specified as "true", then the reset service will be non-functional. The reset service is used to force the running Tapestry application to discard all cached data (including templates, specifications, pooled objects and more). This must be explicitly enabled, and should only be used in development (in production, it is too easily exploited as a denial of service attack). Unlike most other configuration values, this must be specified as a JVM system property.
org.apache.tapestry.engine-class org.apache.tapestry. engine.BaseEngine The fully qualified class name to instantiate as the application engine. This configuration value is only used when the application specification does not exist, or fails to specify a class. By default, BaseEngine is used if this configuration value is also left unspecified.
org.apache.tapestry.enhance. disable-abstract-method-validation false Used to trigger a work around for a bug in IBM's JDK 1.4.0. This particular JDK reports all methods of an abstract class as abstract, even if they are, in fact, concrete. This causes spurious errors about unimplemented abstract methods. Specifying true for this property disables checks for unimplemented abstract methods. Warning: Support for this property has been temporarily removed from release 4.0. java.util.HashMap The fully qualified class name to instantiate as the engine global property. The Global object is much like Visit object, except that it is shared by all instances of the application engine rather than being private to any particular session. If not specified, a synchronized instance of HashMap is used.
org.apache.tapestry.home-page Home The name of the page to be displayed by the home engine service (that is, the page initially displayed when there's no other information in the request URL). The default is "Home".
org.apache.tapestry.jwcid-attribute-name jwcid Controls the attribute used to recognize the locations of contained components within a component template . The default is "jwcid".
org.apache.tapestry.messages-encoding ISO-8859-1 Defines the character set used when reading the properties files comprising a page or component message catalog . The default value is ISO-8859-1. Please see the message catalog localization discussion for more information.
org.apache.tapestry.output-encoding UTF-8 Defines the character set used by the application to encode its HTTP responses. This is also the character set that the application assumes that the browser uses when submitting data unless it is not specified differently in the HTTP request. The default for this configuration property is UTF-8. Normally there is no need to modify this value since UTF-8 allows almost all characters to be correctly encoded and displayed. A comma-seperated list of package names, used when searching for the page class . These must appear as <meta> tags in the application or library specification containing the page.
org.apache.tapestry.servlet-path /app Defines the servlet path used when constructing URLs. The default value is /app . Note that this is just the servlet path . In many cases, the application will be inside a context; Tapestry will automatically prefix this value with the correct value for the context. For example, workbench.war will by default be deployed with a context path of /workbench, and Tapestry will build URLs as /workbench/app.
org.apache.tapestry.template-encoding ISO-8859-1 Defines the character set used by the application templates. The default value is ISO-8859-1. Please see the template localization discussion for more information.
org.apache.tapestry.template-extension html Overrides the default extension used to locate templates for pages or components. The default extension is "html", this configuration property allows overrides where appropriate. For example, an application that produces WML may want to override this to "wml".

This configuration property does not follow the normal search path rules. The <meta> must be provided in the <page-specification> or <component-specification> . If no value is found there, the immediate containing <application> or <library-specification> is checked. If still not found, the default is used.

org.apache.tapestry.607-patch false A workaround for TAPESTRY-607 , a problem related to response character sets when using some versions of Tomcat 5. The Tomcat bug is 37072 . This patch ensures that HttpServletResponse.setContentType() is only invoked once, even if the output is reset (for instance, to switch to the Tapestry exception page). The value must be set to true as a JVM system property.
org.apache.tapestry.visit-class java.util.HashMap The fully qualified class name to instantiate as the Visit object .

If not specified, an instance of HashMap will be created.

This is something of a holdover from Tapestry 3.0; for Tapestry 4.0, you will likely want to override the default visit application state object (or simply add your own application state objects).

org.apache.tapestry.renderTags true Whether or not some block level components will render their template tag names by default.

This currently affects the If, Else and For components.

For example, with the default value of true - the following h2 element tag would be printed out literally as specified:

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

Application extensions


Application extensions are deprecated as of release 4.0. The use of HiveMind services and contributions eliminates the need for 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.

Extension Name Type Description IPropertySource This extension is fit into the configuration property search path, after the servlet context, but before JVM system properties. A typical use would be to access some set of configuration properties stored in a database.
org.apache.tapestry.request-decoder IRequestDecoder A request decoder is used to identify the actual server name, server port, scheme and request URI for the request. In some configurations, a firewall may invalidate the values provided by the actual HttpServletRequest (the values reflect the internal server forwarded to by the firewall, not the actual values used by the external client). A request decoder knows how to determine the actual values.
org.apache.tapestry.monitor-factory IMonitorFactory An object that is used to create IMonitor instances. Monitors are informed about key application events (such as loading a page) during the processing of a request.

The factory may create a new instance for the request, or may simply provide access to a shared instance.

If not specified, a default implementation is used ( DefaultMonitorFactory ).

org.apache.tapestry. specification-resolver-delegate ISpecificationResolverDelegate An object which is used to find page and component specifications that are not located using the default search rules. The use of this is open-ended, but is generally useful in very advanced scenarios where specifications are stored externally (perhaps in a database), or constructed on the fly.
org.apache.tapestry. template-source-delegate ITemplateSourceDelegate An object which is used to find page or component templates that are not located using the default search rules. The use of this is open-ended, but is generally useful in very advanced scenarios where templates are stored externally (perhaps in a database), or constructed on the fly.
org.apache.tapestry.ognl-type-converter ognl.TypeConverter Specifies an implementation of ognl.TypeConverter to be used for expression bindings. See OGNL's Type Converter documentation for further information on implementing a custom type converter.