Modified: websites/production/tapestry/content/release-process.html
==============================================================================
--- websites/production/tapestry/content/release-process.html (original)
+++ websites/production/tapestry/content/release-process.html Wed Sep 20
12:29:16 2017
@@ -27,6 +27,14 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -36,26 +44,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Release Process</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Release Process</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,14 +62,53 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h2
id="ReleaseProcess-Prerequisites">Prerequisites</h2><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "tapestry-dev" and space =
currentSpace()</parameter></rich-text-body><p>Before creating a release, ensure
that:</p><ul><li>You have <a class="external-link"
href="http://www.apache.org/dev/openpgp.html";>setup your own public OpenGPG key
signature</a> for signing the distribution</li><li>You can login to <a
class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a></li><li>You
have a Git workspace for <a class="external-link"
href="https://git-wip-us.apache.org/repos/asf/tapestry-5.git";>ht
tps://git-wip-us.apache.org/repos/asf/tapestry-5.git</a></li><li>You have a
Subversion workspace for <a class="external-link"
href="https://dist.apache.org/repos/dist/dev/tapestry";>https://dist.apache.org/repos/dist/dev/tapestry</a> (dev
archives workspace)</li><li>You have a Subversion workspace for <a
class="external-link"
href="https://dist.apache.org/repos/dist/release/tapestry";>https://dist.apache.org/repos/dist/release/tapestry</a> (release
archives workspace)</li><li>You have a Subversion workspace for <a
class="external-link"
href="https://svn.apache.org/repos/infra/websites/production/tapestry/content";>https://svn.apache.org/repos/infra/websites/production/tapestry/content</a> (site
content workspace)</li></ul><h2
id="ReleaseProcess-GITandDeploymentCredentials">GIT and Deployment
Credentials</h2><p>To successfully create a release, you will need to update
your Gradle settings with the credentials for your git user and the deployment
use
r. These credentials are stored in the Gradle configuration file
<code>~/.gradle/gradle.properties</code>:</p><plain-text-body>apacheDeployUserName=hlship
+ <div id="ConfluenceContent"><h2
id="ReleaseProcess-Prerequisites">Prerequisites</h2><div class="aui-label"
style="float:right" title="Related Articles"><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>
+ <div class="details">
+ <a href="building-tapestry-from-source.html">Building Tapestry from
Source</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="version-numbers.html">Version Numbers</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="developer-bible.html">Developer Bible</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="release-process.html">Release Process</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="developer-information.html">Developer Information</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="confluence-site-setup.html">Confluence Site Setup</a>
+ </div> </li></ul></div><p>Before creating a release, ensure
that:</p><ul><li>You have <a class="external-link"
href="http://www.apache.org/dev/openpgp.html";>setup your own public OpenGPG key
signature</a> for signing the distribution</li><li>You can login to <a
class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a></li><li>You
have a Git workspace for <a class="external-link"
href="https://git-wip-us.apache.org/repos/asf/tapestry-5.git";>https://git-wip-us.apache.org/repos/asf/tapestry-5.git</a></li><li>You
have a Subversion workspace for <a class="external-link"
href="https://dist.apache.org/repos/dist/dev/tapestry";>https://dist.apache.org/repos/dist/dev/tapestry</a> (dev
archives workspace)</li><li>You have a Subversion workspace for <a
class="external-link"
href="https://dist.apache.org/repos/dist/release/tapestry";>https://dist.apache.org/repos/dist/release/tapestry</a> (release
archives workspace)</
li><li>You have a Subversion workspace for <a class="external-link"
href="https://svn.apache.org/repos/infra/websites/production/tapestry/content";>https://svn.apache.org/repos/infra/websites/production/tapestry/content</a> (site
content workspace)</li></ul><h2
id="ReleaseProcess-GITandDeploymentCredentials">GIT and Deployment
Credentials</h2><p>To successfully create a release, you will need to update
your Gradle settings with the credentials for your git user and the deployment
user. These credentials are stored in the Gradle configuration file
<code>~/.gradle/gradle.properties</code>:</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;">apacheDeployUserName=hlship
apacheDeployPassword=...
signing.keyId=7CC19136
signing.secretKeyRingFile=.../.gnupg/secring.gpg
signing.password=...
-apacheArchivesFolder=.../tapestry-dev</plain-text-body><p>You can find your
keyId using <code>gpg --list-keys</code>.</p><p> The
apacheArchivesFolder should be the full path to your dev archives
workspace. The build will copy files to this folder; see further notes
below.</p><h2 id="ReleaseProcess-ReleaseSteps">Release Steps</h2><h3
id="ReleaseProcess-1.GeneratetheRelease">1. Generate the
Release</h3><ol><li>Update your workspace to the release branch<ol><li>For
current work, the release branch is <em>master</em></li><li>When creating
bug fix releases for older releases, the branch will match the release,
e.g., <em>5.3</em></li></ol></li><li><span style="line-height:
1.4285715;">Run the build using </span><code style="line-height:
1.4285715;">gradle generateRelease</code><br clear="none"><ol><li>This will
create, sign, and upload JAR files and other artifacts to the Nexus
repository</li><li>It will also create, sign, and copy the source, binary, and
doc
umentation archives to your dev archives workspace</li></ol></li><li>Tag the
release in Git, then push the changes up to the Apache
repository:<ol><li><code>git tag 5.x</code></li><li><code>git push
--tags</code></li></ol></li><li>Login to <a class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a> and <strong>close</strong> the
automatically created staging repository</li></ol><h3
id="ReleaseProcess-2.CommittheArchives">2. Commit the Archives</h3><ol><li>The
build will have copied archive files to your dist workspace</li><li><code>svn
add</code> the new files</li><li><code>svn commit</code> to copy the files up
to Apache (this is <em>slow</em>)<ol><li>Use the full version number as
the commit message, e.g., <em>5.4-beta-26</em></li></ol></li><li>You can
verify the files via the web: <a class="external-link"
href="https://dist.apache.org/repos/dist/dev/tapestry";>https://dist.apache.org/repos/dist/dev/tap
estry</a></li></ol><h3 id="ReleaseProcess-3.BumptheVersionNumber">3. Bump the
Version Number</h3><ol><li>Update <code>build.gradle</code> to
increment the version number</li><li>Increment the minor version number (inside
the tapestryVersion method, near the top of the file)</li><li><p>Commit and
push the changes</p></li></ol><h3 id="ReleaseProcess-4.SendVote">4. Send
Vote</h3><ol><li><span style="line-height: 1.4285715;">Send vote
email</span></li><li><span style="line-height: 1.4285715;"><strong>Wait 3
days</strong><br clear="none"></span></li><li><span style="line-height:
1.4285715;">The vote is successful if there are at least
three <strong>+1</strong>'s and more <strong>+1</strong> than
<strong>-1</strong></span></li><li><span style="line-height: 1.4285715;">Only
PMC members may cast binding votes</span></li></ol><h3
id="ReleaseProcess-5.UpdateJIRAandgeneratereleasenotes"><span>5. Update JIRA
and generate release notes</span><span style="line-height: 22.857143px;"
> </span></h3><ol><li><span>Use the </span><a class="external-link"
>href="https://issues.apache.org/jira/plugins/servlet/project-config/TAP5/versions";>Manage
> Versions page</a><span> in JIRA to add a new version (this is often not
>necessary as it is often created by someone
>earlier)</span></li><li><strong>Release</strong> the version, moving
>outstanding issues to the next version</li><li>Generate HTML Release
>Notes<ol><li>Visit the <a class="external-link"
>href="https://issues.apache.org/jira/browse/TAP5#selectedTab=com.atlassian.jira.plugin.system.project:versions-panel&subset=-1";>TAP5
> Versions pages in JIRA</a></li><li>Choose the correct version
>number</li><li>Click "Release Notes" (upper right corner of the
>page)</li><li>Create a new Confluence child page of <a
>href="release-notes.html">Release Notes</a> (it may already
>exist)</li><li>Update with text about any unusual aspects of the upgrade
>(especially, non-backwards compatible changes)</
li><li>Paste the HTML release notes content into the new page (you'll have to
use the {html} macro)</li><li>Rename the "Bug" heading to "Bugs Fixed",
"Improvement" to "Improvements Made", "New Feature" to "New Features
Added"</li><li>Update <a href="release-notes.html">Release
Notes</a> index page to point to the new page</li></ol></li></ol><h3
id="ReleaseProcess-6.ReleasetheMavenArtifacts"><span style="line-height:
22.857143px;">6. Release the Maven Artifacts</span></h3><ol><li>Login to <a
class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a>
and <strong>release</strong> the version's repository<ol><li>Enter "Apache
Tapestry 5.x" (adjust as necessary) for the message</li><li>The version will
disappear from the list of repositories after releasing
it</li></ol></li><li>Releasing will ultimately get the artifacts up to the
central Maven repository</li></ol><h3
id="ReleaseProcess-7.ReleasetheArchives">7. Release the Archives</h3
><ol><li>Copy the release archives files (including checksums and GPG
>signatures) to the release archives workspace</li><li>Change to the release
>archives workspace</li><li><code>svn add</code> and<code>svn commit</code>,
>as with the dev archives workspace</li></ol><h3
>id="ReleaseProcess-8.ReleasetheJavadocs">8. Release the
>Javadocs</h3><ol><li>Run the "aggregateJavadoc" gradle task</li><li>Copy the
>resulting files from build/documentation/javadocs/* to a version-numbered
>subdirectory of your site <em>content</em> workspace (see Prerequisites at
>the top of this page)</li><li>svn commit those new javadoc
>files</li><li>Update the "current" symbolic link under the content directory
>to point to new version-numbered directory. For example, if "current" is a
>symbolic link to "5.4" and you want to change it to "5.5", do this:<br
>clear="none"><ul><li>rm current</li><li>ln -s 5.5 current</li><li>svn commit
>-m "Updated javadocs current symbolic link" current</li></ul></li></ol><h3
>id="Release
Process-9.Wait">9. Wait</h3><ul><li>You must wait at least 24 hours for the
archives and artifacts to be distributed to the Apache mirrors and to the
central Maven repository</li></ul><h3
id="ReleaseProcess-10.UpdateDocumentation"><span style="line-height:
1.4285715;">10. Update Documentation</span></h3><ol><li><span
style="line-height: 1.4285715;">Update the release number listed in the
following pages in the Confluence wiki:</span><br clear="none"><ol><li><a
href="download.html">Download</a> page</li><li>(Optional) Tutorial <a
href="creating-the-skeleton-application.html">Creating The Skeleton
Application</a> page: Tapestry version number in the
archetype</li><li>(Optional) <a href="getting-started.html">Getting
Started</a> page: Tapestry version number in the
archetype</li></ol></li><li><span>Change to the site content
workspace</span></li><li><code>svn update</code> to get any recent
changes</li><li><span>Edit </span><a class="external-link"
href="https://svn.apach
e.org/repos/infra/websites/production/tapestry/content/archetype-catalog.xml"><span> </span><code>archetype-catalog.xml</code><span> </span></a><span>to
add or update a new entry for the release</span></li><li><span
style="line-height: 1.4285715;">Update the release number and date
inside </span><code style="line-height: 1.4285715;">doap.rdf</code><span
style="line-height: 1.4285715;">  (this is a </span><a
class="external-link" href="https://projects.apache.org/doap.html";
style="line-height: 1.4285715;">description file</a><span style="line-height:
1.4285715;"> for the project)</span></li><li><span style="line-height:
1.4285715;"><code>svn commit</code></span></li></ol><h3
id="ReleaseProcess-11.Blog&Tweet"><span>11. Blog &
Tweet</span></h3><ol><li><a
href="https://cwiki.apache.org/confluence/pages/viewrecentblogposts.action?key=TAPESTRY";><span>Write
a blog post</span></a><span> in Confluence announcing the
release.</span></li><li><span>Send an email to
the <em>users</em> mailing list announcing the release.<br
clear="none"></span></li><li><span>Send out a tweet (using the <a
class="external-link" href="https://twitter.com/apachetapestry";
rel="nofollow"><em>ApacheTapestry</em></a> Twitter account) announcing the
release.<br clear="none"></span></li></ol><h3
id="ReleaseProcess-Done!"><span>Done!</span></h3><p><span><br
clear="none"></span></p><hr><h2
id="ReleaseProcess-Atemplateforthevotee-mail:">A template for the vote
e-mail:</h2><plain-text-body>I've created and uploaded a release of Tapestry
5.x, ready to be voted upon.
+apacheArchivesFolder=.../tapestry-dev</pre>
+</div></div><p>You can find your keyId using <code>gpg
--list-keys</code>.</p><p> The apacheArchivesFolder should be the full
path to your dev archives workspace. The build will copy files to this
folder; see further notes below.</p><h2
id="ReleaseProcess-ReleaseSteps">Release Steps</h2><h3
id="ReleaseProcess-1.GeneratetheRelease">1. Generate the
Release</h3><ol><li>Update your workspace to the release branch<ol><li>For
current work, the release branch is <em>master</em></li><li>When creating
bug fix releases for older releases, the branch will match the release,
e.g., <em>5.3</em></li></ol></li><li><span style="line-height:
1.4285715;">Run the build using </span><code style="line-height:
1.4285715;">gradle generateRelease</code><br clear="none"><ol><li>This will
create, sign, and upload JAR files and other artifacts to the Nexus
repository</li><li>It will also create, sign, and copy the source, binary, and
documentation archives to your dev archives wo
rkspace</li></ol></li><li>Tag the release in Git, then push the changes up to
the Apache repository:<ol><li><code>git tag 5.x</code></li><li><code>git push
--tags</code></li></ol></li><li>Login to <a class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a> and <strong>close</strong> the
automatically created staging repository</li></ol><h3
id="ReleaseProcess-2.CommittheArchives">2. Commit the Archives</h3><ol><li>The
build will have copied archive files to your dist workspace</li><li><code>svn
add</code> the new files</li><li><code>svn commit</code> to copy the files up
to Apache (this is <em>slow</em>)<ol><li>Use the full version number as
the commit message, e.g., <em>5.4-beta-26</em></li></ol></li><li>You can
verify the files via the web: <a class="external-link"
href="https://dist.apache.org/repos/dist/dev/tapestry";>https://dist.apache.org/repos/dist/dev/tapestry</a></li></ol><h3
id="ReleaseProcess-3
.BumptheVersionNumber">3. Bump the Version
Number</h3><ol><li>Update <code>build.gradle</code> to increment the
version number</li><li>Increment the minor version number (inside the
tapestryVersion method, near the top of the file)</li><li><p>Commit and push
the changes</p></li></ol><h3 id="ReleaseProcess-4.SendVote">4. Send
Vote</h3><ol><li><span style="line-height: 1.4285715;">Send vote
email</span></li><li><span style="line-height: 1.4285715;"><strong>Wait 3
days</strong><br clear="none"></span></li><li><span style="line-height:
1.4285715;">The vote is successful if there are at least
three <strong>+1</strong>'s and more <strong>+1</strong> than
<strong>-1</strong></span></li><li><span style="line-height: 1.4285715;">Only
PMC members may cast binding votes</span></li></ol><h3
id="ReleaseProcess-5.UpdateJIRAandgeneratereleasenotes"><span>5. Update JIRA
and generate release notes</span><span style="line-height:
22.857143px;"> </span></h3><ol><li><span>Use the
60;</span><a class="external-link"
href="https://issues.apache.org/jira/plugins/servlet/project-config/TAP5/versions";>Manage
Versions page</a><span> in JIRA to add a new version (this is often not
necessary as it is often created by someone
earlier)</span></li><li><strong>Release</strong> the version, moving
outstanding issues to the next version</li><li>Generate HTML Release
Notes<ol><li>Visit the <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5#selectedTab=com.atlassian.jira.plugin.system.project:versions-panel&subset=-1";>TAP5
Versions pages in JIRA</a></li><li>Choose the correct version
number</li><li>Click "Release Notes" (upper right corner of the
page)</li><li>Create a new Confluence child page of <a
href="release-notes.html">Release Notes</a> (it may already
exist)</li><li>Update with text about any unusual aspects of the upgrade
(especially, non-backwards compatible changes)</li><li>Paste the HTML release
notes content
into the new page (you'll have to use the {html} macro)</li><li>Rename the
"Bug" heading to "Bugs Fixed", "Improvement" to "Improvements Made", "New
Feature" to "New Features Added"</li><li>Update <a
href="release-notes.html">Release Notes</a> index page to point to the new
page</li></ol></li></ol><h3
id="ReleaseProcess-6.ReleasetheMavenArtifacts"><span style="line-height:
22.857143px;">6. Release the Maven Artifacts</span></h3><ol><li>Login to <a
class="external-link"
href="https://repository.apache.org/index.html#stagingRepositories";>Nexus</a>
and <strong>release</strong> the version's repository<ol><li>Enter "Apache
Tapestry 5.x" (adjust as necessary) for the message</li><li>The version will
disappear from the list of repositories after releasing
it</li></ol></li><li>Releasing will ultimately get the artifacts up to the
central Maven repository</li></ol><h3
id="ReleaseProcess-7.ReleasetheArchives">7. Release the
Archives</h3><ol><li>Copy the release archives files (i
ncluding checksums and GPG signatures) to the release archives
workspace</li><li>Change to the release archives workspace</li><li><code>svn
add</code> and<code>svn commit</code>, as with the dev archives
workspace</li></ol><h3 id="ReleaseProcess-8.ReleasetheJavadocs">8. Release the
Javadocs</h3><ol><li>Run the "aggregateJavadoc" gradle task</li><li>Copy the
resulting files from build/documentation/javadocs/* to a version-numbered
subdirectory of your site <em>content</em> workspace (see Prerequisites at the
top of this page)</li><li>svn commit those new javadoc files</li><li>Update the
"current" symbolic link under the content directory to point to new
version-numbered directory. For example, if "current" is a symbolic link to
"5.4" and you want to change it to "5.5", do this:<br clear="none"><ul><li>rm
current</li><li>ln -s 5.5 current</li><li>svn commit -m "Updated javadocs
current symbolic link" current</li></ul></li></ol><h3
id="ReleaseProcess-9.Wait">9. Wait</h3><ul><li>You mus
t wait at least 24 hours for the archives and artifacts to be distributed to
the Apache mirrors and to the central Maven repository</li></ul><h3
id="ReleaseProcess-10.UpdateDocumentation"><span style="line-height:
1.4285715;">10. Update Documentation</span></h3><ol><li><span
style="line-height: 1.4285715;">Update the release number listed in the
following pages in the Confluence wiki:</span><br clear="none"><ol><li><a
href="download.html">Download</a> page</li><li>(Optional) Tutorial <a
href="creating-the-skeleton-application.html">Creating The Skeleton
Application</a> page: Tapestry version number in the
archetype</li><li>(Optional) <a href="getting-started.html">Getting
Started</a> page: Tapestry version number in the
archetype</li></ol></li><li><span>Change to the site content
workspace</span></li><li><code>svn update</code> to get any recent
changes</li><li><span>Edit </span><a class="external-link"
href="https://svn.apache.org/repos/infra/websites/production/tapes
try/content/archetype-catalog.xml"><span> </span><code>archetype-catalog.xml</code><span> </span></a><span>to
add or update a new entry for the release</span></li><li><span
style="line-height: 1.4285715;">Update the release number and date
inside </span><code style="line-height: 1.4285715;">doap.rdf</code><span
style="line-height: 1.4285715;">  (this is a </span><a
class="external-link" href="https://projects.apache.org/doap.html";
style="line-height: 1.4285715;">description file</a><span style="line-height:
1.4285715;"> for the project)</span></li><li><span style="line-height:
1.4285715;"><code>svn commit</code></span></li></ol><h3
id="ReleaseProcess-11.Blog&Tweet"><span>11. Blog &
Tweet</span></h3><ol><li><a
href="https://cwiki.apache.org/confluence/pages/viewrecentblogposts.action?key=TAPESTRY";><span>Write
a blog post</span></a><span> in Confluence announcing the
release.</span></li><li><span>Send an email to the <em>users</em> mailing list
announcing
the release.<br clear="none"></span></li><li><span>Send out a tweet (using
the <a class="external-link" href="https://twitter.com/apachetapestry";
rel="nofollow"><em>ApacheTapestry</em></a> Twitter account) announcing the
release.<br clear="none"></span></li></ol><h3
id="ReleaseProcess-Done!"><span>Done!</span></h3><p><span><br
clear="none"></span></p><hr><h2
id="ReleaseProcess-Atemplateforthevotee-mail:">A template for the vote
e-mail:</h2><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;">I've created and uploaded a release of Tapestry 5.x,
ready to be voted upon.
The source, binary, and documentation archives have been uploaded to:
@@ -100,7 +134,8 @@ and make the necessary updates to JIRA a
Only votes cast by Tapestry PMC members are binding, but input
from the community is highly valued. Please indicate whether your
vote is binding or not after your full name (as it will appear in
-the end-of-vote summary).</plain-text-body><p>The release manager often
embellishes this template with extra detail.</p><p>It's also a nice touch to
append a text version of the JIRA release notes as well.</p></div>
+the end-of-vote summary).</pre>
+</div></div><p>The release manager often embellishes this template with extra
detail.</p><p>It's also a nice touch to append a text version of the JIRA
release notes as well.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/request-processing.html
==============================================================================
--- websites/production/tapestry/content/request-processing.html (original)
+++ websites/production/tapestry/content/request-processing.html Wed Sep 20
12:29:16 2017
@@ -36,26 +36,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Request Processing</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Request Processing</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,7 +54,43 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "request-processing" and
space = currentSpace()</parameter></rich-text-body><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 pipe
line 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/current/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 pipeline 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 for 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 Dispatch
er 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 pa
ge. 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 typ
e 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 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 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><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-content-image-border"
src="request-processing.data/tapestry_request_processing_800.png"></span></p></div>
+ <div id="ConfluenceContent"><div class="aui-label"
style="float:right" title="Related Articles"><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>
+ <div class="details">
+ <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>
+ <div class="details">
+ <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>
+ <div class="details">
+ <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>
+ <div class="details">
+ <a href="component-events.html">Component Events</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="component-events-faq.html">Component Events FAQ</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="request-processing.html">Request Processing</a>
+ </div> </li></ul></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";>HttpServletR
equestHandler</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/current/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 pipeline 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 for 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-AssetDispatc
her">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 f
rom 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 universall
y, 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
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 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 dispatc
hers interact when processing an incoming request.</p><p><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-content-image-border"
src="request-processing.data/tapestry_request_processing_800.png"></span></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 Wed Sep 20
12:29:16 2017
@@ -36,26 +36,13 @@
<div class="wrapper bs">
- <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div>
-
-</div>
+ <div id="navigation"><div class="nav"><ul class="alternate"><li><a
href="index.html">Home</a></li><li><a href="getting-started.html">Getting
Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a
href="download.html">Download</a></li><li><a
href="about.html">About</a></li><li><a class="external-link"
href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a
href="community.html">Community</a></li><li><a class="external-link"
href="http://www.apache.org/security/";>Security</a></li><li><a
class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a
class="external-link"
href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div>
<div id="top">
- <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span>
-<form enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
- <input type="text" name="q">
- <input type="submit" value="Search">
-</form>
-
-</div>
-
-
-<div class="emblem" style="float:left"><p><a href="index.html"><span
class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image
confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div>
-
-
-<div class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Response Compression</h1></div>
-
-</div>
+ <div id="smallbanner"><div class="searchbox"
style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999;
font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form
enctype="application/x-www-form-urlencoded" method="get"
action="http://tapestry.apache.org/search.html";>
+ <input type="text" name="q">
+ <input type="submit" value="Search">
+</form></div><div class="emblem" style="float:left"><p><a
href="index.html"><span class="confluence-embedded-file-wrapper"><img
class="confluence-embedded-image confluence-external-resource"
src="http://tapestry.apache.org/images/tapestry_small.png";
data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div
class="title" style="float:left; margin: 0 0 0 3em"><h1
id="SmallBanner-PageTitle">Response Compression</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,7 +54,25 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Starting in Tapestry 5.1, the
framework automatically GZIP <strong>compresses</strong> content streamed to
the client. This can significantly reduce the amount of network traffic for a
Tapestry application, at the cost of extra processing time on the server to
compress the response stream.</p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "response" and space =
currentSpace()</parameter></rich-text-body><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 UR
L is handled by Tapestry and not the servlet container.</p><h1
id="ResponseCompression-CompressionConfiguration">Compression
Configuration</h1><p>Main Article: <a
href="configuration.html">Configuration</a></p><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 <code>tapestry.min-gzip-size</code> allows the cutoff to
be set; it defaults to 100 bytes.</p><p>In addition, some file types are
already compressed and should not be recompressed (they actually get larger,
not smaller!). The service <a class="external-link"
href="http://tapestry.apache.org/current/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 co
mpressed. The default content types are "image/jpeg".</p><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="page-navigation.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>
+ <div id="ConfluenceContent"><p>Starting in Tapestry 5.1, the
framework automatically GZIP <strong>compresses</strong> content streamed to
the client. This can significantly reduce the amount of network traffic for a
Tapestry application, at the cost of extra processing time on the server to
compress the response stream.</p><div class="aui-label" style="float:right"
title="Related Articles"><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>
+ <div class="details">
+ <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>
+ <div class="details">
+ <a href="configuration.html">Configuration</a>
+ </div> </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small aui-iconfont-page-default"
title="Page">Page:</span>
+ </div>
+ <div class="details">
+ <a href="assets.html">Assets</a>
+ </div> </li></ul></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>Main Article: <a
href="configuration.html">Configuration</a></p><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 <code>tapestry.min-gzip-size</code> allows the cutoff to
be set; it defaults to 100 bytes.</p><p>In addition, some file types are
already compressed and should not be recompressed (they actually get larger,
not smaller!). The service <a cla
ss="external-link"
href="http://tapestry.apache.org/current/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 content types are "image/jpeg".</p><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="page-navigation.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>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/security-faq.html
==============================================================================
--- websites/production/tapestry/content/security-faq.html (original)
+++ websites/production/tapestry/content/security-faq.html Wed Sep 20 12:29:16
2017
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,12 +77,56 @@
</div>
<div id="content">
- <div
id="ConfluenceContent"><p><plain-text-body>{scrollbar}</plain-text-body></p><h2
id="SecurityFAQ-SecurityFAQ">Security FAQ</h2><p> </p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "security" and space =
currentSpace()</parameter></rich-text-body><h3
id="SecurityFAQ-Thebuilt-inDashboardpagearevisibleinmyproductionapplicationandIdon'twantthemtobe,whatcanIdo?">The
built-in Dashboard page are visible in my production application and I don't
want them to be, what can I do?</h3><p>First off all, don't panic: the <a
href="development-dashboard.html">Developer Dashboard</a> page is marked with
the @<a class="external-link" href="http://tapestry.apache.org/curre
nt/apidocs/org/apache/tapestry5/annotations/WhitelistAccessOnly.html">WhitelistAccessOnly</a>
annotation, which makes it invisible to clients that are not on the whitelist.
Try accessing the page from a different workstation and you may find that the
pages are not visible after all.</p><p>Sometimes, in production, a firewall or
proxy may make it look like the client web browser originates from localhost;
in that situation, you may want to disable the logic that puts localhost onto
the whitelist. This determination is made by the contributions to the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/ClientWhitelist.html";>ClientWhitelist</a>
service. Tapestry makes a contribution with id "LocalhostOnly", which one of
your modules can override:</p><plain-text-body>
@Contribute(ClientWhitelist.class)
+ <div id="ConfluenceContent"><h2
id="SecurityFAQ-SecurityFAQ">Security FAQ</h2><p> </p><div
class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<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>
+
+ <div class="details">
+ <a href="security-faq.html">Security FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <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>
+
+ <div class="details">
+ <a href="security.html">Security</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<h3
id="SecurityFAQ-Thebuilt-inDashboardpagearevisibleinmyproductionapplicationandIdon'twantthemtobe,whatcanIdo?">The
built-in Dashboard page are visible in my production application and I don't
want them to be, what can I do?</h3><p>First off all, don't panic: the <a
href="development-dashboard.html">Developer Dashboard</a> page is marked with
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/WhitelistAccessOnly.html";>WhitelistAccessOnly</a>
annotation, which makes it invisible to clients that are not on the whitelist.
Try accessing the page from a different workstation and you may find that the
pages are not visible after all.</p><p>Sometimes, in production, a firewall or
proxy may make it look like the client web browser originates from localhost;
in that situation, you may want to disable the logic that puts localhost onto
the whitelist. This determination is made by the contributions to the <a
class="external-link
"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/ClientWhitelist.html";>ClientWhitelist</a>
service. Tapestry makes a contribution with id "LocalhostOnly", which one of
your modules can override:</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;"> @Contribute(ClientWhitelist.class)
public static void
turnOffLocalhostInProduction(OrderedConfiguration<WhitelistAnalyzer>
configuration,
@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode) {
if (productionMode) { configuration.override("LocalhostOnly", null); }
}
-</plain-text-body><p><plain-text-body>{scrollbar}</plain-text-body></p></div>
+</pre>
+</div></div><p></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 Wed Sep 20 12:29:16 2017
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,10 +77,61 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Tapestry has a number of
<strong>security</strong> features designed to harden your application against
unwanted intrusion and denial of service.</p><p> </p><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label in ("spring","security") and
space = currentSpace()</parameter></rich-text-body><p> </p><h2
id="Security-HTTPS-onlyPages">HTTPS-only Pages</h2><p>Main Article: <a
href="https.html">HTTPS</a></p><p>Tapestry provides several annotations and
configuration settings that you can use to <span style="text-align:
justify;line-height: 1.4285715;">ensure that all access to certain pages (or
all pages) occurs only via the encrypted
HTTPS protocol</span><span style="text-align: justify;line-height:
1.4285715;">. See <a href="https.html">HTTPS</a> for
details.</span></p><h2 id="Security-ControllingPageAccess"><span
style="text-align: justify;line-height: 1.4285715;">Controlling Page
Access</span></h2><p><plain-text-body>{float:right|background=#eee|padding=0
1em}
- *JumpStart Demo:*
- [Protecting
Pages|http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/protectingpages]
-{float}</plain-text-body><span style="text-align: justify;line-height:
1.4285715;">For simple access control needs, you can contribute a <span><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ComponentRequestFilter.html";>ComponentRequestFilter</a>
with your custom logic that decides which pages should be accessed by which
users. The <a class="external-link"
href="https://tapestry-app.apache.org/hotels/";>Tapestry Hotel Booking </a>app
demonstrates this approach with an <code>@AnonymousAccess</code> annotation
along with a ComponentRequestFilter
named <code>AuthenticationFilter.java</code>. The filter enforces security
by intercepting all requests to pages that don't have that annotation, and it
redirects those requests to the login page. <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/protectingpages";
rel="nofollow">JumpStart</a> has a similar demo.<br clear="no
ne"></span></span></p><p><span style="line-height: 1.4285715;text-align:
justify;">For more advanced needs see the Security Framework Integration
section below.</span></p><h2 id="Security-White-listedPages">White-listed
Pages</h2><p>Pages whose component classes are annotated with @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/WhitelistAccessOnly.html";>WhitelistAccessOnly</a> will
only be displayed to users (clients) that are on the <em>whitelist</em>.
By default the whitelist consists only of clients whose fully-qualified domain
name is "localhost" (or the IP address equivalent, 127.0.0.1 or
0:0:0:0:0:0:0:1), but you can customize this by contributing to the
ClientWhitelist service in your application's module class (usually
AppModule.java):</p><parameter ac:name="language">java</parameter><parameter
ac:name="title">AppModule.java (partial) -- simple inline
example</parameter><plain-text-body>
@Contribute(ClientWhitelist.class)
+ <div id="ConfluenceContent"><p>Tapestry has a number of
<strong>security</strong> features designed to harden your application against
unwanted intrusion and denial of service.</p><p> </p><div
class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<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>
+
+ <div class="details">
+ <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>
+
+ <div class="details">
+ <a
href="integrating-with-spring-framework.html">Integrating with Spring
Framework</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="security-faq.html">Security FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="https.html">HTTPS</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p> </p><h2 id="Security-HTTPS-onlyPages">HTTPS-only Pages</h2><p>Main
Article: <a href="https.html">HTTPS</a></p><p>Tapestry provides several
annotations and configuration settings that you can use to <span
style="text-align: justify;line-height: 1.4285715;">ensure that all access to
certain pages (or all pages) occurs only via the encrypted HTTPS
protocol</span><span style="text-align: justify;line-height: 1.4285715;">.
See <a href="https.html">HTTPS</a> for details.</span></p><h2
id="Security-ControllingPageAccess"><span style="text-align:
justify;line-height: 1.4285715;">Controlling Page Access</span></h2><p></p><div
class="navmenu" style="float:right; background:#eee; margin:3px; padding:0 1em">
+<p> <strong>JumpStart Demo:</strong><br clear="none">
+ <a class="external-link"
href="http://jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/protectingpages";
rel="nofollow">Protecting Pages</a></p></div><span style="text-align:
justify;line-height: 1.4285715;">For simple access control needs, you can
contribute a <span><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ComponentRequestFilter.html";>ComponentRequestFilter</a>
with your custom logic that decides which pages should be accessed by which
users. The <a class="external-link"
href="https://tapestry-app.apache.org/hotels/";>Tapestry Hotel Booking </a>app
demonstrates this approach with an <code>@AnonymousAccess</code> annotation
along with a ComponentRequestFilter
named <code>AuthenticationFilter.java</code>. The filter enforces security
by intercepting all requests to pages that don't have that annotation, and it
redirects those requests to the login page. <a class="external-link"
href="http:
//jumpstart.doublenegative.com.au/jumpstart/examples/infrastructure/protectingpages"
rel="nofollow">JumpStart</a> has a similar demo.<br
clear="none"></span></span><p><span style="line-height: 1.4285715;text-align:
justify;">For more advanced needs see the Security Framework Integration
section below.</span></p><h2 id="Security-White-listedPages">White-listed
Pages</h2><p>Pages whose component classes are annotated with @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/WhitelistAccessOnly.html";>WhitelistAccessOnly</a> will
only be displayed to users (clients) that are on the <em>whitelist</em>.
By default the whitelist consists only of clients whose fully-qualified domain
name is "localhost" (or the IP address equivalent, 127.0.0.1 or
0:0:0:0:0:0:0:1), but you can customize this by contributing to the
ClientWhitelist service in your application's module class (usually
AppModule.java):</p><div class="
code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader
pdl" style="border-bottom-width: 1px;"><b>AppModule.java (partial) –
simple inline example</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> @Contribute(ClientWhitelist.class)
public static void
provideWhitelistAnalyzer(OrderedConfiguration<WhitelistAnalyzer>
configuration)
{
configuration.add("MyCustomAnalyzer", new WhitelistAnalyzer()
@@ -81,7 +142,10 @@
return true;
}
}, "before:*");
- }</plain-text-body><p> </p><p>Sometimes, in production, a firewall or
proxy may make it look like the client web browser originates from localhost,
with the consequence that whitelisted pages may be visible to all users. See
the <a href="security.html">Security FAQ</a> for how to deal with
this.</p><h2 id="Security-AssetSecurity">Asset Security</h2><p>Main
Article: <a href="assets.html">Assets</a></p><p>Tapestry serves assets
(static content such as CSS files, images, and JavaScript, many of which are on
the classpath alongside your compiled class files) to the client. Because
of this, great care has gone into ensuring that certain file types cannot be
served to the client. By default, file ending with ".class', ".tml" and
".properties" can be served to the client only if the request includes the
file's MD5 checksum. As you would expect, that blacklist can be extended.
See <a href="assets.html">Asset Security</a> for more information.</p><h2
id="Secur
ity-ProtectingSerializedObjectDataontheClient">Protecting Serialized Object
Data on the Client</h2><p><span style="color: rgb(0,0,0);">As of version 5.3.6,
Tapestry integrates a </span><a class="external-link"
href="http://en.wikipedia.org/wiki/HMAC"; rel="nofollow" style="text-decoration:
underline;text-align: justify;">hash-based message authentication code</a><span
style="color: rgb(0,0,0);"> (HMAC) into serialized Java object data that
it sends to the client (generally, this means the </span><code
style="text-align: justify;">t:formdata</code><span style="color:
rgb(0,0,0);"> hidden field used by the Form component). This ensures that
the hidden binary object data is guaranteed to be unaltered when it returns to
the server upon form (or AJAX) submission. The HMAC pass phrase is set using
the <a href="configuration.html">tapestry.hmac-passphrase</a>
configuration symbol. If you don't set that value, you'll see a warning message
in the browser, like this:
 </span></p><plain-text-body>The symbol 'tapestry.hmac-passphrase' has
not been configured. This is used to configure hash-based message
authentication of Tapestry data stored in forms, or in the URL. You application
is less secure, and more vulnerable to denial-of-service attacks, when this
symbol is not configured.</plain-text-body><p><span style="color:
rgb(0,0,0);">The solution is to set the tapestry.hmac-passphrase to some value
(any fixed, private string, such as 30 to 40 random-looking characters, will
do) in your application's module class (usually AppModule.java).</span></p><h2
id="Security-CrossSiteRequestForgery(CSRF)"><span style="color:
rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Cross Site Request Forgery
(CSRF)</span></h2><p>Cross Site Request Forgery is a type of security
vulnerability in which legitimate, authorized users may be made to unwittingly
submit malicious requests to your web application.</p><p><a
class="external-link" href="https://github.co
m/porscheinformatik/tapestry-csrf-protection"
rel="nofollow">Tapestry-csrf-protection</a> is a 3rd party module that has
several features for preventing CSRF attacks. It protects
all <span>component event handlers (event links, forms, etc.) by adding
a </span><span>CSRF token to event links and adds a CSRF token as a hidden
field to all forms. </span><span>Tokens are generated on a per-session
basis.</span></p><h2 id="Security-SecurityFrameworkIntegration"><span
style="line-height: 1.5;">Security Framework Integration</span></h2><p>Tapestry
does not lock you into a specific authentication/authorization implementation.
There are integration modules available for the more popular open source Java
security frameworks. A popular choice among Tapestry users is <a
class="external-link" href="http://www.tynamo.org/tapestry-security+guide/";
rel="nofollow">tapestry-security (based on Apache Shiro) from Tynamo.org</a>.
It is always kept up-to-date with the latest Tapestry
versions and offers several supporting security modules (e.g. <a
class="external-link" href="http://www.tynamo.org/tapestry-security-jpa+guide/";
rel="nofollow">tapestry-security-jpa</a>, <a class="external-link"
href="http://www.tynamo.org/tynamo-federatedaccounts+guide/";
rel="nofollow">tynamo-federatedaccounts</a>). There's also an <a
class="external-link"
href="http://www.localhost.nu/java/tapestry-spring-security";
rel="nofollow">integration module available for Spring Security</a> but lately,
it hasn't kept up with the latest versions of Tapestry 5.</p><p>Additional
information:</p><ul><li><a class="external-link"
href="http://www.tynamo.org/tynamo-federatedaccounts+guide/";
rel="nofollow">Tynamo-federatedaccounts</a> <span style="color:
rgb(0,0,0);">is an add-on to the </span><a class="external-link"
href="http://www.tynamo.org/tapestry-security+guide/";
rel="nofollow">tapestry-security</a><span style="color:
rgb(0,0,0);"> module, providing federated (third-pa
rty) authentication with Facebook, Twitter or
Google.</span></li></ul><ul><li><span style="line-height: 1.4285715;">To
include OpenID with Spring Security in your application, see the following Wiki
entry: </span><a class="external-link"
href="http://wiki.apache.org/tapestry/Tapestry5HowToSpringSecurityAndOpenId";
style="line-height:
1.4285715;">http://wiki.apache.org/tapestry/Tapestry5HowToSpringSecurityAndOpenId</a></li></ul><p> </p></div>
+ }</pre>
+</div></div><p> </p><p>Sometimes, in production, a firewall or proxy may
make it look like the client web browser originates from localhost, with the
consequence that whitelisted pages may be visible to all users. See the <a
href="security.html">Security FAQ</a> for how to deal with this.</p><h2
id="Security-AssetSecurity">Asset Security</h2><p>Main Article: <a
href="assets.html">Assets</a></p><p>Tapestry serves assets (static content such
as CSS files, images, and JavaScript, many of which are on the classpath
alongside your compiled class files) to the client. Because of this, great
care has gone into ensuring that certain file types cannot be served to the
client. By default, file ending with ".class', ".tml" and ".properties" can be
served to the client only if the request includes the file's MD5 checksum. As
you would expect, that blacklist can be extended. See <a
href="assets.html">Asset Security</a> for more information.</p><h2
id="Security-Protect
ingSerializedObjectDataontheClient">Protecting Serialized Object Data on the
Client</h2><p><span style="color: rgb(0,0,0);">As of version 5.3.6, Tapestry
integrates a </span><a class="external-link"
href="http://en.wikipedia.org/wiki/HMAC"; rel="nofollow" style="text-decoration:
underline;text-align: justify;">hash-based message authentication code</a><span
style="color: rgb(0,0,0);"> (HMAC) into serialized Java object data that
it sends to the client (generally, this means the </span><code
style="text-align: justify;">t:formdata</code><span style="color:
rgb(0,0,0);"> hidden field used by the Form component). This ensures that
the hidden binary object data is guaranteed to be unaltered when it returns to
the server upon form (or AJAX) submission. The HMAC pass phrase is set using
the <a href="configuration.html">tapestry.hmac-passphrase</a>
configuration symbol. If you don't set that value, you'll see a warning message
in the browser, like this: </spa
n></p><div class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+<pre>The symbol 'tapestry.hmac-passphrase' has not been configured. This is
used to configure hash-based message authentication of Tapestry data stored in
forms, or in the URL. You application is less secure, and more vulnerable to
denial-of-service attacks, when this symbol is not configured.</pre>
+</div></div><p><span style="color: rgb(0,0,0);">The solution is to set the
tapestry.hmac-passphrase to some value (any fixed, private string, such as 30
to 40 random-looking characters, will do) in your application's module class
(usually AppModule.java).</span></p><h2
id="Security-CrossSiteRequestForgery(CSRF)"><span style="color:
rgb(83,145,38);font-size: 20.0px;line-height: 1.5;">Cross Site Request Forgery
(CSRF)</span></h2><p>Cross Site Request Forgery is a type of security
vulnerability in which legitimate, authorized users may be made to unwittingly
submit malicious requests to your web application.</p><p><a
class="external-link"
href="https://github.com/porscheinformatik/tapestry-csrf-protection";
rel="nofollow">Tapestry-csrf-protection</a> is a 3rd party module that has
several features for preventing CSRF attacks. It protects
all <span>component event handlers (event links, forms, etc.) by adding
a </span><span>CSRF token to event links and adds a CSRF token
as a hidden field to all forms. </span><span>Tokens are generated on a
per-session basis.</span></p><h2
id="Security-SecurityFrameworkIntegration"><span style="line-height:
1.5;">Security Framework Integration</span></h2><p>Tapestry does not lock you
into a specific authentication/authorization implementation. There are
integration modules available for the more popular open source Java security
frameworks. A popular choice among Tapestry users is <a class="external-link"
href="http://www.tynamo.org/tapestry-security+guide/";
rel="nofollow">tapestry-security (based on Apache Shiro) from Tynamo.org</a>.
It is always kept up-to-date with the latest Tapestry versions and offers
several supporting security modules (e.g. <a class="external-link"
href="http://www.tynamo.org/tapestry-security-jpa+guide/";
rel="nofollow">tapestry-security-jpa</a>, <a class="external-link"
href="http://www.tynamo.org/tynamo-federatedaccounts+guide/";
rel="nofollow">tynamo-federatedaccounts</a>). There's
also an <a class="external-link"
href="http://www.localhost.nu/java/tapestry-spring-security";
rel="nofollow">integration module available for Spring Security</a> but lately,
it hasn't kept up with the latest versions of Tapestry 5.</p><p>Additional
information:</p><ul><li><a class="external-link"
href="http://www.tynamo.org/tynamo-federatedaccounts+guide/";
rel="nofollow">Tynamo-federatedaccounts</a> <span style="color:
rgb(0,0,0);">is an add-on to the </span><a class="external-link"
href="http://www.tynamo.org/tapestry-security+guide/";
rel="nofollow">tapestry-security</a><span style="color:
rgb(0,0,0);"> module, providing federated (third-party) authentication
with Facebook, Twitter or Google.</span></li></ul><ul><li><span
style="line-height: 1.4285715;">To include OpenID with Spring Security in your
application, see the following Wiki entry: </span><a
class="external-link"
href="http://wiki.apache.org/tapestry/Tapestry5HowToSpringSecurityAndOpenId";
style="l
ine-height:
1.4285715;">http://wiki.apache.org/tapestry/Tapestry5HowToSpringSecurityAndOpenId</a></li></ul><p> </p></div>
</div>
<div class="clearer"></div>
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}