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:
Supported Java Servlet API Versions:
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
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:
|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.|
When specified in an application/library/page/component specification provides an alternate
name to resolve
Example, change default global properties file to be Global.properties instead of the typical default of
<application name="MyApplication"> <meta key="org.apache.tapestry.namespace-properties-name" value="Global" /> </application>
|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.|
|org.apache.tapestry.global-class||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.|
|org.apache.tapestry.page-class-packages||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.|
Defines the servlet path used when constructing URLs. The default value is
|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.|
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.|
The fully qualified class name to instantiate as the
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).
Whether or not some block level components will render their template
tag names by default.
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 </h2>
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.
|org.apache.tapestry.property-source||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.|
An object that is used to create
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.|