Configuring Tapestry

Tapestry runs on top of the standard Java Servlet API. To the servlet container, such as Tomcat, Tapestry appears as a servlet filter. This gives Tapestry great flexibility in matching URLs without requiring lots of XML configuration.

Contents

Changes to web.xml

Tapestry applications are configured almost entirely using Java, not XML. However, a small but necessary amount of configuration occurs inside the servlet deployment descriptor, WEB-INF/web.xml. Most of the configuration is boilerplate, nearly the same for all applications.

<!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 Tapestry Application</display-name>
    <context-param>
        <param-name>tapestry.app-package</param-name>
        <param-value>org.example.myapp</param-value>
    </context-param>
    <filter>
        <filter-name>app</filter-name>
        <filter-class>org.apache.tapestry5.TapestryFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>app</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

The application-specific part, the tapestry.app-package context parameter, provides your application's root package name. Tapestry uses this to locate your page and component classes. It expects page classes in the pages sub-package and components in the components sub-package. In the example above, page classes will be stored in the org.example.myapp.pages package (or in sub-packages below). Likewise, component classes will be stored in the org.example.myapp.components package.

By convention, the filter name (filter-name) is almost always "app", but you can use any name you want. Tapestry uses this to determine what module class name to look for (see below).

Your Application's Module Class

Main Article: Tapestry IoC Configuration

Most other configuration occurs inside your application's module class. The application module class will often define new services, provide overrides of services, or make contributions to service configurations.

Tapestry looks for your application module class in the services package (under the root package) of your application. It capitalizes the <filter-name> and appends "Module". In the previous example, because the filter name was "app" and the application's root package name is "org.example.myapp", the module class would be org.example.myapp.services.AppModule.

If such a class exists, it is added to the IoC Registry. It is not an error for your application to not have a module class, though any non-trivial application will have one.

Your application module class (usually AppModule.java) will typically override some of Tapestry's default, or "factory", symbols, by contributing overrides to the ApplicationDefaults service configuration. For example:

public class AppModule
{
  public static void contributeApplicationDefaults(MappedConfiguration<String,String> configuration)
  {
    configuration.add(SymbolConstants.SUPPORTED_LOCALES, "en,fr,de");
    configuration.add(SymbolConstants.FILE_CHECK_INTERVAL, "10 m");
  }
}

Configuration Symbol Names

Main Article: Symbols

Many of Tapestry's built-in services (some of which are not even public) are configured via symbols. These symbols can be overridden by contributing to the ApplicationDefaults service configuration, or by placing a <context-param> element into the application's web.xml, or on the command line by defining JVM System Properties with the -D command line option.

These symbols are always defined in terms of strings, and those strings are coerced to the appropriate type (a number, a boolean, etc.). Of special note are time intervals, which are specified in a particular format.

Each of these symbols has a corresponding constant defined in the SymbolConstants class.

tapestry.app-catalog

The location of the global application message catalog, the default is context:WEB-INF/app-name.properties.

tapestry.application-version

The version of the application, which is incorporated into URLs for context and classpath assets. Assets may be compressed, and will have far-future expiration headers; they will be aggressively cached by the client web browser. You should change the application version on each new deployment of the application (that is, any time assets in the context change), to force clients to re-download changed versions of files. If you do not specify an application version, a random one will be assigned on every deployment (which is good for development but very bad for production).

tapestry.application-folder

The folder, of the context, in which the Tapestry application executes. By default this is blank, meaning the Tapestry application executes in the root of the web application context. Setting this value allows the Tapestry application to be segregated into a folder, which can be useful when Tapestry is executed inside a web application with other servlets or filters.

tapestry.asset-url-fully-qualified

A boolean value to indicate whether asset URLs should be fully qualified in the rendered page.
This defaults to false (not fully qualified).

tapestry.asset-path-prefix

The prefix to be used for all asset paths. This should start and end with a slash ("/"). By default this is "/assets/".

tapestry.blackbird-enabled

