Author: buildbot
Date: Mon Dec 15 18:20:06 2014
New Revision: 932865
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-parameters.html
websites/production/tapestry/content/session-storage.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-parameters.html
==============================================================================
--- websites/production/tapestry/content/component-parameters.html (original)
+++ websites/production/tapestry/content/component-parameters.html Mon Dec 15
18:20:06 2014
@@ -66,8 +66,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:white; margin:3px; padding:3px">
-<div class="panel" style="border-width: 1px;"><div class="panelContent">
+<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -151,27 +150,21 @@
</div>
</li></ul>
-</div></div>
-
-<h3><a shape="rect" name="ComponentParameters-Contents"></a>Contents</h3>
-<style type="text/css">/*<![CDATA[*/
-div.rbtoc1418660381193 {padding: 0px;}
-div.rbtoc1418660381193 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1418660381193 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1418660381193">
-<ul class="toc-indentation"><li>Related Articles</li><li><a shape="rect"
href="#ComponentParameters-Contents">Contents</a></li></ul>
-<ul><li><a shape="rect"
href="#ComponentParameters-ParameterBindings">Parameter Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-BindingExpressions">Binding
Expressions</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#ComponentParameters-RenderVariables:Bindings">Render Variables:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Property:Bindings">Property: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Validate:Bindings">Validate:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Translate:Bindings">Translate:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Asset:Bindings">Asset: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Context:Bindings">Context:
Bindings</a></li></ul>
-</li><li><a shape="rect"
href="#ComponentParameters-@Parameterannotation">@Parameter annotation</a>
-<ul class="toc-indentation"><li><a shape="rect"
href="#ComponentParameters-RequiredParameters">Required
Parameters</a></li><li><a shape="rect"
href="#ComponentParameters-OptionalParameters">Optional
Parameters</a></li><li><a shape="rect"
href="#ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</a></li><li><a shape="rect"
href="#ComponentParameters-ParameterCaching">Parameter Caching</a></li></ul>
-</li><li><a shape="rect"
href="#ComponentParameters-Don'tusethe${...}syntax!">Don't use the ${...}
syntax!</a></li><li><a shape="rect"
href="#ComponentParameters-InformalParameters">Informal
Parameters</a></li><li><a shape="rect"
href="#ComponentParameters-ParametersAreBi-Directional">Parameters Are
Bi-Directional</a></li><li><a shape="rect"
href="#ComponentParameters-InheritedParameterBindings">Inherited Parameter
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-ComputedParameterBindingDefaults">Computed Parameter
Binding Defaults</a></li><li><a shape="rect"
href="#ComponentParameters-UnboundParameters">Unbound Parameters</a></li><li><a
shape="rect" href="#ComponentParameters-ParameterTypeCoercion">Parameter Type
Coercion</a></li><li><a shape="rect"
href="#ComponentParameters-ParameterNames">Parameter Names</a></li><li><a
shape="rect" href="#ComponentParameters-DeterminingifBound">Determining if
Bound</a></li><li><a shape="rect" href="#ComponentParameters-PublishingP
arameters">Publishing Parameters</a></li></ul>
-</div></div><p><strong>Component parameters</strong> are the primary means for
a component instance and its container to communicate with each other.
Parameters are used to <em>configure</em> component instances.</p><p>In the
following example, <code>page</code> is a parameter of the
<code>pagelink</code> component. The page parameter tells the pagelink
component which page to go to when the user clicks on the rendered
hyperlink:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div><p><strong>Component parameters</strong> are the primary means for a
component instance and its container to communicate with each other. Parameters
are used to <em>configure</em> component instances.</p><p>In the following
example, <code>page</code> is a parameter of the <code>pagelink</code>
component. The page parameter tells the pagelink component which page to go to
when the user clicks on the rendered hyperlink:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: xml; gutter: false"
type="syntaxhighlighter"><![CDATA[<html
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd">
<t:pagelink page="Index">Go Home</t:pagelink>
-</html>
-]]></script>
-</div></div><p>A component may have any number of parameters. Each parameter
has a specific name, a specific Java type (which may be a primitive value), and
may be <em>optional</em> or <em>required</em>.</p><p>Within a component class,
parameters are declared by using the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html";>Parameter</a>
annotation on a private field, as we'll see below.</p><p><span
class="confluence-anchor-link"
id="ComponentParameters-bindingparameters"></span></p><h1
id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In
Tapestry, a parameter is not a slot into which data is pushed: it is a
<em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container.
(Components can be nested, so the container can be either the page or another
component.)</p><p>The connection between a compone
nt and a property (or resource) of its container is called a <em>binding</em>.
The binding is two-way: the component can read the bound property by reading
its parameter field. Likewise, a component that updates its parameter field
will update the bound property.</p><p>This is important in a lot of cases; for
example a TextField component can read <em>and update</em> the property bound
to its value parameter. It reads the value when rendering, but updates the
value when the form is submitted.</p><p>The component listed below is a looping
component; it renders its body a number of times, defined by its
<code>start</code> and <code>end</code> parameters (which set the boundaries of
the loop). The component can update a <code>result</code> parameter bound to a
property of its container; it will automatically count up or down depending on
whether <code>start</code> or <code>end</code> is larger.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelConte
nt pdl">
+</html>]]></script>
+</div></div><p>A component may have any number of parameters. Each parameter
has a specific name, a specific Java type (which may be a primitive value), and
may be <em>optional</em> or <em>required</em>.</p><p>Within a component class,
parameters are declared by using the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Parameter.html";>Parameter</a>
annotation on a private field, as we'll see below.</p><p><span
class="confluence-anchor-link"
id="ComponentParameters-bindingparameters"></span></p><h1
id="ComponentParameters-ParameterBindings">Parameter Bindings</h1><p>In
Tapestry, a parameter is not a slot into which data is pushed: it is a
<em>connection</em> between a field of the component (marked with the
@Parameter annotation) and a property or resource of the component's container.
(Components can be nested, so the container can be either the page or another
component.)</p><div class="navmenu" style="float:r
ight; background:white; margin:3px; padding:3px">
+<div class="panel" style="border-width: 1px;"><div class="panelHeader"
style="border-bottom-width: 1px;"><b>Contents</b></div><div
class="panelContent">
+<style type="text/css">/*<![CDATA[*/
+div.rbtoc1418667590913 {padding: 0px;}
+div.rbtoc1418667590913 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418667590913 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style><div class="toc-macro rbtoc1418667590913">
+<ul class="toc-indentation"><li>Related Articles</li><li><a shape="rect"
href="#ComponentParameters-RenderVariables:Bindings">Render Variables:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Property:Bindings">Property: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Validate:Bindings">Validate:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Translate:Bindings">Translate:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-Asset:Bindings">Asset: Bindings</a></li><li><a
shape="rect" href="#ComponentParameters-Context:Bindings">Context:
Bindings</a></li><li><a shape="rect"
href="#ComponentParameters-RequiredParameters">Required
Parameters</a></li><li><a shape="rect"
href="#ComponentParameters-OptionalParameters">Optional
Parameters</a></li><li><a shape="rect"
href="#ComponentParameters-ParameterBindingDefaults">Parameter Binding
Defaults</a></li><li><a shape="rect"
href="#ComponentParameters-ParameterCaching">Parameter Cach
ing</a></li></ul>
+</div>
+</div></div></div><p> </p><p>The connection between a component and a
property (or resource) of its container is called a <em>binding</em>. The
binding is two-way: the component can read the bound property by reading its
parameter field. Likewise, a component that updates its parameter field will
update the bound property.</p><p>This is important in a lot of cases; for
example a TextField component can read <em>and update</em> the property bound
to its value parameter. It reads the value when rendering, but updates the
value when the form is submitted.</p><p>The component listed below is a looping
component; it renders its body a number of times, defined by its
<code>start</code> and <code>end</code> parameters (which set the boundaries of
the loop). The component can update a <code>result</code> parameter bound to a
property of its container; it will automatically count up or down depending on
whether <code>start</code> or <code>end</code> is larger.</p><div class="code
panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[package org.example.app.components;
import org.apache.tapestry5.annotations.AfterRender;
Modified: websites/production/tapestry/content/session-storage.html
==============================================================================
--- websites/production/tapestry/content/session-storage.html (original)
+++ websites/production/tapestry/content/session-storage.html Mon Dec 15
18:20:06 2014
@@ -66,7 +66,7 @@
</div>
<div id="content">
-<div id="ConfluenceContent"><div class="navmenu" style="float:right;
background:#eee; margin:3px; padding:3px">
+<div id="ConfluenceContent"><p> </p><p>Most web applications will need to
have some data that is shared across multiple pages. Perhaps you are creating a
multi-page wizard, or you have an object that tracks the user's identify once
logged in, or maybe you need to manage a shopping cart.</p><div class="navmenu"
style="float:right; background:#eee; margin:3px; padding:3px">
<h3>Related Articles</h3>
<ul class="content-by-label"><li>
<div>
@@ -82,7 +82,7 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="session-storage.html">Session Storage</a>
+ <a shape="rect"
href="performance-and-clustering.html">Performance and Clustering</a>
</div>
@@ -91,22 +91,21 @@
<span class="icon icon-page" title="Page">Page:</span>
</div>
<div class="details">
- <a shape="rect"
href="performance-and-clustering.html">Performance and Clustering</a>
+ <a shape="rect"
href="session-storage.html">Session Storage</a>
</div>
</li></ul>
-</div>
-
-<h1 id="SessionStorage-SessionStorage">Session Storage</h1>
-
+</div><p>Ordinary <a shape="rect"
href="persistent-page-data.html">page-persistent fields</a> won't work for
this, since persistent fields are available only to a specific page, not shared
across multiple pages.</p><p>Tapestry provides two mechanisms for storing such
data: Session State Objects and Session Attributes. When deciding between the
two, it's best to use Session State Objects for complex objects, and Session
Attributes for simple types.</p><h2
id="SessionStorage-SessionStateObjects">Session State Objects</h2><p>With a
Session State Object (SSO), the value is automatically stored outside the page;
with the default storage strategy, it is stored in the session. Such a value is
global to all pages <em>for the same user</em>, but is stored separately for
different users.</p><p>A field holding an SSO is marked with the @<a
shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SessionState.html";>SessionState</a>
ann
otation.</p><div class="navmenu" style="float:right; background:white;
margin:3px; padding:3px">
+<div class="panel" style="border-width: 1px;"><div class="panelHeader"
style="border-bottom-width: 1px;"><b>Contents</b></div><div
class="panelContent">
<style type="text/css">/*<![CDATA[*/
-div.rbtoc1418617265504 {padding: 0px;}
-div.rbtoc1418617265504 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1418617265504 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style><div class="toc-macro rbtoc1418617265504">
-<ul class="toc-indentation"><li>Related Articles</li><li><a shape="rect"
href="#SessionStorage-SessionStateObjects">Session State Objects</a>
+div.rbtoc1418667592882 {padding: 0px;}
+div.rbtoc1418667592882 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1418667592882 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style><div class="toc-macro rbtoc1418667592882">
+<ul class="toc-indentation"><li>Related Articles</li></ul>
+<ul><li><a shape="rect" href="#SessionStorage-SessionStateObjects">Session
State Objects</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SessionStorage-Pitfalls">Pitfalls</a></li><li><a shape="rect"
href="#SessionStorage-CheckforCreation">Check for Creation</a></li><li><a
shape="rect" href="#SessionStorage-PersistenceStrategies">Persistence
Strategies</a></li><li><a shape="rect"
href="#SessionStorage-ConfiguringSSOs">Configuring SSOs</a></li></ul>
</li><li><a shape="rect" href="#SessionStorage-SessionAttributes">Session
Attributes</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#SessionStorage-Pitfalls.1">Pitfalls</a></li></ul>
@@ -114,24 +113,8 @@ div.rbtoc1418617265504 li {margin-left:
<ul class="toc-indentation"><li><a shape="rect"
href="#SessionStorage-@ImmutableSessionPersistedObjectAnnotation">@ImmutableSessionPersistedObject
Annotation</a></li><li><a shape="rect"
href="#SessionStorage-OptimizedSessionPersistedObjectInterface">OptimizedSessionPersistedObject
Interface</a></li><li><a shape="rect"
href="#SessionStorage-SessionPersistedObjectAnalyzerService">SessionPersistedObjectAnalyzer
Service</a></li></ul>
</li><li><a shape="rect" href="#SessionStorage-SessionLocking">Session
Locking</a></li></ul>
</div>
-
-<p>Most web applications will need to have some data that is shared across
multiple pages. Perhaps you are creating a multi-page wizard, or you have an
object that tracks the user's identify once logged in, or maybe you need to
manage a shopping cart.</p>
-
-<p>Ordinary <a shape="rect" href="persistent-page-data.html">page-persistent
fields</a> won't work for this, since persistent fields are available only to a
specific page, not shared across multiple pages.</p>
-
-<p>Tapestry provides two mechanisms for storing such data: Session State
Objects and Session Attributes. When deciding between the two, it's best to use
Session State Objects for complex objects, and Session Attributes for simple
types.</p>
-
-<h2 id="SessionStorage-SessionStateObjects">Session State Objects</h2>
-
-<p>With a Session State Object (SSO), the value is automatically stored
outside the page; with the default storage strategy, it is stored in the
session. Such a value is global to all pages <em>for the same user</em>, but is
stored separately for different users.</p>
-
-<p>A field holding an SSO is marked with the @<a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SessionState.html";>SessionState</a>
annotation.</p>
-
-<p>Example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public class MyPage
+</div></div></div><p>Example:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public class MyPage
{
@SessionState
private ShoppingCart shoppingCart;
@@ -139,32 +122,14 @@ public class MyPage
. . .
}
]]></script>
-</div></div>
-
-<p>Any other component or page that declares a field <strong>of the same
type</strong>, regardless of name, and marks it with the SessionState
annotation will share the same value. It's that simple. However, using
@SessionState <em>safely</em> requires care:</p>
-
- <div class="aui-message problem shadowed information-macro">
+</div></div><p>Any other component or page that declares a field <strong>of
the same type</strong>, regardless of name, and marks it with the SessionState
annotation will share the same value. It's that simple. However, using
@SessionState <em>safely</em> requires care:</p> <div class="aui-message
problem shadowed information-macro">
<span class="aui-icon icon-problem">Icon</span>
<div class="message-content">
-
-<p>DO NOT USE @SessionState FOR SIMPLE TYPES! Only use it on variables that
are of a custom-built class designed expressly for this purpose! <strong>See
the Pitfalls section below</strong>.</p>
+ <p>DO NOT USE @SessionState FOR SIMPLE TYPES! Only
use it on variables that are of a custom-built class designed expressly for
this purpose! <strong>See the Pitfalls section below</strong>.</p>
</div>
</div>
-
-
-<p>The first time you access an SSO, it is created automatically. Typically,
the SSO will have a public no-args constructor ... but you may inject
dependencies into the SSO via its constructor, as you can with a Tapestry IoC
service implementation.</p>
-
-<p><em>For Tapestry 4 Users:</em> a big change here is that you don't need to
provide any configuration for the SSO before using it, nor do you provide a
logical name. Tapestry 5 uses the class name to identify the SSO, so there's no
need for a logical name.</p>
-
-<p>Assigning a value to an SSO field will store that value. Assigning null to
an SSO field will remove the SSO (reading the field subsequently will force a
new SSO instance to be created).</p>
-
-<h3 id="SessionStorage-Pitfalls">Pitfalls</h3>
-
-<p>With @SessionState, you are creating a session-wide data storage area that
is tied to the <em>type</em> (class) of the variable you annotate. It is not
specifically tied to the variable itself, or even to the class in which that
variable was annotated. As with all session data, there is the serious
possibility of collisions, not just within your application but with other
modules/libraries:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>Example of Data Collision
– Don't Do This!</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
- @SessionState
+<p>The first time you access an SSO, it is created automatically. Typically,
the SSO will have a public no-args constructor ... but you may inject
dependencies into the SSO via its constructor, as you can with a Tapestry IoC
service implementation.</p><p><em>For Tapestry 4 Users:</em> a big change here
is that you don't need to provide any configuration for the SSO before using
it, nor do you provide a logical name. Tapestry 5 uses the class name to
identify the SSO, so there's no need for a logical name.</p><p>Assigning a
value to an SSO field will store that value. Assigning null to an SSO field
will remove the SSO (reading the field subsequently will force a new SSO
instance to be created).</p><h3
id="SessionStorage-Pitfalls">Pitfalls</h3><p>With @SessionState, you are
creating a session-wide data storage area that is tied to the <em>type</em>
(class) of the variable you annotate. It is not specifically tied to the
variable itself, or even to the class in which that variable was
annotated. As with all session data, there is the serious possibility of
collisions, not just within your application but with other
modules/libraries:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>Example of Data Collision – Don't Do This!</b></div><div
class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ @SessionState
private String userName; // Unsafe -- String is not a custom type
... then, later in this class or any other:
@@ -172,54 +137,15 @@ public class MyPage
@sessionState
private String userCity; // This overwrites value in userName, because
it's also a String!
]]></script>
-</div></div>
-
-<p>The simple rule is, NEVER use @SessionState for simple-type variables. It
is ALWAYS worth taking the time to build a special class to hold your session
state information. Doing so will force you to consolidate that information into
a single, logical unit that can't be accidentally accessed by other classes.
(Alternatively, see the Session Attribute section below.)</p>
-
-<h3 id="SessionStorage-CheckforCreation">Check for Creation</h3>
-
-<p>Scalable web applications do not create the server-side session needlessly.
If you can avoid creating the session, especially on first access to your web
application, you will be able to handle an order of magnitude more users. So,
if you can avoid creating the SSO, you should do so.</p>
-
-<p>But how to avoid creating it? Simply checking ("shoppingCart!= null") will
force the creation of the SSO and the session to store it in.</p>
-
-<p>Instead, create a second field with a matching name but with "Exists"
appended:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
- private boolean shoppingCartExists;
+</div></div><p>The simple rule is, NEVER use @SessionState for simple-type
variables. It is ALWAYS worth taking the time to build a special class to hold
your session state information. Doing so will force you to consolidate that
information into a single, logical unit that can't be accidentally accessed by
other classes. (Alternatively, see the Session Attribute section below.)</p><h3
id="SessionStorage-CheckforCreation">Check for Creation</h3><p>Scalable web
applications do not create the server-side session needlessly. If you can avoid
creating the session, especially on first access to your web application, you
will be able to handle an order of magnitude more users. So, if you can avoid
creating the SSO, you should do so.</p><p>But how to avoid creating it? Simply
checking ("shoppingCart!= null") will force the creation of the SSO and the
session to store it in.</p><p>Instead, create a second field with a matching
name but with "Exists" appended:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ private boolean shoppingCartExists;
]]></script>
-</div></div>
-
-<p>It is not annotated; it is located by naming convention ("Exists"
appended). It must be type boolean and must be a private instance variable.
Tapestry will automatically set this variable to <code>true</code> when the SSO
is created, so you can check it to see if the SSO already exists.</p>
-
-<p>Alternately, you may allow for the state being null:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
- @SessionState(create=false)
+</div></div><p>It is not annotated; it is located by naming convention
("Exists" appended). It must be type boolean and must be a private instance
variable. Tapestry will automatically set this variable to <code>true</code>
when the SSO is created, so you can check it to see if the SSO already
exists.</p><p>Alternately, you may allow for the state being null:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ @SessionState(create=false)
private ShoppingCart shoppingCart;
]]></script>
-</div></div>
-
-<p>In this case, the shoppingCart field will be null if the ShoppingCart SSO
does not exist, but will be non-null if it has been created (either by
assigning a value to the field, or by a different SSO field where create is
true).</p>
-
-<h3 id="SessionStorage-PersistenceStrategies">Persistence Strategies</h3>
-
-<p>Main Article: <a shape="rect"
href="persistent-page-data.html#PersistentPageData-PersistenceStrategies">Persistent
Page Data</a></p>
-
-<p>Each SSO is managed according to a persistence strategy. The default
persistence strategy, "session", stores the SSOs inside the session. The
session is created as needed.</p>
-
-<h3 id="SessionStorage-ConfiguringSSOs">Configuring SSOs</h3>
-
-<p>Generally, you will need to configure your Session State Object if you want
to change the persistence strategy to other than the default. (Right now
there's only one built in strategy, but more will be coming in the future.)</p>
-
-<p>Alternately, you can configure a Session State Object in order to control
how it is instantiated. You may need to inject some values into the SSO when it
is first created, or otherwise initialize it. In this case, you may provide an
<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ApplicationStateCreator.html";>ApplicationStateCreator</a>
object, which will be called upon to create the SSO as necessary. This is also
the technique to use when you want your SSO to be represented by an
<em>interface</em> rather than a <em>class</em>: you need to provide a creator
that knows about the class that implements the interface.</p>
-
-<p>A Session State Object is configured using contributions to the
ApplicationStateManager service. From your application's module:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
- public void contributeApplicationStateManager(MappedConfiguration<Class,
ApplicationStateContribution> configuration)
+</div></div><p>In this case, the shoppingCart field will be null if the
ShoppingCart SSO does not exist, but will be non-null if it has been created
(either by assigning a value to the field, or by a different SSO field where
create is true).</p><h3 id="SessionStorage-PersistenceStrategies">Persistence
Strategies</h3><p>Main Article: <a shape="rect"
href="persistent-page-data.html#PersistentPageData-PersistenceStrategies">Persistent
Page Data</a></p><p>Each SSO is managed according to a persistence strategy.
The default persistence strategy, "session", stores the SSOs inside the
session. The session is created as needed.</p><h3
id="SessionStorage-ConfiguringSSOs">Configuring SSOs</h3><p>Generally, you will
need to configure your Session State Object if you want to change the
persistence strategy to other than the default. (Right now there's only one
built in strategy, but more will be coming in the future.)</p><p>Alternately,
you can configure a Session State Object in order to cont
rol how it is instantiated. You may need to inject some values into the SSO
when it is first created, or otherwise initialize it. In this case, you may
provide an <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ApplicationStateCreator.html";>ApplicationStateCreator</a>
object, which will be called upon to create the SSO as necessary. This is also
the technique to use when you want your SSO to be represented by an
<em>interface</em> rather than a <em>class</em>: you need to provide a creator
that knows about the class that implements the interface.</p><p>A Session State
Object is configured using contributions to the ApplicationStateManager
service. From your application's module:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[ public void
contributeApplicationStateManager(MappedConfiguration<Class,
ApplicationStateContribution> configuration)
{
ApplicationStateCreator<MyState> creator = new
ApplicationStateCreator<ShoppingCart>()
{
@@ -232,19 +158,7 @@ public class MyPage
configuration.add(ShoppingCart.class, new
ApplicationStateContribution("session", creator));
}
]]></script>
-</div></div>
-
-<p>Here, we have an SSO type of ShoppingCart, and we're providing a creator
for it. We've dolled the creator up with some generic types, but that isn't
essential.</p>
-
-<p>Our creator creates a new MyState instance using an alternate constructor
that takes the current date and time. Again, just an example.</p>
-
-<p>Finally, we create an <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ApplicationStateContribution.html";>ApplicationStateContribution</a>
identifying the strategy name and the creator, and give that to the
configuration.</p>
-
-<p><strong>Note:</strong> You might be confused by the name
"_Application_StateManager" and "_Application_StateCreator"; these reflect a
difference in naming between 5.0 and 5.1; SSOs were originally called
"Application State Objects", but that naming implied they were stored in the
ServletContext, as application global to all users. The new SessionState
annotation was introduced, but the existing services need to keep thier names
as-is.</p>
-
-<h2 id="SessionStorage-SessionAttributes">Session Attributes</h2>
-
-
+</div></div><p>Here, we have an SSO type of ShoppingCart, and we're providing
a creator for it. We've dolled the creator up with some generic types, but that
isn't essential.</p><p>Our creator creates a new MyState instance using an
alternate constructor that takes the current date and time. Again, just an
example.</p><p>Finally, we create an <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ApplicationStateContribution.html";>ApplicationStateContribution</a>
identifying the strategy name and the creator, and give that to the
configuration.</p><p><strong>Note:</strong> You might be confused by the name
"_Application_StateManager" and "_Application_StateCreator"; these reflect a
difference in naming between 5.0 and 5.1; SSOs were originally called
"Application State Objects", but that naming implied they were stored in the
ServletContext, as application global to all users. The new SessionState
annotation was introduce
d, but the existing services need to keep thier names as-is.</p><h2
id="SessionStorage-SessionAttributes">Session Attributes</h2>
<div class="aui-message hint shadowed information-macro">
<p class="title">Added in 5.2</p>
@@ -256,13 +170,8 @@ public class MyPage
</div>
<div style="border-right: 20px solid #D8E4F1;border-left: 20px solid #D8E4F1;">
-</div>
-
-<p>As an alternative to SSOs, Tapestry provides a <strong>Session
Attribute</strong> mechanism, which lets you store data in the session by name
(rather than type). It is particularly useful when integrating Tapestry with
legacy applications that directly manipulate the HttpSession.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>The Old Way</b></div><div
class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public class Page {
+<p> </p></div><p>As an alternative to SSOs, Tapestry provides a
<strong>Session Attribute</strong> mechanism, which lets you store data in the
session by name (rather than type). It is particularly useful when integrating
Tapestry with legacy applications that directly manipulate the
HttpSession.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>The Old
Way</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public class Page {
@Inject
private Request request;
@@ -271,40 +180,20 @@ public class Page {
}
}
]]></script>
-</div></div>
-
-<p>Starting with Tapestry 5.2, this can be accomplished just by annotating a
page or component property with @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SessionAttribute.html";>SessionAttribute</a>.
This annotation is used to map a property of a page or component to value
stored in session. Unlike Session State Objects, the name (not the type) of the
annotated property is used as the name of the session attribute to look for.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>The New Way</b></div><div
class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public class Page {
+</div></div><p>Starting with Tapestry 5.2, this can be accomplished just by
annotating a page or component property with @<a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/SessionAttribute.html";>SessionAttribute</a>.
This annotation is used to map a property of a page or component to value
stored in session. Unlike Session State Objects, the name (not the type) of the
annotated property is used as the name of the session attribute to look
for.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>The New
Way</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public class Page {
@SessionAttribute
private User loggedInUserName;
}
]]></script>
-</div></div>
-
-<p>You can also provide a name using the annotation's <code>value</code>
parameter:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public class Page {
+</div></div><p>You can also provide a name using the annotation's
<code>value</code> parameter:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public class Page {
@SessionAttribute("loggedInUserName")
private User userName;
}
]]></script>
-</div></div>
-
-
-<h3 id="SessionStorage-Pitfalls.1">Pitfalls</h3>
-
-<p>As with SSOs, when using Session Attributes you are creating a session-wide
data storage area that has the serious possibility of data collisions, not just
within your application but with other modules/libraries. To avoid problems,
you should qualify the session attribute name with a package-like naming
convention. For example, use something like "com.mycompany.myapp.username"
instead of just "username".</p>
-
-<p>It's best to define the session attribute name as constant, and use that in
the annotation's value parameter, rather then defaulting to the instance
variable name. This will help prevent subtle runtime errors due to
misspellings. For example:</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>The Safer
Way</b></div><div class="codeContent panelContent pdl">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[
-public static final String USER_NAME_SESSION_ATTRIBUTE =
"com.example.shoppingapp.username";
+</div></div><h3 id="SessionStorage-Pitfalls.1">Pitfalls</h3><p>As with SSOs,
when using Session Attributes you are creating a session-wide data storage area
that has the serious possibility of data collisions, not just within your
application but with other modules/libraries. To avoid problems, you should
qualify the session attribute name with a package-like naming convention. For
example, use something like "com.mycompany.myapp.username" instead of just
"username".</p><p>It's best to define the session attribute name as constant,
and use that in the annotation's value parameter, rather then defaulting to the
instance variable name. This will help prevent subtle runtime errors due to
misspellings. For example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>The Safer Way</b></div><div class="codeContent panelContent pdl">
+<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><![CDATA[public static final String
USER_NAME_SESSION_ATTRIBUTE = "com.example.shoppingapp.username";
...
@@ -313,9 +202,7 @@ public class Page {
private User userName;
}
]]></script>
-</div></div>
-
-<h2 id="SessionStorage-ClusteringIssues">Clustering Issues</h2>
+</div></div><p></p><h2 id="SessionStorage-ClusteringIssues">Clustering
Issues</h2>
<p>The Servlet API was designed with the intention that there would be only a
modest amount of server-side state, and that the stored values would be
individual numbers and strings, and thus, immutable.</p>
@@ -341,18 +228,8 @@ public class Page {
<h3
id="SessionStorage-SessionPersistedObjectAnalyzerService">SessionPersistedObjectAnalyzer
Service</h3>
-<p>The <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/SessionPersistedObjectAnalyzer.html";>SessionPersistedObjectAnalyzer</a>
service is ultimately responsible for determining whether a session persisted
object is dirty or not (dirty meaning in need of a restore into the session).
This is an extensible service where new strategies, for new classes, can be
introduced.</p>
-
-<h2 id="SessionStorage-SessionLocking">Session Locking</h2>
-
-<p>Starting with version 5.4, by default Tapestry will apply locking semantics
around access to the HttpSession. Reading attribute names occurs with a shared
read lock, and getting or setting an attribute upgrades the lock to an
exclusive write lock. This can tend to serialize threads when a number of
simultaneous (Ajax) requests from the client arrive. However, many
implementations of HttpSession are not thread safe, and often mutable
objects<br clear="none">
-are stored in the session and shared between threads.</p>
-
-<p>The <code>tapestry.session-locking-enabled</code> <a shape="rect"
href="configuration.html">symbol</a> can control this behavior. Setting this to
true (the default) will yield a more robust application; setting it to false
may speed up processing for more Ajax intensive applications (but care should
then be given to ensuring that objects shared inside the session are
themeselves immutable or thread-safe).</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">
-<script class="theme: Default; brush: java; gutter: false"
type="syntaxhighlighter"><