tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Injection in Detail
Date Thu, 23 Dec 2010 01:30:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/12/_/styles/combined.css?spaceKey=TAPESTRY&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Injection+in+Detail">Injection
in Detail</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~bobharner">Bob
Harner</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Renamed<br />
    </div>
        <br/>
                         <h4>Changes (0)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-snipped" >...<br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color:
#f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td
class='ScrollbarPrevIcon'><a href="/confluence/display/TAPESTRY/StrategyBuilder+Service"><img
border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td
width='33%' class='ScrollbarPrevName'><a href="/confluence/display/TAPESTRY/StrategyBuilder+Service">StrategyBuilder
Service</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a
href="/confluence/display/TAPESTRY/IoC"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif'
width='8' height='8'></a></sup><a href="/confluence/display/TAPESTRY/IoC">IoC</a></td><td
width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/TAPESTRY/IoC+-+provider">IoC
- provider</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/TAPESTRY/IoC+-+provider"><img
border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table>!
 </div>

<h1><a name="InjectioninDetail-InjectioninDetail"></a>Injection in Detail</h1>

<p>Injection 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>


<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><a name="InjectioninDetail-InjectionTriggers"></a>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
the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html"
class="external-link" rel="nofollow">Inject</a> annotation.</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 <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html"
class="external-link" rel="nofollow">InjectService</a> annotation.</li>
</ul>


<p>Injection also covers a related matter: providing special resources to a service
or component. 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><a name="InjectioninDetail-StandardInjectionProcessing"></a>Standard
Injection Processing</h1>

<p>This section describes standard injection, which applies at the IoC layer: autobuild
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><a name="InjectioninDetail-CheckforInjectService"></a>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, that
process is done, though it can fail if the service id indicated does not exist, or if the
service's interface is not compatible with the field's type.</p>

<h2><a name="InjectioninDetail-Checkforserviceresources"></a>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. 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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html"
class="external-link" rel="nofollow">ObjectLocator</a> For contribute methods, used
to locate additional objects.</li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ServiceResources.html"
class="external-link" rel="nofollow">ServiceResources</a> For service builder methods,
an extended version of ObjectLocator. Class The service interface type.</li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/OperationTracker.html"
class="external-link" rel="nofollow">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>Configuration, OrderedConfiguration, MappedConfiguration Configuration passed to
contribute methods, to build service configurations.</li>
</ul>


<p>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='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>Injection of resources
into fields is triggered by the presence of the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectResource.html"
class="external-link" rel="nofollow">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.</td></tr></table></div>

<h2><a name="InjectioninDetail-ServiceLookupbyTypeandAnnotations"></a>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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Local.html"
class="external-link" rel="nofollow">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 annotation, Tapestry eliminates services which do not 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 value 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.
<h2><a name="InjectioninDetail-MasterObjectProviderLookup"></a>MasterObjectProvider
Lookup</h2></li>
</ul>


<p>This is the point at which Tapestry's extensibility comes into play. MasterObjectProvider
is a service, with a configuration of <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectProvider.html"
class="external-link" rel="nofollow">ObjectProvider</a>s.</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='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>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 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="#InjectioninDetail-coerce.html">TypeCoercer</a>
service is used by several ObjectProvider implementations, so the same restrictions apply
to TypeCoercer service contributions.</td></tr></table></div>

<h3><a name="InjectioninDetail-ValueObjectProvider"></a>Value ObjectProvider</h3>

<p>Checks for the presence of the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html"
class="external-link" rel="nofollow">Value</a> annotation. If present, then the annotations
value is evaluated (to expand any symbol references), and the TypeCoercer coverts the resulting
String to the injection type.</p>

<h3><a name="InjectioninDetail-SymbolObjectProvider"></a>Symbol ObjectProvider</h3>

<p>Similar to the Value ObjectProvider: the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Symbol.html"
class="external-link" rel="nofollow">Symbol</a> annotation's value (if present) is
lookup up and converted to the injection type.</p>

<h3><a name="InjectioninDetail-AutobuildObjectProvider"></a>Autobuild ObjectProvider</h3>

<p>Checks to see if the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotation/Autobuild.html"
class="external-link" rel="nofollow">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><a name="InjectioninDetail-ServiceOverrideObjectProvider"></a>ServiceOverride
ObjectProvider</h3>

<p>Checks any contributions to the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/ServiceOverride.html"
class="external-link" rel="nofollow">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><a name="InjectioninDetail-AliasObjectProvider%28tapestrycore%29"></a>Alias
ObjectProvider (tapestry-core)</h3>

<p>Uses the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Alias.html"
class="external-link" rel="nofollow">Alias</a> service to look for an object that
can be injected.</p>

<div class='panelMacro'><table class='warningMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/forbidden.gif" width="16"
height="16" align="absmiddle" alt="" border="0"></td><td>Deprecated in Tapestry
5.2.</td></tr></table></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>

<h3><a name="InjectioninDetail-AssetObjectProvider%28tapestrycore%29"></a>Asset
ObjectProvider (tapestry-core)</h3>