A flag (true or false). When "false" the Blackbird JavaScript console will be disabled (in Tapestry 5.2 and newer). Defaults to "true".

tapestry.charset

The character encoding used when generating output (or parsing input). The default is "UTF-8". See Content Type and Markup for more details.

tapestry.combine-scripts

If "true", then Tapestry will combine (or "aggregate") the individual JavaScript libraries within a JavaScript stack; this reduces the number of requests from the client to the server, as the client can cache the combined JavaScript files locally (and will not need to
re-download them on subsequent pages). The implementation of this changed significantly between Tapestry 5.1 and 5.2.

Defaults to "true" in production mode.

tapestry.compatibility.unknown-component-id-check-enabled

When enabled, Tapestry will check that component ids referenced in event handler method names (or the @OnEvent annotation) match up against components in the container's template. The default is true, but applications upgraded form Tapestry 5.2 may want to set this to false, to keep pages from failing due to the presence of such dead code.

tapestry.component-render-tracing-enabled

Starting with version 5.3, if "true" then Tapestry will emit rendering comments for all requests; these are comments (such as <!--BEGIN Index:loop (context:Index.tml, line 15)-->) that can assist you in debugging markup output on the client-side. This will significantly increase the size of the rendered markup, but can be very helpful with complex layouts to determine which component was responsible for which portion of the rendered page. (To turn on rendering comments only for a particular request, add the query parameter t:component-trace=true to the URL.)

tapestry.compress-whitespace

A flag (true or false). When true (the default) whitespace in component templates is compressed by default (this can be fine-tuned using the standard xml:space attribute on an element in the template). When this flag is false, then whitespace is retained by default (but can still be overridden).

tapestry.default-cookie-max-age

The default time interval that cookies created by Tapestry will be kept in the client web browser. Primarily, this is used with a cookie that exists to track the preferred user locale. The default value is "7 d" (7 days; see Time Interval Formats).

tapestry.default-stylesheet

The default stylesheet automatically injected into every rendered HTML page. Many Tapestry components assume that this stylesheet is available. All the classes defined in the stylesheet are prefixed with "t-". The exact contents of the stylesheet are subject to change at any time (they are considered internal), so replacing the stylesheet, rather than overriding selected rules within it, entails some risk.

The default is org/apache/tapestry5/default.css, stored on the classpath.

tapestry.exception-report-page

The name of the page used to report exceptions. This defaults to "ExceptionReport".

tapestry.execution-mode

The execution mode. See Setting Execution Modes below.

tapestry.file-check-interval

Time interval between file system checks. During a file system check, only a single thread is active (all others are blocked) and any files loaded are checked for changes (this is part of automatic component reloading).

The default is "1 s" (one second; see Time Interval Formats), and is usually overridden with a higher value in production (say, between one and five minutes).

tapestry.file-check-update-timeout

Time interval that Tapestry will wait to obtain the exclusive lock needed for a file check. If the exclusive lock can't be obtained in that amount of time, the request will proceed normally (without the check), but each successive request will attempt to get the lock and perform the check until successful.

The default is "50 ms" (50 milliseconds; see Time Interval Formats).

tapestry.force-absolute-uris

For Tapestry 5.0 and 5.1 only: when false (the default), Tapestry will attempt to optimize URIs that it generates, using relative URIs when such URIs are shorter than absolute URIs. When true, all URIs will be absolute URIs (including the context path, and the complete path for the request).

tapestry.gzip-compression-enabled

Override to "false" to disable GZIP compression of dynamic Tapestry pages and static assets.

tapestry.hmac-passphrase

The plaintext phrase used to set the key for HMAC securing of serialized object data. The default is blank, which causes a runtime alert and console error. You should set this to a reasonably unique, private value, and ensure (in a cluster) that all servers use the same value – typically by making a contribution in your applications module class (normally AppModule.java).

tapestry.min-gzip-size

The minimum stream size necessary for Tapestry to use GZIP compression on the response stream. See Response Compression for more details.

