You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2020/01/11 16:19:53 UTC
svn commit: r1055136 [1/2] - in /websites/production/tapestry/content:
cache/main.pageCache component-rendering.html content-type-and-markup.html
dom.html https.html request-processing.html response-compression.html
security.html url-rewriting.html
Author: buildbot
Date: Sat Jan 11 16:19:52 2020
New Revision: 1055136
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-rendering.html
websites/production/tapestry/content/content-type-and-markup.html
websites/production/tapestry/content/dom.html
websites/production/tapestry/content/https.html
websites/production/tapestry/content/request-processing.html
websites/production/tapestry/content/response-compression.html
websites/production/tapestry/content/security.html
websites/production/tapestry/content/url-rewriting.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-rendering.html
==============================================================================
--- websites/production/tapestry/content/component-rendering.html (original)
+++ websites/production/tapestry/content/component-rendering.html Sat Jan 11 16:19:52 2020
@@ -84,11 +84,13 @@
+
+
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="content-type-and-markup.html">Content Type and Markup</a>
@@ -97,34 +99,34 @@
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="page-navigation.html">Page Navigation</a>
+ <a href="component-rendering.html">Component Rendering</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="page-life-cycle.html">Page Life Cycle</a>
+ <a href="request-processing.html">Request Processing</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-rendering.html">Component Rendering</a>
+ <a href="page-life-cycle.html">Page Life Cycle</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="component-events.html">Component Events</a>
@@ -133,19 +135,19 @@
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-events-faq.html">Component Events FAQ</a>
+ <a href="page-navigation.html">Page Navigation</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="request-processing.html">Request Processing</a>
+ <a href="component-events-faq.html">Component Events FAQ</a>
</div>
@@ -153,8 +155,8 @@
</div>
-<h2 id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The rendering of each component is divided into a number of phases, illustrated below.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"></span><br clear="none"> Each of the orange phases (SetupRender, BeginRender, BeforeRenderBody, etc.) corresponds to an annotation you may place on one or more methods of your class. The annotation directs Tapestry to invoke your method as part of that phase.</p><p>Methods marked with these annotations are called <strong>render phase methods</strong>.</p><p>Your methods may be void, or r
eturn a boolean value. Returning a value can force phases to be skipped, or even be re-visited. In the diagram, solid lines show the normal processing path. Dashed lines are alternate flows that are triggered when your render phase methods return false instead of true (or void).</p><p>Render phase methods may take no parameters, or may take a parameter of type <a href="dom.html">MarkupWriter</a>. The methods can have any visibility you like ... typically, package private is used, as this visibility makes it possible to unit test your code (from within the same Java package) without making the methods part of the component's <em>public</em> API.</p><p>All Render phase methods are <em>optional</em>; a default behavior is associated with each phase.</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><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">@SetupRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if any, are needed</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender">@BeginRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestr
y.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate">@BeforeRenderTemplate</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody">@BeforeRenderBody</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody">@AfterRenderBody</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><
p>afterRenderBody()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry renders the body of the component, if any, but before the rest of the component's template is rendered</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate">@AfterRenderTemplate</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>afterRenderTemplate()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry finishes rendering the component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender">@AfterRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tap
estry has finished rendering both the template and body of the component</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender">@CleanupRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When final cleanup actions, if any, are needed</p></td></tr></tbody></table></div><p>The large number of phases reflects the need for precise control of components from <a href="component-mixins.html">component mixins</a>. Several of the phases exist almost exclusively for mixins.</p><p>Generally, your code will use the SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just one or two of those.</p><h2 id="ComponentRendering-AnExample">An Example</h2><p>Here's the source for a looping component that counts up or down between two va
lues, renders its body a number of times, and stores the current index value in a parameter:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.app.components;
+<h2 id="ComponentRendering-RenderingPhases">Rendering Phases</h2><p>The rendering of each component is divided into a number of phases, illustrated below.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="component-rendering.data/tapestry_render_phases.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/21792222/tapestry_render_phases.png?version=3&modificationDate=1381833043000&api=v2"></span><br clear="none">Each of the orange phases (SetupRender, BeginRender, BeforeRenderBody, etc.) corresponds to an annotation you may place on one or more methods of your class. The annotation directs Tapestry to invoke your method as part of that phase.</p><p>Methods marked with these annotations are called <strong>render phase methods</strong>.</p><p>Your methods may be void, or return a boolean value. Returning a value can force phases to be skipped, or even be re-visited. In the diagr
am, solid lines show the normal processing path. Dashed lines are alternate flows that are triggered when your render phase methods return false instead of true (or void).</p><p>Render phase methods may take no parameters, or may take a parameter of type <a href="dom.html">MarkupWriter</a>. The methods can have any visibility you like ... typically, package private is used, as this visibility makes it possible to unit test your code (from within the same Java package) without making the methods part of the component's <em>public</em> API.</p><p>All Render phase methods are <em>optional</em>; a default behavior is associated with each phase.</p><div class="table-wrap"><table class="wrapped 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="confluenceT
d"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">@SetupRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>setupRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When initial setup actions, if any, are needed</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender">@BeginRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beginRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When Tapestry is ready for the component's start tag, if any, to be rendered</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate">@BeforeRenderTem
plate</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderTemplate()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody">@BeforeRenderBody</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>beforeRenderBody()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>Before Tapestry renders the body of the component, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody">@AfterRenderBody</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>afterRenderBody()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry rende
rs the body of the component, if any, but before the rest of the component's template is rendered</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderTemplate">@AfterRenderTemplate</a></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>afterRenderTemplate()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry finishes rendering the component's template, if any</p></td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender">@AfterRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>afterRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>After Tapestry has finished rendering both the template and body of the component</p></td></tr><tr><td colspa
n="1" rowspan="1" class="confluenceTd"><p><strong><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender">@CleanupRender</a></strong></p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>cleanupRender()</p></td><td colspan="1" rowspan="1" class="confluenceTd"><p>When final cleanup actions, if any, are needed</p></td></tr></tbody></table></div><p>The large number of phases reflects the need for precise control of components from <a href="component-mixins.html">component mixins</a>. Several of the phases exist almost exclusively for mixins.</p><p>Generally, your code will use the SetupRender, BeginRender, AfterRender and CleanupRender phases ... often just one or two of those.</p><h2 id="ComponentRendering-AnExample">An Example</h2><p>Here's the source for a looping component that counts up or down between two values, renders its body a number of times, and stores the current index value in a parameter:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
import org.apache.tapestry5.annotations.AfterRender;
@@ -210,7 +212,7 @@ public class Count
}
</pre>
</div></div><p>Returning false from next() causes Tapestry to re-run the BeginRender phase, and from there, re-render the component's body (this component does not have a template). Returning true transitions to the CleanupRender phase.</p><p>Notice how Tapestry adapts to your methods, as marked with the annotations. It also adapts in terms of parameters; the two annotated methods here did not perform any output, so they did not need a MarkupWriter.</p><p>What's really mind blowing is that the template and body of a component will often contain ... more components! That means that many different components will be in different phases of their own state machine.</p><h2 id="ComponentRendering-RenderPhasesinDetail">Render Phases in Detail</h2><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>The SetupRender phase
, like all render phases, occurs once for each rendering of the component. If the component is inside a looping component (<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Loop.html">Loop</a>, <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Grid.html">Grid</a>, etc.), then the SetupRender method will be called once for <em>each</em> iteration of the loop.</p></div></div><h3 id="ComponentRendering-SetupRender">SetupRender</h3><p>The SetupRender phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SetupRender.html">SetupRender</a>) is where you can perform any one-time per-render setup for your component. This is a good place to read component parameters and use them to set temporary instance variables.</p><h3 id="ComponentRendering-BeginRender">BeginRender</h3><p>The BeginRender phase (s
ee @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html">BeginRender</a>) occurs at the start of the rendering of the component. For components that render a tag, the start tag should be rendered here (the close tag should be rendered inside the AfterRender phase). The component can also prevent the template and/or body from being rendered by returning false.</p><p>Components may or may not have a template. If a component has a template, and the template includes a <body> element, then the BeforeRenderBody phase will be triggered (giving the component the option of rendering its body or not).</p><p>If a component does not have a <body> element in its template, then the BeforeRenderBody phase is not triggered.</p><p>If a component does not have a template, but does have a body, the BeforeRenderBody phase is still triggered.</p><p>If no methods are annotated with BeginRender, then no special output oc
curs during this phase, but the template (if present) or body (if no template is present, but the component has a body) will be rendered.</p><h3 id="ComponentRendering-BeforeRenderTemplate">BeforeRenderTemplate</h3><p>The BeforeRenderTemplate phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderTemplate.html">BeforeRenderTemplate</a>) exists to allow a component to decorate its template (creating markup around the template generated markup), or to allow a component to skip its template.</p><h3 id="ComponentRendering-BeforeRenderBody">BeforeRenderBody</h3><p>The BeforeRenderBody phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeforeRenderBody.html">BeforeRenderBody</a>) is associated with a component's body (the portion of its container's template that the component occupies). The BeforeRenderBody phase allows the component the ability
to skip the body, while still rendering the rest of the component's template (if any).</p><p>If no methods are annotated with BeforeRenderBody, then the body will be rendered by default. Again, this occurs when the <body> element of the component's template is reached, or automatically if the component has no template (but the component does have a body).</p><h3 id="ComponentRendering-AfterRenderBody">AfterRenderBody</h3><p>The AfterRenderBody phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRenderBody.html">AfterRenderBody</a>) is executed after the body is rendered; this only occurs for components with a body.</p><h3 id="ComponentRendering-AfterRender">AfterRender</h3><p>The AfterRender phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/AfterRender.html">AfterRender</a>) complements BeginRender, and is often used to render the clos
e tag that matches the start tag rendered in the BeginRender phase. In any case, the AfterRender phase can continue on to CleanupRender, or revert back to BeginRender (as in our Count component example, above).</p><p>If no methods are annotated with AfterRender, then no special output occurs, and the CleanupRender phase is triggered.</p><h3 id="ComponentRendering-CleanupRender">CleanupRender</h3><p>The CleanupRender phase (see @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/CleanupRender.html">CleanupRender</a>) is the counterpart to SetupRender, allowing final cleanup to occur.</p><h2 id="ComponentRendering-UsingMethodNamesinsteadofAnnotations">Using Method Names instead of Annotations</h2><p>If you prefer to avoid using annotations on your methods, you may do so by providing specific names for your methods. The required method name is the annotation name, with the first character decapitalized: setupRender(), beginRender
(), etc. As with annotated render phase methods, Tapestry is flexible about visibility, return type and parameters.</p><p>Using this mechanism, the earlier example can be rewritten as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.app.components;
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">package org.example.app.components;
import org.apache.tapestry5.annotations.Parameter;
@@ -262,7 +264,7 @@ public class Count
}
</pre>
</div></div><p>This style is a trade off: on the gain side, the code is <em>even</em> simpler and shorter, and the method names will, by design, be more consistent from one class to the next. The down side is that the names are very generic, and may in some cases, be less descriptive than using annotated methods (<code>initializeValue()</code> and <code>next()</code> are, to some eyes, more descriptive).</p><p>You can, of course, mix and match, using specifically named render phase methods in some cases, and annotated render phase methods in other cases.</p><h2 id="ComponentRendering-RenderingComponents">Rendering Components</h2><p>Instead of returning true or false, a render phase method may return a component. The component may have been injected via the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Component.html">Component</a> annotation, or may have been passed to the owning component as a parameter.</p><p>In any ca
se, returning a component will queue that component to be rendered <strong>before</strong> the active component continues rendering.</p><p>The component to render may even be from a completely different page of the application.</p><p>Recursive rendering of components is not allowed.</p><p>This technique allows the rendering of Tapestry pages to be <em>highly</em> dynamic.</p><p>Returning a component instance does <strong>not</strong> short circuit method invocation (as described below), the way returning a boolean would. It is possible that multiple methods may return components (this is not advised – insanity may ensue).</p><h2 id="ComponentRendering-AdditionalReturnTypes">Additional Return Types</h2><p>Render phase methods may also return <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Blocks</a>, <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Renderable.html">Rendera
bles</a> or <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/runtime/RenderCommand.html">RenderCommands</a>.</p><p>The following component returns a Renderable in the BeginRender phase and skips the BeforeRenderTemplate phase:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public class OutputValueComponent
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">public class OutputValueComponent
{
@Parameter
private String value;
@@ -280,7 +282,7 @@ public class Count
}
</pre>
</div></div><h2 id="ComponentRendering-ShortCircuiting">Short Circuiting</h2><p>If a method returns a true or false value, this will short circuit processing. Other methods within the phase that would ordinarily be invoked will not be invoked.</p><p>Most render phase methods should return void, to avoid unintentionally short circuiting other methods for the same phase.</p><h2 id="ComponentRendering-MethodConflictsandOrdering">Method Conflicts and Ordering</h2><p>It is possible to have multiple methods that are annotated with the same render phase annotation. This may include methods in the same class, or a mix of method defined in a class and inherited from other classes.</p><h3 id="ComponentRendering-MixinsBeforeComponent">Mixins Before Component</h3><p>When a component has <a href="component-mixins.html">mixins</a>, then the mixins' render phase methods execute <em>before</em> the component's render phase methods. If a mixin extends from a base class, the mixin's parent class met
hods execute before the mixin subclass' render phase methods.</p><p>Exception: Mixins whose class is annotated with @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/MixinAfter.html">MixinAfter</a> are ordered <em>after</em> the component, not before.</p><p>The order in which the mixins of a given class (@MixinAfter or mixins before) execute is determined by the ordering constraints specified for the mixins. If no constraints are provided, the order is undefined. See <a href="component-mixins.html">Component Mixins</a> for more details.</p><h3 id="ComponentRendering-ParentsbeforeChild">Parents before Child</h3><p>Ordering is always parent-first. Methods defined in the parent class are always invoked before methods defined in the child class.</p><p>When a sub-class overrides an render phase method of a base class, the method is only invoked once, along with any other base class methods. The subclass can change the <em>implem
entation</em> of the base class method via an override, but can't change the <em>timing</em> of when that method is invoked. See <a class="external-link" href="https://issues.apache.org/jira/browse/TAPESTRY-2311">TAPESTRY-2311</a>.</p><h3 id="ComponentRendering-ReverseOrderingforAfterXXXandCleanupRender">Reverse Ordering for AfterXXX and CleanupRender</h3><p>The After_XXX_ phases exists to balance the Begin_XXX_ and Before_XXX_ phases. Often elements will be started inside an earlier phase and then the elements will be ended (closed) inside the corresponding After_XXX_ phase (with the body and template of the component rendering between).</p><p>In order to ensure that operations occur in the correct, and natural order, the render phase methods for these two stages are invoked in <em>reverse order</em>:</p><ul><li>Subclass methods</li><li>Parent class methods</li><li>Mixin subclass methods</li><li>Mixin parent class methods</li></ul><h3 id="ComponentRendering-WithinaSingleClass">Wit
hin a Single Class</h3><p>Currently, rendering methods having the same annotation within a single class are executed in alphabetical order by method name. Methods with the same name are ordered by number of parameters. Even so, annotating multiple methods with the same rendering phase is not a great idea. Instead, just define one method, and have it call the other methods in the order you desire.</p><h2 id="ComponentRendering-RenderingComments">Rendering Comments</h2><p>Starting with version 5.3, Tapestry can optionally emit rendering comments for all requests; these are comments such as <!--BEGIN Index:loop (context:Index.tml, line 15)--> that can assist you in debugging markup output on the client-side. This will significantly increase the size of the rendered markup, but can be very helpful with complex layouts to determine which component was responsible for which portion of the rendered page.</p><p>Rendering comments are only available when not running in <a href="config
uration.html">production mode</a>.</p><p>To turn on rendering comments for all requests, set the <a href="configuration.html">tapestry.component-render-tracing-enabled</a> configuration symbol to "true".</p><p>To turn on rendering comments only for a particular request, add the query parameter <code>t:component-trace=true</code> to the URL:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> http://www.example.com/myapp/mypage?t:component-trace=true
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> http://www.example.com/myapp/mypage?t:component-trace=true
</pre>
</div></div><p></p></div>
</div>
Modified: websites/production/tapestry/content/content-type-and-markup.html
==============================================================================
--- websites/production/tapestry/content/content-type-and-markup.html (original)
+++ websites/production/tapestry/content/content-type-and-markup.html Sat Jan 11 16:19:52 2020
@@ -67,7 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Tapestry reads <a href="component-templates.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p><ul><li>The <?xml?> XML declaration is omitted.</li><li>Most elements render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:<ul><li>br</li><li>hr</li><li>img</li></ul></li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul><p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response.</p><p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache
/tapestry5/annotations/Meta.html">@Meta</a> annotation.</p><h3 id="ContentTypeandMarkup-ContentType">Content Type</h3><p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p><p>A page may declare its content type using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html">ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p><h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3><p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one to four 8-bit bytes. Most western language characters (that is, typi
cal ASCII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p><p>In Tapestry, all pages use the same encoding. The default is "UTF-8", but this can be changed using the <a href="configuration.html">tapestry.charset configuration symbol</a>.</p></div>
+ <div id="ConfluenceContent"><p>Tapestry reads <a href="component-templates.html">well-formed XML template files</a> and renders its output as XML, with minor caveats:</p><ul><li>The <?xml?> XML declaration is omitted.</li><li>Most elements render with an open and close tag, even if empty.</li><li>Certain elements will be abbreviated to just the open tag, if empty:<ul><li>br</li><li>hr</li><li>img</li></ul></li><li><![CDATA[]> sections are <strong>not</strong> used</li></ul><p>This is all to ensure that the markup stream, while (almost) well formed, is still properly understood by browsers expecting ordinary HTML. In fact, Tapestry may decide to render a purely XML document; it depends on the content type of the response.</p><p>When Tapestry renders a page, the output content type and charset is obtained from meta data on the page itself. Meta data is specified using the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache
/tapestry5/annotations/Meta.html">@Meta</a> annotation.</p><h3 id="ContentTypeandMarkup-ContentType">Content Type</h3><p>The response content type is obtained via meta-data key <code>tapestry.response-content-type</code>. This value defaults to "text/html", which triggers specialized XML rendering.</p><p>A page may declare its content type using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/ContentType.html">ContentType</a> class annotation. Content types other than "text/html" will render as well-formed XML documents, including the XML declaration, and more standard behavior for empty elements.</p><h3 id="ContentTypeandMarkup-CharacterSet">Character Set</h3><p>The character set (aka character encoding) used when writing output and when parsing requests is normally "utf-8". UTF-8 is a version of Unicode where individual characters are encoded as one to four 8-bit bytes. Most western language characters (that is, typi
cal ASCII characters) are encoded in a single byte. Accented characters or non-western characters (such as Japanese, Arabic, etc.) may be encoded as two or more bytes.</p><p>In Tapestry, all pages use the same encoding. The default is "UTF-8", but this can be changed using the <a href="configuration.html">tapestry.charset configuration symbol</a>.</p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/dom.html
==============================================================================
--- websites/production/tapestry/content/dom.html (original)
+++ websites/production/tapestry/content/dom.html Sat Jan 11 16:19:52 2020
@@ -79,11 +79,11 @@
<h1 id="DOM-DOMClasses">DOM Classes</h1><p>The implementation of this DOM is part of Tapestry, despite the fact that several third-party alternatives exist. This represents a desire to limit dependencies for the framework, but also the Tapestry DOM is streamlined for initial creation, and a limited amount of subsequent modification. Most DOM implementations are more sophisticated than needed for Tapestry, with greater support for querying (often using XPath) and manipulation.</p><p>Once the Document object is created, you don't directly create new DOM objects; instead, each DOM object includes methods that create new sub-objects. This primarily applies to the Element class, which can be a container of text, comments and other elements.</p><h2 id="DOM-Document">Document</h2><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Document.html">Document</a> object represents the an entire document, which is to say, an entire response
to be sent to the client.</p><p>Documents will have a single root element. The newRootElement() method is used to create the root element for the document.</p><p>The Document class also has methods for setting and getting the DTD, adding comments and text, and finding an element based on a path of element names.</p><h2 id="DOM-Element">Element</h2><p>An <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/dom/Element.html">Element</a> object represents an element of the document. Elements may have attributes, and they may themselves contain other elements, as well as text and comments.</p><p>The Element class has methods for searching, traversing and manipulating the DOM after it is built.</p><h1 id="DOM-DOMManipulation/Rewriting">DOM Manipulation/Rewriting</h1><p>A powerful feature of Tapestry 5 is the ability to manipulate the structure and ordering of the DOM after it has been rendered. For example, this can be used to alter the output o
f a component that may otherwise be outside of your control.</p><p>DOM manipulation is surprisingly fast, too.</p><p>Methods on Node (and Element, which is a subclass of Node) allow an existing node to be moved relative to an Element. Nodes may be moved before or after the Element, or may be moved inside an Element at the top (the first child) or the bottom (the last child).</p><p>Element's <code>attribute</code> method adds a new attribute name/value pair to the Element. If an existing attribute with the specified name already exists, then then the new value is ignored. This has implications when different pieces of code try to add attributes to an Element ... the first to add an attribute will "win". Conversely, the <code>forceAttributes</code> method can be used to update or remove an attribute.</p><p>In addition, the children of an Element may be removed or a Node (and all of its children) removed entirely.</p><p>Finally, an Element may "pop": the Element is removed and replaced
with its children.</p><h1 id="DOM-MarkupWriter">MarkupWriter</h1><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/MarkupWriter.html">MarkupWriter interface</a> allows the structure of the document to be built while maintaining a streaming metaphor.</p><h2 id="DOM-element()andend()methods">element() and end() methods</h2><p>Calls to element() create a new element within the tree, and may provide attributes for the new element as well. Calls to write(), writeln() and writef() write text nodes within the current element. <em>Every call to element() should be matched with a call to end()</em>, which is used to move the current node up one level.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*");
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> writer.element("img", "src", "icon.png", "width", 20, "height", 20, alt, "*");
writer.end();
</pre>
</div></div><p>Note that end() must be called here, even though the <img> element is empty (has no body). If the call to end() is omitted, then later elements created by calls to element() will be nested <em>inside</em> the <img> element, which is not desired.</p><p>Again, <strong>every call to element() must be matched with a call to end()</strong>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.element("select", "name", "choice");
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> writer.element("select", "name", "choice");
for (String name : optionsNames)
{
@@ -95,10 +95,10 @@
writer.end();
</pre>
</div></div><h2 id="DOM-attributes()">attributes()</h2><p>Adds additional name/value pairs to the current element.</p><p>When a value is null, no attribute is added.</p><p>When a new name conflicts with an existing name, the new value is ignored. This gives precedence to the first value specified for an attribute over any subsequent value.</p><h2 id="DOM-write()">write()</h2><p>The write() method writes text inside the current element. It scans the provided text for XML control characters ('<', '>', and '&') and converts them to their XML entity equivalents ('&lt;', '&gt;', and '&amp;'). The result is correct, safe, HTML/XML output even when the content (which may come from a template, or from an external source such as a database) contains such problematic characters.</p><h2 id="DOM-writef()">writef()</h2><p>The writef() method formats an number of arguments. It uses a java.util.Formatter. It is a convenience for formatting that ultimately invokes write().</p>
<h2 id="DOM-writeRaw()">writeRaw()</h2><p>The writeRaw() method writes unfiltered text into the DOM. When the DOM is rendered to markup, the provided string is written to the output stream exactly as-is. Care should be taken, as this can easily result invalid markup, or even markup that is not well formed. It can also introduce XSS vulnerabilities if the text comes from end users without proper filtering.</p><h2 id="DOM-comment()">comment()</h2><p>Adds an XML comment. The comment delimiters will be supplied by Tapestry:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> writer.comment("Start of JS Menu code");
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> writer.comment("Start of JS Menu code");
</pre>
-</div></div></div>
+</div></div><p class="auto-cursor-target"></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/https.html
==============================================================================
--- websites/production/tapestry/content/https.html (original)
+++ websites/production/tapestry/content/https.html Sat Jan 11 16:19:52 2020
@@ -84,32 +84,34 @@
+
+
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="security-faq.html">Security FAQ</a>
+ <a href="https.html">HTTPS</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="https.html">HTTPS</a>
+ <a href="security.html">Security</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="security.html">Security</a>
+ <a href="security-faq.html">Security FAQ</a>
</div>
@@ -118,26 +120,26 @@
<p>Many applications will need to have some of their pages secured: only accessible via HTTPS. This could be a login page, or a product ordering wizard, or administrative pages.</p><p>All that is necessary to mark a page as secure is to add the @Secure annotation to the page class:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Secure
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">@Secure
public class ProcessOrder
{
. . .
}
</pre>
</div></div><p>When a page is marked as secure, Tapestry will ensure that access to that page uses HTTPS. All links to the page will use the "https" protocol.</p><p>If an attempt is made to access a secure page using a non-secure request (a normal HTTP request), Tapestry will send an HTTPS redirect to the client.</p><p>Links to non-secure pages from a secure page will do the reverse: a complete URL with an "http" protocol will be used. In other words, Tapestry manages the transition from insecure to secure and back again.</p><p>Links to other (secure) pages <em>and to assets</em> will be based on relative URLs and, therefore, secure.</p><p>The rationale behind using secure links to assets from secure pages is that it prevents the client web browser from reporting a mixed security level.</p><h2 id="HTTPS-SecuringMultiplePages">Securing Multiple Pages</h2><p>Rather than placing an @Secure annotation on individual pages, it is possible to enable https URL redirecting for entire folders
of pages. All pages in or beneath the folder will be secured.</p><p>This is accomplished by making a contribution to the MetaDataLocator service configuration. For example, to secure all pages in the "admin" folder:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
{
configuration.add("admin:" + MetaDataConstants.SECURE_PAGE, "true");
}
</pre>
</div></div><p>Here "admin" is the folder name, and the colon is a separator between the folder name and the the meta data key. SECURE_PAGE is a public constant for value "tapestry.secure-page";</p><p>When Tapestry is determining if a page is secure or not, it starts by checking for the @Secure annotation, then it consults the MetaDataLocator service.</p><p>If you want to make your entire application secure:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default">public void contributeMetaDataLocator(MappedConfiguration<String,String> configuration)
{
configuration.add(MetaDataConstants.SECURE_PAGE, "true");
}
</pre>
</div></div><p>With no colon, the meta data applies to the entire application (including any component libraries used in the application).</p><h2 id="HTTPS-BaseURLSupport">Base URL Support</h2><p>When Tapestry switches back and forth between secure and unsecure mode, it must create a full URL (rather than a relative URL) that identifies the protocol, server host name and perhaps even a port number.</p><p>That can be a stumbling point, especially the server host name. In a cluster, behind a fire wall, the server host name available to Tapestry, via the <code>HttpServletRequest.getServerName()</code> method, is often <em>not</em> the server name the client web browser sees ... instead it is the name of the internal server behind the firewall. The firewall server has the correct name from the web browser's point of view.</p><p>Because of this, Tapestry includes a hook to allow you to override how these default URLs are created: the BaseURLSource service.</p><p>The default implementatio
n is based on just the getServerName() method; it's often not the correct choice even for development.</p><p>Fortunately, it is very easy to override this implementation. Here's an example of an override that uses the default port numbers that the <a class="external-link" href="http://www.eclipse.org/jetty/" rel="nofollow">Jetty servlet container</a> uses for normal HTTP (port 8080) and for secure HTTPS (port 8443):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public static void contributeServiceOverride(MappedConfiguration<Class,Object> configuration)
+<pre class="syntaxhighlighter-pre" data-syntaxhighlighter-params="brush: java; gutter: false; theme: Default" data-theme="Default"> public static void contributeServiceOverride(MappedConfiguration<Class,Object> configuration)
{
BaseURLSource source = new BaseURLSource()
{
Modified: websites/production/tapestry/content/request-processing.html
==============================================================================
--- websites/production/tapestry/content/request-processing.html (original)
+++ websites/production/tapestry/content/request-processing.html Sat Jan 11 16:19:52 2020
@@ -76,38 +76,40 @@
+
+
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="page-navigation.html">Page Navigation</a>
+ <a href="component-rendering.html">Component Rendering</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="page-life-cycle.html">Page Life Cycle</a>
+ <a href="request-processing.html">Request Processing</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-rendering.html">Component Rendering</a>
+ <a href="page-life-cycle.html">Page Life Cycle</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="component-events.html">Component Events</a>
@@ -116,19 +118,19 @@
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="component-events-faq.html">Component Events FAQ</a>
+ <a href="page-navigation.html">Page Navigation</a>
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
- <a href="request-processing.html">Request Processing</a>
+ <a href="component-events-faq.html">Component Events FAQ</a>
</div>
@@ -136,7 +138,7 @@
</div>
-<p><strong>Request Processing</strong> involves a sequence of steps that Tapestry performs when every HTTP request comes in. You <em>don't need</em> to know these steps to use Tapestry productively, but understanding the request processing pipeline is helpful if you want to understand Tapestry deeply.</p><p>Much of the early stages of processing are in the form of extensible <a href="pipelinebuilder-service.html">pipelines</a>.</p><h2 id="RequestProcessing-TapestryFilter">Tapestry Filter</h2><p>All incoming requests originate with the TapestryFilter, which is a servlet filter configured inside your application's <a 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 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 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 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 class="external-link" href="http://tapestry.apache.org/cur
rent/apidocs/org/apache/tapestry5/services/Request.html">Request</a> and <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Response.html">Response</a>, and passes them into the <a 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 to allow for a possible 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 pipe
line includes a number of built-in filters:</p><ul><li>CheckForUpdates is responsible for <a href="class-reloading.html">class and template reloading</a>.</li><li>Localization identifies the <a 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 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 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 fo
r this pipeline stores the Request and the Response into RequestGlobals, then requests that the <a 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 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 re
quest; 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 t
riggered 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 redirec
t to the client; the redirect URL is a page render URL to display the response to the event. This is detailed under <a href="page-navigation.html">Request Processing</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 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 pro
cessing an incoming request.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border" alt="Request Processing" src="https://cwiki-test.apache.org/confluence/download/attachments/22872133/tapestry_request_processing_800.png?version=1&modificationDate=1299128361000&api=v2" data-image-src="https://cwiki-test.apache.org/confluence/download/attachments/22872133/tapestry_request_processing_800.png?version=1&modificationDate=1299128361000&api=v2"></span></p><p></p></div>
+<p><strong>Request Processing</strong> involves a sequence of steps that Tapestry performs when every HTTP request comes in. You <em>don't need</em> to know these steps to use Tapestry productively, but understanding the request processing pipeline is helpful if you want to understand Tapestry deeply.</p><p>Much of the early stages of processing are in the form of extensible <a href="pipelinebuilder-service.html">pipelines</a>.</p><h2 id="RequestProcessing-TapestryFilter">Tapestry Filter</h2><p>All incoming requests originate with the TapestryFilter, which is a servlet filter configured inside your application's <a 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 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 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 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 class="external-link" href="http://tapestry.apache.org/cur
rent/apidocs/org/apache/tapestry5/services/Request.html">Request</a> and <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Response.html">Response</a>, and passes them into the <a 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 to allow for a possible 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 pipe
line includes a number of built-in filters:</p><ul><li>CheckForUpdates is responsible for <a href="class-reloading.html">class and template reloading</a>.</li><li>Localization identifies the <a 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 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 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 fo
r this pipeline stores the Request and the Response into RequestGlobals, then requests that the <a 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 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 re
quest; 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 t
riggered 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 redirec
t to the client; the redirect URL is a page render URL to display the response to the event. This is detailed under <a href="page-navigation.html">Request Processing</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 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 pro
cessing an incoming request.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource confluence-content-image-border" alt="Request Processing" src="request-processing.data/tapestry_request_processing_800.png" data-image-src="https://cwiki.apache.org/confluence/download/attachments/22872133/tapestry_request_processing_800.png?version=1&modificationDate=1299128361000&api=v2"></span></p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/response-compression.html
==============================================================================
--- websites/production/tapestry/content/response-compression.html (original)
+++ websites/production/tapestry/content/response-compression.html Sat Jan 11 16:19:52 2020
@@ -76,11 +76,13 @@
+
+
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="request-processing.html">Request Processing</a>
@@ -89,7 +91,7 @@
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="configuration.html">Configuration</a>
@@ -98,7 +100,7 @@
</div>
</li><li>
<div>
- <span class="icon aui-icon aui-icon-small aui-iconfont-page-default" title="Page">Page:</span> </div>
+ <span class="icon aui-icon content-type-page" title="Page">Page:</span> </div>
<div class="details">
<a href="assets.html">Assets</a>
@@ -109,7 +111,7 @@
</div>
-<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><h1 id="ResponseCompression-CompressionConfiguration">Compression Configuration</h1><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 <a href="configuration.html"><code>tapestry.min-gzip-size</code></a> 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 re-compressed (they actually get larger, not smaller!). The service <a class="external-link" href="http://tapestry.apache.org/curren
t/apidocs/org/apache/tapestry5/services/ResponseCompressionAnalyzer.html">ResponseCompressionAnalyzer</a>'s configuration is an unordered collection of content type strings that should <em>not</em> be compressed. The default list of content types that are NOT compressed are:</p><ul><li>image/* (image/jpeg, image/png, image/gif, etc) <em>except</em> image/svg+xml, which is compressed</li><li>application/x-shockwave-flash</li><li>application/font-woff</li><li>application/x-font-ttf</li><li>application/vnd.ms-fontobj</li></ul><h1 id="ResponseCompression-StreamResponse">StreamResponse</h1><p>When returning a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a> from a <a href="component-events.html">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>
+<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><h1 id="ResponseCompression-CompressionConfiguration">Compression Configuration</h1><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 <a href="configuration.html"><code>tapestry.min-gzip-size</code></a> 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 re-compressed (they actually get larger, not smaller!). The service <a class="external-link" href="http://tapestry.apache.org/curren
t/apidocs/org/apache/tapestry5/services/ResponseCompressionAnalyzer.html">ResponseCompressionAnalyzer</a>'s configuration is an unordered collection of content type strings that should <em>not</em> be compressed. The default list of content types that are NOT compressed are:</p><ul><li>image/* (image/jpeg, image/png, image/gif, etc) <em>except</em> image/svg+xml, which is compressed</li><li>application/x-shockwave-flash</li><li>application/font-woff</li><li>application/x-font-ttf</li><li>application/vnd.ms-fontobj</li></ul><h1 id="ResponseCompression-StreamResponse">StreamResponse</h1><p>When returning a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/StreamResponse.html">StreamResponse</a> from a <a href="component-events.html">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><p></p></div>
</div>
<div class="clearer"></div>