tapestry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > Injection
Date Tue, 23 Nov 2010 21:26: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">Injection</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~ccordenier">Christophe
Cordenier</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Fix broken links<br />
    </div>
        <br/>
                         <h4>Changes (7)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-unchanged" >h1. Injection with Components <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >A key concept in Tapestry is the
use of _injection_. The <span class="diff-changed-words"><span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">[</span>Tapestry</span>
IoC <span class="diff-changed-words">container<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">|../../tapestry-ioc/index.html]</span></span>
makes use of one form of injection, via parameters to service builder methods. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>For components, Tapestry
takes a completely different tack: injection directly into instance variables. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Inject Annotation <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The [Inject <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">annotation|../apidocs/org/apache/tapestry5/ioc/annotations/Inject.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">annotation|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html]</span>
is used to identify fields that will contain injected services and other resources. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Tapestry allows for two
kinds of injection: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Asset Injection <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >When the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Path|../apidocs/org/apache/tapestry5/annotations/Path.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">[Path|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html]</span>
annotation is also present, then the injected value (relative to the component) will be a
localized [asset|#assets.html]. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Symbols in the annotation
value are expanded. <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. Block Injection <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >For field type <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Block|../apidocs/org/apache/tapestry5/Block.html],</span>
<span class="diff-added-words"style="background-color: #dfd;">[Block|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html],</span>
the value of the Inject annotation is the id of the [&lt;block&gt; element|#templates.html]
within the component&#39;s template. Normally, the id of the block is determined from
the field name (after stripping out leading &quot;_&quot; and &quot;$&quot;
characters). Where that is not appropriate, an <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Id|../apidocs/org/apache/tapestry5/annotations/Id.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">[Id|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html]</span>
annotation can be supplied: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code:java} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >For a particular set of field types,
Tapestry will inject a _resource_ related to the component, such as its Locale. <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >A very common example occurs when
a component needs access to its <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[resources|../apidocs/org/apache/tapestry5/ComponentResources.html].</span>
<span class="diff-added-words"style="background-color: #dfd;">[resources|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html].</span>
The component can define a field of the appropriate type and use the Inject annotation without
a value: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code:java} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > java.lang.String 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. java.util.Locale The locale for the component
(all components within a page use the same locale). org.slf4j.Logger A Logger instance configured
for the component, based on the component&#39;s class name. [SLF4J|http://www.slf4j.org/]
is a wrapper around Log4J or other logging toolkits. org.apache.tapestry5.ComponentResources
The resources for the component, often used to generate links related to the component. org.apache.tapestry5.ioc.Messages
The component message catalog for the component, from which [localized|#localization.html]
messages can be generated.h1. Explicit Service Injection <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Here, a specific object is requested.
A <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[Service|../apidocs/org/apache/tapestry5/annotations/Service.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">[Service|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html]</span>
annotation is used to identify the service name. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>Example: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h1. Defining New Injection Logic <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >Annonymous injection is controlled
by the <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">[InjectionProvider|../apidocs/org/apache/tapestry5/services/InjectionProvider.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">[InjectionProvider|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html]</span>
service. The configuration for this service is a [chain of <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">command|../../tapestry-ioc/command.html]</span>
<span class="diff-added-words"style="background-color: #dfd;">command|IoC - command]</span>
for handling component injections. <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Injection-InjectionwithComponents"></a>Injection with
Components</h1>

<p>A key concept in Tapestry is the use of <em>injection</em>. The Tapestry
IoC container makes use of one form of injection, via parameters to service builder methods.</p>

<p>For components, Tapestry takes a completely different tack: injection directly into
instance variables.</p>

<h1><a name="Injection-InjectAnnotation"></a>Inject Annotation</h1>

<p>The <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html"
class="external-link" rel="nofollow">Inject annotation</a> 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>Explicit injection, where the particular service to be injected is specified.</li>
	<li>Default injection, where Tapestry determines the object to inject into the field
based on its type.<br/>
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.</li>
</ul>


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

<h2><a name="Injection-AssetInjection"></a>Asset Injection</h2>

<p>When the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html"
class="external-link" rel="nofollow">Path</a> annotation is also present, then the
injected value (relative to the component) will be a localized <a href="#Injection-assets.html">asset</a>.</p>

<p>Symbols in the annotation value are expanded.</p>

<h2><a name="Injection-BlockInjection"></a>Block Injection</h2>

<p>For field type <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html"
class="external-link" rel="nofollow">Block</a>, the value of the Inject annotation
is the id of the <a href="#Injection-templates.html">&lt;block&gt; element</a>
within the component's template. Normally, the id of the block is determined from the field
name (after stripping out leading "_" and "$" characters). Where that is not appropriate,
an <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html"
class="external-link" rel="nofollow">Id</a> annotation can be supplied:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
  @Inject
  <span class="code-keyword">private</span> Block foo;
  
  @Inject
  @Id(<span class="code-quote">"bar"</span>)
  <span class="code-keyword">private</span> Block barBlock;
</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>

<h2><a name="Injection-ResourceInjection"></a>Resource Injection</h2>

<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 href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html"
class="external-link" rel="nofollow">resources</a>. The component can define a field
of the appropriate type and use the Inject annotation without a value:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Inject
<span class="code-keyword">private</span> ComponentResources resources;
</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>

<p> java.lang.String 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. java.util.Locale
The locale for the component (all components within a page use the same locale). org.slf4j.Logger
A Logger instance configured for the component, based on the component's class name. <a
href="http://www.slf4j.org/" class="external-link" rel="nofollow">SLF4J</a> is a
wrapper around Log4J or other logging toolkits. org.apache.tapestry5.ComponentResources The
resources for the component, often used to generate links related to the component. org.apache.tapestry5.ioc.Messages
The component message catalog for the component, from which <a href="#Injection-localization.html">localized</a>
messages can be generated.h1. Explicit Service Injection</p>

<p>Here, a specific object is requested. A <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html"
class="external-link" rel="nofollow">Service</a> annotation is used to identify the
service name.</p>

<p>Example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Inject
@Service(<span class="code-quote">"Request"</span>)
<span class="code-keyword">private</span> Request request;
</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
... if you rename the service interface and rename the service id to match, your existing
injections using the explicit service id will break.</p>

<h1><a name="Injection-DefaultInjection"></a>Default Injection</h1>

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

<h1><a name="Injection-DefiningNewInjectionLogic"></a>Defining New Injection
Logic</h1>

<p>Annonymous injection is controlled by the <a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html"
class="external-link" rel="nofollow">InjectionProvider</a> service. The configuration
for this service is a <a href="/confluence/display/TAPESTRY/IoC+-+command" title="IoC -
command">chain of command</a> for handling component injections.</p>

    </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">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=22872107&revisedVersion=2&originalVersion=1">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message