tapestry.omit-generator-meta

If "true", then the <meta> tag that Tapestry normally writes into the <head>, identifying the Tapestry version, will be omitted. Use this when you do not wish to advertise your application's use of Tapestry.

tapestry.page-pool.active-window

The time interval that an instantiated page instance may be cached before being removed. As pages are returned to the pool, they are time stamped. Periodically (as per the file check interval), the pool is scanned for page instances that have not been used recently; those that are outside the active window are discarded. This is used to free up unnecessary page instances after a request surge. Starting in 5.2, this is only effective if tapestry.page-pool-enabled is true.

The default is "10 m" (10 minutes; see Time Interval Formats).

tapestry.page-pool-enabled

Starting with Tapestry 5.2, page pooling has been turned off by default. This symbol lets you re-enable page pooling. Under most circumstances this symbol should not be set. The disabling of page pooling starting in 5.2 significantly reduces heap memory usage and improves performance for most web applications.

The default is "false".

tapestry.page-pool.hard-limit

The absolute maximum number of page instances (for a particular page name / locale combination) that Tapestry will create at any time. If this number is reached, then requests will fail because a page instance is not available ... this can happen as part of a denial of service attack. For this value to have any meaning, it should be lower than the number of threads that the servlet container is configured to use when processing requests.

The default is 20 page instances.

tapestry.page-pool.soft-limit

The number of pages in the page pool (for a given page name / locale combination) before which Tapestry will start to wait for existing pages to be made available. Under this limit of pages, Tapestry will simply create a new page instance if no existing instance is readily available. Once the soft limit is reached, Tapestry will wait a short period of time (the soft wait interval) to see if an existing page instance is made available. It will then create a new page instance (unless the hard limit has been reached).

The default is 5 page instances. Remember that page pooling is done separately for each page (and localization of the page).

tapestry.page-pool.soft-wait

The time interval that Tapestry will wait for a page instance to become available before deciding whether to create an entirely new page instance.

The default is "10 ms" (10 milliseconds; see Time Interval Formats).

tapestry.production-mode

A flag (true or false) indicating whether the application is running in production or in development. The default is true, which means that runtime exceptions are not reported with full detail (only the root exception message is displayed, not the entire stack of exceptions, properties and other information shown in development mode).

tapestry.secure-enabled

If true, then @Secure annotation is honored; if false, no security checks or redirects take place. This defaults to tapestry.production-mode, meaning that in development mode it will (by default) be disabled.

tapestry.secure-page

If true, then the page may only be accessed via HTTPS. The @Secure annotation will set this value to true. This symbol is the default for all pages; set it to "true" to force the entire application to be secure.

tapestry.service-reloading-enabled

If true (the default), then Tapestry IoC will attempt to reload service implementations when they change. This only applies to classes that Tapestry IoC instantiates itself, and have a known service interface (the container creates a proxy that, internally, can reload the implementation). Service reloading only works when the underlying class files are on the filesystem ... it is intended for development, not an option at deployment.

This must be specified as a JVM system property.

tapestry.scriptaculous

The path to the embedded copy of script.aculo.us packaged with Tapestry. This value may be overridden to use a different version of the script.aculo.us library. See JavaScript for the default version.

tapestry.session-locking-enabled

If true (the default), then Tapestry will use a lock when reading/updating HttpSession attributes, to avoid simultaneous access by multiple threads when using AJAX. See TAP5-2049. Set to false to deactivate the session locking logic.

Prior to version 5.4 session locking was not performed.

tapestry.start-page-name

The logical name of the start page, the page that is rendered for the root URL. This is normally "start". This functionality is vestigial: it has been superseded by the use of Index pages.

tapestry.supported-locales

A comma-separated list of supported locales. Incoming requests as "narrowed" to one of these locales, based on closest match. If no match can be found, the first locale in the list is treated as the default.

