Author: buildbot
Date: Sun Feb 18 19:21:00 2018
New Revision: 1025566
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/cache/main.pageCache
websites/production/tapestry/content/development-dashboard.html
websites/production/tapestry/content/integration-testing.html
websites/production/tapestry/content/ioc.html
websites/production/tapestry/content/tapestry-ioc-modules.html
websites/production/tapestry/content/tapestry-ioc-overview.html
websites/production/tapestry/content/unit-testing-pages-or-components.html
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/tapestry/content/development-dashboard.html
==============================================================================
--- websites/production/tapestry/content/development-dashboard.html (original)
+++ websites/production/tapestry/content/development-dashboard.html Sun Feb 18
19:21:00 2018
@@ -67,7 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>The <strong>development
dashboard</strong> is a built-in Tapestry page that can help identify and
resolve problems in your application.</p><p>The dashboard is typically only
available to requests from localhost (the page is whitelist access only, see <a
href="development-dashboard.html">Development Dashboard</a>).</p><p><span>Some
features of the dashboard are only available in development
mode.</span></p><p>The dashboard is available via the URI "core/t5dashboard",
or can be accessed by the <a class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/components/DevTool.html";>DevTool</a>
component's dropdown menu.</p><p><span> <span
class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
image-center" width="500"
src="development-dashboard.data/Tapestry_5_Dashboard_-_pages.png"></span></span></p><p>By
default, there a
re three tabs (this is extensible).</p><h2
id="DevelopmentDashboard-Pages">Pages</h2><p>The pages tab shows what pages are
currently loaded into the application. Tapestry only loads a page when it is
first needed.</p><p>It is possible to clear out Tapestry's caches, forcing a
reload. You can also run a garbage collection (GC).</p><p>It is possible to
load any individual page, or attempt to load all pages. This can be a good way
to see if all pages (and templates) are error free ... loading all will catch
quite a few potential errors.</p><h2
id="DevelopmentDashboard-Services">Services</h2><p>When using Tapestry there
will often be a large number of services defined in the registry; a mix of the
built-in services provided by the framework and your own.</p><p>Services are
usually only instantiated once they are needed.</p><p><span
class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
image-center" width="500"
src="development-dashboard.data/Tapestry_5_Dashboard.png"></span></p><p> </p><p>Services
may be builtin, defined, virtual or real.</p><p><strong>Builtin</strong> only
applies to a few special services that are part of Tapestry
IoC.</p><p><strong>Defined</strong> services are defined in some module, but
have not yet been referenced in any way.</p><p><strong>Virtual</strong>
services have been referenced and have gotten as far as creating a service
proxy.</p><p><strong>Real</strong> services have had methods invoked, this
forces the <em>realization</em> of the service which includes instantiating the
service, injecting dependencies, and decorating with any applicable
interceptors.</p><h2 id="DevelopmentDashboard-ComponentLibraries">Component
Libraries</h2><p><span class="confluence-embedded-file-wrapper
image-center-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image image-center" width="500"
src="development-dashboard.data/Tapestry_5_Dashboard_-_libs.
png"></span></p><p>This page gives a summary of all component libraries used
in the current application.</p></div>
+ <div id="ConfluenceContent"><p>The <strong>development
dashboard</strong> is a built-in Tapestry page that can help identify and
resolve problems in your application.</p><p>The dashboard is typically only
available to requests from localhost (the page is whitelist access only, see <a
href="security.html">Security</a>).</p><p><span>Some features of the dashboard
are only available in development mode.</span></p><p>The dashboard is available
via the URI "core/t5dashboard", or can be accessed by the <a
class="external-link"
href="http://tapestry.apache.org/5.4/apidocs/org/apache/tapestry5/corelib/components/DevTool.html";>DevTool</a>
component's dropdown menu.</p><p><span> <span
class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
image-center" width="500"
src="development-dashboard.data/Tapestry_5_Dashboard_-_pages.png"></span></span></p><p>By
default, there are three tabs (this is ext
ensible).</p><h2 id="DevelopmentDashboard-Pages">Pages</h2><p>The pages tab
shows what pages are currently loaded into the application. Tapestry only loads
a page when it is first needed.</p><p>It is possible to clear out Tapestry's
caches, forcing a reload. You can also run a garbage collection (GC).</p><p>It
is possible to load any individual page, or attempt to load all pages. This can
be a good way to see if all pages (and templates) are error free ... loading
all will catch quite a few potential errors.</p><h2
id="DevelopmentDashboard-Services">Services</h2><p>When using Tapestry there
will often be a large number of services defined in the registry; a mix of the
built-in services provided by the framework and your own.</p><p>Services are
usually only instantiated once they are needed.</p><p><span
class="confluence-embedded-file-wrapper image-center-wrapper
confluence-embedded-manual-size"><img class="confluence-embedded-image
image-center" width="500" src="development-dashboar
d.data/Tapestry_5_Dashboard.png"></span></p><p> </p><p>Services may be
builtin, defined, virtual or real.</p><p><strong>Builtin</strong> only applies
to a few special services that are part of Tapestry
IoC.</p><p><strong>Defined</strong> services are defined in some module, but
have not yet been referenced in any way.</p><p><strong>Virtual</strong>
services have been referenced and have gotten as far as creating a service
proxy.</p><p><strong>Real</strong> services have had methods invoked, this
forces the <em>realization</em> of the service which includes instantiating the
service, injecting dependencies, and decorating with any applicable
interceptors.</p><h2 id="DevelopmentDashboard-ComponentLibraries">Component
Libraries</h2><p><span class="confluence-embedded-file-wrapper
image-center-wrapper confluence-embedded-manual-size"><img
class="confluence-embedded-image image-center" width="500"
src="development-dashboard.data/Tapestry_5_Dashboard_-_libs.png"></span></p><p>This
pa
ge gives a summary of all component libraries used in the current
application.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/integration-testing.html
==============================================================================
--- websites/production/tapestry/content/integration-testing.html (original)
+++ websites/production/tapestry/content/integration-testing.html Sun Feb 18
19:21:00 2018
@@ -109,7 +109,7 @@
</div>
-<p>The Tapestry Test Utilities is a small library to make it easier to build
integration test suites around <a class="external-link"
href="http://www.openqa.org/selenium/"; rel="nofollow">Selenium</a> version
2.14.0.</p><p>The strategy is to start, in-process, a Selenimum Server (which,
in turn, starts and manages a web browser), a Jetty instance (for the web
browser to talk to), and a Selenium client (which talks to the
server).</p><p>The client is able to request URLs, fill in form data, click
links, and make assertions about output and behavior.</p><h1
id="IntegrationTesting-Usage">Usage</h1><p>The core part of this library is a
base class for you to extend your tests classes : <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/SeleniumTestCase.html";>SeleniumTestCase</a>.</p><p>This
class is responsible for starting an instance of Jetty to server your web
application, as well as a copy of Selenium Server. It also implements the <a
class="external-link"
href="http://release.openqa.org/selenium-remote-control/0.9.0/doc/java/";
rel="nofollow">Selenium</a> interface.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Before Tapestry 5.2, your class
should extend <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/AbstractIntegrationTestSuite.html";>AbstractIntegrationTestSuite</a></p></div></div><p>Here's
an example from one of the Tapestry modules:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Your Integration Test Class :
SinglePersistenceUnitIntegrationTest.java</b></div><div class="codeContent
panelContent pdl">
+<p>The Tapestry Test Utilities is a small library to make it easier to build
integration test suites around <a class="external-link"
href="http://www.seleniumhq.org"; rel="nofollow">Selenium</a> version
2.14.0.</p><p>The strategy is to start, in-process, a Selenium Server (which,
in turn, starts and manages a web browser), a Jetty instance (for the web
browser to talk to), and a Selenium client (which talks to the
server).</p><p>The client is able to request URLs, fill in form data, click
links, and make assertions about output and behavior.</p><h1
id="IntegrationTesting-Usage">Usage</h1><p>The core part of this library is a
base class for you to extend your tests classes : <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/test/SeleniumTestCase.html";>SeleniumTestCase</a>.</p><p>This
class is responsible for starting an instance of Jetty to server your web
application, as well as a copy of Selenium Server. It also implements the <a
class
="external-link"
href="http://release.openqa.org/selenium-remote-control/0.9.0/doc/java/";
rel="nofollow">Selenium</a> interface.</p><div
class="confluence-information-macro confluence-information-macro-note"><span
class="aui-icon aui-icon-small aui-iconfont-warning
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>Before Tapestry 5.2, your class
should extend AbstractIntegrationTestSuite</p></div></div><p>Here's an example
from one of the Tapestry modules:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>Your Integration Test Class :
SinglePersistenceUnitIntegrationTest.java</b></div><div class="codeContent
panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.apache.tapestry5.jpa.integration.app2;
import org.apache.tapestry5.test.SeleniumTestCase;
Modified: websites/production/tapestry/content/ioc.html
==============================================================================
--- websites/production/tapestry/content/ioc.html (original)
+++ websites/production/tapestry/content/ioc.html Sun Feb 18 19:21:00 2018
@@ -118,7 +118,7 @@
</div>
-<p>An additional benefit of using IoC is that, by breaking a complex system
into small pieces, it becomes easier to modify and extend the system, by
overriding or replacing selected parts of the system.</p><p>The use of IoC in
Tapestry represents an evolution from Tapestry 3 to Tapestry 4 to Tapestry 5.
Tapestry 3 did not use IoC, though it included some weaker mechanisms, such as
extensions, that served a similar purpose. To make large scale changes to the
behavior of Tapestry 3 required subclassing key classes and overriding
methods.</p><p>Tapestry 4 introduced the use of the <a class="external-link"
href="http://hivemind.apache.org/";>Apache HiveMind</a> IoC container. In fact,
the HiveMind project was created specifically for use as the IoC container for
Tapestry 4. Tapestry 4 has met its goals for extensibility and configurability,
largely because of HiveMind's flexibility.</p><p>Tapestry 5 extends on this,
replacing HiveMind with a new container specifically build for Tapestry
5, designed for greater ease of use, expressiveness and performance. HiveMind
itself has been subsequently shelved; T5 IoC can be considered a streamlined
and improved HiveMind. And T5 IoC can be used separately from the rest of
Tapestry!</p><h2 id="IOC-WhyNotSpring?">Why Not Spring?</h2><p><a
class="external-link" href="http://www.springframework.org";
rel="nofollow">Spring</a> is the most successful IoC container project. The
Spring project combines a very good IoC container, integrated <a
class="external-link" href="http://www.eclipse.org/aspectj/";
rel="nofollow">AspectJ</a> support, and a large number of libraries built on
top of the container. Spring is an excellent <em>application</em> container,
but lacks a number of features necessary for a <em>framework</em>
container:</p><ul><li>Spring beans can be wired together by name (or id), but
it is not possible to introduce additional naming abstractions. Tapestry 4's
"infrastructure:" abstraction was the key to allowing easy spo
t overrides of internal Tapestry services without having to duplicate the
large web of interrelated services (nearly 200 in Tapestry
4.0).</li><li>Although Spring allows beans to be intercepted, it does so in the
form of a new bean, leaving the un-intercepted bean visible (and subject to
misuse). Tapestry IoC "wraps" the service inside interceptors, preventing
un-intercepted access to the core service implementation.</li><li>Spring's XML
configuration files are quite verbose. This has improved with Spring 2.0, but
still far more verbose that T5 IoC module classes.</li><li>Spring has a simple
map/list/value configuration scheme, but it is not distributed; it is part of a
single bean definition. Tapestry 5 IoC allows a service configuration to be
assembled from multiple modules. This is very important for seamless
extensibility of the framework, with zero configuration (just drop the module
into the classpath and everything hooks together).</li></ul><h2
id="IOC-WhyNotHiveMind?">Why No
t HiveMind?</h2><p>The difficulty of managing the release schedules of two
complex frameworks proved to be an issue.</p><p>The use of HiveMind was also
related to one of the common criticisms of Tapestry 4: startup time. The time
it took to parse and organize all that XML showed up as several seconds of
startup time. Creating a streamlined IoC container that is not driven by XML
has alleviated those issues.</p><p>With the advent of new technologies (in
particular, JDK 1.5 <a class="external-link"
href="http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html";
rel="nofollow">Annotations</a> and runtime class generation via <a
class="external-link" href="http://www.jboss.org/products/javassist";
rel="nofollow">Javassist</a>) some of the precepts of HiveMind were undermined.
That is to say, in HiveMind (as in Spring), all that XML was an awkward way to
describe a few basic Java operations: instantiating classes and invoking
methods on those classes (to inject dependenci
es into the instantiated instances). The central concept in Tapestry IoC is to
eliminate XML and build an equivalent system around simple objects and
methods.</p><p>Tapestry IoC also represents many simplifications of HiveMind,
building on lessons learned from both HiveMind and Tapestry 4. The HiveMind
project itself is no longer under development, and most of the user base has
moved to Tapestry 5.</p><h2 id="IOC-WhynotGuice?">Why not Guice?</h2><p><a
class="external-link" href="http://code.google.com/p/google-guice/";
rel="nofollow">Google Guice</a> is a relative newcomer to the IoC landscape.
Guice and T5 IoC are very close and, in fact, T5 IoC expressly borrows many
great and innovative ideas from Guice. Guice abandons not only XML but even any
concept of a service id ... for injection, services are matched by type and
perhaps filtered based on annotations.</p><p>Guice is still missing some core
ideas needed in T5 IoC. There's no concept of configurations or anything
similar. And
there are limitations on injection based on scope (a request scoped value
can't be injected into a global scope service; in T5 IoC, scope is internal to
the proxy and never an issue).</p><h1 id="IOC-Goals">Goals</h1><p>As with
Tapestry 5 in general, the goal of Tapestry IoC is greater simplicity, greater
power, and an avoidance of XML.</p><p>Existing IoC containers such as HiveMind
and Spring typically contain large amounts of XML configuration that exists to
describe how and when to instantiate a particular JavaBean, and how to provide
that bean with its dependencies (either by constructor injection, or by
property injection). Other XML is used to hook objects into some form of life
cycle ... typically callback methods invoked when the object is instantiated
and configured, or when it is being discarded.</p><p>The core concept of
Tapestry IoC is that the Java language itself is the easiest and most succinct
way to describe object creation and method invocation. Any approximation i
n XML is ultimately more verbose and unwieldy. As the <a
href="ioc.html">examples</a> show, a small amount of Java code and a handful of
naming conventions and annotations is far simpler and easier than a big chunk
of XML.</p><p>In addition, moving from XML to Java code encourages testing; you
can unit test the service builder methods of your module class, but you can't
realistically unit test an XML descriptor.</p><p>Tapestry IoC modules are
easily packaged into JAR files, supporting zero-configuration usage: just drop
the JAR onto the classpath.</p><p>Another goal is "developer friendliness".
This is a true cross-cutting concern, and one not likely to be packaged into an
aspect any time soon. The Tapestry IoC framework is designed to be easy to use
and easy to understand. Further, when things go wrong, it actively attempts to
help you via comprehensive checks and carefully composed error messages.
Further, all user-visible objects implement a <a class="external-link"
href="http:
//howardlewisship.com/blog/2003/08/importance-of-tostring.html"
rel="nofollow">reasonable toString() method</a>, to help you understand what's
going when you inevitably try to figure things out in the debugger.</p><p>In
terms of building services using Tapestry IoC ... the objective here is
"lightness", a term borrowed from the board game <a class="external-link"
href="http://boardgamegeek.com/game/188"; rel="nofollow">Go</a>. In Go, two
players place stones on an initially empty board, creating walls to enclose
territory or eliminate the encroaching stones played by the opponent. The
winner at the end of the game controls the most territory, and it is the
constant tension between taking territory and defending existing territory that
drives the game. In Go, groups of playing stones are "light" (or have "good
shape") when the minimum number of them control the maximum area on the board.
Playing "heavy" just gives your opponent a free chance to take control of
another section of the
board.</p><p>In software development, we are also attempting to create complex
systems from simple pieces, but our tension is derived from the need to add
functionality balanced against the need to test and maintain existing code. Too
often in the world of software development, the need to add functionality
trumps all, and testing and maintenance is deferred ... until too
late.</p><p>IoC containers in general, and Tapestry IoC very specifically,
exist to address this issue, to provide the foundations for balancing the need
to quickly add functionality against the need to test new functionality and
maintain existing functionality. IoC containers provide the means to break
large, complex, monolithic blocks into light, small, testable
pieces.</p><p>When building a registry of services, lightness refers to the
proper division of responsibility, the separation of concerns, and the limiting
of dependencies between different parts of the system. This style is often
called <a class="extern
al-link"
href="http://www.ccs.neu.edu/research/demeter/demeter-method/LawOfDemeter/general-formulation.html";
rel="nofollow">Law of Demeter</a>. Using an IoC container makes it easier to
embrace this approach, since one critical concern, which objects are
responsible for instantiating which others, is entirely managed by the
container. With this life cycle concern removed, it becomes very easy to reduce
complex chunks of code into small, testable, reusable services.</p><p>"Light"
means:</p><ul><li>Small interfaces of two or three methods.</li><li>Small
methods, with two or three parameters (because dependencies are injected in
behind the scenes, rather than passed into the method).</li><li>Anonymous
communication via events, rather than explicit method invocations. The service
implementation can implement an event listener interface.</li></ul><p>See <a
class="external-link"
href="http://www.pragmaticprogrammer.com/ppbook/index.shtml"; rel="nofollow">The
Pragmatic Programmer</a> for m
ore insights into building solid code.</p><h1
id="IOC-Terminology">Terminology</h1><p>The basic unit in Tapestry IoC is a
<strong>service</strong>. A service consists of a <strong>service
interface</strong> and a <strong>service implementation</strong>. The service
interface is an ordinary Java interface. The service implementation is a Java
object that implements the service interface. Often there will only be a single
service per service interface, but in some situations, there may be many
different services and service implementations all sharing the same service
interface.</p><p>Services are identified by a unique id. Typically, a service
id matches the unqualified name of the service interface, but this is simply a
convention.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The evolutionary direction
of the Tapestry IoC is to eventually eliminate service ids and work totally
in terms of service interfaces and marker
annotations.</p></div></div><p>Services are aggregated into
<strong>modules</strong>:</p><ul><li>A module is defined by a <strong>module
class</strong>, a specific class containing a mix of static or instance
methods, used to define services, decorate them (see below), or contribute to
service configurations (again, more below).</li><li>Methods of the module class
define the services provided by the module, and the same methods are
responsible for instantiating the service implementation.</li></ul><p>The
methods which define and construct services are called <strong>service builder
methods</strong>.</p><p>The <strong>registry</strong> is the outside world's
view of the modules and services. From the registry, it is possible to obtain a
service, via its unique id or by its service interface. Access by unique id is
<em>caseless</em> (meaning, a match will be found eve
n the case of the search key doesn't match the case of the service id
itself).</p><p>Services may be <strong>decorated</strong> by <strong>service
decorator methods</strong>. These methods create <strong>interceptor</strong>
objects that wrap around core service implementations, adding behavior such as
logging, security access, or transaction management. Interceptors implement the
same service interface as the service. Control is given over the order in which
decorators are applied to a service.</p><p>A service may have a
<strong>configuration</strong>. The configuration is either a map, a
collection, or an ordered list. The service defines the type of object allowed
to be contributed into the configuration. The configuration is constructed from
<strong>contributions</strong> provided by one or more modules. <strong>Service
contributor methods</strong> are invoked to contribute objects into
configurations.</p><p>Services are instantiated as needed. In this case, "need"
translates to
"when a method of the service is invoked". A service is represented (to the
outside world, or to other services) as a <strong>proxy</strong> that
implements the service interface. The first time a method is invoked on the
proxy, the full service (consisting of the core service implementation wrapped
with any interceptors) is constructed. This occurs in a completely
<strong>thread-safe</strong> manner. Just-in-time instantiation allows for more
complex, more finely grained networks of services, and improves start-up
time.</p><p>Instantiating a service, injecting dependencies, and decorating the
service are all parts of service <strong>realization</strong>, the point at
which a service transitions from virtual (just a proxy) to real (fully
instantiated and ready to operate).</p><p>Services define a
<strong>scope</strong> that controls when the service is constructed, as well
as its visibility. The default scope is <strong>singleton</strong>, meaning a
single global instance created a
s needed. Other scopes allow service implementations to be bound to the
current thread (i.e., the current request in a servlet
application).</p><p><strong>Dependencies</strong> are other services (or other
objects) that are needed by a service implementation. These dependencies can be
<strong>injected</strong> into a service builder method and provided, from
there, to a service implementation via its constructor, or via methods on the
service implementation. These may also be referred to as
<strong>collaborators</strong>, especially in the context of writing unit
tests.</p><p>The <strong>point of Injection</strong> is a field, method
parameter, or constructor parameter that receives an injected value. The type
of service (or other dependency) is determined by the type of the field or
parameter. Often, annotations further identify what is to be injected, or in
the case of field injection, that an injection is required.</p><h2
id="IOC-IoCSubtopics">IoC Subtopics</h2><p></p><ul class="
childpages-macro"><li><a href="tapestry-ioc-overview.html">Tapestry IoC
Overview</a></li><li><a href="tapestry-ioc-modules.html">Tapestry IoC
Modules</a></li><li><a href="defining-tapestry-ioc-services.html">Defining
Tapestry IOC Services</a></li><li><a href="service-advisors.html">Service
Advisors</a></li><li><a href="tapestry-ioc-decorators.html">Tapestry IoC
Decorators</a></li><li><a href="tapestry-ioc-configuration.html">Tapestry IoC
Configuration</a></li><li><a href="case-insensitivity.html">Case
Insensitivity</a></li><li><a href="autoloading-modules.html">Autoloading
Modules</a></li><li><a href="service-implementation-reloading.html">Service
Implementation Reloading</a></li><li><a
href="ordering-by-constraints.html">Ordering by Constraints</a></li><li><a
href="symbols.html">Symbols</a></li><li><a
href="chainbuilder-service.html">ChainBuilder Service</a></li><li><a
href="pipelinebuilder-service.html">PipelineBuilder Service</a></li><li><a
href="shadowbuilder-servi
ce.html">ShadowBuilder Service</a></li><li><a
href="strategybuilder-service.html">StrategyBuilder Service</a></li><li><a
href="injection-in-detail.html">Injection in Detail</a></li><li><a
href="object-providers.html">Object Providers</a></li><li><a
href="service-serialization.html">Service Serialization</a></li><li><a
href="type-coercion.html">Type Coercion</a></li><li><a
href="starting-the-ioc-registry.html">Starting the IoC Registry</a></li><li><a
href="registry-startup.html">Registry Startup</a></li><li><a
href="parallel-execution.html">Parallel Execution</a></li><li><a
href="logging-in-tapestry.html">Logging in Tapestry</a></li><li><a
href="using-jsr-330-standard-annotations.html">Using JSR 330 standard
annotations</a></li><li><a href="operation-tracker.html">Operation
Tracker</a></li></ul></div>
+<p>An additional benefit of using IoC is that, by breaking a complex system
into small pieces, it becomes easier to modify and extend the system, by
overriding or replacing selected parts of the system.</p><p>The use of IoC in
Tapestry represents an evolution from Tapestry 3 to Tapestry 4 to Tapestry 5.
Tapestry 3 did not use IoC, though it included some weaker mechanisms, such as
extensions, that served a similar purpose. To make large scale changes to the
behavior of Tapestry 3 required subclassing key classes and overriding
methods.</p><p>Tapestry 4 introduced the use of the <a class="external-link"
href="http://hivemind.apache.org/";>Apache HiveMind</a> IoC container. In fact,
the HiveMind project was created specifically for use as the IoC container for
Tapestry 4. Tapestry 4 has met its goals for extensibility and configurability,
largely because of HiveMind's flexibility.</p><p>Tapestry 5 extends on this,
replacing HiveMind with a new container specifically build for Tapestry
5, designed for greater ease of use, expressiveness and performance. HiveMind
itself has been subsequently shelved; T5 IoC can be considered a streamlined
and improved HiveMind. And T5 IoC can be used separately from the rest of
Tapestry!</p><h2 id="IOC-WhyNotSpring?">Why Not Spring?</h2><p><a
class="external-link" href="http://www.springframework.org";
rel="nofollow">Spring</a> is the most successful IoC container project. The
Spring project combines a very good IoC container, integrated <a
class="external-link" href="http://www.eclipse.org/aspectj/";
rel="nofollow">AspectJ</a> support, and a large number of libraries built on
top of the container. Spring is an excellent <em>application</em> container,
but lacks a number of features necessary for a <em>framework</em>
container:</p><ul><li>Spring beans can be wired together by name (or id), but
it is not possible to introduce additional naming abstractions. Tapestry 4's
"infrastructure:" abstraction was the key to allowing easy spo
t overrides of internal Tapestry services without having to duplicate the
large web of interrelated services (nearly 200 in Tapestry
4.0).</li><li>Although Spring allows beans to be intercepted, it does so in the
form of a new bean, leaving the un-intercepted bean visible (and subject to
misuse). Tapestry IoC "wraps" the service inside interceptors, preventing
un-intercepted access to the core service implementation.</li><li>Spring's XML
configuration files are quite verbose. This has improved with Spring 2.0, but
still far more verbose that T5 IoC module classes.</li><li>Spring has a simple
map/list/value configuration scheme, but it is not distributed; it is part of a
single bean definition. Tapestry 5 IoC allows a service configuration to be
assembled from multiple modules. This is very important for seamless
extensibility of the framework, with zero configuration (just drop the module
into the classpath and everything hooks together).</li></ul><h2
id="IOC-WhyNotHiveMind?">Why No
t HiveMind?</h2><p>The difficulty of managing the release schedules of two
complex frameworks proved to be an issue.</p><p>The use of HiveMind was also
related to one of the common criticisms of Tapestry 4: startup time. The time
it took to parse and organize all that XML showed up as several seconds of
startup time. Creating a streamlined IoC container that is not driven by XML
has alleviated those issues.</p><p>With the advent of new technologies (in
particular, JDK 1.5 <a class="external-link"
href="http://download.oracle.com/javase/tutorial/java/javaOO/annotations.html";
rel="nofollow">Annotations</a> and runtime class generation via <a
class="external-link" href="http://www.jboss.org/products/javassist";
rel="nofollow">Javassist</a>) some of the precepts of HiveMind were undermined.
That is to say, in HiveMind (as in Spring), all that XML was an awkward way to
describe a few basic Java operations: instantiating classes and invoking
methods on those classes (to inject dependenci
es into the instantiated instances). The central concept in Tapestry IoC is to
eliminate XML and build an equivalent system around simple objects and
methods.</p><p>Tapestry IoC also represents many simplifications of HiveMind,
building on lessons learned from both HiveMind and Tapestry 4. The HiveMind
project itself is no longer under development, and most of the user base has
moved to Tapestry 5.</p><h2 id="IOC-WhynotGuice?">Why not Guice?</h2><p><a
class="external-link" href="http://code.google.com/p/google-guice/";
rel="nofollow">Google Guice</a> is a relative newcomer to the IoC landscape.
Guice and T5 IoC are very close and, in fact, T5 IoC expressly borrows many
great and innovative ideas from Guice. Guice abandons not only XML but even any
concept of a service id ... for injection, services are matched by type and
perhaps filtered based on annotations.</p><p>Guice is still missing some core
ideas needed in T5 IoC. There's no concept of configurations or anything
similar. And
there are limitations on injection based on scope (a request scoped value
can't be injected into a global scope service; in T5 IoC, scope is internal to
the proxy and never an issue).</p><h1 id="IOC-Goals">Goals</h1><p>As with
Tapestry 5 in general, the goal of Tapestry IoC is greater simplicity, greater
power, and an avoidance of XML.</p><p>Existing IoC containers such as HiveMind
and Spring typically contain large amounts of XML configuration that exists to
describe how and when to instantiate a particular JavaBean, and how to provide
that bean with its dependencies (either by constructor injection, or by
property injection). Other XML is used to hook objects into some form of life
cycle ... typically callback methods invoked when the object is instantiated
and configured, or when it is being discarded.</p><p>The core concept of
Tapestry IoC is that the Java language itself is the easiest and most succinct
way to describe object creation and method invocation. Any approximation i
n XML is ultimately more verbose and unwieldy. As the <a
href="defining-tapestry-ioc-services.html">Tapestry IOC examples</a> show, a
small amount of Java code and a handful of naming conventions and annotations
is far simpler and easier than a big chunk of XML.</p><p>In addition, moving
from XML to Java code encourages testing; you can unit test the service builder
methods of your module class, but you can't realistically unit test an XML
descriptor.</p><p>Tapestry IoC modules are easily packaged into JAR files,
supporting zero-configuration usage: just drop the JAR onto the
classpath.</p><p>Another goal is "developer friendliness". This is a true
cross-cutting concern, and one not likely to be packaged into an aspect any
time soon. The Tapestry IoC framework is designed to be easy to use and easy to
understand. Further, when things go wrong, it actively attempts to help you via
comprehensive checks and carefully composed error messages. Further, all
user-visible objects implement
a <a class="external-link"
href="https://web.archive.org/web/20041125140446/http://howardlewisship.com/blog/2003/08/importance-of-tostring.html";
rel="nofollow">reasonable toString() method</a>, to help you understand what's
going when you inevitably try to figure things out in the debugger.</p><p>In
terms of building services using Tapestry IoC ... the objective here is
"lightness", a term borrowed from the board game <a class="external-link"
href="http://boardgamegeek.com/game/188"; rel="nofollow">Go</a>. In Go, two
players place stones on an initially empty board, creating walls to enclose
territory or eliminate the encroaching stones played by the opponent. The
winner at the end of the game controls the most territory, and it is the
constant tension between taking territory and defending existing territory that
drives the game. In Go, groups of playing stones are "light" (or have "good
shape") when the minimum number of them control the maximum area on the board.
Playing "heavy
" just gives your opponent a free chance to take control of another section of
the board.</p><p>In software development, we are also attempting to create
complex systems from simple pieces, but our tension is derived from the need to
add functionality balanced against the need to test and maintain existing code.
Too often in the world of software development, the need to add functionality
trumps all, and testing and maintenance is deferred ... until too
late.</p><p>IoC containers in general, and Tapestry IoC very specifically,
exist to address this issue, to provide the foundations for balancing the need
to quickly add functionality against the need to test new functionality and
maintain existing functionality. IoC containers provide the means to break
large, complex, monolithic blocks into light, small, testable
pieces.</p><p>When building a registry of services, lightness refers to the
proper division of responsibility, the separation of concerns, and the limiting
of dependencies
between different parts of the system. This style is often called <a
class="external-link"
href="http://www.ccs.neu.edu/research/demeter/demeter-method/LawOfDemeter/general-formulation.html";
rel="nofollow">Law of Demeter</a>. Using an IoC container makes it easier to
embrace this approach, since one critical concern, which objects are
responsible for instantiating which others, is entirely managed by the
container. With this life cycle concern removed, it becomes very easy to reduce
complex chunks of code into small, testable, reusable services.</p><p>"Light"
means:</p><ul><li>Small interfaces of two or three methods.</li><li>Small
methods, with two or three parameters (because dependencies are injected in
behind the scenes, rather than passed into the method).</li><li>Anonymous
communication via events, rather than explicit method invocations. The service
implementation can implement an event listener interface.</li></ul><p>See <a
class="external-link" href="http://www.pragmaticp
rogrammer.com/ppbook/index.shtml" rel="nofollow">The Pragmatic Programmer</a>
for more insights into building solid code.</p><h1
id="IOC-Terminology">Terminology</h1><p>The basic unit in Tapestry IoC is a
<strong>service</strong>. A service consists of a <strong>service
interface</strong> and a <strong>service implementation</strong>. The service
interface is an ordinary Java interface. The service implementation is a Java
object that implements the service interface. Often there will only be a single
service per service interface, but in some situations, there may be many
different services and service implementations all sharing the same service
interface.</p><p>Services are identified by a unique id. Typically, a service
id matches the unqualified name of the service interface, but this is simply a
convention.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon">
</span><div class="confluence-information-macro-body"><p>The evolutionary
direction of the Tapestry IoC is to eventually eliminate service ids and work
totally in terms of service interfaces and marker
annotations.</p></div></div><p>Services are aggregated into
<strong>modules</strong>:</p><ul><li>A module is defined by a <strong>module
class</strong>, a specific class containing a mix of static or instance
methods, used to define services, decorate them (see below), or contribute to
service configurations (again, more below).</li><li>Methods of the module class
define the services provided by the module, and the same methods are
responsible for instantiating the service implementation.</li></ul><p>The
methods which define and construct services are called <strong>service builder
methods</strong>.</p><p>The <strong>registry</strong> is the outside world's
view of the modules and services. From the registry, it is possible to obtain a
service, via its unique id or by its service inte
rface. Access by unique id is <em>caseless</em> (meaning, a match will be
found even the case of the search key doesn't match the case of the service id
itself).</p><p>Services may be <strong>decorated</strong> by <strong>service
decorator methods</strong>. These methods create <strong>interceptor</strong>
objects that wrap around core service implementations, adding behavior such as
logging, security access, or transaction management. Interceptors implement the
same service interface as the service. Control is given over the order in which
decorators are applied to a service.</p><p>A service may have a
<strong>configuration</strong>. The configuration is either a map, a
collection, or an ordered list. The service defines the type of object allowed
to be contributed into the configuration. The configuration is constructed from
<strong>contributions</strong> provided by one or more modules. <strong>Service
contributor methods</strong> are invoked to contribute objects into configurat
ions.</p><p>Services are instantiated as needed. In this case, "need"
translates to "when a method of the service is invoked". A service is
represented (to the outside world, or to other services) as a
<strong>proxy</strong> that implements the service interface. The first time a
method is invoked on the proxy, the full service (consisting of the core
service implementation wrapped with any interceptors) is constructed. This
occurs in a completely <strong>thread-safe</strong> manner. Just-in-time
instantiation allows for more complex, more finely grained networks of
services, and improves start-up time.</p><p>Instantiating a service, injecting
dependencies, and decorating the service are all parts of service
<strong>realization</strong>, the point at which a service transitions from
virtual (just a proxy) to real (fully instantiated and ready to
operate).</p><p>Services define a <strong>scope</strong> that controls when the
service is constructed, as well as its visibility. The defa
ult scope is <strong>singleton</strong>, meaning a single global instance
created as needed. Other scopes allow service implementations to be bound to
the current thread (i.e., the current request in a servlet
application).</p><p><strong>Dependencies</strong> are other services (or other
objects) that are needed by a service implementation. These dependencies can be
<strong>injected</strong> into a service builder method and provided, from
there, to a service implementation via its constructor, or via methods on the
service implementation. These may also be referred to as
<strong>collaborators</strong>, especially in the context of writing unit
tests.</p><p>The <strong>point of Injection</strong> is a field, method
parameter, or constructor parameter that receives an injected value. The type
of service (or other dependency) is determined by the type of the field or
parameter. Often, annotations further identify what is to be injected, or in
the case of field injection, that an injec
tion is required.</p><h2 id="IOC-IoCSubtopics">IoC Subtopics</h2><p></p><ul
class="childpages-macro"><li><a href="tapestry-ioc-overview.html">Tapestry IoC
Overview</a></li><li><a href="tapestry-ioc-modules.html">Tapestry IoC
Modules</a></li><li><a href="defining-tapestry-ioc-services.html">Defining
Tapestry IOC Services</a></li><li><a href="service-advisors.html">Service
Advisors</a></li><li><a href="tapestry-ioc-decorators.html">Tapestry IoC
Decorators</a></li><li><a href="tapestry-ioc-configuration.html">Tapestry IoC
Configuration</a></li><li><a href="case-insensitivity.html">Case
Insensitivity</a></li><li><a href="autoloading-modules.html">Autoloading
Modules</a></li><li><a href="service-implementation-reloading.html">Service
Implementation Reloading</a></li><li><a
href="ordering-by-constraints.html">Ordering by Constraints</a></li><li><a
href="symbols.html">Symbols</a></li><li><a
href="chainbuilder-service.html">ChainBuilder Service</a></li><li><a
href="pipelinebuil
der-service.html">PipelineBuilder Service</a></li><li><a
href="shadowbuilder-service.html">ShadowBuilder Service</a></li><li><a
href="strategybuilder-service.html">StrategyBuilder Service</a></li><li><a
href="injection-in-detail.html">Injection in Detail</a></li><li><a
href="object-providers.html">Object Providers</a></li><li><a
href="service-serialization.html">Service Serialization</a></li><li><a
href="type-coercion.html">Type Coercion</a></li><li><a
href="starting-the-ioc-registry.html">Starting the IoC Registry</a></li><li><a
href="registry-startup.html">Registry Startup</a></li><li><a
href="parallel-execution.html">Parallel Execution</a></li><li><a
href="logging-in-tapestry.html">Logging in Tapestry</a></li><li><a
href="using-jsr-330-standard-annotations.html">Using JSR 330 standard
annotations</a></li><li><a href="operation-tracker.html">Operation
Tracker</a></li></ul></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/tapestry-ioc-modules.html
==============================================================================
--- websites/production/tapestry/content/tapestry-ioc-modules.html (original)
+++ websites/production/tapestry/content/tapestry-ioc-modules.html Sun Feb 18
19:21:00 2018
@@ -85,7 +85,7 @@ public class MyAppModule
return new IndexerImpl();
}
}</pre>
-</div></div><p>Any public method (static or instance) whose name starts with
"build" is a service builder method, implicitly defining a service within the
module.</p><p>Here we're defining a service around the Indexer service
interface (presumably also in the org.example.myapp.services
package).</p><p>Every service has a unique id, used to identify it throughout
the Registry of services (the Registry is the combined sum of all services from
all modules). If you don't provide an explicit service id, as in this example,
the service id is drawn from the return type; this service has an id of
"Indexer".</p><p>You can give a service an explicit id by adding it to the
method name: buildIndexer(). This is useful when you do not want the service id
to match the service interface name (for example, when you have different
services that implement the same interface), or when you need to avoid name
collisions on the method name (Java allows only a single method with a given
name and set of par
ameters, even if the return types are different, so if you have two different
service builder methods that take the same parameters, you should give them
explicit service ids in the method name).</p><p>Tapestry IoC is <a
href="tapestry-ioc-modules.html">case insensitive</a>; later we can refer to
this service as "indexer" or "INDEXER" or any variation thereof, and connect to
this service.</p><p>Service ids must be unique; if another module contributes a
service with the id "Indexer" (or any case variation thereof) a runtime
exception will occur when the Registry is created.</p><p>We could extend this
example by adding additional service builder methods, or by showing how to
inject dependencies. See <a href="tapestry-ioc-modules.html">the service
documentation</a> for more details.</p><h1
id="TapestryIoCModules-AutobuildingServices">Autobuilding Services</h1><p>Main
article: <a href="tapestry-ioc-modules.html">Tapestry IoC Modules</a></p><p>An
alternate, and usually preferred, way
to define a service is via a module's bind() method. The previous example can
be rewritten as:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>Any public method (static or instance) whose name starts with
"build" is a service builder method, implicitly defining a service within the
module.</p><p>Here we're defining a service around the Indexer service
interface (presumably also in the org.example.myapp.services
package).</p><p>Every service has a unique id, used to identify it throughout
the Registry of services (the Registry is the combined sum of all services from
all modules). If you don't provide an explicit service id, as in this example,
the service id is drawn from the return type; this service has an id of
"Indexer".</p><p>You can give a service an explicit id by adding it to the
method name: buildIndexer(). This is useful when you do not want the service id
to match the service interface name (for example, when you have different
services that implement the same interface), or when you need to avoid name
collisions on the method name (Java allows only a single method with a given
name and set of par
ameters, even if the return types are different, so if you have two different
service builder methods that take the same parameters, you should give them
explicit service ids in the method name).</p><p>Tapestry IoC is <a
href="case-insensitivity.html">case insensitive</a>; later we can refer to this
service as "indexer" or "INDEXER" or any variation thereof, and connect to this
service.</p><p>Service ids must be unique; if another module contributes a
service with the id "Indexer" (or any case variation thereof) a runtime
exception will occur when the Registry is created.</p><p>We could extend this
example by adding additional service builder methods, or by showing how to
inject dependencies. See <a href="defining-tapestry-ioc-services.html">the
service documentation</a> for more details.</p><h1
id="TapestryIoCModules-AutobuildingServices">Autobuilding Services</h1><p>Main
article: <a href="defining-tapestry-ioc-services.html">Defining Tapestry IOC
Services</a></p><p>An alternate
, and usually preferred, way to define a service is via a module's bind()
method. The previous example can be rewritten as:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package org.example.myapp.services;
import org.apache.tapestry5.ioc.ServiceBinder;
@@ -97,7 +97,7 @@ public class MyAppModule
binder.bind(Indexer.class, IndexerImpl.class);
}
}</pre>
-</div></div><p>For more details, see see <a
href="tapestry-ioc-modules.html">Tapestry IoC Modules</a>. In most cases,
autobuilding is the <em>preferred</em> approach.</p><p>Generally speaking, you
should always bind and autobuild your services. The only exceptions are
when:</p><ul><li>You wish to do more than just instantiate a class; for
example, to register the class as an event listener with some other
service.</li><li>There is <em>no implementation class</em>; in some cases, you
can create your implementation on the fly using JDK dynamic proxies or bytecode
generation.</li></ul><p>The bind() method must be static; an exception is
thrown if the bind() method exists but is an instance method.</p><h1
id="TapestryIoCModules-Cacheing_ServicesCachingServices"><span
class="confluence-anchor-link"
id="TapestryIoCModules-Cacheing_Services"></span>Caching Services</h1><p>You
will occasionally find yourself in the position of injecting the same services
into your service builder or servic
e decorator methods repeatedly (this occurs much less often since the
introduction of service autobuilding). This can result in quite a bit of
redundant typing. Less code is better code, so as an alternative, you may
define a <em>constructor</em> for your module that accepts annotated parameters
(as with <a href="tapestry-ioc-modules.html">service builder
injection</a>).</p><p>This gives you a chance to store common services in
instance variables for later use inside service builder methods.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><p class="confluence-link">For more details, see see <a
href="defining-tapestry-ioc-services.html">Defining Tapestry IOC Services</a>.
In most cases, autobuilding is the <em>preferred</em> approach.</p><p>Generally
speaking, you should always bind and autobuild your services. The only
exceptions are when:</p><ul><li>You wish to do more than just instantiate a
class; for example, to register the class as an event listener with some other
service.</li><li>There is <em>no implementation class</em>; in some cases, you
can create your implementation on the fly using JDK dynamic proxies or bytecode
generation.</li></ul><p>The bind() method must be static; an exception is
thrown if the bind() method exists but is an instance method.</p><h1
id="TapestryIoCModules-Cacheing_ServicesCachingServices"><span
class="confluence-anchor-link"
id="TapestryIoCModules-Cacheing_Services"></span>Caching Services</h1><p>You
will occasionally find yourself in the position of injecting the same
services into your service builder or service decorator methods repeatedly
(this occurs much less often since the introduction of service autobuilding).
This can result in quite a bit of redundant typing. Less code is better code,
so as an alternative, you may define a <em>constructor</em> for your module
that accepts annotated parameters (as with <a
href="defining-tapestry-ioc-services.html">service builder
injection</a>).</p><p>This gives you a chance to store common services in
instance variables for later use inside service builder methods.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public class MyModule
{
private final JobScheduler scheduler;
@@ -118,7 +118,7 @@ public class MyAppModule
return indexer;
}
}</pre>
-</div></div><p>Notice that we've switched from <em>static</em> methods to
<em>instance</em> methods. Since the builder methods are not static, the
MyModule class will be instantiated so that the methods may be invoked. The
constructor receives two common dependencies, which are stored into instance
fields that may later be used inside service builder methods such as
buildIndexer().</p><p>This approach is far from required; all the builder
methods of your module can be static if you wish. It is used when you have many
common dependencies and wish to avoid defining those dependencies as parameters
to multiple methods.</p><p>Tapestry IoC automatically resolves the parameter
type (JobScheduler and FileSystem, in the example) to the corresponding
services that implement that type. When there's more than one service that
implements the service interface, you'll get an error (but additional
annotations and configuration can be used to ensure the correct service
injected).</p><p>For modules
, there are two additional parameter types that are used to refer to
<em>resources</em> that can be provided to the module instance (rather than
<em>services</em> which may be injected).</p><ul><li><a class="external-link"
href="http://www.slf4j.org/api/org/slf4j/Logger.html";
rel="nofollow">org.slf4j.Logger</a>: logger for the module (derived from the
module's class name)</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>:
access to other services<br clear="none"> Note that the fields are final: this
is important. Tapestry IoC is thread-safe and you largely never have to think
about concurrency issues. But in a busy application, different services may be
built by different threads simultaneously. Each module class is a singleton,
instantiated at most once, and making these fields final ensures that the
values are available across multiple threads. Refer to Brian Goetz's <a
class="externa
l-link" href="http://www.javaconcurrencyinpractice.com/"; rel="nofollow">Java
Concurrency in Practice</a> for a more complete explanation of the relationship
between final fields, constructors, and threads ... or just trust
us!</li></ul><p>Care should be taken with this approach: in some circumstances,
you may force a situation in which the module constructor is dependent on
itself. For example, if you invoke a method on any injected services defined
within the same module from the module class' constructor, then the service
implementation will be needed. Creating service implementations requires the
module builder instance ... that's a recursive reference.</p><p>Tapestry
detects these scenarios and throws a runtime exception to prevent an endless
loop.</p><h1 id="TapestryIoCModules-ModuleClassImplementationNotes">Module
Class Implementation Notes</h1><p>Module classes are designed to be very, very
simple to implement.</p><p>Again, keep the methods very simple. Use <a
href="tapestry
-ioc-modules.html">parameter injection</a> to gain access to the dependencies
you need.</p><p>Be careful about inheritance. Tapestry will see all
<em>public</em> methods, even those inherited from base classes. Tapestry
<em>only</em> sees public methods.</p><p>By convention, module class names end
in Module and are final classes.</p><p>You don't <em>have</em> to define your
methods as static. The use of static methods is only absolutely necessary in a
few cases, where the constructor for a module is dependent on contributions
from the same module (this creates a chicken-and-the-egg situation that is
resolved through static methods).</p><h1
id="TapestryIoCModules-DefaultMarker">Default Marker</h1><p>Services are often
referenced by a particular marker interface on the method or constructor
parameter. Tapestry will use the intersection of services with that exact
marker and assignable by type to find a unique service to inject.</p><p>Often,
all services in a module should share a mark
er, this can be specified with a @Marker annotation on the module class. For
example, the TapestryIOCModule:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Notice that we've switched from <em>static</em> methods to
<em>instance</em> methods. Since the builder methods are not static, the
MyModule class will be instantiated so that the methods may be invoked. The
constructor receives two common dependencies, which are stored into instance
fields that may later be used inside service builder methods such as
buildIndexer().</p><p>This approach is far from required; all the builder
methods of your module can be static if you wish. It is used when you have many
common dependencies and wish to avoid defining those dependencies as parameters
to multiple methods.</p><p>Tapestry IoC automatically resolves the parameter
type (JobScheduler and FileSystem, in the example) to the corresponding
services that implement that type. When there's more than one service that
implements the service interface, you'll get an error (but additional
annotations and configuration can be used to ensure the correct service
injected).</p><p>For modules
, there are two additional parameter types that are used to refer to
<em>resources</em> that can be provided to the module instance (rather than
<em>services</em> which may be injected).</p><ul><li><a class="external-link"
href="http://www.slf4j.org/api/org/slf4j/Logger.html";
rel="nofollow">org.slf4j.Logger</a>: logger for the module (derived from the
module's class name)</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>:
access to other services</li></ul><p>Note that the fields are final: this is
important. Tapestry IoC is thread-safe and you largely never have to think
about concurrency issues. But in a busy application, different services may be
built by different threads simultaneously. Each module class is a singleton,
instantiated at most once, and making these fields final ensures that the
values are available across multiple threads. Refer to Brian Goetz's <a
class="external-lin
k" href="http://www.javaconcurrencyinpractice.com/"; rel="nofollow">Java
Concurrency in Practice</a> for a more complete explanation of the relationship
between final fields, constructors, and threads ... or just trust
us!</p><p>Care should be taken with this approach: in some circumstances, you
may force a situation in which the module constructor is dependent on itself.
For example, if you invoke a method on any injected services defined within the
same module from the module class' constructor, then the service implementation
will be needed. Creating service implementations requires the module builder
instance ... that's a recursive reference.</p><p>Tapestry detects these
scenarios and throws a runtime exception to prevent an endless loop.</p><h1
id="TapestryIoCModules-ModuleClassImplementationNotes">Module Class
Implementation Notes</h1><p>Module classes are designed to be very, very simple
to implement.</p><p>Again, keep the methods very simple. Use <a
href="defining-tapestry-i
oc-services.html">parameter injection</a> to gain access to the dependencies
you need.</p><p>Be careful about inheritance. Tapestry will see all
<em>public</em> methods, even those inherited from base classes. Tapestry
<em>only</em> sees public methods.</p><p>By convention, module class names end
in Module and are final classes.</p><p>You don't <em>have</em> to define your
methods as static. The use of static methods is only absolutely necessary in a
few cases, where the constructor for a module is dependent on contributions
from the same module (this creates a chicken-and-the-egg situation that is
resolved through static methods).</p><h1
id="TapestryIoCModules-DefaultMarker">Default Marker</h1><p>Services are often
referenced by a particular marker interface on the method or constructor
parameter. Tapestry will use the intersection of services with that exact
marker and assignable by type to find a unique service to inject.</p><p>Often,
all services in a module should share a marke
r, this can be specified with a @Marker annotation on the module class. For
example, the TapestryIOCModule:</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;">@Marker(Builtin.class)
public final class TapestryIOCModule
{
