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 Thu, 30 Dec 2010 23:35:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/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/~bobharner">Bob
Harner</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Corrected tapestry.force-absolute-uris description for 5.2 per Howard.  Also, spelling
fixes, minor formatting tweaks, fixed a broken link<br />
    </div>
        <br/>
                         <h4>Changes (12)</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" >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
configuration inside web.xml. <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >h2. <span class="diff-added-words"style="background-color:
#dfd;">Changes to</span> web.xml <br></td></tr>
            <tr><td class="diff-unchanged" > <br>The majority of configuration
occurs inside the servlet deployment descriptor, WEB-INF/web.xml. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. tapestry.application-version
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">The
version of the application, which is incorporated into URLs for context and classpath assets.
Assets may be [compressed|#compress.html], and will have far-future expiration headers; they
will be aggresively 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). <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
version of the application, which is incorporated into URLs for context and classpath assets.
Assets may be [compressed|Response Compression], 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). <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. tapestry.charset <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. tapestry.force-absolute-uris
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">A
flag (true or false). When false (the default), Tapestry will attempt to optimize URIs that
it generates, using relative URIs when such URIs are shorter than absolute URIs. You will
see some savings when you make generous use of libraries, sub-folders and page activation
contexts ... otherwise, no significant difference.When true, all URIs will be absolute URIs
(including the context path, and the complete path for the request). <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">_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).  Starting in Tapestry 5.2, URL optimization has been removed, and all URIs are
always absolute. <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. tapestry.gzip-compression-enabled
<br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. tapestry.secure-enabled
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">If
true, then [@Secure|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html]
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.
<br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">If
true, then @[Secure|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html]
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.
<br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. tapestry.secure-page <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">If
true, then the page may only be accessed via HTTPS. The [@Secure|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html]
annotation will set this value to true. This symbol is the default for all pages; set it to
&quot;true&quot; to force the entire application to be secure.  <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">If
true, then the page may only be accessed via HTTPS. The @[Secure|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Secure.html]
annotation will set this value to true. This symbol is the default for all pages; set it to
&quot;true&quot; to force the entire application to be secure.  <br> <br></td></tr>
            <tr><td class="diff-unchanged" >h3. tapestry.scriptaculous <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h3. tapestry.suppress-redirect-from-action-requests
<br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Normally,
Tapestry responds to action requests (such as form submissions) by sending a client-side redirect
to the renderring 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). <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">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). <br> <br></td></tr>
            <tr><td class="diff-unchanged" >Setting this symbol to &quot;true&quot;
changes the Tapestry behavior to make it more like Tapestry 4: a markup response is sent directly
for the action request, 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. <br>
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Response Compression <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >Starting in Tapestry 5.1, the
framework automatically GZIP compresses content streamed to the client. This can <span
class="diff-changed-words">signif<span class="diff-added-chars"style="background-color:
#dfd;">i</span>cantly</span> reduce the amount of network traffic for a Tapestry
application, at the cost of extra processing time on the server to compress the response stream.
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>This directly applies to
both rendered pages and streamed assets from the classpath. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <style type='text/css'>/*<![CDATA[*/
div.rbtoc1293752065303 {margin-left: 1.5em;padding: 0px;}
div.rbtoc1293752065303 ul {margin-left: 0px;padding-left: 20px;}
div.rbtoc1293752065303 li {margin-left: 0px;padding-left: 0px;}

/*]]>*/</style><div class='rbtoc1293752065303'>
<ul>
    <li><span class='TOCOutline'>1</span> <a href='#Configuration-ConfiguringTapestry'>Configuring
Tapestry</a></li>
<ul>
    <li><span class='TOCOutline'>1.1</span> <a href='#Configuration-Changestoweb.xml'>Changes
to web.xml</a></li>
    <li><span class='TOCOutline'>1.2</span> <a href='#Configuration-TapestryRequestsvs.ContainerRequests'>Tapestry
Requests vs. Container Requests</a></li>
    <li><span class='TOCOutline'>1.3</span> <a href='#Configuration-TapestryIoCConfiguration'>Tapestry
IoC Configuration</a></li>
    <li><span class='TOCOutline'>1.4</span> <a href='#Configuration-ConfigurationSymbols'>Configuration
Symbols</a></li>
</ul>
    <li><span class='TOCOutline'>2</span> <a href='#Configuration-IgnoredPaths'>Ignored
Paths</a></li>
    <li><span class='TOCOutline'>3</span> <a href='#Configuration-ResponseCompression'>Response
Compression</a></li>
<ul>
    <li><span class='TOCOutline'>3.1</span> <a href='#Configuration-CompressionConfiguration'>Compression
Configuration</a></li>
    <li><span class='TOCOutline'>3.2</span> <a href='#Configuration-StreamResponse'>StreamResponse</a></li>
</ul>
</ul></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 configuration inside web.xml.</p>

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