The default is (currently) "en,it,es,zh_CN,pt_PT,de,ru,hr,fi_FI,sv_SE,fr_FR,da,pt_BR,ja,el". As the community contributes new localizations of the necessary messages files, this list will expand. Note that the Tapestry quickstart archetype overrides the factory default, forcing the application to be localized only for "en".

tapestry.suppress-redirect-from-action-requests

Normally, Tapestry responds to action requests (such as form submissions) by sending a client-side redirect to the rendering page. This has a lot of benefits in terms of improving browser navigation, making sure URLs are bookmarkable, and so forth. However, it has a cost: more data stored persistently in the session, and a double-request for each user action (one action request, one render request).

Setting this symbol to "true" changes the Tapestry behavior to make it more like Tapestry 4: a markup response is sent directly for the action request, with no redirect in the middle. This option should be used with care, and only in cases where you are certain that the benefits outweigh the disadvantages.

tapestry.thread-pool.core-pool-size

Nominal size of the thread pool Tapestry uses to execute tasks in parallel. Under sufficient load, the thread pool may grow larger than this core size. Defaults to 3.

tapestry.thread-pool.max-pool-size

Maximum size of the thread pool Tapestry uses to execute tasks in parallel. Defaults to 10.

tapestry.thread-pool.queue-size

Size of the task queue for the thread pool. Once the core pool size is reached, new threads are not created until the queue is full. The default queue size is 100.

tapestry.thread-pool.keep-alive

The time to keep a created but unused thread in the pool alive. Defaults to one minute.

tapestry.thread-pool-enabled

If set to false, then parallel task execution does not occur. This is useful in environments where it is not allowed to create new threads, such as Google App Engine.

Setting Component Parameter Defaults

configuration.add(ComponentParameterConstants.GRID_ROWS_PER_PAGE, "15");

See the complete list of such constants at ComponentParameterConstants.

Configuring Ignored Paths

You may sometimes need to use Tapestry in concert with other servlets. This can cause problems, since Tapestry (being a servlet filter) may see URLs intended for another servlet and attempt to process them.

The Servlet API does not provide Tapestry with any clues about what other servlets are available in the web application. Instead, you must configure Tapestry to ignore paths intended for other servlets.

The IgnoredPathsFilter service is the method for this kind of configuration. Its configuration is an unordered collection of regular expression patterns. A request whose path matches any of these patterns is not processed by Tapestry.

For example, say you are using Direct Web Remoting. You'll likely have the servlet path /dwr mapped to the Direct Web Remoting servlet.

You contribution would look like:

  public static void contributeIgnoredPathsFilter(Configuration<String> configuration)
  {
    configuration.add("/dwr/.*");
  }

The regular expression matches any path that begins with "/dwr/".

The regular expressions provided in the configuration are always compiled with case insensitivity enabled.

Also note that actual files in your web application (images, stylesheets, etc.) are always ignored by Tapestry.

Configuring Content Type Mapping

The mapping from file type (by extension) to content type is typically done as part of your servlet-containers configuration. Alternately, you may contribute to the ResourceStreamer service's configuration. This is a mapped configuration; it maps file extensions (such as "css" or "js") to content types ("text/css" or "text/javascript") respectively.

Setting Execution Modes

Starting with Tapestry 5.2.4, we can specify an execution mode by loading specific Tapestry Modules through a JVM System property. All modules declared in this way will be loaded after the AppModule of your application. This feature is very useful for defining a different environment for Production and Development modes, for example.

This JVM System property, named tapestry.execution-mode, is a comma-separated list of mode names. You can declare this property in a number of different ways:

1. Add the parameter to your JVM command line:

-Dtapestry.execution-mode=DevelopmentMode jetty:run

2. Add the parameter to the Jetty plugin:

<plugin>
    <groupId>org.mortbay.jetty</groupId>
    <artifactId>maven-jetty-plugin</artifactId>
    <version>6.1.16</version>
    <configuration>
        <requestLog implementation="org.mortbay.jetty.NCSARequestLog">
            <append>true</append>
        </requestLog>
        <systemProperties>
	    <systemProperty>
	        <name>tapestry.execution-mode</name>
	        <value>DevelopmentMode</value>
	    </systemProperty>
        </systemProperties>
    </configuration>
