Modified: websites/production/tapestry/content/injection-in-detail.html
==============================================================================
--- websites/production/tapestry/content/injection-in-detail.html (original)
+++ websites/production/tapestry/content/injection-in-detail.html Wed Sep 20
12:29:16 2017
@@ -27,6 +27,14 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,7 +75,50 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Injection</strong> in
Tapestry IoC can be a complicated subject for a number of
reasons:</p><ul><li>Injection can occur in many places: on fields, and on
parameters to methods and constructors of certain objects.</li><li>Parts of
Injection are themselves defined in terms of Tapestry IoC services, many of
which are extensible.</li></ul><parameter
ac:name="style">float:right</parameter><parameter ac:name="title">Related
Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "injection" and space =
currentSpace()</parameter></rich-text-body><p>Despite this, injection generally
<em>Just Works</em>: most of the time, you want Tapestry to inject a service,
and only a single service implements the service interface.</p><p>Thi
s document discusses what to do when you hit a case that doesn't Just Work, or
when you want to extend the injection logic in some way.</p><p>Some aspects of
this discussion reflect Tapestry IoC used within a Tapestry web application:
the tapestry-core module makes some extensions to injection.</p><h1
id="InjectioninDetail-InjectionTriggers">Injection Triggers</h1><p>Injection is
triggered in a number of ways:</p><ul><li>A field in a component class,
autobuilt object, or service implementation class is annotated with
@Inject.</li><li>A method parameter to a service builder method, a decorator
method, or a contribute method (in a Tapestry IoC module class).</li><li>A
constructor parameter to an autobuilt object, or a service implementation
class.</li><li>Any of the above with an @InjectService
annotation.</li></ul><p>These define the <em>point of
injection</em>.</p><p>Injection also covers a related matter: providing special
resources to a service or component (remember that pag
es are specialized components). For a service, the service's id (as a string)
or extensible configuration (as a Collection, List or Map) may be provided. For
a component, the component's id, locale, message catalog, or component
resources may be provided.</p><h1
id="InjectioninDetail-StandardInjectionProcessing">Standard Injection
Processing</h1><p>This section describes standard injection, which applies at
the IoC layer: autobuilt objects and service implementations. The steps for
injection into Tapestry components are slightly different and are covered
later.</p><p>So a the point of injection, Tapestry has identified a field or
parameter that should be injected. At this point, Tapestry knows the
following:</p><ul><li>The field name (if field injection). The parameter name
is not available.</li><li>The field or parameter type, as a Java class. In many
cases, this will be enough to identify what object shall be
injected.</li><li>Any additional annotations on the field or parameter.<
/li></ul><p>Tapestry proceeds with this information.</p><h2
id="InjectioninDetail-Checkfor@InjectService">Check for
@InjectService</h2><p>Tapestry checks first for the @InjectService annotation.
The value of this annotation is the service id to inject. When @InjectService
is present at the point of injection, the search is complete, though the
injection can fail (throwing an exception) if the service id indicated does not
exist, or if the service's interface is not compatible with the field's
type.</p><h2 id="InjectioninDetail-Checkforserviceresources">Check for service
resources</h2><p>This step applies only to IoC layer injection (not to
injection into components).</p><p>When the @Inject annotation is <em>not
present</em> at the point of injection, Tapestry checks to see if a resource
can be injected. Services are global values, but resources are specific to the
service under construction.</p><p>When the Inject annotation is present, this
step is skipped (this is necessary when th
e object to be injected has a type that conflicts with a resource type, such
as List or Class).</p><ul><li>org.slf4j.Logger – The Logger of the
service being constructed (or the logger of the Module class being
instantiated).</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>
– For contribute methods, used to locate additional objects.</li><li><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ServiceResources.html";>ServiceResources</a>
– For service builder methods, an extended version of
ObjectLocator. </li><li>Class – The service interface
type.</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/OperationTracker.html";>OperationTracker</a>
– Used to track deeply nested operations so that errors can be reported
sensibly.</li><li>Object, or servi
ce interface type – Passed to decorator methods.</li><li>Collection,
List, Map – Assembled service configurations passed to service builder
methods (or service class constructors).</li><li><p>Configuration,
OrderedConfiguration, MappedConfiguration – Configuration passed to
contribute methods, to build service configurations. <br clear="none"
class="atl-forced-newline"> <br clear="none" class="atl-forced-newline"> If
field type does not match any of the available resource types, or the Inject
annotation is present, logic continues to the next
step.</p><rich-text-body><p>Injection of resources into fields is triggered by
the presence of the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectResource.html";>InjectResource</a>
annotation, whereas injection of resources into parameters occurs when the
Inject or InjectService annotation is <em>not</em> present. These rules are
slightly tricky, which refl
ects a desire to avoid any annotations except when needed, and the fact that
field injection came much later than parameter
injection.</p></rich-text-body></li></ul><h2
id="InjectioninDetail-ServiceLookupbyTypeandAnnotations">Service Lookup by Type
and Annotations</h2><p>Tapestry attempts to find a matching
<em>service</em>.</p><p>First, it generates a set of services whose service
interface is compatible with the injection type. This is based on
assignability.</p><p>If the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Local.html";>Local</a>
annotation is present, then services not from the module containing the
service being constructed will be eliminated.</p><p>Tapestry then works through
the known marker annotations. For each marker annotation that is present at the
point of injection, Tapestry eliminates services which <em>do not</em> have the
marker. Thus, if multiple marker annotations are present, the final ser
vice must have <em>all of them</em>.</p><p>At the end, of this, Tapestry
determines how many services match.</p><ul><li>If there is a single matching
service, then the service to inject as been identified.</li><li>If there are no
matches, and there were no marker annotations at the point of injection, then
the Tapestry continues to the next step.</li><li>Otherwise there were either no
matches, or too many matches: Tapestry will throw a
RuntimeException.</li></ul><h2
id="InjectioninDetail-MasterObjectProviderLookup">MasterObjectProvider
Lookup</h2><p>This is the point at which Tapestry's extensibility comes into
play. MasterObjectProvider is a service, with a configuration of <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectProvider.html";>ObjectProviders</a>.</p><p>The
MasterObjectProvider is also the point at which Tapestry's IoC layer
injection, and Tapestry's component injection, unite.</p><p>As a
chain-of-command, each of t
he following ObjectProviders will be considered and will attempt to identify
the object to be injected.</p><rich-text-body><p>A common problem when
extending injection is that contributions into the MasterObjectProvider
configuration have to be handled carefully. Any dependencies of the contributed
objects should be resolvable using only the early stages of the injection
process, otherwise MasterObjectProvider will have to be instantiated in order
to handle its own injection: Tapestry will detect this impossibility and throw
an exception. In addition, the <a
href="typecoercer-service.html">TypeCoercer</a> service is used by several
ObjectProvider implementations, so the same restrictions apply to TypeCoercer
service contributions.</p></rich-text-body><h3
id="InjectioninDetail-ValueObjectProvider">Value ObjectProvider</h3><p>Checks
for the presence of the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Valu
e</a> annotation. If present, then the annotation's value is evaluated (to
expand any symbol references), and the TypeCoercer service is used to convert
the resulting String to the injection type (the field or parameter
type).</p><h3 id="InjectioninDetail-SymbolObjectProvider">Symbol
ObjectProvider</h3><p>Similar to the Value ObjectProvider: the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Symbol.html";>Symbol</a>
annotation's value (if present) is looked up using the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/SymbolSource.html";>SymbolSource</a>
service, and converted to the injection type via the TypeCoercer
service.</p><h3 id="InjectioninDetail-AutobuildObjectProvider">Autobuild
ObjectProvider</h3><p>Checks to see if the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Autobuild.htm
l">Autobuild</a> annotation is present and, if so, autobuilds the value for
the parameter. Of course, the object being built will itself be configured via
injection.</p><h3
id="InjectioninDetail-ServiceOverrideObjectProvider">ServiceOverride
ObjectProvider</h3><p>Checks any contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/ServiceOverride.html";>ServiceOverride</a>
service. Contributions map a type to an object of that type. Thus,
ServiceOverrides will override injections of services that are not qualified
with a marker annotation.</p><h3
id="InjectioninDetail-AliasObjectProvider(tapestry-core)">Alias ObjectProvider
(tapestry-core)</h3><p>Uses the Alias service (<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Alias.html";>API</a>)
to look for an object that can be injected.</p><rich-text-body><p>Deprecated
in Tapestry 5.2 and removed in 5.4.</p></ric
h-text-body><p>This is commonly used to override a built-in service by
contributing an object with the exact same interface. This is an older and more
complex version of the ServiceOverride provider.</p><h3
id="InjectioninDetail-AssetObjectProvider(tapestry-core)">Asset ObjectProvider
(tapestry-core)</h3><p>Checks for the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation.</p><p>If present, the annotation's value has embedded symbols
expanded, and is converted into an Asset (which must exist).</p><p>The
TypeCoercer can then convert the Asset to the injection type, for example, as
Resource.</p><h3
id="InjectioninDetail-ServiceObjectProvider(tapestry-core)">Service
ObjectProvider (tapestry-core)</h3><p>Looks for the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation; if present, the annotation's value is
the exact service id to inject. This is necessary because injections into
<em>component</em> fields are always triggered by the Inject
annotation.</p><rich-text-body><p>This is supported but no longer necessary, as
the @InjectService annotation is now also supported for component
fields.</p></rich-text-body><h3
id="InjectioninDetail-SpringBeanObjectProvider(tapestry-spring)">SpringBean
ObjectProvider (tapestry-spring)</h3><p>Attempts to resolve a Spring bean
purely by object type (Spring qualifiers are not supported). If no beans are
assignable to the type, then processing continues. If exactly one is
assignable, it is used as the injection value. If more than one bean is
assignable, it is an error (and a list of matching beans names will be part of
the thrown exception).</p><h2 id="InjectioninDetail-ServiceLookup">Service
Lookup</h2><p>If none of the ObjectProviders can identify the value to inject,
a last step occurs: lookup by service type. If exactly <em>one</em> service
matche
s the injection type, then that service is injected.</p><p>Otherwise, the
lookup fails because either no services match, or more than one matches. An
exception will be thrown with the details, including a list of matching
services (if there is more than one match).</p><h1
id="InjectioninDetail-Post-InjectionMethods">Post-Injection
Methods</h1><p>Autobuilt objects (services and the like, but <em>not</em>
components) may have post-injection methods.</p><p>Any public method may have
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PostInjection.html";>PostInjection</a>
annotation.</p><p>Such methods are invoked after constructor and/or field
injection. Only <strong>public methods</strong> will be invoked. Any return
value is ignored.</p><p>The method often takes no parameters; however if the
method has parameters, these parameters are new points of
injection.</p><p>Often this is used to perform additional setup, such as reg
isterring a service as a listener of events produced by another
service:</p><plain-text-body>public class MyServiceImpl implements MyService,
UpdateListener
+ <div id="ConfluenceContent"><p><strong>Injection</strong> in
Tapestry IoC can be a complicated subject for a number of
reasons:</p><ul><li>Injection can occur in many places: on fields, and on
parameters to methods and constructors of certain objects.</li><li>Parts of
Injection are themselves defined in terms of Tapestry IoC services, many of
which are extensible.</li></ul><div class="aui-label" style="float:right"
title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection-in-detail.html">Injection in
Detail</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection-faq.html">Injection FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection.html">Injection</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Despite this, injection generally <em>Just Works</em>: most of the time,
you want Tapestry to inject a service, and only a single service implements the
service interface.</p><p>This document discusses what to do when you hit a case
that doesn't Just Work, or when you want to extend the injection logic in some
way.</p><p>Some aspects of this discussion reflect Tapestry IoC used within a
Tapestry web application: the tapestry-core module makes some extensions to
injection.</p><h1 id="InjectioninDetail-InjectionTriggers">Injection
Triggers</h1><p>Injection is triggered in a number of ways:</p><ul><li>A field
in a component class, autobuilt object, or service implementation class is
annotated with @Inject.</li><li>A method parameter to a service builder method,
a decorator method, or a contribute method (in a Tapestry IoC module
class).</li><li>A constructor parameter to an autobuilt object, or a service
implementation class.</li><li>Any of the above with an @InjectService annotatio
n.</li></ul><p>These define the <em>point of
injection</em>.</p><p>Injection also covers a related matter: providing special
resources to a service or component (remember that pages are specialized
components). For a service, the service's id (as a string) or extensible
configuration (as a Collection, List or Map) may be provided. For a component,
the component's id, locale, message catalog, or component resources may be
provided.</p><h1 id="InjectioninDetail-StandardInjectionProcessing">Standard
Injection Processing</h1><p>This section describes standard injection, which
applies at the IoC layer: autobuilt objects and service implementations. The
steps for injection into Tapestry components are slightly different and are
covered later.</p><p>So a the point of injection, Tapestry has identified a
field or parameter that should be injected. At this point, Tapestry knows the
following:</p><ul><li>The field name (if field injection). The parameter name
is not available.</li><li>Th
e field or parameter type, as a Java class. In many cases, this will be enough
to identify what object shall be injected.</li><li>Any additional annotations
on the field or parameter.</li></ul><p>Tapestry proceeds with this
information.</p><h2 id="InjectioninDetail-Checkfor@InjectService">Check for
@InjectService</h2><p>Tapestry checks first for the @InjectService annotation.
The value of this annotation is the service id to inject. When @InjectService
is present at the point of injection, the search is complete, though the
injection can fail (throwing an exception) if the service id indicated does not
exist, or if the service's interface is not compatible with the field's
type.</p><h2 id="InjectioninDetail-Checkforserviceresources">Check for service
resources</h2><p>This step applies only to IoC layer injection (not to
injection into components).</p><p>When the @Inject annotation is <em>not
present</em> at the point of injection, Tapestry checks to see if a resource
can be injected
. Services are global values, but resources are specific to the service under
construction.</p><p>When the Inject annotation is present, this step is skipped
(this is necessary when the object to be injected has a type that conflicts
with a resource type, such as List or Class).</p><ul><li>org.slf4j.Logger
– The Logger of the service being constructed (or the logger of the
Module class being instantiated).</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>
– For contribute methods, used to locate additional objects.</li><li><a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ServiceResources.html";>ServiceResources</a>
– For service builder methods, an extended version of
ObjectLocator. </li><li>Class – The service interface
type.</li><li><a class="external-link"
href="http://tapestry.apache.org/current/apido
cs/org/apache/tapestry5/ioc/OperationTracker.html">OperationTracker</a>
– Used to track deeply nested operations so that errors can be reported
sensibly.</li><li>Object, or service interface type – Passed to decorator
methods.</li><li>Collection, List, Map – Assembled service configurations
passed to service builder methods (or service class
constructors).</li><li><p>Configuration, OrderedConfiguration,
MappedConfiguration – Configuration passed to contribute methods, to
build service configurations. <br clear="none" class="atl-forced-newline"> <br
clear="none" class="atl-forced-newline"> If field type does not match any of
the available resource types, or the Inject annotation is present, logic
continues to the next step.</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>Injection
of resources into fields is triggered by the presence of the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectResource.html";>InjectResource</a>
annotation, whereas injection of resources into parameters occurs when the
Inject or InjectService annotation is <em>not</em> present. These rules are
slightly tricky, which reflects a desire to avoid any annotations except when
needed, and the fact that field injection came much later than parameter
injection.</p></div></div></li></ul><h2
id="InjectioninDetail-ServiceLookupbyTypeandAnnotations">Service Lookup by Type
and Annotations</h2><p>Tapestry attempts to find a matching
<em>service</em>.</p><p>First, it generates a set of services whose service
interface is compatible with the injection type. This is based on
assignability.</p><p>If the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Local.html";>Local<
/a> annotation is present, then services not from the module containing the
service being constructed will be eliminated.</p><p>Tapestry then works through
the known marker annotations. For each marker annotation that is present at the
point of injection, Tapestry eliminates services which <em>do not</em> have the
marker. Thus, if multiple marker annotations are present, the final service
must have <em>all of them</em>.</p><p>At the end, of this, Tapestry determines
how many services match.</p><ul><li>If there is a single matching service, then
the service to inject as been identified.</li><li>If there are no matches, and
there were no marker annotations at the point of injection, then the Tapestry
continues to the next step.</li><li>Otherwise there were either no matches, or
too many matches: Tapestry will throw a RuntimeException.</li></ul><h2
id="InjectioninDetail-MasterObjectProviderLookup">MasterObjectProvider
Lookup</h2><p>This is the point at which Tapestry's extensibility co
mes into play. MasterObjectProvider is a service, with a configuration of <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectProvider.html";>ObjectProviders</a>.</p><p>The
MasterObjectProvider is also the point at which Tapestry's IoC layer
injection, and Tapestry's component injection, unite.</p><p>As a
chain-of-command, each of the following ObjectProviders will be considered and
will attempt to identify the object to be injected.</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>A common problem when extending
injection is that contributions into the MasterObjectProvider configuration
have to be handled carefully. Any dependencies of the contributed objects
should be resolvable using only the early stages of the injection process,
otherwise MasterObje
ctProvider will have to be instantiated in order to handle its own injection:
Tapestry will detect this impossibility and throw an exception. In addition,
the <a href="typecoercer-service.html">TypeCoercer</a> service is used by
several ObjectProvider implementations, so the same restrictions apply to
TypeCoercer service contributions.</p></div></div><h3
id="InjectioninDetail-ValueObjectProvider">Value ObjectProvider</h3><p>Checks
for the presence of the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Value</a>
annotation. If present, then the annotation's value is evaluated (to expand
any symbol references), and the TypeCoercer service is used to convert the
resulting String to the injection type (the field or parameter type).</p><h3
id="InjectioninDetail-SymbolObjectProvider">Symbol
ObjectProvider</h3><p>Similar to the Value ObjectProvider: the @<a
class="external-link" href="http://tapestry.apache.org/
current/apidocs/org/apache/tapestry5/ioc/annotations/Symbol.html">Symbol</a>
annotation's value (if present) is looked up using the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/SymbolSource.html";>SymbolSource</a>
service, and converted to the injection type via the TypeCoercer
service.</p><h3 id="InjectioninDetail-AutobuildObjectProvider">Autobuild
ObjectProvider</h3><p>Checks to see if the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Autobuild.html";>Autobuild</a>
annotation is present and, if so, autobuilds the value for the parameter. Of
course, the object being built will itself be configured via injection.</p><h3
id="InjectioninDetail-ServiceOverrideObjectProvider">ServiceOverride
ObjectProvider</h3><p>Checks any contributions to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/Ser
viceOverride.html">ServiceOverride</a> service. Contributions map a type to an
object of that type. Thus, ServiceOverrides will override injections of
services that are not qualified with a marker annotation.</p><h3
id="InjectioninDetail-AliasObjectProvider(tapestry-core)">Alias ObjectProvider
(tapestry-core)</h3><p>Uses the Alias service (<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Alias.html";>API</a>)
to look for an object that can be injected.</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>Deprecated in Tapestry 5.2 and
removed in 5.4.</p></div></div><p>This is commonly used to override a built-in
service by contributing an object with the exact same interface. This is an
older and more complex version of the ServiceOverride provider.</p><h
3 id="InjectioninDetail-AssetObjectProvider(tapestry-core)">Asset
ObjectProvider (tapestry-core)</h3><p>Checks for the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation.</p><p>If present, the annotation's value has embedded symbols
expanded, and is converted into an Asset (which must exist).</p><p>The
TypeCoercer can then convert the Asset to the injection type, for example, as
Resource.</p><h3
id="InjectioninDetail-ServiceObjectProvider(tapestry-core)">Service
ObjectProvider (tapestry-core)</h3><p>Looks for the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation; if present, the annotation's value is the exact service id to
inject. This is necessary because injections into <em>component</em> fields are
always triggered by the Inject annotation.</p><div
class="confluence-information-macro confluence-in
formation-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This is supported but no longer
necessary, as the @InjectService annotation is now also supported for component
fields.</p></div></div><h3
id="InjectioninDetail-SpringBeanObjectProvider(tapestry-spring)">SpringBean
ObjectProvider (tapestry-spring)</h3><p>Attempts to resolve a Spring bean
purely by object type (Spring qualifiers are not supported). If no beans are
assignable to the type, then processing continues. If exactly one is
assignable, it is used as the injection value. If more than one bean is
assignable, it is an error (and a list of matching beans names will be part of
the thrown exception).</p><h2 id="InjectioninDetail-ServiceLookup">Service
Lookup</h2><p>If none of the ObjectProviders can identify the value to inject,
a last step occurs: lookup by service type. If exactly <em>one</em> service
matches t
he injection type, then that service is injected.</p><p>Otherwise, the lookup
fails because either no services match, or more than one matches. An exception
will be thrown with the details, including a list of matching services (if
there is more than one match).</p><h1
id="InjectioninDetail-Post-InjectionMethods">Post-Injection
Methods</h1><p>Autobuilt objects (services and the like, but <em>not</em>
components) may have post-injection methods.</p><p>Any public method may have
the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PostInjection.html";>PostInjection</a>
annotation.</p><p>Such methods are invoked after constructor and/or field
injection. Only <strong>public methods</strong> will be invoked. Any return
value is ignored.</p><p>The method often takes no parameters; however if the
method has parameters, these parameters are new points of
injection.</p><p>Often this is used to perform additional setup, such as regist
erring a service as a listener of events produced by another service:</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 MyServiceImpl implements MyService,
UpdateListener
{
@PostInjection
public void registerAsListener(UpdateListenerHub hub)
@@ -75,7 +126,8 @@
hub.addUpdateListener(this);
}
}
-</plain-text-body><h1 id="InjectioninDetail-ComponentInjection">Component
Injection</h1><p>Inside Tapestry components, injection occurs exclusively on
<em>fields</em> and is always triggered by the @Inject (or @InjectService)
annotation.</p><p>Component field injection is very similar to IoC layer, but
with a different set of injectable resources.</p><p>Injection is the
responsibility of the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service, which is a chain-of-command across a number of
implementations.</p><h2 id="InjectioninDetail-BlockInjectionProvider">Block
InjectionProvider</h2><p>Checks if the field type is Block. If so, determines
the block id to inject (either from the field name, or from an @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation, if present).</p><h2 id="InjectioninDetail
-DefaultInjectionProvider">Default InjectionProvider</h2><p>Uses the
MasterObjectProvider service to provide the injectable value. The Service
Lookup stage is skipped.</p><h2
id="InjectioninDetail-ComponentResourcesInjectionProvider">ComponentResources
InjectionProvider</h2><p>Injects fields of type ComponentResources.</p><h2
id="InjectioninDetail-CommonResourcesInjectionProvider">CommonResources
InjectionProvider</h2><p>Injects fields with common
resources:</p><ul><li>String: the components' complete
id</li><li>org.slf4j.Logger: Logger for the component (based on component class
name)</li><li>Locale: locale for the containing page (page locale is
immutable)</li><li>Messages: Component's message
catalog</li><li>ComponentResourceSelector: selector for the containing page
(selector is immutable)</li></ul>
+</pre>
+</div></div><h1 id="InjectioninDetail-ComponentInjection">Component
Injection</h1><p>Inside Tapestry components, injection occurs exclusively on
<em>fields</em> and is always triggered by the @Inject (or @InjectService)
annotation.</p><p>Component field injection is very similar to IoC layer, but
with a different set of injectable resources.</p><p>Injection is the
responsibility of the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service, which is a chain-of-command across a number of
implementations.</p><h2 id="InjectioninDetail-BlockInjectionProvider">Block
InjectionProvider</h2><p>Checks if the field type is Block. If so, determines
the block id to inject (either from the field name, or from an @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation, if present).</p><h2 id="InjectioninDetail-Defau
ltInjectionProvider">Default InjectionProvider</h2><p>Uses the
MasterObjectProvider service to provide the injectable value. The Service
Lookup stage is skipped.</p><h2
id="InjectioninDetail-ComponentResourcesInjectionProvider">ComponentResources
InjectionProvider</h2><p>Injects fields of type ComponentResources.</p><h2
id="InjectioninDetail-CommonResourcesInjectionProvider">CommonResources
InjectionProvider</h2><p>Injects fields with common
resources:</p><ul><li>String: the components' complete
id</li><li>org.slf4j.Logger: Logger for the component (based on component class
name)</li><li>Locale: locale for the containing page (page locale is
immutable)</li><li>Messages: Component's message
catalog</li><li>ComponentResourceSelector: selector for the containing page
(selector is immutable)</li></ul>
<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>
Modified: websites/production/tapestry/content/injection.html
==============================================================================
--- websites/production/tapestry/content/injection.html (original)
+++ websites/production/tapestry/content/injection.html Wed Sep 20 12:29:16 2017
@@ -27,6 +27,16 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,42 +77,84 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Injection</strong> is
Tapestry's way of making a dependency – such as a resource, asset,
component, block or service – available in a page, component, mixin or
service class.</p><parameter ac:name="style">float:right</parameter><parameter
ac:name="title">Related Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "injection" and space =
currentSpace()</parameter></rich-text-body><p>Injection is a key concept in
Tapestry, and it is used in several different but related ways.</p><h2
id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC
Services</h2><p>Main Article: <a href="tapestry-ioc-overview.html">Tapestry
IoC Overview</a></p><p>The Tapestry IoC container makes use of injection prima
rily through constructors and via parameters to service builder
methods.</p><h2 id="Injection-InjectioninComponentClasses">Injection in
Component Classes</h2><p>For components, however, Tapestry takes a completely
different tack: injection directly into component fields.</p><p>The @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation is used to identify fields that will contain injected services and
other resources.</p><p>Tapestry allows for two kinds of
injection:</p><ul><li><strong>Default injection</strong>, where Tapestry
determines the object to inject into the field based on its
type.</li><li><strong>Explicit injection</strong>, where the particular service
to be injected is specified.</li></ul><p>In both cases, the field is
transformed into a read only value. As elsewhere in Tapestry, this
transformation occurs at runtime (which is very important in terms of being
able to test your c
omponents). Attempting to update an injected field will result in a runtime
exception.</p><p>In addition, there are a few special cases that are triggered
by specific field types, or additional annotations, in addition, to @Inject, on
a field.</p><h3 id="Injection-BlockInjection">Block Injection</h3><p>For field
type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Block</a>,
the value of the Inject annotation is the id of the <a
href="component-templates.html"><t:block></a> element within the
component's template. Normally, the id of the block is determined from the
field name (after stripping out any leading "_" and "$"
characters):</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
+ <div id="ConfluenceContent"><p><strong>Injection</strong> is
Tapestry's way of making a dependency – such as a resource, asset,
component, block or service – available in a page, component, mixin or
service class.</p><div class="aui-label" style="float:right" title="Related
Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection-in-detail.html">Injection in
Detail</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection-faq.html">Injection FAQ</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="injection.html">Injection</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>Injection is a key concept in Tapestry, and it is used in several different
but related ways.</p><h2
id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC
Services</h2><p>Main Article: <a href="tapestry-ioc-overview.html">Tapestry
IoC Overview</a></p><p>The Tapestry IoC container makes use of injection
primarily through constructors and via parameters to service builder
methods.</p><h2 id="Injection-InjectioninComponentClasses">Injection in
Component Classes</h2><p>For components, however, Tapestry takes a completely
different tack: injection directly into component fields.</p><p>The @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation is used to identify fields that will contain injected services and
other resources.</p><p>Tapestry allows for two kinds of
injection:</p><ul><li><strong>Default injection</strong>, where Tapestry
determines the object to inject into the
field based on its type.</li><li><strong>Explicit injection</strong>, where
the particular service to be injected is specified.</li></ul><p>In both cases,
the field is transformed into a read only value. As elsewhere in Tapestry, this
transformation occurs at runtime (which is very important in terms of being
able to test your components). Attempting to update an injected field will
result in a runtime exception.</p><p>In addition, there are a few special cases
that are triggered by specific field types, or additional annotations, in
addition, to @Inject, on a field.</p><h3 id="Injection-BlockInjection">Block
Injection</h3><p>For field type <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html";>Block</a>,
the value of the Inject annotation is the id of the <a
href="component-templates.html"><t:block></a> element within the
component's template. Normally, the id of the block is determined from the
field name (after strippin
g out any leading "_" and "$" characters):</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;">@Inject
private Block foo;
-</plain-text-body><p>Where that is not appropriate, an @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation can be supplied:</p><plain-text-body>@Inject
+</pre>
+</div></div><p>Where that is not appropriate, an @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html";>Id</a>
annotation can be supplied:</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;">@Inject
@Id("bar")
private Block barBlock;
-</plain-text-body><p>The first injection will inject the Block with id "foo"
(as always, case is ignored). The second injection will inject the Block with
id "bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For
a particular set of field types, Tapestry will inject a <em>resource</em>
related to the component, such as its Locale.</p><p>A very common example
occurs when a component needs access to its <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>resources</a>.
The component can define a field of the appropriate type and use the
<code>@Inject</code> annotation without a value:</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>The first injection will inject the Block with id "foo" (as
always, case is ignored). The second injection will inject the Block with id
"bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For a
particular set of field types, Tapestry will inject a <em>resource</em> related
to the component, such as its Locale.</p><p>A very common example occurs when a
component needs access to its <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>resources</a>.
The component can define a field of the appropriate type and use the
<code>@Inject</code> annotation without a value:</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;">@Inject
private ComponentResources resources;
-</plain-text-body><p>Tapestry uses the type of the field, ComponentResources,
to determine what to inject into this field.</p><p>The following types are
supported for resources injection:</p><ul><li><strong>java.lang.String</strong>
– The complete id of the component, which incorporates the complete class
name of the containing page and the nested id of the component within the
page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for
the component (all components within a page use the same
locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger
instance configured for the component, based on the component's class name. <a
class="external-link" href="http://www.slf4j.org/"; rel="nofollow">SLF4J</a> is
a wrapper around Log4J or other logging
toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong>
– The resources for the component, often used to generate links related
to the component.</li></ul><ul><li>
<strong>org.apache.tapestry5.ioc.Messages</strong> – The component
message catalog for the component, from which <a
href="injection.html">localized</a> messages can be generated.</li></ul><h3
id="Injection-AssetInjection">Asset Injection</h3><p>Main Article: <a
href="assets.html">Assets</a></p><p>When the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation is also present, then the injected value (relative to the
component) will be a localized asset.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>Tapestry uses the type of the field, ComponentResources, to
determine what to inject into this field.</p><p>The following types are
supported for resources injection:</p><ul><li><strong>java.lang.String</strong>
– The complete id of the component, which incorporates the complete class
name of the containing page and the nested id of the component within the
page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for
the component (all components within a page use the same
locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger
instance configured for the component, based on the component's class name. <a
class="external-link" href="http://www.slf4j.org/"; rel="nofollow">SLF4J</a> is
a wrapper around Log4J or other logging
toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong>
– The resources for the component, often used to generate links related
to the component.</li></ul><ul><li><stron
g>org.apache.tapestry5.ioc.Messages</strong> – The component message
catalog for the component, from which <a href="injection.html">localized</a>
messages can be generated.</li></ul><h3 id="Injection-AssetInjection">Asset
Injection</h3><p>Main Article: <a href="assets.html">Assets</a></p><p>When the
@<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html";>Path</a>
annotation is also present, then the injected value (relative to the
component) will be a localized asset.</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;">@Inject
@Path("context:images/top_banner.png")
private Asset banner;
-</plain-text-body><p>Symbols in the annotation value are expanded.</p><h3
id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom
EmployeeService service is injected, but any custom or built-in service may be
injected in the same way.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>Symbols in the annotation value are expanded.</p><h3
id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom
EmployeeService service is injected, but any custom or built-in service may be
injected in the same way.</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;">@Inject
private EmployeeService employeeService;
-</plain-text-body><p>A large number of services are provided by Tapestry. See
the following packages:<plain-text-body>{float:left|width=15em}
-* [Core
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html]
-* [AJAX
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html]
-* [Assets
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html]
-* [Dynamic Component
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [JavaScript
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html]
-* [Link Transformation
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html]
-* [Message
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html]
-* [Component Metadata
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [Page Loading
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html]
-* [Security
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html]
-* [Template
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html]
-* [Class Transformation
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html]
-{float}</plain-text-body><plain-text-body>{float:left|width=15em}
-* [Tapestry IOC
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html]
-* [Tapestry IOC Cron
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html]
-* [Kaptcha
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html]
-* [File Upload
Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html]
-{float}</plain-text-body><parameter
ac:name="atlassian-macro-output-type">INLINE</parameter><plain-text-body><div
style="clear:both"></div></plain-text-body> </p><h3
id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here,
a specific object is requested. A @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation is used to identify the service name.</p><parameter
ac:name="">java</parameter><plain-text-body>@Inject
+</pre>
+</div></div><p>A large number of services are provided by Tapestry. See the
following packages:</p><div class="navmenu" style="float:left; width:15em;
background:white; margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html";>Core
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html";>AJAX
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html";>Assets
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html";>Dynamic
Component Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html";>JavaScript
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html";>Link
Transformation Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html";>Message
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html";>Component
Metadata Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html";>Page
Loading Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html";>Security
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html";>Template
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html";>Class
Transformation Services</a></li></ul>
+</div><div class="navmenu" style="float:left; width:15em; background:white;
margin:3px; padding:3px">
+<ul><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html";>Tapestry
IOC Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html";>Tapestry
IOC Cron Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html";>Kaptcha
Services</a></li><li><a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html";>File
Upload Services</a></li></ul>
+</div><div style="clear:both"></div> <h3
id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here,
a specific object is requested. A @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html";>Service</a>
annotation is used to identify the service name.</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;">@Inject
@Service("Request")
private Request request;
-</plain-text-body><p>This is generally not necessary; you should always be
able to identify the service to be injected just by type, not by explicit id.
Explicit ids have the disadvantage of not being refactoring-safe: this won't
happen with the Request service, but perhaps in your own code ... if you rename
the service interface and rename the service id to match, your existing
injections using the explicit service id will break.</p><h2
id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or
other annotations are not sufficient to identify the object or service to
inject, Tapestry falls back on two remaining steps. It assumes that the field
type will be used to identify a service, by the service interface.</p><p>First,
the object provider created by the Alias service is consulted. This object
provider is used to disambiguate injections when there is more than one service
that implements the same service interface.</p><p>Second, a search for a unique
service th
at implements the interface occurs. This will fail if either there are no
services that implement the interface, or there is more than one. In the latter
case, you must disambiguate, either with a contribution to the Alias service,
or by explicitly identifying the service with the @Service annotation.</p><h2
id="Injection-DefiningNewInjectionLogic">Defining New Injection
Logic</h2><p>Anonymous injection is controlled by the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service. The configuration for this service is a <a
href="chainbuilder-service.html">chain of command</a> for handling component
injections.</p></div>
+</pre>
+</div></div><p>This is generally not necessary; you should always be able to
identify the service to be injected just by type, not by explicit id. Explicit
ids have the disadvantage of not being refactoring-safe: this won't happen with
the Request service, but perhaps in your own code ... if you rename the service
interface and rename the service id to match, your existing injections using
the explicit service id will break.</p><h2
id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or
other annotations are not sufficient to identify the object or service to
inject, Tapestry falls back on two remaining steps. It assumes that the field
type will be used to identify a service, by the service interface.</p><p>First,
the object provider created by the Alias service is consulted. This object
provider is used to disambiguate injections when there is more than one service
that implements the same service interface.</p><p>Second, a search for a unique
service that imp
lements the interface occurs. This will fail if either there are no services
that implement the interface, or there is more than one. In the latter case,
you must disambiguate, either with a contribution to the Alias service, or by
explicitly identifying the service with the @Service annotation.</p><h2
id="Injection-DefiningNewInjectionLogic">Defining New Injection
Logic</h2><p>Anonymous injection is controlled by the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html";>InjectionProvider</a>
service. The configuration for this service is a <a
href="chainbuilder-service.html">chain of command</a> for handling component
injections.</p></div>
</div>
<div class="clearer"></div>
Modified:
websites/production/tapestry/content/integrating-with-spring-framework.html
==============================================================================
--- websites/production/tapestry/content/integrating-with-spring-framework.html
(original)
+++ websites/production/tapestry/content/integrating-with-spring-framework.html
Wed Sep 20 12:29:16 2017
@@ -27,6 +27,15 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css'
rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet'
type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,23 +76,76 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Tapestry easily integrates with
Spring Framework, allowing beans defined by Spring to be injected into Tapestry
IoC services, and into Tapestry components. In addition, with Tapestry 5.2 and
later, you can also go the other way, injecting Tapestry services in Spring
beans.</p><parameter ac:name="style">float:right</parameter><parameter
ac:name="title">Related Articles</parameter><parameter
ac:name="class">aui-label</parameter><rich-text-body><parameter
ac:name="showLabels">false</parameter><parameter
ac:name="showSpace">false</parameter><parameter ac:name="title">Related
Articles</parameter><parameter ac:name="cql">label = "spring" and space =
currentSpace()</parameter></rich-text-body><p>For integrating Spring Security
into your application, see <a
href="security.html">Security</a>.</p><p><strong>Contents</strong></p><p><parameter
ac:name="maxLevel">3</parameter><parameter
ac:name="type">list</parameter></p><h2 id="IntegratingwithSpri
ngFramework-SpringVersion">Spring Version</h2><p>This module is compiled and
tested against Spring Framework 2.5.6. It should be reasonable to override the
dependency to earlier versions of Spring, though the code makes use of some
APIs that were added to Spring to support JDK 1.5 annotations.</p><h2
id="IntegratingwithSpringFramework-Usage">Usage</h2><p>The integration is
designed to be a very thin layer on top of Spring's normal configuration for a
web application.</p><p>Detailed instructions are available in the <a
class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#context-create";
rel="nofollow">Spring documentation</a>. Please omit the part about creating a
ContextLoaderListener: this is now done automatically by Tapestry.</p><h3
id="IntegratingwithSpringFramework-Requireddependency">Required
dependency</h3><p>To integrate Spring with Tapestry, you should add the below
dependency in your classpath. The following exemple is for M
aven users.</p><parameter ac:name="language">xml</parameter><plain-text-body>
<dependency>
+ <div id="ConfluenceContent"><p>Tapestry easily integrates with
Spring Framework, allowing beans defined by Spring to be injected into Tapestry
IoC services, and into Tapestry components. In addition, with Tapestry 5.2 and
later, you can also go the other way, injecting Tapestry services in Spring
beans.</p><div class="aui-label" style="float:right" title="Related Articles">
+
+
+
+
+
+
+
+
+<h3>Related Articles</h3>
+
+<ul class="content-by-label"><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a
href="integrating-with-spring-framework.html">Integrating with Spring
Framework</a>
+
+
+ </div>
+ </li><li>
+ <div>
+ <span class="icon aui-icon aui-icon-small
aui-iconfont-page-default" title="Page">Page:</span> </div>
+
+ <div class="details">
+ <a href="security.html">Security</a>
+
+
+ </div>
+ </li></ul>
+</div>
+
+
+<p>For integrating Spring Security into your application, see <a
href="security.html">Security</a>.</p><p><strong>Contents</strong></p><p><style
type="text/css">/*<![CDATA[*/
+div.rbtoc1491819649664 {padding: 0px;}
+div.rbtoc1491819649664 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1491819649664 li {margin-left: 0px;padding-left: 0px;}
+
+/*]]>*/</style></p><div class="toc-macro rbtoc1491819649664">
+<ul class="toc-indentation"><li>Related Articles</li></ul>
+<ul><li><a href="#IntegratingwithSpringFramework-SpringVersion">Spring
Version</a></li><li><a href="#IntegratingwithSpringFramework-Usage">Usage</a>
+<ul class="toc-indentation"><li><a
href="#IntegratingwithSpringFramework-Requireddependency">Required
dependency</a></li><li><a
href="#IntegratingwithSpringFramework-Updateyourweb.xmlfile">Update your
web.xml file</a></li><li><a
href="#IntegratingwithSpringFramework-AccessingtheSpringApplicationContext">Accessing
the Spring Application Context</a></li><li><a
href="#IntegratingwithSpringFramework-Injectingbeans">Injecting
beans</a></li><li><a
href="#IntegratingwithSpringFramework-InjectingTapestryservicesinSpringbeans">Injecting
Tapestry services in Spring beans</a></li></ul>
+</li><li><a
href="#IntegratingwithSpringFramework-ApplicationContextCustomizer">ApplicationContextCustomizer</a></li><li><a
href="#IntegratingwithSpringFramework-5.0CompatibilityMode">5.0 Compatibility
Mode</a></li><li><a
href="#IntegratingwithSpringFramework-ChangesFrom5.0">Changes From
5.0</a></li><li><a
href="#IntegratingwithSpringFramework-Limitations">Limitations</a></li></ul>
+</div><h2 id="IntegratingwithSpringFramework-SpringVersion">Spring
Version</h2><p>This module is compiled and tested against Spring Framework
2.5.6. It should be reasonable to override the dependency to earlier versions
of Spring, though the code makes use of some APIs that were added to Spring to
support JDK 1.5 annotations.</p><h2
id="IntegratingwithSpringFramework-Usage">Usage</h2><p>The integration is
designed to be a very thin layer on top of Spring's normal configuration for a
web application.</p><p>Detailed instructions are available in the <a
class="external-link"
href="http://static.springframework.org/spring/docs/2.5.x/reference/beans.html#context-create";
rel="nofollow">Spring documentation</a>. Please omit the part about creating a
ContextLoaderListener: this is now done automatically by Tapestry.</p><h3
id="IntegratingwithSpringFramework-Requireddependency">Required
dependency</h3><p>To integrate Spring with Tapestry, you should add the below
dependency in your classpat
h. The following exemple is for Maven users.</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <dependency>
<groupId>org.apache.tapestry</groupId>
<artifactId>tapestry-spring</artifactId>
<version>[your-tapestry-version]</version>
</dependency>
-</plain-text-body><h3
id="IntegratingwithSpringFramework-Updateyourweb.xmlfile">Update your web.xml
file</h3><p>The short form is that you must make two small changes to your
application's web.xml.</p><p>First, a special filter is used in replace of the
standard TapestryFilter:</p><parameter
ac:name="language">java</parameter><plain-text-body> <filter>
+</pre>
+</div></div><h3
id="IntegratingwithSpringFramework-Updateyourweb.xmlfile">Update your web.xml
file</h3><p>The short form is that you must make two small changes to your
application's web.xml.</p><p>First, a special filter is used in replace of the
standard TapestryFilter:</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;"> <filter>
<filter-name>app</filter-name>
<!-- Special filter that adds in a T5 IoC module derived from the
Spring WebApplicationContext. -->
<filter-class>org.apache.tapestry5.spring.TapestrySpringFilter</filter-class>
- </filter></plain-text-body><p>Secondly, you may add the normal Spring
configuration, consisting of an optional <context-param> identifying
which Spring bean configuration file(s) to load:</p><parameter
ac:name="language">java</parameter><plain-text-body><context-param>
+ </filter></pre>
+</div></div><p>Secondly, you may add the normal Spring configuration,
consisting of an optional <context-param> identifying which Spring bean
configuration file(s) to load:</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;"><context-param>
<param-name>contextConfigLocation</param-name>
<param-value>/WEB-INF/daoContext.xml
/WEB-INF/applicationContext.xml</param-value>
</context-param>
-</plain-text-body><p>The <context-param> lists the Spring bean
configuration file. It is optional and defaults to just
/WEB-INF/applicationContext.xml if omitted.</p><h3
id="IntegratingwithSpringFramework-AccessingtheSpringApplicationContext">Accessing
the Spring Application Context</h3><p>By integrating Spring in Tapestry, you
get full access on Spring ApplicationContext as if you were accessing to any
Tapestry service. Simply @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
into your pages and components.</p><parameter
ac:name="language">java</parameter><plain-text-body> @Inject
+</pre>
+</div></div><p>The <context-param> lists the Spring bean configuration
file. It is optional and defaults to just /WEB-INF/applicationContext.xml if
omitted.</p><h3
id="IntegratingwithSpringFramework-AccessingtheSpringApplicationContext">Accessing
the Spring Application Context</h3><p>By integrating Spring in Tapestry, you
get full access on Spring ApplicationContext as if you were accessing to any
Tapestry service. Simply @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
into your pages and components.</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;"> @Inject
private ApplicationContext springContext;
-</plain-text-body><h3
id="IntegratingwithSpringFramework-Injectingbeans">Injecting
beans</h3><p>Inside your component classes, you may use the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation. Typically, just adding @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
to the field type is sufficient to identify the Spring bean to
inject:</p><parameter ac:name="language">java</parameter><plain-text-body>
@Inject
- private UserDAO userDAO;</plain-text-body><p>Searching for Spring beans is
threaded into the <a href="injection.html">MasterObjectProvider service</a>.
The Spring context becomes one more place that Tapestry searches when
determining the injection for a injected field or method parameter.</p><h3
id="IntegratingwithSpringFramework-InjectingTapestryservicesinSpringbeans">Injecting
Tapestry services in Spring beans</h3>
+</pre>
+</div></div><h3 id="IntegratingwithSpringFramework-Injectingbeans">Injecting
beans</h3><p>Inside your component classes, you may use the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
annotation. Typically, just adding @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html";>Inject</a>
to the field type is sufficient to identify the Spring bean to inject:</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;"> @Inject
+ private UserDAO userDAO;</pre>
+</div></div><p>Searching for Spring beans is threaded into the <a
href="injection.html">MasterObjectProvider service</a>. The Spring context
becomes one more place that Tapestry searches when determining the injection
for a injected field or method parameter.</p><h3
id="IntegratingwithSpringFramework-InjectingTapestryservicesinSpringbeans">Injecting
Tapestry services in Spring beans</h3>
<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>