<p>The majority of configuration occurs inside the servlet deployment descriptor, WEB-INF/web.xml.</p>

<p>Most of the configuration is boilerplate; the same for all applications.</p>

<p>The application specific configuration is to identify the root application package.
Tapestry uses this package name to locate your page and component classes.</p>

<p>Page classes must go in the pages sub-package, and components must go in the components
sub-package.</p>

<p>You specify the root package as a context parameter:</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>

<p>You may name the filter whatever you want, though "app" is a common convention.</p>

<p>In this example, 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>

<h2><a name="Configuration-TapestryRequestsvs.ContainerRequests"></a>Tapestry
Requests vs. Container Requests</h2>

<p>The Tapestry filter matches all the requests that apply to Tapestry, and passes the
rest off to the servlet container.</p>

<p>Actual files inside the web application take precedence over Tapestry pages, in situation
where there would be a naming conflict.</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>

<h2><a name="Configuration-TapestryIoCConfiguration"></a>Tapestry IoC Configuration</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 a module class in the services package (under the root package).
It capitalizes the &lt;filter-name&gt; and appends "Module". In the previous example,
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, though any non-trivial application will have a module.</p>

<p>An application module will often 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="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-ConfigurationSymbols"></a>Configuration Symbols</h2>

<p>Tapestry may also be configured via <a href="/confluence/display/TAPESTRY/Symbols"
title="Symbols">symbols</a>. A certain number of 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 -D command line option.</p>

<p>These symbols are always defined in terms of strings, that 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>Many of these symbols have an associated constant in the class <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/SymbolConstants.html"
class="external-link" rel="nofollow">SymbolConstants</a>.</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.charset"></a>tapestry.charset</h3>

<p>The character encoding used when generating output (or parsing input). The default
is "UTF-8".</p>

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

<p>If "true", then all JavaScript libraries required for a particular page render will
be combined into a single request (the contents of the libraries are dynamically combined
by Tapestry). Defaults to "true" in production mode.</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. The default value is equal to one week. </p>

<p>Primarily, this is used with a cookie that exists to track the preferred user locale.</p>

<p>The default is "7 d" (that is, seven days).</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), 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. The default is "50 ms" (50 milliseconds).</p>

<p>If the exclusive lock can't be obtained in that amount of time, the request will
proceeed normally (without the check), but each successive request will attempt to get the
lock and perform the check until successful.</p>

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

<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).  Starting in Tapestry 5.2, URL optimization has been
removed, and all URIs are always absolute.</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.</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.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.pagepool.activewindow"></a>tapestry.page-pool.active-window</h3>

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

<p>The default is "10 m" (10 minutes).</p>

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

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

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

<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".</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. Tapestry's default version is 1.8.1
(including Prototype 1.6.0.1).</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>

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

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

<h1><a name="Configuration-IgnoredPaths"></a>Ignored Paths</h1>

<p>In some cases, you may use Tapestry is 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>

<h1><a name="Configuration-ResponseCompression"></a>Response Compression</h1>

<p>Starting in Tapestry 5.1, the framework automatically GZIP compresses content streamed
to the client. This can significantly reduce the amount of network traffic for a Tapestry
application, at the cost of extra processing time on the server to compress the response stream.</p>

<p>This directly applies to both rendered pages and streamed assets from the classpath.</p>

<p>Context assets will also be compressed ... but this requires referencing such assets
using the "context:" binding prefix, so that generated URL is handled by Tapestry and not
the servlet container.</p>

<h2><a name="Configuration-CompressionConfiguration"></a>Compression Configuration</h2>

<p>Small streams generally do not benefit from being compressed; there is overhead when
using compression, not just the CPU time to compress the bytes, but a lot of overhead. For
small responses, Tapestry does not attempt to compress the output stream.</p>

<p>The configuration symbol <tt>tapestry.min-gzip-size</tt> allows the cutoff
to be set; it defaults to 100 bytes.</p>

<p>In addition, some file types are already compressed and should not be recompressed
(they actually get larger, not smaller!). The service <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ResponseCompressionAnalyzer.html"
class="external-link" rel="nofollow">ResponseCompressionAnalyzer</a>'s configuration
is an unordered collection of content type strings that should <em>not</em> be
compressed. The default content types are "image/jpeg".</p>

<p>The mapping from file type (by extension) to content type is typically done as part
of your servlet-containers configuration. Alternately, you can 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.</p>

<h2><a name="Configuration-StreamResponse"></a>StreamResponse</h2>

<p>When returning a <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html"
class="external-link" rel="nofollow">StreamResponse</a> from a <a href="/confluence/display/TAPESTRY/Page+Navigation"
title="Page Navigation">component event method</a>, the stream is totally under your
control; it will not be compressed. You should use the ResponseCompressionAnalyzer service
to determine if the client supports compression, and add a java.util.zip.GZIPOutputStream
to your stream stack if compression is desired.</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=9&originalVersion=8">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message