Author: buildbot
Date: Mon Jul 27 11:19:45 2015
New Revision: 959752
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/component-classes.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/component-classes.html
==============================================================================
--- websites/production/tapestry/content/component-classes.html (original)
+++ websites/production/tapestry/content/component-classes.html Mon Jul 27
11:19:45 2015
@@ -82,7 +82,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect"
href="page-and-component-classes-faq.html">Page And Component Classes FAQ</a>
+ <a shape="rect"
href="component-reference.html">Component Reference</a>
</div>
@@ -91,7 +91,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect"
href="component-reference.html">Component Reference</a>
+ <a shape="rect"
href="component-libraries.html">Component Libraries</a>
</div>
@@ -100,7 +100,7 @@
<span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
<div class="details">
- <a shape="rect"
href="component-libraries.html">Component Libraries</a>
+ <a shape="rect"
href="page-and-component-classes-faq.html">Page And Component Classes FAQ</a>
</div>
@@ -158,7 +158,7 @@ public class HelloWorld
}
}
</pre>
-</div></div><p>In this example, just like the first one, the component's only
job is to write out a fixed message. The @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>
annotation is a type of <em><a shape="rect"
href="component-rendering.html">render phase annotation</a></em>, a method
annotation that instructs Tapestry when and under what circumstances to invoke
methods of your class.</p><p>These methods are not necessarily public; they can
have any access level you like (unlike in Tapestry 4). By convention they
usually have package-private access level (the default).</p><h2
id="ComponentClasses-ComponentPackages">Component Packages</h2><p>Component
classes must exist within an appropriate package (this is necessary for runtime
code transformation and class reloading to operate).</p><p>These packages exist
under the application's root package, as follows:</p><ul><li>For pages,
place classes in <em>root</em>.<strong>pages</strong>. Page names are mapped
to classes within this package.</li><li>For mixins, place classes in
<em>root</em>.<strong>mixins</strong>. Mixin types are mapped to classes within
this package.</li><li>For other components, place classes in
<em>root</em>.<strong>components</strong>. Component types are mapped to
classes within this package.</li></ul><p>In addition, it is common for an
application to have base classes, often <em>abstract</em> base classes, that
should not be directly referenced. These should <em>not</em> go in the
<strong>pages</strong>, <strong>components</strong> or <strong>mixins</strong>
packages, because they then look like valid pages, components or mixins.
Instead, use the <em>root</em>.<strong>base</strong> package to store such base
classes.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon">
</span><div class="confluence-information-macro-body"><p>Only component
classes should go in any of these controlled packages; classes representing
data, or interfaces, or anything that isn't precisely a component class, must
go elsewhere. Any top-level class in any of the controlled packages will be
transformed at runtime. The only exception is inner classes<br clear="none">
(anonymous or not), which are loaded by the same class loader as the component
class loader, but not transformed as components.</p></div></div><h2
id="ComponentClasses-Sub-Folders/Sub-Packages">Sub-Folders /
Sub-Packages</h2><p>Classes do not have to go directly inside the package
(pages, components, mixins, etc.). It is valid to create a sub-package to store
some of the classes. The sub-package name becomes part of the page name or
component type. Thus you might define a page component
<code>com.example.myapp.pages.admin.CreateUser</code> and the logical page name
(which often shows up inside URLs) will be <st
rong>admin/CreateUser</strong>.</p><p>Tapestry performs some simple
optimizations of the logical page name (or component type, or mixin type). It
checks to see if the package name is either a prefix or a suffix of the
unqualified class name (case insensitively, of course) and removes the prefix
or suffix if so. The net result is that a class name such as
<code>com.example.myapp.pages.user.EditUser</code> will have a page name of
<code>user/Edit</code> (<em>not</em> <code>user/EditUser</code>). The goal here
is to provide shorter, more natural URLs.</p><h2
id="ComponentClasses-IndexPages">Index Pages</h2><p>One special simplification
are Index pages: if the logical page name is Index after removing the package
name from the unqualified class name, it will map to the root of that folder. A
class such as <code>com.example.myapp.pages.user.IndexUser</code> or
<code>com.example.myapp.pages.user.UserIndex</code> will have a page name of
<code>user/</code>.</p><p>In previous versions of Ta
pestry there was also the concept of a start page configured with the <code><a
shape="rect" href="configuration.html">tapestry.start-page-name</a></code>
configuration symbol (defaults to "start"). If a page with a name as configured
with that symbol exists at the root level, this page is used as the root URL.
This has precedence over an existing Index page. If for example you have a page
class <code>com.example.myapp.pages.Start</code> it will map to
<code>/</code>.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of start-pages is discouraged
and support for it will eventually be removed. Use an Index page
instead.</p></div></div><h2 id="ComponentClasses-Pagesvs.Components">Pages vs.
Components</h2><p>The distinction between pages and component is very, very
small. The only real difference is the pa
ckage name: <em>root</em>.<strong>pages</strong>.<em>PageName</em> for pages,
and <em>root</em>.<strong>components</strong>.<em>ComponentType</em> for
components. Conceptually, page components are simply the <em>root
component</em> of a page's component tree.</p><p><em>For Tapestry 4 users:
there was a much greater distinction in Tapestry 4 between pages and
components, which showed up as separate interfaces and a hierarchy of abstract
implementations to extend your classes from.</em></p><h2
id="ComponentClasses-ClassTransformation">Class Transformation</h2><p>Tapestry
uses your class as a starting point. It <em>transforms</em> your class at
runtime. This is necessary for a number of reasons, including to address how
Tapestry shares pages between requests.</p><p>For the most part, these
transformations are both sensible and invisible. In a few limited cases, they
are marginally <a shape="rect" class="external-link"
href="http://www.joelonsoftware.com/printerFriendly/articles/LeakyAb
stractions.html" >leaky</a> – for instance, the scope restrictions on
instance variables described below – but we feel that the programming
model in general will support very high levels of developer
productivity.</p><p>Because transformation doesn't occur until
<em>runtime</em>, the build stage of your application is not affected by the
fact that you are creating a Tapestry application. Further, your classes are
absolutely simple POJOs during unit testing.</p><h2
id="ComponentClasses-LiveClassReloading">Live Class Reloading</h2><p>Main
Article: <a shape="rect" href="class-reloading.html">Class
Reloading</a></p><p>Component classes are monitored for changes by the
framework. <a shape="rect" href="class-reloading.html">Classes are reloaded
when changed</a>. This allows you to build your application with a speed
approaching that of a scripting environment, without sacrificing any of the
power of the Java platform.</p><p>And it's fast! You won't even notice that
this magic
class reloading has occurred.</p><p>The net result: super productivity —
change your class, see the change instantly. This is designed to be a blend of
the best of scripting environments (such as Python or Ruby) with all the speed
and power of Java backing it up.</p><p>However, class reloading <em>only</em>
applies to component classes and, starting in 5.2, Tapestry IOC-based service
implementations (with some restrictions). Other classes, such as service
interfaces, entity/model classes, and other data objects, are loaded by the
normal class loader and not subject to live class reloading.</p><h2
id="ComponentClasses-InstanceVariables">Instance Variables</h2><p>Tapestry
components may have instance variables (unlike Tapestry 4, where you had to use
<em>abstract properties</em>).</p><p>Since release 5.3.2, instance variables
may be protected, or package private (that is, no access modifier). Under
specific circumstances they may even be public (public fields must either be
fina
l, or have the @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Retain.html";>Retain</a> annotation).</p><p><span
style="line-height: 1.4285715;">Be aware that you will need to provide getter
and setter methods to access your classes' instance variables. Tapestry
</span><em style="line-height: 1.4285715;">does not</em><span
style="line-height: 1.4285715;"> do this automatically unless you provide the
@</span><a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html";
style="line-height: 1.4285715;">Property</a><span style="line-height:
1.4285715;"> annotation on the field.</span></p><h2
id="ComponentClasses-TransientInstanceVariables">Transient Instance
Variables</h2><p>Unless an instance variable is decorated with an annotation,
it will be a <em>transient</em> instance variable. This means that its value
resets to its default value a
t the end of reach request (when the <a shape="rect"
href="page-life-cycle.html">page is detached from the request</a>).</p><div
class="confluence-information-macro confluence-information-macro-note"><p
class="title">About initialization</p><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Never initialize an instance field
to a <em>mutable</em> object at the point of declaration. If this is done, the
instance created from that initializer becomes the default value for that field
and is reused inside the component on every request. This could cause state to
inadvertently be shared between different sessions in an
application.</p></div></div>
+</div></div><p>In this example, just like the first one, the component's only
job is to write out a fixed message. The @<a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/BeginRender.html";>BeginRender</a>
annotation is a type of <em><a shape="rect"
href="component-rendering.html">render phase annotation</a></em>, a method
annotation that instructs Tapestry when and under what circumstances to invoke
methods of your class.</p><p>These methods are not necessarily public; they can
have any access level you like (unlike in Tapestry 4). By convention they
usually have package-private access level (the default).</p><h2
id="ComponentClasses-ComponentPackages">Component Packages</h2><p>Component
classes must exist within an appropriate package (this is necessary for runtime
code transformation and class reloading to operate).</p><p>These packages exist
under the application's root package, as follows:</p><ul><li>For pages,
place classes in <em>root</em>.<strong>pages</strong>. Page names are mapped
to classes within this package.</li><li>For mixins, place classes in
<em>root</em>.<strong>mixins</strong>. Mixin types are mapped to classes within
this package.</li><li>For other components, place classes in
<em>root</em>.<strong>components</strong>. Component types are mapped to
classes within this package.</li></ul><p>In addition, it is common for an
application to have base classes, often <em>abstract</em> base classes, that
should not be directly referenced. These should <em>not</em> go in the
<strong>pages</strong>, <strong>components</strong> or <strong>mixins</strong>
packages, because they then look like valid pages, components or mixins.
Instead, use the <em>root</em>.<strong>base</strong> package to store such base
classes.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon">
</span><div class="confluence-information-macro-body"><p>Only component
classes should go in any of these controlled packages; classes representing
data, or interfaces, or anything that isn't precisely a component class, must
go elsewhere. Any top-level class in any of the controlled packages will be
transformed at runtime. The only exception is inner classes<br clear="none">
(anonymous or not), which are loaded by the same class loader as the component
class loader, but not transformed as components.</p></div></div><h2
id="ComponentClasses-Sub-Folders/Sub-Packages">Sub-Folders /
Sub-Packages</h2><p>Classes do not have to go directly inside the package
(pages, components, mixins, etc.). It is valid to create a sub-package to store
some of the classes. The sub-package name becomes part of the page name or
component type. Thus you might define a page component
<code>com.example.myapp.pages.admin.CreateUser</code> and the logical page name
(which often shows up inside URLs) will be <st
rong>admin/CreateUser</strong>.</p><p>Tapestry performs some simple
optimizations of the logical page name (or component type, or mixin type). It
checks to see if the package name is either a prefix or a suffix of the
unqualified class name (case insensitively, of course) and removes the prefix
or suffix if so. The net result is that a class name such as
<code>com.example.myapp.pages.user.EditUser</code> will have a page name of
<code>user/Edit</code> (<em>not</em> <code>user/EditUser</code>). The goal here
is to provide shorter, more natural URLs.</p><h2
id="ComponentClasses-IndexPages">Index Pages</h2><p>One special simplification
are Index pages: if the logical page name is Index after removing the package
name from the unqualified class name, it will map to the root of that folder. A
class such as <code>com.example.myapp.pages.user.IndexUser</code> or
<code>com.example.myapp.pages.user.UserIndex</code> will have a page name of
<code>user/</code>.</p><p>In previous versions of Ta
pestry there was also the concept of a start page configured with the <code><a
shape="rect" href="configuration.html">tapestry.start-page-name</a></code>
configuration symbol (defaults to "start"). If a page with a name as configured
with that symbol exists at the root level, this page is used as the root URL.
This has precedence over an existing Index page. If for example you have a page
class <code>com.example.myapp.pages.Start</code> it will map to
<code>/</code>.</p><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Use of start-pages is discouraged
and support for it will eventually be removed. Use an Index page
instead.</p></div></div><h2 id="ComponentClasses-Pagesvs.Components">Pages vs.
Components</h2><p>The distinction between pages and component is very, very
small. The only real difference is the pa
ckage name: <em>root</em>.<strong>pages</strong>.<em>PageName</em> for pages,
and <em>root</em>.<strong>components</strong>.<em>ComponentType</em> for
components. Conceptually, page components are simply the <em>root
component</em> of a page's component tree.</p><p><em>For Tapestry 4 users:
there was a much greater distinction in Tapestry 4 between pages and
components, which showed up as separate interfaces and a hierarchy of abstract
implementations to extend your classes from.</em></p><h2
id="ComponentClasses-ClassTransformation">Class Transformation</h2><p>Tapestry
uses your class as a starting point. It <em>transforms</em> your class at
runtime. This is necessary for a number of reasons, including to address how
Tapestry shares pages between requests.</p><p>For the most part, these
transformations are both sensible and invisible. In a few limited cases, they
are marginally <a shape="rect" class="external-link"
href="http://www.joelonsoftware.com/printerFriendly/articles/LeakyAb
stractions.html" >leaky</a> – for instance, the scope restrictions on
instance variables described below – but we feel that the programming
model in general will support very high levels of developer
productivity.</p><p>Because transformation doesn't occur until
<em>runtime</em>, the build stage of your application is not affected by the
fact that you are creating a Tapestry application. Further, your classes are
absolutely simple POJOs during unit testing.</p><h2
id="ComponentClasses-LiveClassReloading">Live Class Reloading</h2><p>Main
Article: <a shape="rect" href="class-reloading.html">Class
Reloading</a></p><p>Component classes are monitored for changes by the
framework. <a shape="rect" href="class-reloading.html">Classes are reloaded
when changed</a>. This allows you to build your application with a speed
approaching that of a scripting environment, without sacrificing any of the
power of the Java platform.</p><p>And it's fast! You won't even notice that
this magic
class reloading has occurred.</p><p>The net result: super productivity —
change your class, see the change instantly. This is designed to be a blend of
the best of scripting environments (such as Python or Ruby) with all the speed
and power of Java backing it up.</p><p>However, class reloading <em>only</em>
applies to component classes (pages, components and mixins) and, starting in
5.2, Tapestry IOC-based service implementations (with some restrictions). Other
classes, such as service interfaces, entity/model classes, and other data
objects, are loaded by the normal class loader and not subject to live class
reloading.</p><h2 id="ComponentClasses-InstanceVariables">Instance
Variables</h2><p>Tapestry components may have instance variables (unlike
Tapestry 4, where you had to use <em>abstract properties</em>).</p><p>Since
release 5.3.2, instance variables may be protected, or package private (that
is, no access modifier). Under specific circumstances they may even be public
(pu
blic fields must either be final, or have the @<a shape="rect"
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Retain.html";>Retain</a> annotation).</p><p><span
style="line-height: 1.4285715;">Be aware that you will need to provide getter
and setter methods to access your classes' instance variables. Tapestry
</span><em style="line-height: 1.4285715;">does not</em><span
style="line-height: 1.4285715;"> do this automatically unless you provide the
@</span><a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Property.html";
style="line-height: 1.4285715;">Property</a><span style="line-height:
1.4285715;"> annotation on the field.</span></p><h2
id="ComponentClasses-TransientInstanceVariables">Transient Instance
Variables</h2><p>Unless an instance variable is decorated with an annotation,
it will be a <em>transient</em> instance variable. This means that its valu
e resets to its default value at the end of reach request (when the <a
shape="rect" href="page-life-cycle.html">page is detached from the
request</a>).</p><div class="confluence-information-macro
confluence-information-macro-note"><p class="title">About
initialization</p><span class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Never initialize an instance field
to a <em>mutable</em> object at the point of declaration. If this is done, the
instance created from that initializer becomes the default value for that field
and is reused inside the component on every request. This could cause state to
inadvertently be shared between different sessions in an
application.</p></div></div>
<div class="confluence-information-macro
confluence-information-macro-warning"><p class="title">Deprecated since
5.2</p><span class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
</div></div>
