Modified: websites/production/tapestry/content/starting-the-ioc-registry.html
==============================================================================
--- websites/production/tapestry/content/starting-the-ioc-registry.html
(original)
+++ websites/production/tapestry/content/starting-the-ioc-registry.html Sun Feb
11 12:23:46 2018
@@ -85,10 +85,12 @@ Registry registry = builder.build();
registry.performRegistryStartup();</pre>
</div></div><p>You may invoke add() as many times as you wish, or pass as many
module classes as you wish.</p><p>Using this approach, you will form a Registry
containing the built-in services from the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/TapestryIoCModule.html";>Tapestry
IoC module</a>, plus the modules you explicitly list.</p><p>The call to
performRegistryStartup() is necessary to ensure that any services marked with
the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/EagerLoad.html";>EagerLoad</a>
annotation are, in fact, loaded.</p>
-<div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div><p>As of version 5.2 the class <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html";>RegistryBuilder</a>
has convenience methods to build and start a Registry. The static method <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html#buildAndStartupRegistry(java.lang.Class...)">RegistryBuilder.buildAndStartupRegistry(Class...)</a>
constructs a registry, adds a number of modules to the registry and performs
registry startup. The returned registry is ready to use.</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+
+
+<div class="aui-message aui-message-info">
+Added in 5.2 |
+ 
+</div><p>As of version 5.2 the class <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html";>RegistryBuilder</a>
has convenience methods to build and start a Registry. The static method <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html#buildAndStartupRegistry(java.lang.Class...)">RegistryBuilder.buildAndStartupRegistry(Class...)</a>
constructs a registry, adds a number of modules to the registry and performs
registry startup. The returned registry is ready to use.</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;">Registry registry =
RegistryBuilder.buildAndStartupRegistry(AppModule.class, UtilModule.class);
</pre>
</div></div><h1
id="StartingtheIoCRegistry-BuildingtheDefaultRegistry">Building the Default
Registry</h1><p>The default registry is available by invoking the static method
<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCUtilities.html#buildDefaultRegistry";>IOCUtilities.buildDefaultRegistry()</a>.
This method builds a Registry using <a
href="starting-the-ioc-registry.html">autoloading logic</a>, where modules to
load are identified via a JAR Manifest entry.</p><p>In addition, the JVM system
property <code>tapestry.modules</code> (if specified) is a list of additional
module classes to load. This is often used in development, where tests may be
executed against the local classes, not JARs, and so there is no manifest to
read.</p><h1 id="StartingtheIoCRegistry-ShuttingdowntheRegistry">Shutting down
the Registry</h1><p>The method <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Reg
istry.html#shutdown">Registry.shutdown()</a> will shutdown the Registry. This
immediately invalidates all service proxies. Some services may have chosen to
register for shutdown notification (for example, to do cleanup work such as
closing a database connection).</p><p>Once the Registry is shutdown, it may not
be used again: it will not be possible to access services within the Registry,
or invoke methods on services previously acquired. All you can do is release
the Registry to the garbage collector.</p><p> </p><p></p></div>
Modified: websites/production/tapestry/content/tapestry-ioc-configuration.html
==============================================================================
--- websites/production/tapestry/content/tapestry-ioc-configuration.html
(original)
+++ websites/production/tapestry/content/tapestry-ioc-configuration.html Sun
Feb 11 12:23:46 2018
@@ -172,10 +172,12 @@
} </pre>
</div></div><p>Now the FileServicerDispatcher builder method gets a Map with
at least four entries in it.</p><p>Because Tapestry IoC is highly dynamic (it
scans the visible JAR manifest files to identify module classes), the
FileServicerDispatcher service may be in one module, and the other contributing
modules (such as the one that contributes the Office file services) may be
written at a much later date. With no change to the FileServicerDispatcher
service or its module class, the new services "plug into" the overall solution,
simply by having their JAR's on the runtime classpath.</p><h1
id="TapestryIoCConfiguration-Namingconventionsvs.Annotations">Naming
conventions vs. Annotations</h1><p>
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div>If you prefer annotations over naming conventions you can
use the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Contribute.html";>Contribute</a>
annotation. As of version 5.2 this annotation that may be placed on a
contributor method of a module instead of starting the methods name with
"contribute". The value of the annotation is the type of the service to
contribute into.<p>The primary reasons to use @Contribute and marker
annotations is twofold:</p><ul><li>There is no longer a linkage between the
contribution method name and the service id, which is much more refactoring
safe: if you change the service interface name, or the ID of the service, your
method will still be invoked when using @Contribute.</li></ul><ul><li>It makes
it much easier for an <a href="tapestry-ioc-configuration.html">override</a>
of the service to get the configuration intended for the original
service.</li></ul><p>The followin
g example is an annotation-based alternative for the contribution method
above.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.2 |
+ 
+</div>If you prefer annotations over naming conventions you can use the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Contribute.html";>Contribute</a>
annotation. As of version 5.2 this annotation that may be placed on a
contributor method of a module instead of starting the methods name with
"contribute". The value of the annotation is the type of the service to
contribute into.<p>The primary reasons to use @Contribute and marker
annotations is twofold:</p><ul><li>There is no longer a linkage between the
contribution method name and the service id, which is much more refactoring
safe: if you change the service interface name, or the ID of the service, your
method will still be invoked when using @Contribute.</li></ul><ul><li>It makes
it much easier for an <a href="tapestry-ioc-configuration.html">override</a>
of the service to get the configuration intended for the original
service.</li></ul><p>The following example is
an annotation-based alternative for the contribution method above.</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(FileServiceDispatcher.class)
public static void
arbitraryMethodName(MappedConfiguration<String,FileServicer>
configuration)
{
@@ -239,16 +241,20 @@ public static void arbitraryMethodName(M
} </pre>
</div></div><p>Often, you don't care about ordering; the first form of the add
method is used then. The ordering algorithm will find a spot for the object
(here the JMSStartup instance) based on the constraints of other contributed
objects.</p><p>For the "FileSystem" contribution, a constraint has been
specified, indicating that FileSystem should be ordered after some other
contribution named "CacheSetup". Any number of such <a
href="tapestry-ioc-configuration.html">ordering constraints</a> may be
specified (the <code>add()</code> method accepts a variable number of
arguments).</p><p>The object passed in may be null; this is valid, and is
considered a "join point": points of reference in the list that don't actually
have any meaning of their own, but can be used when ordering other elements.
<em>TODO: Show example for chain of command, once that's put
together.</em></p><p>Null values, once ordered, are edited out (the List passed
to the service builder method does not include any n
ulls). Again, they are allowed as placeholders, for the actual contributed
objects to organize themselves around.
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.3</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p>When using <code>add()</code> without any specific constraints, a default
constraint is added: after the previously added element. These default
constraints are only within a single contribution method, but makes it much
easier to set the order of several related contributions. Note that the
contributions will be ordered relative to each other and it's possible that
contributions by some other module or method may be interspersed between
them.</p>
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.3 |
+When using {{add()}} without any specific constraints, a default constraint is
added: after the previously added element. These default constraints are only
within a single contribution method, but makes it much easier to set the order
of several related contributions. Note that the contributions will be ordered
relative to each other and it's possible that contributions by some other
module or method may be interspersed between them.
+
</div><h2 id="TapestryIoCConfiguration-MappedConfigurations">Mapped
Configurations</h2><p>As discussed in the earlier examples, mapped
configurations are also supported. The keys passed in must be unique. When
conflicts occur, Tapestry will log warnings (identifying the source of the
conflict, in terms of invoked methods), and ignore the conflicting
value.</p><p>Neither the key nor the value may be null.</p><p>For mapped
configurations where the key type is String, a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/CaseInsensitiveMap.html";>CaseInsensitiveMap</a>
will be automatically used (and passed to the service builder method), to help
ensure that <a href="tapestry-ioc-configuration.html">case insensitivity</a>
is automatic and pervasive.</p><h1
id="TapestryIoCConfiguration-InjectingClasses">Injecting Classes</h1><p>All
three configuration interfaces have a second method,
<code>addInstance()</code>. This method takes a cla
ss, not an instance. The class is instantiated and contributed. If the
constructor for the class takes dependencies, those are injected as
well.</p><h1 id="TapestryIoCConfiguration-InjectingResources">Injecting
Resources</h1><p>In addition to injecting services into a contributor method
(via the @InjectService and @Inject annotations), Tapestry will key off of the
parameter type to allow other things to be injected.</p><ul><li><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>:
access to other services visible to the contributing
module</li><li>org.slf4j.Logger: the Logger for the service being contributed
to</li></ul><p>No annotation is needed for these cases.</p><p><span
class="confluence-anchor-link"
id="TapestryIoCConfiguration-overrides"></span></p><h1
id="TapestryIoCConfiguration-ConfigurationOverrides">Configuration
Overrides</h1><p>
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.1</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div>The OrderedConfiguration and MappedConfiguration interfaces
now support overrides. An override is a replacement for a normally contributed
object. An override <em>must</em> match a contributed object, and each
contributed object may be overridden at most once.<p>The new object replaces
the original object; alternately, you may override the original object with
null.</p><p>This allows you to fine tune configuration values that are
contributed from modules that you are using, rather than just those that you
write yourself. It is powerful and a bit dangerous.</p><p>In Tapestry 5.0,
services that wanted to support this kind of override behavior had to implement
it on an ad-hoc basis, such as ApplicationDefaults overriding FactoryDefaults.
In many cases, that is still useful.</p><p> </p><p></p></div>
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.1 |
+ 
+</div>The OrderedConfiguration and MappedConfiguration interfaces now support
overrides. An override is a replacement for a normally contributed object. An
override <em>must</em> match a contributed object, and each contributed object
may be overridden at most once.<p>The new object replaces the original object;
alternately, you may override the original object with null.</p><p>This allows
you to fine tune configuration values that are contributed from modules that
you are using, rather than just those that you write yourself. It is powerful
and a bit dangerous.</p><p>In Tapestry 5.0, services that wanted to support
this kind of override behavior had to implement it on an ad-hoc basis, such as
ApplicationDefaults overriding FactoryDefaults. In many cases, that is still
useful.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/tapestry-ioc-decorators.html
==============================================================================
--- websites/production/tapestry/content/tapestry-ioc-decorators.html (original)
+++ websites/production/tapestry/content/tapestry-ioc-decorators.html Sun Feb
11 12:23:46 2018
@@ -133,10 +133,12 @@ public class MyAppModule
} </pre>
</div></div><p>"before:*" indicates that this decorator should come before any
decorator in <em>any</em> module.</p><p><strong>Note:</strong> the ordering of
decorators is in terms of the <em>effect</em> desired. Internally, the
decorators are invoked last to first (since each once receives the "next"
interceptor as its delegate). So the core service implementation is created
(via a service builder method) and that is passed to the last decorator method.
The interceptor created there is passed to the the next-to-last decorator
method, and so forth.</p><p>It should now be evident that the delegate passed
into a decorator method is sometimes the core service implementation, and some
times an interceptor object created by some other decorator method.</p><h1
id="TapestryIoCDecorators-Annotationdrivendecorators">Annotation driven
decorators</h1><p>
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div>Starting from version 5.2, Tapestry supports
annotation-driven decorator methods. If the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html";>@Decorate</a>
annotation is present, the decorator method can be arbitrary named, as shown
in the following example.<div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.2 |
+ 
+</div>Starting from version 5.2, Tapestry supports annotation-driven decorator
methods. If the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html";>@Decorate</a>
annotation is present, the decorator method can be arbitrary named, as shown
in the following example.<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;"> @Decorate
@Match("*DAO")
public static <T> T byServiceId(Class<T> serviceInterface, T
delegate,
Modified:
websites/production/tapestry/content/using-jsr-330-standard-annotations.html
==============================================================================
---
websites/production/tapestry/content/using-jsr-330-standard-annotations.html
(original)
+++
websites/production/tapestry/content/using-jsr-330-standard-annotations.html
Sun Feb 11 12:23:46 2018
@@ -77,10 +77,12 @@
<div id="content">
<div id="ConfluenceContent"><p>
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.3</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div><strong>JSR-330 annotations</strong> can be used for
injection in Tapestry 5.3 and later.<div class="aui-label" style="float:right"
title="Related Articles">
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.3 |
+ 
+</div><strong>JSR-330 annotations</strong> can be used for injection in
Tapestry 5.3 and later.<div class="aui-label" style="float:right"
title="Related Articles">
Modified: websites/production/tapestry/content/version-numbers.html
==============================================================================
--- websites/production/tapestry/content/version-numbers.html (original)
+++ websites/production/tapestry/content/version-numbers.html Sun Feb 11
12:23:46 2018
@@ -69,10 +69,12 @@
<div id="content">
<div id="ConfluenceContent"><p>
-</p><div class="confluence-information-macro
confluence-information-macro-information"><p class="title">Added in
5.3</p><span class="aui-icon aui-icon-small aui-iconfont-info
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body">
-</div></div>
-<div class="error"><span class="error">Unknown macro: {div}</span>
-<p>Tapestry version numbering was change starting in release 5.3. Tapestry
5.2 and earlier used a different numbering scheme whose primary failing was
that, from the version number, it was not obvious what the <em>stability</em>
of the version was.</p>
+
+
+</p><div class="aui-message aui-message-info">
+Added in 5.3 |
+Tapestry version numbering was change starting in release 5.3. Tapestry 5.2
and earlier used a different numbering scheme whose primary failing was that,
from the version number, it was not obvious what the _stability_ of the version
was.
+
</div>This document describes Tapestry's version numbering system. This is
important, as version numbers relate both to artifacts available for download,
or from a Maven repository, and also to bugs recorded in the issue tracking
system.<h1 id="VersionNumbers-TapestryReleaseNumbers">Tapestry Release
Numbers</h1><p>Tapestry release numbers consist of a product version number,
and release index number, seperated by periods, for example "5.3". The product
version number, 5, is unlikely to change any time soon (it would indicate a
non-backwards compatible rewrite of the framework, and we've had enough of
that, thank you very much).</p><h1
id="VersionNumbers-TapestryStableReleaseVersions">Tapestry Stable Release
Versions</h1><p>Tapestry stable releases use the name version number as the
release number.</p><p>A bug fix release follows a stable release, when
necessary. Bug fix releases add a sequence number to the product release
number. Thus, the first bug fix release for Tapestry 5.3 wil
l be version 5.3.1, then 5.3.2, as necessary.</p><p>A bug fix release
<em>replaces</em> the previous stable release.</p><h1
id="VersionNumbers-PreviewVersions">Preview Versions</h1><p>During the course
of development of a release, there will be preview releases of non-final
versions. A preview version consists of the product version, a stability term,
and an index number, separated by dashes. The stability term is "alpha",
"beta", or "rc".</p><p>The index number starts at 1. A preview version number
might be "5.3-alpha-2", or "5.3-beta-1", for example. The index number resets
back to one when the stability itself is upgraded.</p><p>"alpha" versions are
not stable; the represent functionality in flux; classes and methods may be
renamed or otherwise refactored between releases.</p><p>"beta" versions occur
once main functionality is complete; they exist to fix bugs in both old and new
functionality, and fill any gaps in functionality.</p><p>"rc" versions are
"release candidates"; the f
unctionality should be solid; the point of a release candidate is to get wide
exposure to the new codebase to ensure that the final release is free of
bugs.</p><h1 id="VersionNumbers-PreviewPackages">Preview Packages</h1><p>A
preview package may be created at any time. A tag is created in Git to label
the exact source from which the preview package is generated. The preview
package is built and uploaded to the Apache Nexus. Once uploaded, the master
version number (in trunk) should be advanced to the next index number within
the same stability series (example: "5.3-alpha-2" to "5.3-alpha-3").</p><p>The
Apache Nexus URL for the preview package may be distributed on the Tapestry
user mailing list. However, preview packages are deleted, not released. This is
important ... preview packages are never released to the Maven Central
repository, only final releases are distributed via Maven Central.</p><p>A
stability vote may follow a preview package. This is to vote the code base up
to the
next level of stability (to "beta", then "rc", then "stable"). This a lazy
consensus vote.</p><h1 id="VersionNumbers-StableReleases">Stable
Releases</h1><p>Once a version has been voted "stable", a release may be built
and uploaded to the Apache Nexus. A stable release also includes additional
non-Maven artifacts containing the project's source code, and additional<br
clear="none"> artifacts containing JavaDoc or other reports. The other
artifacts are distributed via the Apache Mirrors.</p><p>The vote for a release
is a binding vote, requiring at least 3 +1 votes and no vetoes, as outlined in
<a class="external-link"
href="http://www.apache.org/foundation/voting.html";>http://www.apache.org/foundation/voting.html</a></p><p>Following
a successful release vote, the final release artifacts in the Apache Nexus
repository may be released to the Maven Central repository, and the additional
artifacts moved into place for download from the Apache distribution mirrors.
This is also the point
at which the Tapestry wiki is updated to announce the new release (and
provide proper links to it), as well as announcements on the Tapestry user
mailing list and elsewhere.</p><p>Bug fix releases are follow-ons to stable
releases. Bug fix versions automatically start at stability "rc", reflecting
the fact that only localized bug fixes are expected to be included in such a
release. Once all desired bug fixes are in place, a stability vote (to
"stable") is followed by a release vote.</p></div>
</div>