<p>Checks for the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html"
class="external-link" rel="nofollow">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><a name="InjectioninDetail-ServiceObjectProvider%28tapestrycore%29"></a>Service
ObjectProvider (tapestry-core)</h3>

<p>Looks for the @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html"
class="external-link" rel="nofollow">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='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td
valign='top'><img src="/confluence/images/icons/emoticons/warning.gif" width="16" height="16"
align="absmiddle" alt="" border="0"></td><td>This is supported but no longer
necessary, as the @InjectService annotation is now also supported for component fields.</td></tr></table></div>

<h3><a name="InjectioninDetail-SpringBeanObjectProvider%28tapestryspring%29"></a>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><a name="InjectioninDetail-ServiceLookup"></a>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 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><a name="InjectioninDetail-PostInjectionMethods"></a>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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/PostInjection.html"
class="external-link" rel="nofollow">PostInjection</a> annotation.</p>

<p>Such methods are invoked after constructor and/or field injection. Only <b>public
methods</b> will be invoked. Any return value is ignored.</p>

<p>Further injections may take place using the parameters of the method.</p>

<p>Often this is used to perform additional setup, such as registerring a service as
a listener of events produced by another service:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class MyServiceImpl <span class="code-keyword">implements</span>
MyService, UpdateListener
{
  @PostInjection
  <span class="code-keyword">public</span> void registerAsListener(UpdateListenerHub
hub)
  {
    hub.addUpdateListener(<span class="code-keyword">this</span>);
  }
}
</pre>
</div></div>

<h1><a name="InjectioninDetail-ComponentInjection"></a>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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html"
class="external-link" rel="nofollow">InjectionProvider</a> service, which is a chain-of-command
across a number of implementations.</p>

<h2><a name="InjectioninDetail-BlockInjectionProvider"></a>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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html"
class="external-link" rel="nofollow">Id</a> annotation, if present).</p>

<h2><a name="InjectioninDetail-DefaultInjectionProvider"></a>Default InjectionProvider</h2>

<p>Uses the MasterObjectProvider service to provide the injectable value. The Service
Lookup stage is skipped.</p>

<h2><a name="InjectioninDetail-ComponentResourcesInjectionProvider"></a>ComponentResources
InjectionProvider</h2>

<p>Injects fields of type ComponentResources.</p>

<h2><a name="InjectioninDetail-CommonResourcesInjectionProvider"></a>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>
</ul>


<h2><a name="InjectioninDetail-AssetInjectionProvider"></a>Asset InjectionProvider</h2>

<p>Triggered by the @Path annotation: the Path value has symbols expanded, and is then
converted to an Asset.</p>

<h2><a name="InjectioninDetail-ServiceInjectionProvider"></a>Service InjectionProvider</h2>

<p>Equivalent to the Service Lookup phase in an IoC layer injection.</p>

<h1><a name="InjectioninDetail-@InjectServiceinComponents"></a>@InjectService
in Components</h1>

<p>This is now supported; you may use the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html"
class="external-link" rel="nofollow">InjectService</a> annotation on component fields.</p>

<style type='text/css'>/*<![CDATA[*/
table.ScrollbarTable  {border: none;padding: 3px;width: 100%;padding: 3px;margin: 0px;background-color:
#f0f0f0}
table.ScrollbarTable td.ScrollbarPrevIcon {text-align: center;width: 16px;border: none;}
table.ScrollbarTable td.ScrollbarPrevName {text-align: left;border: none;}
table.ScrollbarTable td.ScrollbarParent {text-align: center;border: none;}
table.ScrollbarTable td.ScrollbarNextName {text-align: right;border: none;}
table.ScrollbarTable td.ScrollbarNextIcon {text-align: center;width: 16px;border: none;}

/*]]>*/</style><div class="Scrollbar"><table class='ScrollbarTable'><tr><td
class='ScrollbarPrevIcon'><a href="/confluence/display/TAPESTRY/StrategyBuilder+Service"><img
border='0' align='middle' src='/confluence/images/icons/back_16.gif' width='16' height='16'></a></td><td
width='33%' class='ScrollbarPrevName'><a href="/confluence/display/TAPESTRY/StrategyBuilder+Service">StrategyBuilder
Service</a>&nbsp;</td><td width='33%' class='ScrollbarParent'><sup><a
href="/confluence/display/TAPESTRY/IoC"><img border='0' align='middle' src='/confluence/images/icons/up_16.gif'
width='8' height='8'></a></sup><a href="/confluence/display/TAPESTRY/IoC">IoC</a></td><td
width='33%' class='ScrollbarNextName'>&nbsp;<a href="/confluence/display/TAPESTRY/IoC+-+provider">IoC
- provider</a></td><td class='ScrollbarNextIcon'><a href="/confluence/display/TAPESTRY/IoC+-+provider"><img
border='0' align='middle' src='/confluence/images/icons/forwd_16.gif' width='16' height='16'></a></td></tr></table>!
 </div>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/TAPESTRY/Injection+in+Detail">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=23338482&revisedVersion=7&originalVersion=6">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message