tapestry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bob Harner (Confluence)" <conflue...@apache.org>
Subject [CONF] Apache Tapestry > Injection
Date Sat, 12 Oct 2013 14:48:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/en/2176/1/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/~bobharner">Bob
Harner</a>
    </h4>
        <div id="versionComment">
        <b>Comment:</b>
        Minor layout issue<br />
    </div>
        <br/>
                         <h4>Changes (8)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >A large number of services are provided
by Tapestry. See the following packages: <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{float:left}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{float:left|width=12em}
<br></td></tr>
            <tr><td class="diff-unchanged" >* [Core Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html]
<br>* [AJAX Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html]
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{float} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{float:left}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{float:left|width=12em}
<br></td></tr>
            <tr><td class="diff-unchanged" >* [JavaScript Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html]
<br>* [Link Transformation Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html]
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{float} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{float:left}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{float:left|width=12em}
<br></td></tr>
            <tr><td class="diff-unchanged" >* [Page Loading Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html]
<br>* [Security Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html]
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{float} <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">{float:left}
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">{float:left|width=12em}
<br></td></tr>
            <tr><td class="diff-unchanged" >* [Tapestry IOC Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html]
<br>* [Tapestry IOC Cron Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html]
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Injection-Injection"></a>Injection</h1>

<p><b>Injection</b> is Tapestry's way of making a dependency &#8211;
such as a resource, asset, component, block or service &#8211; available in a page, component,
mixin or service class.</p>

<p>Injection is a key concept in Tapestry, and it is used in several different but related
ways.</p>

<div class='navmenu' style='float:right; background:#eee; margin:3px; padding:3px'><table
class="tableview" width="100%">
            <tr><th style="padding: 3px 3px 3px 0px">Related Articles</th></tr>
                        <tr>
            <td>
                                 <span class="icon icon-page" title="Page">Page:</span>
                         <a href="/confluence/display/TAPESTRY/Injection+FAQ">Injection
FAQ</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title="Page">Page:</span>
                         <a href="/confluence/display/TAPESTRY/Injection+in+Detail">Injection
in Detail</a>
        
                                            </td>
        </tr>
                <tr>
            <td>
                                 <span class="icon icon-page" title="Page">Page:</span>
                         <a href="/confluence/display/TAPESTRY/Injection">Injection</a>
        
                                            </td>
        </tr>
            </table>
</div>

<h2><a name="Injection-InjectioninTapestryIOCServices"></a>Injection in
Tapestry IOC Services</h2>

<p>Main Article: <a href="/confluence/display/TAPESTRY/Tapestry+IoC+Overview" title="Tapestry
IoC Overview">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><a name="Injection-InjectioninComponentClasses"></a>Injection in Component
Classes</h2>

<p>For components, however, Tapestry takes a completely different tack: injection directly
into component fields.</p>

<p>The @<a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html"
class="external-link" rel="nofollow">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><b>Default injection</b>, where Tapestry determines the object to inject
into the field based on its type.</li>
	<li><b>Explicit injection</b>, 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><a name="Injection-BlockInjection"></a>Block Injection</h3>

<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="/confluence/display/TAPESTRY/Component+Templates#ComponentTemplates-block">&lt;t:block&gt;</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>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
private Block foo;
</pre>
</div></div>

<p>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="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
@Id("bar")
private 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>

<h3><a name="Injection-ResourceInjection"></a>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 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 <tt>@Inject</tt> annotation without a value:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
private 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>

<ul>
	<li><b>java.lang.String</b> &#8211;  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><b>java.util.Locale</b> &#8211; The locale for the component (all
components within a page use the same locale).</li>
</ul>


<ul>
	<li><b>org.slf4j.Logger</b> &#8211; 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.</li>
</ul>


<ul>
	<li><b>org.apache.tapestry5.ComponentResources</b> &#8211; The resources
for the component, often used to generate links related to the component.</li>
</ul>


<ul>
	<li><b>org.apache.tapestry5.ioc.Messages</b> &#8211; The component
message catalog for the component, from which <a href="#Injection-localization.html">localized</a>
messages can be generated.</li>
</ul>


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

<p>Main Article: <a href="/confluence/display/TAPESTRY/Assets" title="Assets">Assets</a></p>

<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 asset.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
@Path("context:images/top_banner.png")
private Asset banner;
</pre>
</div></div>

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

<h3><a name="Injection-ServiceInjection"></a>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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
private EmployeeService employeeService;
</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:12em; background:white; margin:3px; padding:3px'><ul>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html"
class="external-link" rel="nofollow">Core Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html"
class="external-link" rel="nofollow">AJAX Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html"
class="external-link" rel="nofollow">Assets Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html"
class="external-link" rel="nofollow">Dynamic Component Services</a></li>
</ul>
</div>

<div class='navmenu' style='float:left; width:12em; background:white; margin:3px; padding:3px'><ul>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html"
class="external-link" rel="nofollow">JavaScript Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html"
class="external-link" rel="nofollow">Link Transformation Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html"
class="external-link" rel="nofollow">Message Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html"
class="external-link" rel="nofollow">Component Metadata Services</a></li>
</ul>
</div>

<div class='navmenu' style='float:left; width:12em; background:white; margin:3px; padding:3px'><ul>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html"
class="external-link" rel="nofollow">Page Loading Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html"
class="external-link" rel="nofollow">Security Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html"
class="external-link" rel="nofollow">Template Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html"
class="external-link" rel="nofollow">Class Transformation Services</a></li>
</ul>
</div>

<div class='navmenu' style='float:left; width:12em; background:white; margin:3px; padding:3px'><ul>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html"
class="external-link" rel="nofollow">Tapestry IOC Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html"
class="external-link" rel="nofollow">Tapestry IOC Cron Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html"
class="external-link" rel="nofollow">Kaptcha Services</a></li>
	<li><a href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html"
class="external-link" rel="nofollow">File Upload Services</a></li>
</ul>
</div>
<p><div style="clear:both"></div></p>

<h3><a name="Injection-ExplicitServiceInjection"></a>Explicit Service Injection</h3>

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

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="theme: Default; brush: java; gutter: false" style="font-size:12px; font-family:
ConfluenceInstalledFont,monospace;">
@Inject
@Service("Request")
private 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
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><a name="Injection-DefaultInjection"></a>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 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><a name="Injection-DefiningNewInjectionLogic"></a>Defining New Injection
Logic</h2>

<p>Anonymous 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/ChainBuilder+Service" title="ChainBuilder
Service">chain of command</a> for handling component injections.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;" class="grey">
                        <a href="https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=TAPESTRY">Stop
watching space</a>
            <span style="padding: 0px 5px;">|</span>
                <a href="https://cwiki.apache.org/confluence/users/editmyemailsettings.action">Change
email 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=11&originalVersion=10">View
Changes</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message