tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Configuration
Date Sat, 02 Jul 2011 19:43:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/12/_/styles/combined.css?spaceKey=TAPESTRY&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Configuration">Configuration</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~hlship">Howard
M. Lewis Ship</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >A flag (true or false). When &quot;false&quot;
the Blackbird javascript console will be disabled (in Tapestry 5.2 and newer).  Defaults to
&quot;true&quot;. <br> <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{deprecated:since=5.3}The
client-side BlackBird console has been removed.{deprecated} <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. tapestry.charset <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <div class='navmenu' style='float:right; background:#eee; margin:3px; padding:3px'><table
class="tableview" width="100%">
            <tr><th style="padding: 3px 3px 3px 0px">Related Articles</th></tr>
                        <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/IoC+cookbook+-+Service+Configurations">IoC
cookbook - Service Configurations</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Tapestry+IoC+Configuration">Tapestry
IoC Configuration</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Application+Module+Class+Cheat+Sheet">Application
Module Class Cheat Sheet</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Symbols">Symbols</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Response+Compression">Response
Compression</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title=Page>Page:</span>
                         <a href="/confluence/display/TAPESTRY/Configuration">Configuration</a>
        
                                            </td>
        </tr>
            </table>
</div>

<h1><a name="Configuration-ConfiguringTapestry"></a>Configuring Tapestry</h1>

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

<p><b>Contents</b></p>
<div>
<ul>
    <li><a href='#Configuration-Changestoweb.xml'>Changes to web.xml</a></li>
    <li><a href='#Configuration-YourApplication%27sModuleClass'>Your Application's
Module Class</a></li>
    <li><a href='#Configuration-ConfigurationSymbolNames'>Configuration Symbol
Names</a></li>
    <li><a href='#Configuration-ConfiguringIgnoredPaths'>Configuring Ignored Paths</a></li>
    <li><a href='#Configuration-ConfiguringContentTypeMapping'>Configuring Content
Type Mapping</a></li>
    <li><a href='#Configuration-SettingExecutionModes'>Setting Execution Modes</a></li>
</ul></div>

<h2><a name="Configuration-Changestoweb.xml"></a>Changes to web.xml</h2>

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

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;!DOCTYPE web-app
      PUBLIC <span class="code-quote">"-//Sun Microsystems, Inc.//DTD Web Application
2.3//EN"</span>
      <span class="code-quote">"http://java.sun.com/dtd/web-app_2_3.dtd"</span>&gt;
<span class="code-tag">&lt;web-app&gt;</span>
    <span class="code-tag">&lt;display-name&gt;</span>My Tapestry Application<span
class="code-tag">&lt;/display-name&gt;</span>
    <span class="code-tag">&lt;context-param&gt;</span>
        <span class="code-tag">&lt;param-name&gt;</span>tapestry.app-package<span
class="code-tag">&lt;/param-name&gt;</span>
        <span class="code-tag">&lt;param-value&gt;</span>org.example.myapp<span
class="code-tag">&lt;/param-value&gt;</span>
    <span class="code-tag">&lt;/context-param&gt;</span>
    <span class="code-tag">&lt;filter&gt;</span>
        <span class="code-tag">&lt;filter-name&gt;</span>app<span class="code-tag">&lt;/filter-name&gt;</span>
        <span class="code-tag">&lt;filter-class&gt;</span>org.apache.tapestry5.TapestryFilter<span
