tapestry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Tapestry > IoC - symbols
Date Mon, 20 Sep 2010 08:38:01 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/IoC+-+symbols">IoC
- symbols</a></h2>
    <h4>Page  <b>added</b> by             <a href="https://cwiki.apache.org/confluence/display/~uli">Ulrich
Stärk</a>
    </h4>
         <br/>
    <div class="notificationGreySide">
         <h1><a name="IoC-symbols-Symbols"></a>Symbols</h1>

<p>Tapestry IOC makes use of runtime-evaluated <em>symbols</em> to handle
certains types of configuration tasks.</p>

<p>The syntax of symbols is based on Ant expression, that is, a leading <tt>$</tt>{
before the symbol name, and a trailing <tt>}</tt> after. The value on the inside
is the <em>symbol name</em>. By convention, the symbol name is segmented with
periods.</p>

<p>These symbols are used inside the <span class="error">&#91;Value|../apidocs/org/apache/tapestry5/ioc/annoations/Value.html&#93;</span>
and <span class="error">&#91;InjectService|../apidocs/org/apache/tapestry5/ioc/annoations/InjectService.html&#93;</span>
annotations.</p>

<p>For example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">  <span class="code-keyword">public</span> <span
class="code-keyword">static</span> MyService build(
      @InjectService(<span class="code-quote">"${some-service-id}"</span>) Collaborator
collab)
  {
    <span class="code-keyword">return</span> . . . ;
  }</pre>
</div></div>

<p>Here, the symbol, <tt>some-service-id</tt> is a service id, such as <tt>WackyCollaborator</tt>.</p>

<p>Although not shown here, it is possible to use multple symbols inside the string,
or mix literal text with symbols.</p>

<h1><a name="IoC-symbols-InjectingValuesfromSymbols"></a>Injecting Values
from Symbols</h1>

<p>You may also inject symbol values. For example, if you are interested in whether
the application is in production mode or developer mode:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyService
<span class="code-keyword">implements</span> MyServiceInterface
{
  <span class="code-keyword">private</span> <span class="code-object">boolean</span>
productionMode;

  <span class="code-keyword">public</span> MyService(@Value(<span class="code-quote">"${tapestry.production-mode}"</span>)
<span class="code-object">boolean</span> productionMode, ...)
  {
    <span class="code-keyword">this</span>.productionMode = productionMode;
    . . .</pre>
</div></div>

<p>Here Tapestry has <a href="#IoC-symbols-coerce.apt">coerced</a> the "tapestry.production-mode"
symbol to a boolean to be injected.</p>

<p>An alternate annotation, @Symbol, may be used:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"><span class="code-keyword">public</span> class MyService
<span class="code-keyword">implements</span> MyServiceInterface
{
  <span class="code-keyword">private</span> <span class="code-object">boolean</span>
productionMode;

  <span class="code-keyword">public</span> MyService(@Symbol(SymbolConstants.PRODUCTION_MODE)
<span class="code-object">boolean</span> productionMode, ...)
  {
    <span class="code-keyword">this</span>.productionMode = productionMode;
    . . .</pre>
</div></div>

<p>This is very useful when a constant value is defined for the symbol; it means that
the compiler can catch a typo, rather than detecting it a runtime.</p>

<p><b>Note:</b> When injecting a symbol as a <em>string</em>
into a service, you must use the @Inject annotation as well as @Value or @Symbol; otherwise
Tapestry will inject the service's service id.</p>

<h1><a name="IoC-symbols-SymbolResolution"></a>Symbol Resolution</h1>

<p>Symbols are resolved by the <span class="error">&#91;SymbolSource|../apidocs/org/apache/tapestry5/ioc/services/SymbolSource.html&#93;</span>
service. The SymbolSource checks against an ordered list of <span class="error">&#91;SymbolProvider|../apidocs/org/apache/tapestry5/ioc/services/SymbolProvider.html&#93;</span>
objects.</p>

<p>Additional symbol providers may be employed by contributing to the tapestry.ioc.SymbolSource
service configuration, which is an ordered list of SymbolProviders.</p>

<p>By default, there are three providers:</p>

<h2><a name="IoC-symbols-SystemProperties"></a>SystemProperties</h2>

<p>The first provider allows JVM System Properties to provide symbol values. This allows
the use of the <b>java</b> command's <b>-D</b> option to provide runtime
overrides. This is most often used when testing code, rather than in production. SystemProperties
is always checked first.</p>

<h2><a name="IoC-symbols-ApplicationDefaults"></a>ApplicationDefaults</h2>

<p>Values not found as System Properties are searched for in the ApplicationDefaults.
This service, ApplicationDefaults, may be configured using a mapped configuration to provide
values.</p>

<p>From the previous example:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">  <span class="code-keyword">public</span> void contributeApplicationDefaults(MappedConfiguration&lt;<span
class="code-object">String</span>, <span class="code-object">String</span>&gt;
configuration)
  {
    configuration.add(<span class="code-quote">"some-service-id"</span>, <span
class="code-quote">"WackyCollaborator"</span>);
  }</pre>
</div></div>

<h2><a name="IoC-symbols-FactoryDefaults"></a>FactoryDefaults</h2>

<p>The same as ApplicationDefaults, but checked only if a value is not satisfied by
SystemProperties or ApplicationDefaults.</p>

<p>Libraries will typically set reasonable defaults as contributions to the FactoryDefaults
service configuration. Individual applications may hard code overrides of those defaults using
ApplicationDefaults. Individual developers may override even those defaults by setting JVM
System Properties.</p>

<p>FactoryDefaults is always checked last when resolving symbol names to symbol values.</p>

<h1><a name="IoC-symbols-RecursiveSymbols"></a>Recursive Symbols</h1>

<p>It is possible and valid to define one symbol in terms of one ore more other symbols.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">  <span class="code-keyword">public</span> void contributeFactoryDefaults(MappedConfiguration&lt;<span
class="code-object">String</span>, <span class="code-object">String</span>&gt;
configuration)
  {
      configuration.add(<span class="code-quote">"report.url"</span>, <span
class="code-quote">"http:<span class="code-comment">//${report.host}:${report.port}/${report.path}"</span>);
</span>      configuration.add(<span class="code-quote">"report.host"</span>,
<span class="code-quote">"www.myreportsite.com"</span>);
      configuration.add(<span class="code-quote">"report.port"</span>, <span
class="code-quote">"80"</span>);
      configuration.add(<span class="code-quote">"report.path"</span>, <span
class="code-quote">"/report.cgi"</span>);
  }</pre>
</div></div>

<p>The ordinary default for <tt>report.url</tt> will be <tt><a
href="http://www.myreportsite.com:80/report.cgi" class="external-link" rel="nofollow">http://www.myreportsite.com:80/report.cgi</a></tt>.</p>

<p>However, this can be changed by making an overriding contribution to the ApplicationDefaults
service configuration.</p>

<p>Tapestry checks that no symbol is directly or indirectly dependent on itself. For
example, the following contribution is illegal:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">  <span class="code-keyword">public</span> void contributeApplicationDefaults(MappedConfiguration&lt;<span
class="code-object">String</span>, <span class="code-object">String</span>&gt;
configuration)
  {
      configuration.add(<span class="code-quote">"report.path"</span>, <span
class="code-quote">"${report.url}/report.cgi"</span>);
  }</pre>
</div></div>

<p>When the <tt>report.url</tt> is referenced, an exception will be thrown
with the message: * Symbol 'report.path' is defined in terms of itself (report.path --&gt;
report.url --&gt; report.path).*</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/IoC+-+symbols">View
Online</a>
           </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message