</plugin>

3. Add the parameter to the Surfire plugin for your test:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>2.8.1</version>
    <configuration>
       <systemPropertyVariables>
         <tapestry.execution-mode>DevelopmentMode</tapestry.execution-mode>
       </systemPropertyVariables>
    </configuration>
</plugin>

For each mode declared in your JVM System Property, TapestryFilter checks for a parameter in your web.xml, named tapestry.TheModeName-modules, with TheModeName being the name of the desired mode. Its value will be a comma-separated list of modules.

If the tapestry.execution-mode is not declared, Tapestry will automatically look for the tapestry.production-modules parameter, because “production” is the default tapestry.execution-mode value.

The example below defines two differents execution modes in your web.xml file: production (the default value) and DevelopmentMode. For each mode, we list the modules we want to load. If we use JVM System property declared in the example above, the DevelopmentModeModule module will be loaded.

<context-param>
    <param-name>tapestry.production-modules</param-name>
    <param-value>org.apache.tapestry.appli.services.ProductionModeModule</param-value>
</context-param>
<context-param>
    <param-name>tapestry.DevelopmentMode-modules</param-name>
    <param-value>org.apache.tapestry.appli.services.DevelopmentModeModule</param-value>
</context-param>

Tapestry will load modules in the order that they are declared. For example, if we run the following command line:

-Dtapestry.execution-mode=DevelopmentMode,DevelopmentMode2 jetty:run

and then for each modes we have two modules:

<context-param>
      <param-name>tapestry.DevelopmentMode-modules</param-name>
      <param-value>
          org.apache.tapestry.appli.services.DevelopmentMode1Module1,
          org.apache.tapestry.appli.services.DevelopmentMode1Module2
      </param-value>
</context-param>
<context-param>
      <param-name>tapestry.DevelopmentMode2-modules</param-name>
      <param-value>
          org.apache.tapestry.appli.services.DevelopmentMode2Module1,
          org.apache.tapestry.appli.services.DevelopmentMode2Module2
      </param-value>
</context-param>

then Tapestry will load modules in the order: DevelopmentMode1Module1, DevelopmentMode1Module2, DevelopmentMode2Module1 and DevelopmentMode2Module2

Segregating Applications Into Folders

In many cases where Tapestry is being adopted into an existing web application (possibly written in Tapestry 4 or some other framework), it is nice to segregate the Tapestry application into its own folder, to avoid conflicts with the existing application or servlets.

Setting this up is in two parts:

• Modifying the configuration of the <url-pattern> for the Tapestry filter to match the specified folder.
• Identifying the folder name using a Tapestry symbol value contribution.

So, if you wanted to run the Tapestry application inside folder t5app, you would modify your web.xml indicate the use of the folder:

  <filter-mapping>
    <filter-name>app</filter-name>
    <url-pattern>/t5app/*</url-pattern>
  </filter-mapping>

... and in your AppModule, you would inform Tapestry about the mapping change:

public class AppModule
{
    @Contribute(SymbolProvider.class)
    @ApplicationDefaults
    public static void applicationDefaults(MappedConfiguration<String, String> configuration)
    {
        configuration.add(SymbolConstants.APPLICATION_FOLDER, "t5app")
    }
}

This changes the servlet container to only forward requests inside the t5app folder to Tapestry; requests for other folders (or the root folder) will not be passed to Tapestry at all. The symbol contribution informs Tapestry to change the URLs it generates to include the necessary folder name; it also affects the logic in Tapestry that recognizes and handles requests.

In addition, if you choose to place page template files in the context, rather than on the classpath (as with component templates), then you will place those template files inside the t5app folder.

At this time, it is still not possible to run multiple Tapestry 5 applications within the same web application.