You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tapestry.apache.org by bu...@apache.org on 2015/04/03 20:19:36 UTC
svn commit: r946218 [2/2] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/configuration.html
==============================================================================
--- websites/production/tapestry/content/configuration.html (original)
+++ websites/production/tapestry/content/configuration.html Fri Apr 3 18:19:36 2015
@@ -101,7 +101,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="configuration.html">Configuration</a>
+ <a shape="rect" href="symbols.html">Symbols</a>
</div>
@@ -110,7 +110,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="symbols.html">Symbols</a>
+ <a shape="rect" href="ioc-cookbook-service-configurations.html">IoC cookbook - Service Configurations</a>
</div>
@@ -119,18 +119,18 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="ioc-cookbook-service-configurations.html">IoC cookbook - Service Configurations</a>
+ <a shape="rect" href="configuration.html">Configuration</a>
</div>
</li></ul>
</div><h1 id="Configuration-ConfiguringTapestry">Configuring Tapestry</h1><p>This page discusses all the ways in which Tapestry can be configured. Tapestry applications are configured almost entirely using Java, with very little XML at all.</p><p><strong>Contents</strong></p><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1427879983240 {padding: 0px;}
-div.rbtoc1427879983240 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1427879983240 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1428085157009 {padding: 0px;}
+div.rbtoc1428085157009 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1428085157009 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1427879983240">
-<ul class="toc-indentation"><li><a shape="rect" href="#Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</a></li><li><a shape="rect" href="#Configuration-YourApplication'sModuleClass">Your Application's Module Class</a></li><li><a shape="rect" href="#Configuration-ConfigurationSymbolNames">Configuration Symbol Names</a></li><li><a shape="rect" href="#Configuration-SettingComponentParameterDefaults">Setting Component Parameter Defaults</a></li><li><a shape="rect" href="#Configuration-ConfiguringIgnoredPaths">Configuring Ignored Paths</a></li><li><a shape="rect" href="#Configuration-ConfiguringContentTypeMapping">Configuring Content Type Mapping</a></li><li><a shape="rect" href="#Configuration-SettingExecutionModes">Setting Execution Modes</a></li><li><a shape="rect" href="#Configuration-SegregatingApplicationsIntoFolders">Segregating Applications Into Folders</a></li></ul>
+/*]]>*/</style></p><div class="toc-macro rbtoc1428085157009">
+<ul class="toc-indentation"><li><a shape="rect" href="#Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</a></li><li><a shape="rect" href="#Configuration-YourApplication'sModuleClass">Your Application's Module Class</a></li><li><a shape="rect" href="#Configuration-ConfigurationSymbolNames">Configuration Symbol Names</a></li><li><a shape="rect" href="#Configuration-SettingComponentParameterDefaults">Setting Component Parameter Defaults</a></li><li><a shape="rect" href="#Configuration-ConfiguringIgnoredPaths">Configuring Ignored Paths</a></li><li><a shape="rect" href="#Configuration-ConfiguringContentTypeMapping">Configuring Content Type Mapping</a></li><li><a shape="rect" href="#Configuration-SettingExecutionModes">Setting Execution Modes</a></li></ul>
</div><h2 id="Configuration-XMLconfiguration(web.xml)">XML configuration (web.xml)</h2><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>Although most configuration is done with Java, 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 pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml (partial)</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
@@ -442,7 +442,6 @@ div.rbtoc1427879983240 li {margin-left:
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-
<p>When set to true, the DateField component will be lenient about date calculations, for example allowing a January 32 date as input and automatically converting it to February 1. When false (the default), only valid dates may be entered.</p>
</div><p><br clear="none">If false (the default)</p><h3 id="Configuration-tapestry.min-gzip-size">tapestry.min-gzip-size</h3><p>The minimum stream size necessary for Tapestry to use GZIP compression on the response stream. See <a shape="rect" href="response-compression.html">Response Compression</a> for more details.</p><h3 id="Configuration-tapestry.omit-generator-meta">tapestry.omit-generator-meta</h3><p>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.</p><h3 id="Configuration-tapestry.page-pool.active-window">tapestry.page-pool.active-window</h3>
@@ -581,7 +580,7 @@ configuration.add(ComponentParameterCons
}
]]></script>
</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 id="Configuration-ConfiguringContentTypeMapping">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 shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/internal/services/ResourceStreamer.html">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 id="Configuration-SettingExecutionModes">Setting Execution Modes</h2><p>Start
ing 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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[-Dtapestry.execution-mode=DevelopmentMode jetty:run
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[-Dtapestry.execution-mode=uat jetty:run
]]></script>
</div></div><p>2. Add the parameter to the Jetty plugin:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<plugin>
@@ -595,7 +594,7 @@ configuration.add(ComponentParameterCons
<systemProperties>
<systemProperty>
<name>tapestry.execution-mode</name>
- <value>DevelopmentMode</value>
+ <value>uat</value>
</systemProperty>
</systemProperties>
</configuration>
@@ -608,41 +607,30 @@ configuration.add(ComponentParameterCons
<version>2.8.1</version>
<configuration>
<systemPropertyVariables>
- <tapestry.execution-mode>DevelopmentMode</tapestry.execution-mode>
+ <tapestry.execution-mode>uat</tapestry.execution-mode>
</systemPropertyVariables>
</configuration>
</plugin>
]]></script>
-</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.execution-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 pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent panelContent pdl">
+</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.execution-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 UatModeModule module will be loaded.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<context-param>
<param-name>tapestry.production-modules</param-name>
- <param-value>org.apache.tapestry.appli.services.ProductionModeModule</param-value>
+ <param-value>com.example.myapp.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>
-]]></script>
-</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 pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[-Dtapestry.execution-mode=DevelopmentMode,DevelopmentMode2 jetty:run
-]]></script>
-</div></div><p>and then for each modes we have two modules:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>web.xml</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<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>
+ <param-name>tapestry.uat-modules</param-name>
+ <param-value>com.example.myapp.services.UatModeModule</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>
+ <param-name>tapestry.integration-modules</param-name>
+ <param-value>com.example.myapp.services.IntegrationModeModule</param-value>
</context-param>
]]></script>
-</div></div><p>then Tapestry will load modules in the order: DevelopmentMode1Module1, DevelopmentMode1Module2, DevelopmentMode2Module1 and DevelopmentMode2Module2</p><h2 id="Configuration-SegregatingApplicationsIntoFolders">Segregating Applications Into Folders</h2><p>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.</p>
+</div></div><p>Execution mode itself may be a comma separated list:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[-Dtapestry.execution-mode=uat,integration jetty:run
+]]></script>
+</div></div><p><span style="color: rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Segregating Applications Into Folders</span></p><p>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.</p>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.3</p>
Modified: websites/production/tapestry/content/layout-component.html
==============================================================================
--- websites/production/tapestry/content/layout-component.html (original)
+++ websites/production/tapestry/content/layout-component.html Fri Apr 3 18:19:36 2015
@@ -125,7 +125,7 @@
</div>
</li></ul>
</div><p>You'll see frequent reference to a <strong>Layout Component</strong> in Tapestry documentation, but you won't find such a component in the <a shape="rect" href="component-reference.html">component reference</a>. The Layout component is a component <em>that you create</em> to provide common elements across all of your pages.</p><p>In traditional servlet development, you may be familiar with the use of a JSP include to include a banner across the top of your page and a copyright message across the bottom. In Tapestry, you <em>could</em> implement those recurring page elements as components (a banner component, a copyright component, etc.) and then add those components to every page.</p><p>But there's an even better way. Just create a layout component that provides the overall structure and recurring content for your pages:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.tml (a templa
te for a Layout component)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<head>
<title>My Nifty Web Application</title>
</head>
@@ -143,7 +143,7 @@
</html>
]]></script>
</div></div><p>In a real-world example, the two <div> elements above might contain the typical recurring content you'll see across the pages of a web application: banners, menus, login forms and so forth. Often these layout components get very complex ... in fact, in many applications the Layout component can grow to be as complex as any other component.</p><h2 id="LayoutComponent-UsingtheLayoutinaPage">Using the Layout in a Page</h2><p>To use your layout component, just have each page in your application <em>wrap itself</em> in the layout, like this:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Welcome.tml (the template for a page)</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html t:type="layout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<h1>Welcome to the Nifty Web Application!</h1>
@@ -165,7 +165,7 @@ public class Layout
}
]]></script>
</div></div><p>We use the @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Import.html">Import</a> annotation (in 5.2 or later), as opposed to directly adding the <link> element to the template, for significant performance benefits <a shape="rect" href="assets.html">described elsewhere</a>. (For 5.0 and 5.1, use the deprecated @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/IncludeStylesheet.html">IncludeStyleSheet</a> annotation instead.)</p><p>You may find that your application has more than one look and feel: perhaps user registration pages have one look, while administrative pages have another. This can be accomplished by having multiple layout components (using any names you choose) and using those different layout types for different pages.</p><h2 id="LayoutComponent-NestedLayouts">Nested Layouts</h2><p>Layouts are really just o
rdinary components, so they can be nested to any level needed. You can have, for example, a "CommonLayout" component that provides the peripheral elements for all your pages, and then a more specialized "AdminLayout" component that provides the layout only for the administrative pages, and make the AdminLayout component wrap itself in the CommonLayout component. So then the administrative pages would start with <code><html t:type="adminLayout" ...></code> and the other pages (and the AdminLayout component itself) would start with <code><html t:type="commonLayout" ...></code>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AdminLayout.tml</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html t:type="commonLayout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_1_0.xsd">
+<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html t:type="commonLayout" xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<h1>Administrative Functions</h1>
@@ -175,10 +175,10 @@ public class Layout
]]></script>
</div></div><h2 id="LayoutComponent-Amoreadvancedexample">A more advanced example</h2><p>Here's an example of a Layout component with a few more features. It has a "title" parameter, so that every page can pass in its own title to be rendered in the <title> tag <em>and</em> in an <h1> tag at the top of the HTML. There is also a "style" parameter that allows each page to pass in a block of CSS rules to be rendered in the <head> section of the page (useful for those few CSS rules that can't be put into a static CSS file). Notice the HTML5-style DOCTYPE declaration at the top, the charset definition as UTF-8, and the addition of an "alerts" component.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>Layout.tml (a template for a Layout component)</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<!DOCTYPE html>
-<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
+<html xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd">
<head>
<meta charset="UTF-8" />
- <title>$title - NiftyWebCo, Inc</title>
+ <title>${title} - NiftyWebCo, Inc</title>
<style type="text/css">
<t:delegate to="style" />
</style>
@@ -217,7 +217,7 @@ public class Layout
]]></script>
</div></div><p>Here's how you might use the above layout component for a UserList page:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>UserList.tml</b></div><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<html t:type="layout" title="List of Users"
- xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd"
+ xmlns:t="http://tapestry.apache.org/schema/tapestry_5_4.xsd"
xmlns:p="tapestry:parameter">
<p:style>
TD.profile { background: url('${backgroundImage}') }
Modified: websites/production/tapestry/content/page-life-cycle.html
==============================================================================
--- websites/production/tapestry/content/page-life-cycle.html (original)
+++ websites/production/tapestry/content/page-life-cycle.html Fri Apr 3 18:19:36 2015
@@ -67,9 +67,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="PageLifeCycle-PageLifeCycle">Page Life Cycle</h1>
-
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><h1 id="PageLifeCycle-PageLifeCycle">Page Life Cycle</h1><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -85,7 +83,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="request-processing.html">Request Processing</a>
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
</div>
@@ -94,7 +92,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
+ <a shape="rect" href="component-events.html">Component Events</a>
</div>
@@ -103,7 +101,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-rendering.html">Component Rendering</a>
+ <a shape="rect" href="request-processing.html">Request Processing</a>
</div>
@@ -112,7 +110,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-navigation.html">Page Navigation</a>
+ <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
</div>
@@ -121,94 +119,24 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-events.html">Component Events</a>
+ <a shape="rect" href="page-navigation.html">Page Navigation</a>
</div>
</li></ul>
-</div>
-
-<p>In Tapestry, you are free to develop your presentation objects, page and components classes, as ordinary objects, complete with instance variables and so forth.</p>
-
-<p>This is somewhat revolutionary in terms of web development in Java. Using traditional servlets, or Struts, your presentation objects (Servlets, or Struts Actions, or the equivalent in other frameworks) are <em>stateless singletons</em>. That is, a <em>single</em> instance is created, and all incoming requests are threaded through that single instance.</p>
-
-<p>Because multiple requests are handled by many different threads, this means that the single instance's variable are useless ... any value written into an instance variable would immediately be overwritten by a different thread. Thus, it is necessary to use the Servlet API's HttpServletRequest object to store per-request data, and the HttpSession object to store data between requests.</p>
-
-<p>Tapestry takes a very different approach.</p>
-
-<p>In Tapestry, each page is a singleton, but with a <em>per thread</em> map of field names & values that Tapestry invisibly manages for you.</p>
-
-<p>With this approach, all the difficult, ugly issues related to multi-threading go by the wayside. Instead, familiar, simple coding practices (using ordinary methods and fields) can be used.</p>
-
- <div class="aui-message hint shadowed information-macro">
+</div><p>In Tapestry, you are free to develop your presentation objects, page and components classes, as ordinary objects, complete with instance variables and so forth.</p><p>This is somewhat revolutionary in terms of web development in Java. Using traditional servlets, or Struts, your presentation objects (Servlets, or Struts Actions, or the equivalent in other frameworks) are <em>stateless singletons</em>. That is, a <em>single</em> instance is created, and all incoming requests are threaded through that single instance.</p><p>Because multiple requests are handled by many different threads, this means that the single instance's variable are useless ... any value written into an instance variable would immediately be overwritten by a different thread. Thus, it is necessary to use the Servlet API's HttpServletRequest object to store per-request data, and the HttpSession object to store data between requests.</p><p>Tapestry takes a very different approach.</p><p>In Tapestry, each pa
ge is a singleton, but with a <em>per thread</em> map of field names & values that Tapestry invisibly manages for you.</p><p>With this approach, all the difficult, ugly issues related to multi-threading go by the wayside. Instead, familiar, simple coding practices (using ordinary methods and fields) can be used.</p> <div class="aui-message hint shadowed information-macro">
<span class="aui-icon icon-hint">Icon</span>
<div class="message-content">
-
-<p>Tapestry 5.0 and 5.1 used page pooling, rather than a singleton page with a per_thread map, to achieve the same effect.</p>
+ <p>Tapestry 5.0 and 5.1 used page pooling, rather than a singleton page with a per_thread map, to achieve the same effect.</p>
</div>
</div>
-
-
-<h2 id="PageLifeCycle-PageLifeCycleMethods">Page Life Cycle Methods</h2>
-
-<p>There are a few situations where it is useful for a component to perform some operations, usually some kind of initialization or caching, based on the life cycle of the page.</p>
-
-<p>The page life cycle is quite simple. When first needed, a page is loaded. Loading a page involves instantiating the components of the page and connecting them together.</p>
-
-<p>Once a page is loaded, it is <em>attached</em> to the current request. Remember that there will be many threads, each handling its own request to the same page.</p>
-
-<p>At the end of a request, after a response has been sent to the client, the page is <em>detached</em> from the request. This is a chance to perform any cleanup needed for the page.</p>
-
-<p>As with <a shape="rect" href="component-rendering.html">component rendering</a>, you have the ability to make your components "aware" of these events by identifying methods to be invoked.</p>
-
-<p>Page life cycle methods should take no parameters and return void.</p>
-
-<p>You have the choice of attaching an annotation to a method, or simply using the method naming conventions:</p>
-
-<div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p> Annotation </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> Method Name </p></th><th colspan="1" rowspan="1" class="confluenceTh"><p> When Called </p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PageLoaded.html">PageLoaded</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>pageLoaded()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> After the page is fully loaded </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PageAttached.html">PageAttached</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> pageAttached() </p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p> After the page is attached to the request. <strong>Deprecated in Tapestry 5.3</strong> </p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p> @<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PageDetached.html">PageDetached</a> </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> pageDetached() </p></td><td colspan="1" rowspan="1" class="confluenceTd"><p> AFter the page is detached from the request. <strong>Deprecated in Tapestry 5.3</strong> </p></td></tr></tbody></table></div>
-
-
-<h2 id="PageLifeCycle-ComparisontoJavaServerPages">Comparison to JavaServer Pages</h2>
-
-<p>JSPs also act as singletons. However, the individual JSP tags are pooled.</p>
-
-<p>This is one of the areas where Tapestry can significantly outperform JSPs. Much of the code inside a compiled JSP class concerns getting tags from a tag pool, configuring the properties of the tag instance, using the tag instance, then cleaning up the tag instance and putting it back in the pool.</p>
-
-<p>The operations Tapestry does once per request are instead executed dozens or potentially hundreds of times (depending the complexity of the page, and if any nested loops occur).</p>
-
-<p>Pooling JSP tags is simply the wrong granularity.</p>
-
-<p>Tapestry can also take advantage of its more coarse grained caching to optimize how data moves, via parameters, between components. This means that Tapestry pages will actually speed up after they render the first time.</p>
-
-<h2 id="PageLifeCycle-PagePoolConfiguration">Page Pool Configuration</h2>
-
- <div class="aui-message warning shadowed information-macro">
+<h2 id="PageLifeCycle-PageLifeCycleMethods">Page Life Cycle Methods</h2><p>There are a few situations where it is useful for a component to perform some operations, usually some kind of initialization or caching, based on the life cycle of the page.</p><p>The page life cycle is quite simple. When first needed, a page is loaded. Loading a page involves instantiating the components of the page and connecting them together.</p><p>Once a page is loaded, it is <em>attached</em> to the current request. Remember that there will be many threads, each handling its own request to the same page.</p><p>At the end of a request, after a response has been sent to the client, the page is <em>detached</em> from the request. This is a chance to perform any cleanup needed for the page.</p><p>As with <a shape="rect" href="component-rendering.html">component rendering</a>, you have the ability to make your components "aware" of these events by identifying methods to be invoked.</p><p>Page life cycle met
hods should take no parameters and return void.</p><p>You have the choice of attaching an annotation to a method, or simply using the method naming conventions:</p><div class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1" rowspan="1" class="confluenceTh"><p>Annotation</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>Method Name</p></th><th colspan="1" rowspan="1" class="confluenceTh"><p>When Called</p></th></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>@<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PageLoaded.html">PageLoaded</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>pageLoaded()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After the page is fully loaded</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>@<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapest
ry5/annotations/PageAttached.html">PageAttached</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>pageAttached()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After the page is attached to the request.</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p>@<a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PageDetached.html">PageDetached</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>pageDetached()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>AFter the page is detached from the request.</p></td></tr></tbody></table></div><h2 id="PageLifeCycle-ComparisontoJavaServerPages">Comparison to JavaServer Pages</h2><p>JSPs also act as singletons. However, the individual JSP tags are pooled.</p><p>This is one of the areas where Tapestry can significantly outperform JSPs. Much of the code inside a compiled JSP class concerns getting tags from a tag pool
, configuring the properties of the tag instance, using the tag instance, then cleaning up the tag instance and putting it back in the pool.</p><p>The operations Tapestry does once per request are instead executed dozens or potentially hundreds of times (depending the complexity of the page, and if any nested loops occur).</p><p>Pooling JSP tags is simply the wrong granularity.</p><p>Tapestry can also take advantage of its more coarse grained caching to optimize how data moves, via parameters, between components. This means that Tapestry pages will actually speed up after they render the first time.</p><h2 id="PageLifeCycle-PagePoolConfiguration">Page Pool Configuration</h2> <div class="aui-message warning shadowed information-macro">
<span class="aui-icon icon-warning">Icon</span>
<div class="message-content">
- <p>As of 5.2, Tapestry does <em>not</em> employ page pooling by default</p>
+ <p>This related to versions of Tapestry prior to 5.2. Modern Tapestry uses an alternate approach that allows a single page instance to be shared across many request processing threads.</p>
</div>
</div>
-
-
-<p>In Tapestry 5.0 and 5.1, a page pool is used to store page instances. The pool is "keyed" on the name of the page (such as "start") and the <em>locale</em> for the page (such as "en" or "fr").</p>
-
-<p>Within each key, Tapestry tracks the number of page instances that have been created, as well as the number that are in use (currently attached to a request).</p>
-
-<p>When a page is first accessed in a request, it is taken from the pool. Tapestry has some <a shape="rect" href="configuration.html">configuration values</a> that control the details of how and when page instances are created.</p>
-
-<ul><li>If a free page instance is available, the page is marked in use and attached to the request.</li><li>If there are fewer page instances than the <em>soft limit</em>, then a new page instance is simply created and attached to the request.</li><li>If the soft limit has been reached, Tapestry will wait for a short period of time for a page instance to become available before creating a new page instance.</li><li>If the hard limit has been reached, Tapestry will throw an exception rather than create a new page instance.</li><li>Otherwise, Tapestry will create a new page instance.<br clear="none">
-Thus a busy application will initially create pages up-to the soft limit (which defaults to five page instances). If the application continues to be pounded with requests, it will slow its request processing, using the soft wait time in an attempt to reuse an existing page instance.</li></ul>
-
-
-<p>A truly busy application will continue to create new page instances as needed until the hard limit is reached.</p>
-
-<p>Remember that all these configuration values are per key: the combination of page name and locale. Thus even with a hard limit of 20, you may eventually find that Tapestry has created 20 start page instances for locale "en" <em>and</em> 20 start page instances for locale "fr" (if your application is configured to support both English and French). Likewise, you may have 20 instances for the start page, and 20 instances for the newaccount page.</p>
-
-<p>Tapestry periodically checks its cache for page instances that have not been used recently (within a configurable window). Unused page instances are release to the garbage collector.</p>
-
-<p>The end result is that you have quite a degree of tuning control over the process. If memory is a limitation and throughput can be sacrificed, try lowering the soft and hard limit and increasing the soft wait.</p>
-
-<p>If performance is absolute and you have lots of memory, then increase the soft and hard limit and reduce the soft wait. This encourages Tapestry to create more page instances and not wait as long to re-use existing instances.</p></div>
+<p>In Tapestry 5.0 and 5.1, a page pool is used to store page instances. The pool is "keyed" on the name of the page (such as "start") and the <em>locale</em> for the page (such as "en" or "fr").</p><p>Within each key, Tapestry tracks the number of page instances that have been created, as well as the number that are in use (currently attached to a request).</p><p>When a page is first accessed in a request, it is taken from the pool. Tapestry has some <a shape="rect" href="configuration.html">configuration values</a> that control the details of how and when page instances are created.</p><ul><li>If a free page instance is available, the page is marked in use and attached to the request.</li><li>If there are fewer page instances than the <em>soft limit</em>, then a new page instance is simply created and attached to the request.</li><li>If the soft limit has been reached, Tapestry will wait for a short period of time for a page instance to become available before creating a new page
instance.</li><li>If the hard limit has been reached, Tapestry will throw an exception rather than create a new page instance.</li><li>Otherwise, Tapestry will create a new page instance.<br clear="none"> Thus a busy application will initially create pages up-to the soft limit (which defaults to five page instances). If the application continues to be pounded with requests, it will slow its request processing, using the soft wait time in an attempt to reuse an existing page instance.</li></ul><p>A truly busy application will continue to create new page instances as needed until the hard limit is reached.</p><p>Remember that all these configuration values are per key: the combination of page name and locale. Thus even with a hard limit of 20, you may eventually find that Tapestry has created 20 start page instances for locale "en" <em>and</em> 20 start page instances for locale "fr" (if your application is configured to support both English and French). Likewise, you may have 20 inst
ances for the start page, and 20 instances for the newaccount page.</p><p>Tapestry periodically checks its cache for page instances that have not been used recently (within a configurable window). Unused page instances are release to the garbage collector.</p><p>The end result is that you have quite a degree of tuning control over the process. If memory is a limitation and throughput can be sacrificed, try lowering the soft and hard limit and increasing the soft wait.</p><p>If performance is absolute and you have lots of memory, then increase the soft and hard limit and reduce the soft wait. This encourages Tapestry to create more page instances and not wait as long to re-use existing instances.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/page-navigation.html
==============================================================================
--- websites/production/tapestry/content/page-navigation.html (original)
+++ websites/production/tapestry/content/page-navigation.html Fri Apr 3 18:19:36 2015
@@ -92,7 +92,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="request-processing.html">Request Processing</a>
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
</div>
@@ -101,7 +101,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
+ <a shape="rect" href="component-events.html">Component Events</a>
</div>
@@ -110,7 +110,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-rendering.html">Component Rendering</a>
+ <a shape="rect" href="request-processing.html">Request Processing</a>
</div>
@@ -119,7 +119,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-navigation.html">Page Navigation</a>
+ <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
</div>
@@ -128,7 +128,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-events.html">Component Events</a>
+ <a shape="rect" href="page-navigation.html">Page Navigation</a>
</div>
@@ -156,7 +156,7 @@ public Object onAction(){
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public Object onAction(){
return new HttpError(302, "The Error message);
}]]></script>
-</div></div><h3 id="PageNavigation-6.Linkresponse">6. Link response</h3><p>An event handler method may return a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a> instance directly. The Link is converted into a URL and a client redirect to that URL is sent to the client.</p><p>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">ComponentResources</a> object that is injected into your pages (and components) has methods for creating component event and page render links.</p><h3 id="PageNavigation-7.Streamresponse">7. Stream response</h3><p>An event handler can also return a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a> object, which encapsulates a stream to be sent directly to the client browser. This is useful for components
that want to, say, generate an image or PDF and provide it to the client.</p><h3 id="PageNavigation-8.URLresponse">8. URL response</h3><p>A java.net.URL response is handled as a client redirect to an external URL. (In Tapestry 5.3.x and earlier this only works for non-Ajax requests.)</p><h3 id="PageNavigation-9.Objectresponse">9. Object response</h3><p>Any other type of object returned from an event handler method is an error.</p><h2 id="PageNavigation-PageRenderRequests">Page Render Requests</h2><p>Render requests are simpler in structure and behavior than component event requests. In the simplest case, the URL is simply the logical name of the page.</p><p>Pages may have an <em>activation context</em>. The activation context represents persistent information about the state of the page. In practical terms, the activation context is usually the id of some database-persistent object.</p><p>When a page has an activation context, the values of the context are appended to the URL path.
</p><p>Not all pages have an activation context.</p><p>The activation context may be explicitly set when the render request link is created (the PageLink component has a context parameter for this purpose). When no explicit activation context is provided, the page itself is queried for its activation context.</p><p>This querying takes the form of an event trigger. The event name is "passivate" (as we'll see shortly, there's a corresponding "activate"). The return value of the method is used as the context. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="PageNavigation-6.Linkresponse">6. Link response</h3><p>An event handler method may return a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Link.html">Link</a> instance directly. The Link is converted into a URL and a client redirect to that URL is sent to the client.</p><p>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">ComponentResources</a> object that is injected into your pages (and components) has methods for creating component links.</p><p>The <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/PageRenderLinkSource.html">PageRenderLinkSource</a> service can be injected to allow links to other pages to be created (though that is rarely necessary, given the other options listed above).</p><h3 id="PageNavigation-7.Streamresponse">7. Stream resp
onse</h3><p>An event handler can also return a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a> object, which encapsulates a stream to be sent directly to the client browser. This is useful for components that want to, say, generate an image or PDF and provide it to the client.</p><h3 id="PageNavigation-8.URLresponse">8. URL response</h3><p>A java.net.URL response is handled as a client redirect to an external URL. (In Tapestry 5.3.x and earlier this only works for non-Ajax requests.)</p><h3 id="PageNavigation-9.Objectresponse">9. Object response</h3><p>Any other type of object returned from an event handler method is an error.</p><h2 id="PageNavigation-PageRenderRequests">Page Render Requests</h2><p>Render requests are simpler in structure and behavior than component event requests. In the simplest case, the URL is simply the logical name of the page.</p><p>Pages may have an <em>activ
ation context</em>. The activation context represents persistent information about the state of the page. In practical terms, the activation context is usually the id of some database-persistent object.</p><p>When a page has an activation context, the values of the context are appended to the URL path.</p><p>Not all pages have an activation context.</p><p>The activation context may be explicitly set when the render request link is created (the PageLink component has a context parameter for this purpose). When no explicit activation context is provided, the page itself is queried for its activation context.</p><p>This querying takes the form of an event trigger. The event name is "passivate" (as we'll see shortly, there's a corresponding "activate"). The return value of the method is used as the context. For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[public class ProductDetail
{
private Product product;
Modified: websites/production/tapestry/content/request-processing.html
==============================================================================
--- websites/production/tapestry/content/request-processing.html (original)
+++ websites/production/tapestry/content/request-processing.html Fri Apr 3 18:19:36 2015
@@ -67,9 +67,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><h1 id="RequestProcessing-RequestProcessing">Request Processing</h1>
-
-<div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><h1 id="RequestProcessing-RequestProcessing">Request Processing</h1><div class="navmenu" style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -85,7 +83,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="request-processing.html">Request Processing</a>
+ <a shape="rect" href="component-rendering.html">Component Rendering</a>
</div>
@@ -94,7 +92,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
+ <a shape="rect" href="component-events.html">Component Events</a>
</div>
@@ -103,7 +101,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-rendering.html">Component Rendering</a>
+ <a shape="rect" href="request-processing.html">Request Processing</a>
</div>
@@ -112,7 +110,7 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="page-navigation.html">Page Navigation</a>
+ <a shape="rect" href="page-life-cycle.html">Page Life Cycle</a>
</div>
@@ -121,92 +119,12 @@
<span class="icon icon-page" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect" href="component-events.html">Component Events</a>
+ <a shape="rect" href="page-navigation.html">Page Navigation</a>
</div>
</li></ul>
-</div>
-
-<p>Understanding the request processing pipeline is very important, as it is one of the chief extension points for Tapestry.</p>
-
-<p>Much of the early stages of processing are in the form of extensible <a shape="rect" href="pipelinebuilder-service.html">pipelines</a>.</p>
-
-<h2 id="RequestProcessing-TapestryFilter">Tapestry Filter</h2>
-
-<p>All incoming requests originate with the TapestryFilter, which is configured inside the application's <a shape="rect" href="configuration.html">web.xml</a>.</p>
-
-<p>The TapestryFilter is responsible for a number of startup and initialization functions.</p>
-
-<p>When it receives a request, the TapestryFilter obtains the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpServletRequestHandler.html">HttpServletRequestHandler</a> service, and invokes its service() method.</p>
-
-<h2 id="RequestProcessing-HttpServletRequestHandlerPipeline">HttpServletRequestHandler Pipeline</h2>
-
-<p>This pipeline performs initial processing of the request. It can be extended by contributing a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpServletRequestFilter.html">HttpServletRequestFilter</a> into the HttpServletRequestHandler service's configuration.</p>
-
-<p>Tapestry does not contribute any filters into this pipeline of its own.</p>
-
-<p>The terminator for the pipeline does two things:</p>
-
-<ul><li>It stores the request and response into the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html">RequestGlobals</a> service. This is a threaded service that stores per-thread/per-request information.</li><li>It wraps the request and response as a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Request.html">Request</a> and <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Response.html">Response</a>, and passes them into the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestHandler.html">RequestHandler</a> pipeline.</li></ul>
-
-
-<h2 id="RequestProcessing-RequestHandlerPipeline">RequestHandler Pipeline</h2>
-
-<p>This pipeline is where most extensions related to requests take place. Request represents an abstraction on top of HttpServletRequest. (Primarily, this exists to bridge from the Servlet API objects to the corresponding Tapestry objects. This is the basis for the planned portlet integration for Tapestry.) Where other code and services within Tapestry require access to information in the request, such as query parameters, that information is obtained from the Request (or Response) objects.</p>
-
-<p>The RequestHandler pipeline includes a number of built-in filters:</p>
-
-<ul><li>CheckForUpdates is responsible for <a shape="rect" href="class-reloading.html">class and template reloading</a>.</li><li>Localization identifies the <a shape="rect" href="localization.html">locale for the user</a>.</li><li>StaticFiles checks for URLs that are for static files (files that exist inside the web context) and aborts the request, so that the servlet container can handle the request normally.</li><li>ErrorFilter catches uncaught exceptions from the lower levels of Tapestry and presents the exception report page. This involves the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html">RequestExceptionHandler</a> service, which is responsible for initializing and rendering the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/pages/ExceptionReport.html">core/ExceptionReport</a> page.</li></ul>
-
-
-<p>The terminator for this pipeline stores the Request and the Response into RequestGlobals, then requests that the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Dispatcher.html">MasterDispatcher</a> service figure out how to handle the request (if it is, indeed, a Tapestry request).</p>
-
-<h2 id="RequestProcessing-MasterDispatcherService">Master Dispatcher Service</h2>
-
-<p>The MasterDispatcher service is a chain-of-command, aggregating together (in a specific order), several Dispatcher objects. Each Dispatcher is built to recognize and process a particular kind of URL.</p>
-
-<h3 id="RequestProcessing-RootPathDispatcher">RootPath Dispatcher</h3>
-
-<p>The RootPath Dispatcher recognizes a request for the application root (i.e., "/") and handles this the same as a render request for the "Start" page. Support for the Start page is kept for legacy purposes. Index pages are the correct approach.</p>
-
-<h3 id="RequestProcessing-AssetDispatcher">Asset Dispatcher</h3>
-
-<p>Requests that begin with "/assets/" are references to <a shape="rect" href="assets.html">asset resources</a> that are stored on the classpath, inside the Tapestry JARs (or perhaps inside the JAR for a component library). The contents of the file will be delivered to the client browser as a byte stream. This dispatcher also handles requests that are simply polling for a change to the file.</p>
-
-<h3 id="RequestProcessing-PageRenderDispatcher">PageRender Dispatcher</h3>
-
-<p>Page render requests are requests to render a particular page. Such requests may include additional elements on the path, which will be treated as activation context (see ComponentEvent Dispatcher below). Generally speaking, the activation context is the primary key of some related entity object. This allows the page to reconstruct the state it will need to successfully render itself.</p>
-
-<p>The event handler method for the activate event may return a value; this is treated the same as the return value from a component action request; typically this will result in a redirect to another page. In this way, the activate event can perform simple validation at the page level ("can the user see this page?").</p>
-
-<p>Page render URLs consist of the logical name of the page plus additional path elements for the activation context. The dispatcher here strips terms off of the path until it finds a known page name. Thus, "/mypage/27" would look first for a page whose name was "mypage/27", then look for a page name "mypage". Assuming the second search was successful, the page would be activated with the context "27". If no logical page name can be identified, control passes to the next dispatcher.</p>
-
-<h3 id="RequestProcessing-ComponentEventDispatcher">ComponentEvent Dispatcher</h3>
-
-<p>The ComponentEvent dispatcher is used to trigger events in components.</p>
-
-<p>The URL identifies the name of the page, then a series of component ids (the path from the page down to the specific component), then the name of the event to be triggered on the component. The remaining path elements are used as the context for the <em>event</em> (not for the page activation, which does not currently apply). For example, "/griddemo.FOO.BAR/3" would locate page "griddemo", then component "FOO.BAR", and trigger an event named "action" (the default event type, which is omitted from the URL), with the context "3".</p>
-
-<p>If the page in question has an activation context, it is supplied as an additional query parameter on the link.</p>
-
-<p>In cases where the event type is not the default, "action", it will appear between the nested component id and the event context, preceded by a colon. Example: "/example/foo.bar:magic/99" would trigger an event of type "magic". This is not common in the vanilla Tapestry framework, but will likely be more common as Ajax features (which would not use the normal request logic) are implemented.</p>
-
-<p>The response from a component action request is typically, but not universally, used to send a redirect to the client; the redirect URL is a page render URL to display the response to the event. This is detailed under <a shape="rect" href="page-navigation.html">page navigation</a>.</p>
-
-<h2 id="RequestProcessing-RequestGlobalsService">RequestGlobals Service</h2>
-
-<p>The RequestGlobals service has a life cycle of per-thread; this means that a separate instance exists for every thread, and therefore, for every request. The terminators of the two handler pipelines store the request/response pairs into the RequestGlobals service.</p>
-
-<h2 id="RequestProcessing-RequestService">Request Service</h2>
-
-<p>The Request service is a <a shape="rect" href="shadowbuilder-service.html">shadow</a> of the RequestGlobals services' request property. That is, any methods invoked on this service are delegated to the request object stored inside the RequestGlobals.</p>
-
-<h2 id="RequestProcessing-Overview">Overview</h2>
-
-<p>The following diagram provides an overview of how the different pipelines, filters and dispatchers interact when processing an incoming request.</p>
-
-<p><img class="confluence-embedded-image confluence-content-image-border" src="request-processing.data/tapestry_request_processing_800.png" data-image-src="/confluence/download/attachments/22872133/tapestry_request_processing_800.png?version=1&modificationDate=1299128361000&api=v2"></p></div>
+</div><p>Understanding the request processing pipeline is very important, as it is one of the chief extension points for Tapestry.</p><p>Much of the early stages of processing are in the form of extensible <a shape="rect" href="pipelinebuilder-service.html">pipelines</a>.</p><h2 id="RequestProcessing-TapestryFilter">Tapestry Filter</h2><p>All incoming requests originate with the TapestryFilter, which is configured inside the application's <a shape="rect" href="configuration.html">web.xml</a>.</p><p>The TapestryFilter is responsible for a number of startup and initialization functions.</p><p>When it receives a request, the TapestryFilter obtains the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpServletRequestHandler.html">HttpServletRequestHandler</a> service, and invokes its service() method.</p><h2 id="RequestProcessing-HttpServletRequestHandlerPipeline">HttpServletRequestHandler Pipeline</h2><p>This pipelin
e performs initial processing of the request. It can be extended by contributing a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/HttpServletRequestFilter.html">HttpServletRequestFilter</a> into the HttpServletRequestHandler service's configuration.</p><p>Tapestry does not contribute any filters into this pipeline of its own.</p><p>The terminator for the pipeline does two things:</p><ul><li>It stores the request and response into the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html">RequestGlobals</a> service. This is a per-thread scoped service that stores per-thread/per-request information.</li><li>It wraps the request and response as a <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Request.html">Request</a> and <a shape="rect" class="external-link" href="h
ttp://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Response.html">Response</a>, and passes them into the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestHandler.html">RequestHandler</a> pipeline.</li></ul><h2 id="RequestProcessing-RequestHandlerPipeline">RequestHandler Pipeline</h2><p>This pipeline is where most extensions related to requests take place. Request represents an abstraction on top of HttpServletRequest. (Primarily, this exists to bridge from the Servlet API objects to the corresponding Tapestry objects. This is the basis for the planned portlet integration for Tapestry.) Where other code and services within Tapestry require access to information in the request, such as query parameters, that information is obtained from the Request (or Response) objects.</p><p>The RequestHandler pipeline includes a number of built-in filters:</p><ul><li>CheckForUpdates is responsible for <a
shape="rect" href="class-reloading.html">class and template reloading</a>.</li><li>Localization identifies the <a shape="rect" href="localization.html">locale for the user</a>.</li><li>StaticFiles checks for URLs that are for static files (files that exist inside the web context) and aborts the request, so that the servlet container can handle the request normally.</li><li>ErrorFilter catches uncaught exceptions from the lower levels of Tapestry and presents the exception report page. This involves the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestExceptionHandler.html">RequestExceptionHandler</a> service, which is responsible for initializing and rendering the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/pages/ExceptionReport.html">core/ExceptionReport</a> page.</li></ul><p>The terminator for this pipeline stores the Request and the R
esponse into RequestGlobals, then requests that the <a shape="rect" class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Dispatcher.html">MasterDispatcher</a> service figure out how to handle the request (if it is, indeed, a Tapestry request).</p><h2 id="RequestProcessing-MasterDispatcherService">Master Dispatcher Service</h2><p>The MasterDispatcher service is a chain-of-command, aggregating together (in a specific order), several Dispatcher objects. Each Dispatcher is built to recognize and process a particular kind of URL.</p><h3 id="RequestProcessing-RootPathDispatcher">RootPath Dispatcher</h3><p>The RootPath Dispatcher recognizes a request for the application root (i.e., "/") and handles this the same as a render request for the "Start" page. Support for the Start page is kept for legacy purposes. Index pages are the correct approach.</p><h3 id="RequestProcessing-AssetDispatcher">Asset Dispatcher</h3><p>Requests that begin with "/a
ssets/" are references to <a shape="rect" href="assets.html">asset resources</a> that are stored on the classpath, inside the Tapestry JARs (or perhaps inside the JAR for a component library). The contents of the file will be delivered to the client browser as a byte stream. This dispatcher also handles requests that are simply polling for a change to the file.</p><h3 id="RequestProcessing-PageRenderDispatcher">PageRender Dispatcher</h3><p>Page render requests are requests to render a particular page. Such requests may include additional elements on the path, which will be treated as activation context (see ComponentEvent Dispatcher below). Generally speaking, the activation context is the primary key of some related entity object. This allows the page to reconstruct the state it will need to successfully render itself.</p><p>The event handler method for the activate event may return a value; this is treated the same as the return value from a component action request; typically thi
s will result in a redirect to another page. In this way, the activate event can perform simple validation at the page level ("can the user see this page?").</p><p>Page render URLs consist of the logical name of the page plus additional path elements for the activation context. The dispatcher here strips terms off of the path until it finds a known page name. Thus, "/mypage/27" would look first for a page whose name was "mypage/27", then look for a page name "mypage". Assuming the second search was successful, the page would be activated with the context "27". If no logical page name can be identified, control passes to the next dispatcher.</p><h3 id="RequestProcessing-ComponentEventDispatcher">ComponentEvent Dispatcher</h3><p>The ComponentEvent dispatcher is used to trigger events in components.</p><p>The URL identifies the name of the page, then a series of component ids (the path from the page down to the specific component), then the name of the event to be triggered on the comp
onent. The remaining path elements are used as the context for the <em>event</em> (not for the page activation, which does not currently apply). For example, "/griddemo.FOO.BAR/3" would locate page "griddemo", then component "FOO.BAR", and trigger an event named "action" (the default event type, which is omitted from the URL), with the context "3".</p><p>If the page in question has an activation context, it is supplied as an additional query parameter on the link.</p><p>In cases where the event type is not the default, "action", it will appear between the nested component id and the event context, preceded by a colon. Example: "/example/foo.bar:magic/99" would trigger an event of type "magic". This is not common in the vanilla Tapestry framework, but will likely be more common as Ajax features (which would not use the normal request logic) are implemented.</p><p>The response from a component action request is typically, but not universally, used to send a redirect to the client; the
redirect URL is a page render URL to display the response to the event. This is detailed under <a shape="rect" href="page-navigation.html">Page Navigation</a>.</p><h2 id="RequestProcessing-RequestGlobalsService">RequestGlobals Service</h2><p>The RequestGlobals service has a life cycle of per-thread; this means that a separate instance exists for every thread, and therefore, for every request. The terminators of the two handler pipelines store the request/response pairs into the RequestGlobals service.</p><h2 id="RequestProcessing-RequestService">Request Service</h2><p>The Request service is a <a shape="rect" href="shadowbuilder-service.html">shadow</a> of the RequestGlobals services' request property. That is, any methods invoked on this service are delegated to the request object stored inside the RequestGlobals.</p><h2 id="RequestProcessing-Overview">Overview</h2><p>The following diagram provides an overview of how the different pipelines, filters and dispatchers interact when pr
ocessing an incoming request.</p><p><img class="confluence-embedded-image confluence-content-image-border" src="request-processing.data/tapestry_request_processing_800.png" data-image-src="/confluence/download/attachments/22872133/tapestry_request_processing_800.png?version=1&modificationDate=1299128361000&api=v2"></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/security.html
==============================================================================
--- websites/production/tapestry/content/security.html (original)
+++ websites/production/tapestry/content/security.html Fri Apr 3 18:19:36 2015
@@ -112,7 +112,7 @@
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Contribute(ClientWhitelist.class)
public static void provideWhitelistAnalyzer(OrderedConfiguration<WhitelistAnalyzer> configuration)
{
- configuration.add("FooAnalyzer", new WhitelistAnalyzer()
+ configuration.add("MyCustomAnalyzer", new WhitelistAnalyzer()
{
public boolean isRequestOnWhitelist(Request request)
{
Modified: websites/production/tapestry/content/using-beaneditform-to-create-user-forms.html
==============================================================================
--- websites/production/tapestry/content/using-beaneditform-to-create-user-forms.html (original)
+++ websites/production/tapestry/content/using-beaneditform-to-create-user-forms.html Fri Apr 3 18:19:36 2015
@@ -197,7 +197,13 @@ DR=Dr.
<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[ @Validate("required,regexp=^\\d{5}(-\\d{4})?$")
public String zip;
]]></script>
-</div></div><p>Let's give it a try; restart the application and enter an "abc" for the zip code.</p><p><img class="confluence-embedded-image confluence-content-image-border" src="using-beaneditform-to-create-user-forms.data/address-v7.png" data-image-src="/confluence/download/attachments/23340431/address-v7.png?version=2&modificationDate=1417056608000&api=v2"><br clear="none">This is what you'll see after typing "abc" and clicking the Create Address button.</p><p>In any case, that's the right validation behavior, but it's the wrong message. Your users are not going to know or care about regular expressions.</p><p>Fortunately, it's easy to customize validation messages. All we need to know is the name of the property ("zip") and the name of the validator ("regexp"). We can then put an entry into the CreateAddress message catalog:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
+</div></div><p>Let's give it a try; restart the application and enter an "abc" for the zip code.</p><p><img class="confluence-embedded-image confluence-content-image-border" src="using-beaneditform-to-create-user-forms.data/address-v7.png" data-image-src="/confluence/download/attachments/23340431/address-v7.png?version=2&modificationDate=1417056608000&api=v2"><br clear="none">This is what you'll see after typing "abc" and clicking the Create Address button.</p> <div class="aui-message warning shadowed information-macro">
+ <span class="aui-icon icon-warning">Icon</span>
+ <div class="message-content">
+ <p>Modern browsers will automatically validate a regexp field when the form is submitted, as shown above. Older browsers do not have that automatic support, but will still validate input, using the same decorations as for the required fields in the previous screenshot.</p>
+ </div>
+ </div>
+<p>In any case, that's the right validation behavior, but it's the wrong message. Your users are not going to know or care about regular expressions.</p><p>Fortunately, it's easy to customize validation messages. All we need to know is the name of the property ("zip") and the name of the validator ("regexp"). We can then put an entry into the CreateAddress message catalog:</p><div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent panelContent">
<pre>zip-regexp-message=Zip Codes are five or nine digits. Example: 02134 or 90125-1655.
</pre>
</div></div><p>Refresh the page and submit again:</p><p><img class="confluence-embedded-image confluence-content-image-border" src="using-beaneditform-to-create-user-forms.data/address-v8.png" data-image-src="/confluence/download/attachments/23340431/address-v8.png?version=2&modificationDate=1417056608000&api=v2"></p><p>This trick isn't limited to just the regexp validator, it works equally well with <em>any</em> validator.</p><p>Let's go one step further. Turns out, we can move the regexp pattern to the message catalog as well. If you only provide the name of the validator in the @Validate annotation, Tapestry will search the containing page's message catalog of the constraint value, as well as the validation message. The constraint value for the regexp validator is the regular expression to match against.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">