class="code-tag">&lt;/filter-class&gt;</span>
    <span class="code-tag">&lt;/filter&gt;</span>
    <span class="code-tag">&lt;filter-mapping&gt;</span>
        <span class="code-tag">&lt;filter-name&gt;</span>app<span class="code-tag">&lt;/filter-name&gt;</span>
        <span class="code-tag">&lt;url-pattern&gt;</span>/*<span class="code-tag">&lt;/url-pattern&gt;</span>
    <span class="code-tag">&lt;/filter-mapping&gt;</span>
<span class="code-tag">&lt;/web-app&gt;</span>
</pre>
</div></div>

<div class='navmenu' style='float:right; width:30%; background:#eee; margin:3px; padding:3px'><p><font
color="#539126"><b>Tapestry Requests vs. Container Requests</b></font></p>

<p>The Tapestry filter matches all the requests that apply to Tapestry, and passes the
rest off to the servlet container. In situations where there would be a naming conflict, actual
files inside the web application take precedence over Tapestry pages.</p>

<p>Tapestry recognizes the <em>root URL</em>, where the servlet path is
simply "/", and renders the application page "Index", if it exists.</p></div>

<p>The application-specific part, the <tt>tapestry.app-package</tt> 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 <tt>pages</tt> sub-package
and components in the <tt>components</tt> sub-package. In the example above, page
classes will be stored in the <tt>org.example.myapp.pages</tt> package (or in
sub-packages below). Likewise, component classes will be stored in the <tt>org.example.myapp.components</tt>
package.</p>

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

<h2><a name="Configuration-YourApplication%27sModuleClass"></a>Your Application's
Module Class</h2>

<p>Main Article: <a href="/confluence/display/TAPESTRY/Tapestry+IoC+Configuration"
title="Tapestry IoC Configuration">Tapestry IoC Configuration</a></p>

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

<p>Tapestry looks for your application module class in the services package (under the
root package) of your application. It capitalizes the &lt;filter-name&gt; 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.</p>

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

<p>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:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>AppModule.java</b></div><div
class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class AppModule
{
  <span class="code-keyword">public</span> <span class="code-keyword">static</span>
void contributeApplicationDefaults(MappedConfiguration&lt;<span class="code-object">String</span>,<span
class="code-object">String</span>&gt; configuration)
  {
    configuration.add(SymbolConstants.SUPPORTED_LOCALES, <span class="code-quote">"en,fr,de"</span>);
    configuration.add(SymbolConstants.FILE_CHECK_INTERVAL, <span class="code-quote">"10
m"</span>);
  }
}
</pre>
</div></div>

<h2><a name="Configuration-ConfigurationSymbolNames"></a>Configuration Symbol
Names</h2>

<p>Main Article: <a href="/confluence/display/TAPESTRY/Symbols" title="Symbols">Symbols</a></p>

<p>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 &lt;context-param&gt; element into the application's
web.xml, or on the command line by defining JVM System Properties with the &#45;D command
line option.</p>

<p>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 <em>time intervals</em>,
which are specified in a <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">particular format</a>.</p>

<p>Each of these symbols has a corresponding constant defined in the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/SymbolConstants.html"
class="external-link" rel="nofollow">SymbolConstants</a> class.</p>

<h3><a name="Configuration-tapestry.appcatalog"></a>tapestry.app-catalog</h3>

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

<h3><a name="Configuration-tapestry.applicationversion"></a>tapestry.application-version</h3>

<p>The version of the application, which is incorporated into URLs for context and classpath
assets. Assets may be <a href="/confluence/display/TAPESTRY/Response+Compression" title="Response
Compression">compressed</a>, 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 <em>random</em> one will be assigned on every deployment (which is
good for development but very bad for production).</p>

<h3><a name="Configuration-tapestry.blackbirdenabled"></a>tapestry.blackbird-enabled</h3>

<p>A flag (true or false). When "false" the Blackbird javascript console will be disabled
(in Tapestry 5.2 and newer).  Defaults to "true".</p>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.3</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>The
client-side BlackBird console has been removed.</p></div>

<h3><a name="Configuration-tapestry.charset"></a>tapestry.charset</h3>

<p>The character encoding used when generating output (or parsing input). The default
is "UTF-8".  See <a href="/confluence/display/TAPESTRY/Content+Type+and+Markup" title="Content
Type and Markup">Content Type and Markup</a> for more details.</p>

<h3><a name="Configuration-tapestry.combinescripts"></a>tapestry.combine-scripts</h3>

<p>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<br/>
re-download them on subsequent pages).  The implementation of this changed significantly between
Tapestry 5.1 and 5.2.</p>

<p>Defaults to "true" in production mode.</p>

<h3><a name="Configuration-tapestry.componentrendertracingenabled"></a>tapestry.component-render-tracing-enabled</h3>

<p>Starting with version 5.3, if "true" then Tapestry will emit rendering comments for
all requests; these are comments (such as &lt;!&#45;&#45;BEGIN Index:loop (context:Index.tml,
line 15)&#45;&#45;&gt;) 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.)</p>

<h3><a name="Configuration-tapestry.compresswhitespace"></a>tapestry.compress-whitespace</h3>

<p>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).</p>

<h3><a name="Configuration-tapestry.defaultcookiemaxage"></a>tapestry.default-cookie-max-age</h3>

<p>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 <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">Time Interval Formats</a>).</p>


<h3><a name="Configuration-tapestry.defaultstylesheet"></a>tapestry.default-stylesheet</h3>

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

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

<h3><a name="Configuration-tapestry.exceptionreportpage"></a>tapestry.exception-report-page</h3>

<p>The name of the page used to report exceptions. This defaults to "ExceptionReport".</p>

<h3><a name="Configuration-tapestry.filecheckinterval"></a>tapestry.file-check-interval</h3>

<p>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 <a href="#Configuration-reload.html">automatic component reloading</a>).</p>

<p>The default is "1 s" (one second; see <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">Time Interval Formats</a>), and is usually overridden
with a higher value in production (say, between one and five minutes).</p>

<h3><a name="Configuration-tapestry.filecheckupdatetimeout"></a>tapestry.file-check-update-timeout</h3>

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

<p>The default is "50 ms" (50 milliseconds; see <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">Time Interval Formats</a>).</p>

<h3><a name="Configuration-tapestry.forceabsoluteuris"></a>tapestry.force-absolute-uris</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Starting
in Tapestry 5.2, the optimization to generate relative URIs has been removed, and all URIs
are always absolute.  <em>Removed in 5.3.</em></p></div>

<p><em>For Tapestry 5.0 and 5.1 only</em>: 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).  </p>

<h3><a name="Configuration-tapestry.gzipcompressionenabled"></a>tapestry.gzip-compression-enabled</h3>

<p>Override to "false" to disable GZIP compression of dynamic Tapestry pages and static
assets.</p>

<h3><a name="Configuration-tapestry.mingzipsize"></a>tapestry.min-gzip-size</h3>

<p>The minimum stream size necessary for Tapestry to use GZIP compression on the response
stream.  See <a href="/confluence/display/TAPESTRY/Response+Compression" title="Response
Compression">Response Compression</a> for more details.</p>

<h3><a name="Configuration-tapestry.omitgeneratormeta"></a>tapestry.omit-generator-meta</h3>

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

<h3><a name="Configuration-tapestry.pagepool.activewindow"></a>tapestry.page-pool.active-window</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Starting
in 5.2, this is only used if tapestry.page-pool-enabled is "true". <em>Removed in 5.3</em></p></div>

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

<p>The default is "10 m" (10 minutes; see <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">Time Interval Formats</a>).</p>

<h3><a name="Configuration-tapestry.pagepoolenabled"></a>tapestry.page-pool-enabled</h3>

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

<p>The default is "false".</p>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Removed
in 5.3.</p></div>

<h3><a name="Configuration-tapestry.pagepool.hardlimit"></a>tapestry.page-pool.hard-limit</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Starting
in 5.2, this is only used if tapestry.page-pool-enabled is "true". <em>Removed in 5.3</em></p></div>

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

<p>The default is 20 page instances.</p>

<h3><a name="Configuration-tapestry.pagepool.softlimit"></a>tapestry.page-pool.soft-limit</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Starting
in 5.2, this is only used if tapestry.page-pool-enabled is "true". <em>Removed in 5.3</em></p></div>

<p>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).</p>

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

<h3><a name="Configuration-tapestry.pagepool.softwait"></a>tapestry.page-pool.soft-wait</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p>Starting
in 5.2, this is only used if tapestry.page-pool-enabled is "true". <em>Removed in 5.3</em></p></div>

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

<p>The default is "10 ms" (10 milliseconds; see <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/TimeInterval.html"
class="external-link" rel="nofollow">Time Interval Formats</a>).</p>

<h3><a name="Configuration-tapestry.productionmode"></a>tapestry.production-mode</h3>

<p>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).</p>

<h3><a name="Configuration-tapestry.secureenabled"></a>tapestry.secure-enabled</h3>

<p>If true, then @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html"
class="external-link" rel="nofollow">Secure</a> 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.</p>

<h3><a name="Configuration-tapestry.securepage"></a>tapestry.secure-page</h3>

<p>If true, then the page may only be accessed via HTTPS. The @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html"
class="external-link" rel="nofollow">Secure</a> 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.</p>

<h3><a name="Configuration-tapestry.scriptaculous"></a>tapestry.scriptaculous</h3>

<p>The path to the embedded copy of <a href="http://script.aculo.us/" class="external-link"
rel="nofollow">script.aculo.us</a> packaged with Tapestry. This value may be overridden
to use a different version of the script.aculo.us library. See <a href="/confluence/display/TAPESTRY/JavaScript"
title="JavaScript">JavaScript</a> for the default version.</p>

<h3><a name="Configuration-tapestry.startpagename"></a>tapestry.start-page-name</h3>

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

<p><a name="Configuration-supportedlocales"></a></p>

<h3><a name="Configuration-tapestry.supportedlocales"></a>tapestry.supported-locales</h3>

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

<p>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".</p>

<h3><a name="Configuration-tapestry.suppressredirectfromactionrequests"></a>tapestry.suppress-redirect-from-action-requests</h3>



<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Deprecated
since 5.2</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #ffcccc;border-left: 20px solid #ffcccc;"><p><em>Removed
in 5.3.</em></p></div>

<p>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).</p>

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

<h3><a name="Configuration-tapestry.threadpool.corepoolsize"></a>tapestry.thread-pool.core-pool-size</h3>

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

<h3><a name="Configuration-tapestry.threadpool.maxpoolsize"></a>tapestry.thread-pool.max-pool-size</h3>

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


<h3><a name="Configuration-tapestry.threadpool.queuesize"></a>tapestry.thread-pool.queue-size</h3>



<div class='panelMacro'><table class='infoMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/information.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td><b>Added in
5.3</b><br /></td></tr></table></div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;"><p>Previously,
the queue size was unbounded, which meant that max-pool-size was ignored.</p></div>

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

<h3><a name="Configuration-tapestry.threadpool.keepalive"></a>tapestry.thread-pool.keep-alive</h3>

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

<h3><a name="Configuration-tapestry.threadpoolenabled"></a>tapestry.thread-pool-enabled</h3>

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

<h2><a name="Configuration-ConfiguringIgnoredPaths"></a>Configuring Ignored
Paths</h2>

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

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

<p>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 <b>not</b> processed by Tapestry.</p>

<p>For example, say you are using <a href="http://getahead.org/dwr/" class="external-link"
rel="nofollow">Direct Web Remoting</a>. You'll likely have the servlet path /dwr
mapped to the Direct Web Remoting servlet.</p>

<p>You contribution would look like:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  <span class="code-keyword">public</span> <span class="code-keyword">static</span>
void contributeIgnoredPathsFilter(Configuration&lt;<span class="code-object">String</span>&gt;
configuration)
  {
    configuration.add(<span class="code-quote">"/dwr/.*"</span>);
  }
</pre>
</div></div>

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

<p>The regular expressions provided in the configuration are always compiled with case
insensitivity enabled.</p>

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

<h2><a name="Configuration-ConfiguringContentTypeMapping"></a>Configuring
Content Type Mapping</h2>

<p>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 <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/ResourceStreamer.html"
class="external-link" rel="nofollow">ResourceStreamer</a> 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.</p>


<h2><a name="Configuration-SettingExecutionModes"></a>Setting Execution
Modes</h2>

<p>Starting with Tapestry 5.2.4, we can specify an <em>execution mode</em>
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.</p>

<p>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:</p>

<p>1. Add the parameter to your JVM command line:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-Dtapestry.execution-mode=DevelopmentMode jetty:run
</pre>
</div></div>

<p>2. Add the parameter to the Jetty plugin:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;plugin&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.mortbay.jetty<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>maven-jetty-plugin<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>6.1.16<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;configuration&gt;</span>
        <span class="code-tag">&lt;requestLog implementation=<span class="code-quote">"org.mortbay.jetty.NCSARequestLog"</span>&gt;</span>
            <span class="code-tag">&lt;append&gt;</span>true<span class="code-tag">&lt;/append&gt;</span>
        <span class="code-tag">&lt;/requestLog&gt;</span>
        <span class="code-tag">&lt;systemProperties&gt;</span>
	    <span class="code-tag">&lt;systemProperty&gt;</span>
	        <span class="code-tag">&lt;name&gt;</span>tapestry.execution-mode<span
class="code-tag">&lt;/name&gt;</span>
	        <span class="code-tag">&lt;value&gt;</span>DevelopmentMode<span
class="code-tag">&lt;/value&gt;</span>
	    <span class="code-tag">&lt;/systemProperty&gt;</span>
        <span class="code-tag">&lt;/systemProperties&gt;</span>
    <span class="code-tag">&lt;/configuration&gt;</span>
<span class="code-tag">&lt;/plugin&gt;</span>
</pre>
</div></div>

<p>3. Add the parameter to the Surfire plugin for your test:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;plugin&gt;</span>
    <span class="code-tag">&lt;groupId&gt;</span>org.apache.maven.plugins<span
class="code-tag">&lt;/groupId&gt;</span>
    <span class="code-tag">&lt;artifactId&gt;</span>maven-surefire-plugin<span
class="code-tag">&lt;/artifactId&gt;</span>
    <span class="code-tag">&lt;version&gt;</span>2.8.1<span class="code-tag">&lt;/version&gt;</span>
    <span class="code-tag">&lt;configuration&gt;</span>
       <span class="code-tag">&lt;systemPropertyVariables&gt;</span>
         <span class="code-tag">&lt;tapestry.execution-mode&gt;</span>DevelopmentMode<span
class="code-tag">&lt;/tapestry.execution-mode&gt;</span>
       <span class="code-tag">&lt;/systemPropertyVariables&gt;</span>
    <span class="code-tag">&lt;/configuration&gt;</span>
<span class="code-tag">&lt;/plugin&gt;</span>
</pre>
</div></div>

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

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

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

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;context-param&gt;</span>
    <span class="code-tag">&lt;param-name&gt;</span>tapestry.production-modules<span
class="code-tag">&lt;/param-name&gt;</span>
    <span class="code-tag">&lt;param-value&gt;</span>org.apache.tapestry.appli.services.ProductionModeModule<span
class="code-tag">&lt;/param-value&gt;</span>
<span class="code-tag">&lt;/context-param&gt;</span>
<span class="code-tag">&lt;context-param&gt;</span>
    <span class="code-tag">&lt;param-name&gt;</span>tapestry.DevelopmentMode-modules<span
class="code-tag">&lt;/param-name&gt;</span>
    <span class="code-tag">&lt;param-value&gt;</span>org.apache.tapestry.appli.services.DevelopmentModeModule<span
class="code-tag">&lt;/param-value&gt;</span>
<span class="code-tag">&lt;/context-param&gt;</span>
</pre>
</div></div>

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

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
-Dtapestry.execution-mode=DevelopmentMode,DevelopmentMode2 jetty:run
</pre>
</div></div>

<p>and then for each modes we have two modules:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeHeader panelHeader"
style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent
panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;context-param&gt;</span>
      <span class="code-tag">&lt;param-name&gt;</span>tapestry.DevelopmentMode-modules<span
class="code-tag">&lt;/param-name&gt;</span>
      <span class="code-tag">&lt;param-value&gt;</span>
          org.apache.tapestry.appli.services.DevelopmentMode1Module1,
          org.apache.tapestry.appli.services.DevelopmentMode1Module2
      <span class="code-tag">&lt;/param-value&gt;</span>
<span class="code-tag">&lt;/context-param&gt;</span>
<span class="code-tag">&lt;context-param&gt;</span>
      <span class="code-tag">&lt;param-name&gt;</span>tapestry.DevelopmentMode2-modules<span
class="code-tag">&lt;/param-name&gt;</span>
      <span class="code-tag">&lt;param-value&gt;</span>
          org.apache.tapestry.appli.services.DevelopmentMode2Module1,
          org.apache.tapestry.appli.services.DevelopmentMode2Module2
      <span class="code-tag">&lt;/param-value&gt;</span>
<span class="code-tag">&lt;/context-param&gt;</span>
</pre>
</div></div>

<p>then Tapestry will load modules in the order: DevelopmentMode1Module1, DevelopmentMode1Module2,
DevelopmentMode2Module1 and DevelopmentMode2Module2</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Configuration">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=21792227&revisedVersion=35&originalVersion=34">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message