Modified: websites/production/tapestry/content/shadowbuilder-service.html ============================================================================== --- websites/production/tapestry/content/shadowbuilder-service.html (original) +++ websites/production/tapestry/content/shadowbuilder-service.html Sat Feb 3 17:21:22 2018 @@ -44,13 +44,26 @@ <div class="wrapper bs"> - <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div> + <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div> + +</div> <div id="top"> - <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> - <input type="text" name="q"> - <input type="submit" value="Search"> -</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">ShadowBuilder Service</h1></div></div> + <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span> +<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> + <input type="text" name="q"> + <input type="submit" value="Search"> +</form> + +</div> + + +<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div> + + +<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">ShadowBuilder Service</h1></div> + +</div> <div class="clearer"></div> </div> @@ -62,31 +75,58 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p>The <strong>ShadowBuilder service</strong> (see the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/PropertyShadowBuilder.html";>PropertyShadowBuilder</a> API) is used to build a special, delegating kind of service implementation that, essentially, allows a property of another service to be exposed as its own service.</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="shadowbuilder-service.html">ShadowBuilder Service</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="strategybuilder-service.html">StrategyBuilder Service</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="pipelinebuilder-service.html">PipelineBuilder Service</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="chainbuilder-service.html">ChainBuilder Service</a> - </div> </li></ul></div><p>For example, the tapestry-core module provides a Request property as a shadow of the RequestGlobals service's request property:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> + <div id="ConfluenceContent"><p>The <strong>ShadowBuilder service</strong> (see the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/PropertyShadowBuilder.html";>PropertyShadowBuilder</a> API) is used to build a special, delegating kind of service implementation that, essentially, allows a property of another service to be exposed as its own service.</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="shadowbuilder-service.html">ShadowBuilder Service</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="strategybuilder-service.html">StrategyBuilder Service</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="pipelinebuilder-service.html">PipelineBuilder Service</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="chainbuilder-service.html">ChainBuilder Service</a> + + + </div> + </li></ul> +</div> + + +<p>For example, the tapestry-core module provides a Request property as a shadow of the RequestGlobals service's request property:</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 Request build() { return shadowBuilder.build(requestGlobals, "request", Request.class);
Modified: websites/production/tapestry/content/starting-the-ioc-registry.html ============================================================================== --- websites/production/tapestry/content/starting-the-ioc-registry.html (original) +++ websites/production/tapestry/content/starting-the-ioc-registry.html Sat Feb 3 17:21:22 2018 @@ -91,7 +91,7 @@ registry.performRegistryStartup();</pre> <p> </p></div><p>As of version 5.2 the class <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html";>RegistryBuilder</a> has convenience methods to build and start a Registry. The static method <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/RegistryBuilder.html#buildAndStartupRegistry(java.lang.Class...)">RegistryBuilder.buildAndStartupRegistry(Class...)</a> constructs a registry, adds a number of modules to the registry and performs registry startup. The returned registry is ready to use.</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;">Registry registry = RegistryBuilder.buildAndStartupRegistry(AppModule.class, UtilModule.class); </pre> -</div></div><h1 id="StartingtheIoCRegistry-BuildingtheDefaultRegistry">Building the Default Registry</h1><p>The default registry is available by invoking the static method <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCUtilities.html#buildDefaultRegistry";>IOCUtilities.buildDefaultRegistry()</a>. This method builds a Registry using <a href="autoloading-modules.html">autoloading logic</a>, where modules to load are identified via a JAR Manifest entry.</p><p>In addition, the JVM system property <code>tapestry.modules</code> (if specified) is a list of additional module classes to load. This is often used in development, where tests may be executed against the local classes, not JARs, and so there is no manifest to read.</p><h1 id="StartingtheIoCRegistry-ShuttingdowntheRegistry">Shutting down the Registry</h1><p>The method <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Registry. html#shutdown">Registry.shutdown()</a> will shutdown the Registry. This immediately invalidates all service proxies. Some services may have chosen to register for shutdown notification (for example, to do cleanup work such as closing a database connection).</p><p>Once the Registry is shutdown, it may not be used again: it will not be possible to access services within the Registry, or invoke methods on services previously acquired. All you can do is release the Registry to the garbage collector.</p><p> </p><p></p></div> +</div></div><h1 id="StartingtheIoCRegistry-BuildingtheDefaultRegistry">Building the Default Registry</h1><p>The default registry is available by invoking the static method <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/IOCUtilities.html#buildDefaultRegistry";>IOCUtilities.buildDefaultRegistry()</a>. This method builds a Registry using <a href="starting-the-ioc-registry.html">autoloading logic</a>, where modules to load are identified via a JAR Manifest entry.</p><p>In addition, the JVM system property <code>tapestry.modules</code> (if specified) is a list of additional module classes to load. This is often used in development, where tests may be executed against the local classes, not JARs, and so there is no manifest to read.</p><h1 id="StartingtheIoCRegistry-ShuttingdowntheRegistry">Shutting down the Registry</h1><p>The method <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Reg istry.html#shutdown">Registry.shutdown()</a> will shutdown the Registry. This immediately invalidates all service proxies. Some services may have chosen to register for shutdown notification (for example, to do cleanup work such as closing a database connection).</p><p>Once the Registry is shutdown, it may not be used again: it will not be possible to access services within the Registry, or invoke methods on services previously acquired. All you can do is release the Registry to the garbage collector.</p><p> </p><p></p></div> </div> <div class="clearer"></div> Modified: websites/production/tapestry/content/strategybuilder-service.html ============================================================================== --- websites/production/tapestry/content/strategybuilder-service.html (original) +++ websites/production/tapestry/content/strategybuilder-service.html Sat Feb 3 17:21:22 2018 @@ -44,13 +44,26 @@ <div class="wrapper bs"> - <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div> + <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div> + +</div> <div id="top"> - <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> - <input type="text" name="q"> - <input type="submit" value="Search"> -</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">StrategyBuilder Service</h1></div></div> + <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span> +<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> + <input type="text" name="q"> + <input type="submit" value="Search"> +</form> + +</div> + + +<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div> + + +<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">StrategyBuilder Service</h1></div> + +</div> <div class="clearer"></div> </div> @@ -62,31 +75,58 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p>The <strong>StrategyBuilder Service</strong> provides a convenient way to create an implementation of the <a class="external-link" href="https://en.wikipedia.org/wiki/Strategy_pattern"; rel="nofollow">Strategy</a> design pattern.</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="shadowbuilder-service.html">ShadowBuilder Service</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="strategybuilder-service.html">StrategyBuilder Service</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="pipelinebuilder-service.html">PipelineBuilder Service</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="chainbuilder-service.html">ChainBuilder Service</a> - </div> </li></ul></div><p>Another of the Gang Of Four patterns, the strategy pattern as implemented in Tapestry IoC is a kind of late binding.</p><p>The idea is that <em>adapters</em> for objects are accessed based on the <em>actual type</em> of an object. These adapters supply additional functionality. The adapters are located using a StrategyRegistry (<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/StrategyRegistry.html";>API</a>).</p><p>The lookup of adapters is based on an inheritance search; thus providing an adapter for type java.util.Map will match any object that implements the Map interface. The inheritance search works its way up the class hierarchy looking for a matching registration. If nothing is found, then all the interfaces directly or indirectly implemented by the selector class are checked. java.lang.Object is always the final match.</p><p>A runtime exception is thrown if no match can be found.</p><p>As a sp ecial case, the value null is searched for as if it were an instance of the class void.</p><p>The StrategyBuilder service (<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/StrategyBuilder.html";>API</a>) creates a service implementation around a strategy registry.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> + <div id="ConfluenceContent"><p>The <strong>StrategyBuilder Service</strong> provides a convenient way to create an implementation of the <a class="external-link" href="https://en.wikipedia.org/wiki/Strategy_pattern"; rel="nofollow">Strategy</a> design pattern.</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="shadowbuilder-service.html">ShadowBuilder Service</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="strategybuilder-service.html">StrategyBuilder Service</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="pipelinebuilder-service.html">PipelineBuilder Service</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="chainbuilder-service.html">ChainBuilder Service</a> + + + </div> + </li></ul> +</div> + + +<p>Another of the Gang Of Four patterns, the strategy pattern as implemented in Tapestry IoC is a kind of late binding.</p><p>The idea is that <em>adapters</em> for objects are accessed based on the <em>actual type</em> of an object. These adapters supply additional functionality. The adapters are located using a StrategyRegistry (<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/StrategyRegistry.html";>API</a>).</p><p>The lookup of adapters is based on an inheritance search; thus providing an adapter for type java.util.Map will match any object that implements the Map interface. The inheritance search works its way up the class hierarchy looking for a matching registration. If nothing is found, then all the interfaces directly or indirectly implemented by the selector class are checked. java.lang.Object is always the final match.</p><p>A runtime exception is thrown if no match can be found.</p><p>As a special case, the value nul l is searched for as if it were an instance of the class void.</p><p>The StrategyBuilder service (<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/StrategyBuilder.html";>API</a>) creates a service implementation around a strategy registry.</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 interface StrategyBuilder { <S> S build(StrategyRegistry<S> registry); Modified: websites/production/tapestry/content/symbols.html ============================================================================== --- websites/production/tapestry/content/symbols.html (original) +++ websites/production/tapestry/content/symbols.html Sat Feb 3 17:21:22 2018 @@ -44,13 +44,26 @@ <div class="wrapper bs"> - <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div> + <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div> + +</div> <div id="top"> - <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> - <input type="text" name="q"> - <input type="submit" value="Search"> -</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Symbols</h1></div></div> + <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span> +<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> + <input type="text" name="q"> + <input type="submit" value="Search"> +</form> + +</div> + + +<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div> + + +<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Symbols</h1></div> + +</div> <div class="clearer"></div> </div> @@ -62,46 +75,79 @@ </div> <div id="content"> - <div id="ConfluenceContent"><p><strong>Symbols</strong> are named configuration settings for Tapestry IOC-based services. Tapestry provides mechanisms for easy access to symbols from within such services.</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="application-module-class-cheat-sheet.html">Application Module Class Cheat Sheet</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="ioc-cookbook-service-configurations.html">IoC cookbook - Service Configurations</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="symbols.html">Symbols</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="tapestry-ioc-configuration.html">Tapestry IoC Configuration</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="response-compression.html">Response Compression</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="configuration.html">Configuration</a> - </div> </li></ul></div><h2 id="Symbols-Syntax">Syntax</h2><p>The syntax of symbols is based on Ant expressions. That is, the name is surrounded by ${ and } characters:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> + <div id="ConfluenceContent"><p><strong>Symbols</strong> are named configuration settings for Tapestry IOC-based services. Tapestry provides mechanisms for easy access to symbols from within such services.</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="application-module-class-cheat-sheet.html">Application Module Class Cheat Sheet</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="ioc-cookbook-service-configurations.html">IoC cookbook - Service Configurations</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="symbols.html">Symbols</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="tapestry-ioc-configuration.html">Tapestry IoC Configuration</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="response-compression.html">Response Compression</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="configuration.html">Configuration</a> + + + </div> + </li></ul> +</div> + + +<h2 id="Symbols-Syntax">Syntax</h2><p>The syntax of symbols is based on Ant expressions. That is, the name is surrounded by ${ 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;">${some.symbol.name} </pre> -</div></div><p>The value on the inside is the <em>symbol name</em>. By convention, the symbol name is segmented with periods (for example, "tapestry.production-mode").</p><h2 id="Symbols-Built-inSymbols">Built-in Symbols</h2><p>The <a href="configuration.html">Configuration</a> page lists the symbol names used by Tapestry's built-in services.</p><h2 id="Symbols-UsingSymbolsinyourServices">Using Symbols in your Services</h2><p>Symbols are used inside the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Value</a> and @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html";>InjectService</a> annotations.</p><p>For example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>The value on the inside is the <em>symbol name</em>. By convention, the symbol name is segmented with periods (for example, "tapestry.production-mode").</p><h2 id="Symbols-Built-inSymbols">Built-in Symbols</h2><p>The <a href="symbols.html">Symbols</a> page lists the symbol names used by Tapestry's built-in services.</p><h2 id="Symbols-UsingSymbolsinyourServices">Using Symbols in your Services</h2><p>Symbols are used inside the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Value</a> and @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html";>InjectService</a> annotations.</p><p>For example:</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 static MyService build( @InjectService("${some-service-id}") Collaborator collab) { @@ -115,7 +161,7 @@ if (productionMode) { . . . </pre> -</div></div><p>Here Tapestry has <a href="type-coercion.html">coerced</a> the "tapestry.production-mode" symbol to a boolean to be injected.</p><p>As an alternative, the @Symbol annotation, may be used:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>Here Tapestry has <a href="symbols.html">coerced</a> the "tapestry.production-mode" symbol to a boolean to be injected.</p><p>As an alternative, the @Symbol annotation, may be used:</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 MyService implements MyServiceInterface { public MyService(@Symbol(SymbolConstants.PRODUCTION_MODE) boolean productionMode, ...) Modified: websites/production/tapestry/content/tapestry-ioc-configuration.html ============================================================================== --- websites/production/tapestry/content/tapestry-ioc-configuration.html (original) +++ websites/production/tapestry/content/tapestry-ioc-configuration.html Sat Feb 3 17:21:22 2018 @@ -144,7 +144,7 @@ </div> -<p>One of the key concepts in Tapestry IoC is <em>distributed configuration</em>. The <em>distributed</em> part refers to the fact that <em>any module</em> may configure a service. Distributed configuration is the key feature of Tapestry IoC that supports extensibility and modularity.</p><p>Modules configure a service by <em>contributing</em> to service configurations. This may seem esoteric but is really pretty simple. We'll explain with an example.</p><p>Let's say you've written a bunch of different services, each of which does something specific for a particular type of file (identified by the file's extension), and each implements the same interface, which we'll call FileServicer. And now let's say you need a central service that selects the one of your FileServicer implementations based on a given file extension. You start by providing a <a href="defining-tapestry-ioc-services.html">service builder method</a>:</p><div class="code panel pdl" style="border-width: 1px;"><div clas s="codeContent panelContent pdl"> +<p>One of the key concepts in Tapestry IoC is <em>distributed configuration</em>. The <em>distributed</em> part refers to the fact that <em>any module</em> may configure a service. Distributed configuration is the key feature of Tapestry IoC that supports extensibility and modularity.</p><p>Modules configure a service by <em>contributing</em> to service configurations. This may seem esoteric but is really pretty simple. We'll explain with an example.</p><p>Let's say you've written a bunch of different services, each of which does something specific for a particular type of file (identified by the file's extension), and each implements the same interface, which we'll call FileServicer. And now let's say you need a central service that selects the one of your FileServicer implementations based on a given file extension. You start by providing a <a href="tapestry-ioc-configuration.html">service builder method</a>:</p><div class="code panel pdl" style="border-width: 1px;"><div class="c odeContent panelContent pdl"> <pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public static FileServiceDispatcher buildFileServicerDispatcher(Map<String,FileServicer> contributions) { return new FileServiceDispatcherImpl(contributions); @@ -155,7 +155,7 @@ configuration.add("txt", new TextFileServicer()); configuration.add("pdf", new PDFFileServicer()); } </pre> -</div></div><p>Or, instead of instantiating those services ourselves, we could <a href="injection-in-detail.html">inject</a> them:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>Or, instead of instantiating those services ourselves, we could <a href="tapestry-ioc-configuration.html">inject</a> them:</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 static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration, @InjectService("TextFileServicer") FileServicer textFileServicer, @@ -219,7 +219,7 @@ public static void arbitraryMethodName(M configuration.add(new JMSStartup()); configuration.add(new FileSystemStartup()); } </pre> -</div></div><p>The Configuration interface defines just a single method: <code>add()</code>. This is very intentional: the only thing you can do is add new items. If we passed in a Collection, you might be tempted to check it for values, or remove them ... but that flies in the face of the fact that the order of execution of these service contribution methods is entirely unknown.</p><p>For readability, we've parameterized the configuration parameter of the method, constraining it to instances of java.lang.Runnable, so as to match the corresponding parameter. This is optional, but often very helpful. In any case, attempting to contribute an object that doesn't extend or implement the type (Runnable) will result in a runtime warning (and the value will be ignored).</p><p>Tapestry supports only this simple form of parameterized types. Java generics supports a wider form, "wildcards", that Tapestry doesn't understand.</p><p><span class="confluence-anchor-link" id="TapestryIoCConfigurati on-Ordered_List"></span></p><h2 id="TapestryIoCConfiguration-OrderedList">Ordered List</h2><p>Ordered lists are much more common. With an ordered list, the contributions are sorted into a proper order before being provided to the service builder method.</p><p>Again, the order in which service contribution methods are invoked is unknown. Therefore, the order in which objects are added to the configuration is not known. Instead, we enforce an order on the items <em>after</em> all the contributions have been added. As with <a href="tapestry-ioc-decorators.html">service decorators</a>, we set the order by giving each contributed object a unique id, and identifying (by id) which items must preceded it in the list, and which must follow.</p><p>So, if we changed our Startup service to require a specific order for startup:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>The Configuration interface defines just a single method: <code>add()</code>. This is very intentional: the only thing you can do is add new items. If we passed in a Collection, you might be tempted to check it for values, or remove them ... but that flies in the face of the fact that the order of execution of these service contribution methods is entirely unknown.</p><p>For readability, we've parameterized the configuration parameter of the method, constraining it to instances of java.lang.Runnable, so as to match the corresponding parameter. This is optional, but often very helpful. In any case, attempting to contribute an object that doesn't extend or implement the type (Runnable) will result in a runtime warning (and the value will be ignored).</p><p>Tapestry supports only this simple form of parameterized types. Java generics supports a wider form, "wildcards", that Tapestry doesn't understand.</p><p><span class="confluence-anchor-link" id="TapestryIoCConfigurati on-Ordered_List"></span></p><h2 id="TapestryIoCConfiguration-OrderedList">Ordered List</h2><p>Ordered lists are much more common. With an ordered list, the contributions are sorted into a proper order before being provided to the service builder method.</p><p>Again, the order in which service contribution methods are invoked is unknown. Therefore, the order in which objects are added to the configuration is not known. Instead, we enforce an order on the items <em>after</em> all the contributions have been added. As with <a href="tapestry-ioc-configuration.html">service decorators</a>, we set the order by giving each contributed object a unique id, and identifying (by id) which items must preceded it in the list, and which must follow.</p><p>So, if we changed our Startup service to require a specific order for startup:</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 static Runnable buildStartup(final List<Runnable> configuration) { return new Runnable() @@ -237,7 +237,7 @@ public static void arbitraryMethodName(M configuration.add("JMS", new JMSStartup()); configuration.add("FileSystem", new FileSystemStartup(), "after:CacheSetup"); } </pre> -</div></div><p>Often, you don't care about ordering; the first form of the add method is used then. The ordering algorithm will find a spot for the object (here the JMSStartup instance) based on the constraints of other contributed objects.</p><p>For the "FileSystem" contribution, a constraint has been specified, indicating that FileSystem should be ordered after some other contribution named "CacheSetup". Any number of such <a href="ordering-by-constraints.html">ordering constraints</a> may be specified (the <code>add()</code> method accepts a variable number of arguments).</p><p>The object passed in may be null; this is valid, and is considered a "join point": points of reference in the list that don't actually have any meaning of their own, but can be used when ordering other elements. <em>TODO: Show example for chain of command, once that's put together.</em></p><p>Null values, once ordered, are edited out (the List passed to the service builder method does not include any null s). Again, they are allowed as placeholders, for the actual contributed objects to organize themselves around. +</div></div><p>Often, you don't care about ordering; the first form of the add method is used then. The ordering algorithm will find a spot for the object (here the JMSStartup instance) based on the constraints of other contributed objects.</p><p>For the "FileSystem" contribution, a constraint has been specified, indicating that FileSystem should be ordered after some other contribution named "CacheSetup". Any number of such <a href="tapestry-ioc-configuration.html">ordering constraints</a> may be specified (the <code>add()</code> method accepts a variable number of arguments).</p><p>The object passed in may be null; this is valid, and is considered a "join point": points of reference in the list that don't actually have any meaning of their own, but can be used when ordering other elements. <em>TODO: Show example for chain of command, once that's put together.</em></p><p>Null values, once ordered, are edited out (the List passed to the service builder method does not include any n ulls). Again, they are allowed as placeholders, for the actual contributed objects to organize themselves around. </p><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/tapestry-ioc-decorators.html ============================================================================== --- websites/production/tapestry/content/tapestry-ioc-decorators.html (original) +++ websites/production/tapestry/content/tapestry-ioc-decorators.html Sat Feb 3 17:21:22 2018 @@ -75,7 +75,7 @@ </div> <div id="content"> - <div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Starting with Tapestry 5.1, Service Decoration is augmented with <a href="service-advisors.html">Service Advice</a>. Advisors are similar but more general, as they work on any service interface, which doesn't have to be known at build time. Decoration is used when the type of the service being decorated <em>is</em> known at build time, and involves supplying a new implementation of the service interface.</p></div></div><p><em>Decoration</em> is the name of a popular design pattern. Using decoration, an existing object's behavior can be extended without changing the implementation of the object.</p><p>Instead, a new object is placed <em>around</em> the existing object. The rest of the world sees this new object, t ermed an <strong>interceptor</strong>. The interceptor implements the same interface as the underlying object being decorated.</p><p>A common example for this is the Java I/O library. The abstract InputStream base class has a very simple API for reading bytes from a stream (and a few other things). Subclasses of InputStream provide a wide array of other options such as buffering, encryption or decryption, as well as control over the source of data read by the stream. All of these <em>concerns</em> are encapsulated in different implementations of InputStream, and all can be connected together in a kind of pipeline, using the common InputStream API.</p><p>Tapestry IoC uses a similar approach, where one or more interceptor objects, all implementing the service interface, are strung together. The service's proxy (responsible for just-in-time instantiation of the service implementation) is at one end of this pipeline, the core service implementation is at the other.</p><p>For each method in the service interface, the interceptor object can perform some operations before and after re-invoking the same method on the core service implementation. This is another design pattern: <em>delegation</em>. An interceptor can even catch exceptions thrown by the underlying implementation and react to them. A sufficiently clever interceptor could retry a method if an exception is thrown, or could "soften" a checked exception by wrapping it in a RuntimeException.</p><p>Decorators often are used in the context of <em>cross-cutting concerns</em>, such as logging or transaction management. This approach is a kind of <em>aspect oriented design</em>.</p><p>One such cross cutting concern is lazy initialization of services. In Apache HiveMind, services are created only as needed, when a method of a service interface is first invoked. This concern is supplied by the Tapestry IoC framework itself, but similar concerns are easily implemented as decorations.</p><p>Whereas the popular AspectJ framework changes the compiled bytecode of your classes (it calls the process "weaving"), with Tapestry IoC, the approach is to wrap your existing classes in new objects. These wrapper objects are often dynamically created at runtime.</p><p>It is also common to have <em>multiple</em> decorations on a single service. In this case, a whole stack of interceptor objects will be created, each delegating to the next. Tapestry IoC provides control over the order in which such decorations occur.</p><p>Decorations are driven by service decoration methods. Often, a reusable service exists to do the grunt work of creating and instantiating a new class.</p><h1 id="TapestryIoCDecorators-ServiceDecorationMethods">Service Decoration Methods</h1><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> + <div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-information"><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Starting with Tapestry 5.1, Service Decoration is augmented with <a href="tapestry-ioc-decorators.html">Service Advice</a>. Advisors are similar but more general, as they work on any service interface, which doesn't have to be known at build time. Decoration is used when the type of the service being decorated <em>is</em> known at build time, and involves supplying a new implementation of the service interface.</p></div></div><p><em>Decoration</em> is the name of a popular design pattern. Using decoration, an existing object's behavior can be extended without changing the implementation of the object.</p><p>Instead, a new object is placed <em>around</em> the existing object. The rest of the world sees this new ob ject, termed an <strong>interceptor</strong>. The interceptor implements the same interface as the underlying object being decorated.</p><p>A common example for this is the Java I/O library. The abstract InputStream base class has a very simple API for reading bytes from a stream (and a few other things). Subclasses of InputStream provide a wide array of other options such as buffering, encryption or decryption, as well as control over the source of data read by the stream. All of these <em>concerns</em> are encapsulated in different implementations of InputStream, and all can be connected together in a kind of pipeline, using the common InputStream API.</p><p>Tapestry IoC uses a similar approach, where one or more interceptor objects, all implementing the service interface, are strung together. The service's proxy (responsible for just-in-time instantiation of the service implementation) is at one end of this pipeline, the core service implementation is at the other.</p><p>For each method in the service interface, the interceptor object can perform some operations before and after re-invoking the same method on the core service implementation. This is another design pattern: <em>delegation</em>. An interceptor can even catch exceptions thrown by the underlying implementation and react to them. A sufficiently clever interceptor could retry a method if an exception is thrown, or could "soften" a checked exception by wrapping it in a RuntimeException.</p><p>Decorators often are used in the context of <em>cross-cutting concerns</em>, such as logging or transaction management. This approach is a kind of <em>aspect oriented design</em>.</p><p>One such cross cutting concern is lazy initialization of services. In Apache HiveMind, services are created only as needed, when a method of a service interface is first invoked. This concern is supplied by the Tapestry IoC framework itself, but similar concerns are easily implemented as decorations.</p><p>Whereas the popular AspectJ framework changes the compiled bytecode of your classes (it calls the process "weaving"), with Tapestry IoC, the approach is to wrap your existing classes in new objects. These wrapper objects are often dynamically created at runtime.</p><p>It is also common to have <em>multiple</em> decorations on a single service. In this case, a whole stack of interceptor objects will be created, each delegating to the next. Tapestry IoC provides control over the order in which such decorations occur.</p><p>Decorations are driven by service decoration methods. Often, a reusable service exists to do the grunt work of creating and instantiating a new class.</p><h1 id="TapestryIoCDecorators-ServiceDecorationMethods">Service Decoration Methods</h1><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;">package org.example.myapp.services; import org.apache.tapestry5.ioc.services.LoggingDecorator; @@ -122,7 +122,7 @@ public class MyAppModule { return decorator.build(serviceInterface, delegate, serviceId, logger); } </pre> -</div></div><p>You can use multiple patterns with @Match, in which case, the decorator will be applied to a service that matches <em>any</em> of the patterns. For instance, if you only wanted logging for your data access and business logic services, you might end up with <code>@Match("Data*", "*Logic")</code> (based, of course, on how you name your services).</p><p>As the preceding example showed, a simple "glob" matching is supported, where a asterisk ('*') may be used at the start or end of the match string to match any number of characters. As elsewhere, matching is case insensitive.</p><p>Thus, <code>@Match("*")</code> is dangerous, because it will match every service in every module.</p><p><em>Note: It is not possible to decorate the services of the TapestryIOCModule.</em></p><p><em>Note: Another idea will be other ways of matching services: base on inheritance of the service interface and/or based on the presence of particular class annotations on the service interface. None o f this has been implemented yet, and can readily be accomplished inside the decorator method (which will return null if it decides the service doesn't need decoration).</em></p><h1 id="TapestryIoCDecorators-OrderingofDecorators">Ordering of Decorators</h1><p>In cases where multiple decorators will apply to a single service, you can control the order in which decorators are applied using an additional annotation: @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Order.html";>Order</a>.</p><p>This annotation allows any number of <a href="ordering-by-constraints.html">ordering constraints</a> to be specified for the decorator, to order it relative to any other decorators.</p><p>For example, you almost always want logging decorators to come first, so:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>You can use multiple patterns with @Match, in which case, the decorator will be applied to a service that matches <em>any</em> of the patterns. For instance, if you only wanted logging for your data access and business logic services, you might end up with <code>@Match("Data*", "*Logic")</code> (based, of course, on how you name your services).</p><p>As the preceding example showed, a simple "glob" matching is supported, where a asterisk ('*') may be used at the start or end of the match string to match any number of characters. As elsewhere, matching is case insensitive.</p><p>Thus, <code>@Match("*")</code> is dangerous, because it will match every service in every module.</p><p><em>Note: It is not possible to decorate the services of the TapestryIOCModule.</em></p><p><em>Note: Another idea will be other ways of matching services: base on inheritance of the service interface and/or based on the presence of particular class annotations on the service interface. None o f this has been implemented yet, and can readily be accomplished inside the decorator method (which will return null if it decides the service doesn't need decoration).</em></p><h1 id="TapestryIoCDecorators-OrderingofDecorators">Ordering of Decorators</h1><p>In cases where multiple decorators will apply to a single service, you can control the order in which decorators are applied using an additional annotation: @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Order.html";>Order</a>.</p><p>This annotation allows any number of <a href="tapestry-ioc-decorators.html">ordering constraints</a> to be specified for the decorator, to order it relative to any other decorators.</p><p>For example, you almost always want logging decorators to come first, so:</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;"> @Match("*") @Order("before:*") public static <T> T decorateLogging(Class<T> serviceInterface, T delegate, Modified: websites/production/tapestry/content/tapestry-ioc-modules.html ============================================================================== --- websites/production/tapestry/content/tapestry-ioc-modules.html (original) +++ websites/production/tapestry/content/tapestry-ioc-modules.html Sat Feb 3 17:21:22 2018 @@ -44,13 +44,26 @@ <div class="wrapper bs"> - <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div></div> + <div id="navigation"><div class="nav"><ul class="alternate"><li><a href="index.html">Home</a></li><li><a href="getting-started.html">Getting Started</a></li><li><a href="documentation.html">Documentation</a></li><li><a href="download.html">Download</a></li><li><a href="about.html">About</a></li><li><a class="external-link" href="http://www.apache.org/licenses/LICENSE-2.0";>License</a></li><li><a href="community.html">Community</a></li><li><a class="external-link" href="http://www.apache.org/security/";>Security</a></li><li><a class="external-link" href="http://www.apache.org/";>Apache</a></li><li><a class="external-link" href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li><li><a class="external-link" href="http://www.apache.org/foundation/thanks.html";>Thanks</a></li></ul></div> + +</div> <div id="top"> - <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span><form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> - <input type="text" name="q"> - <input type="submit" value="Search"> -</form></div><div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div><div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Tapestry IoC Modules</h1></div></div> + <div id="smallbanner"><div class="searchbox" style="float:right;margin: .3em 1em .1em 1em"><span style="color: #999; font-size: 90%">Tapestry docs, issues, wikis & blogs:</span> +<form enctype="application/x-www-form-urlencoded" method="get" action="http://tapestry.apache.org/search.html";> + <input type="text" name="q"> + <input type="submit" value="Search"> +</form> + +</div> + + +<div class="emblem" style="float:left"><p><a href="index.html"><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image confluence-external-resource" src="http://tapestry.apache.org/images/tapestry_small.png"; data-image-src="http://tapestry.apache.org/images/tapestry_small.png";></span></a></p></div> + + +<div class="title" style="float:left; margin: 0 0 0 3em"><h1 id="SmallBanner-PageTitle">Tapestry IoC Modules</h1></div> + +</div> <div class="clearer"></div> </div> @@ -72,7 +85,7 @@ public class MyAppModule return new IndexerImpl(); } }</pre> -</div></div><p>Any public method (static or instance) whose name starts with "build" is a service builder method, implicitly defining a service within the module.</p><p>Here we're defining a service around the Indexer service interface (presumably also in the org.example.myapp.services package).</p><p>Every service has a unique id, used to identify it throughout the Registry of services (the Registry is the combined sum of all services from all modules). If you don't provide an explicit service id, as in this example, the service id is drawn from the return type; this service has an id of "Indexer".</p><p>You can give a service an explicit id by adding it to the method name: buildIndexer(). This is useful when you do not want the service id to match the service interface name (for example, when you have different services that implement the same interface), or when you need to avoid name collisions on the method name (Java allows only a single method with a given name and set of par ameters, even if the return types are different, so if you have two different service builder methods that take the same parameters, you should give them explicit service ids in the method name).</p><p>Tapestry IoC is <a href="case-insensitivity.html">case insensitive</a>; later we can refer to this service as "indexer" or "INDEXER" or any variation thereof, and connect to this service.</p><p>Service ids must be unique; if another module contributes a service with the id "Indexer" (or any case variation thereof) a runtime exception will occur when the Registry is created.</p><p>We could extend this example by adding additional service builder methods, or by showing how to inject dependencies. See <a href="defining-tapestry-ioc-services.html">the service documentation</a> for more details.</p><h1 id="TapestryIoCModules-AutobuildingServices">Autobuilding Services</h1><p>Main article: <a href="defining-tapestry-ioc-services.html">Defining Tapestry IOC Services</a></p><p>An alternate , and usually preferred, way to define a service is via a module's bind() method. The previous example can be rewritten as:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>Any public method (static or instance) whose name starts with "build" is a service builder method, implicitly defining a service within the module.</p><p>Here we're defining a service around the Indexer service interface (presumably also in the org.example.myapp.services package).</p><p>Every service has a unique id, used to identify it throughout the Registry of services (the Registry is the combined sum of all services from all modules). If you don't provide an explicit service id, as in this example, the service id is drawn from the return type; this service has an id of "Indexer".</p><p>You can give a service an explicit id by adding it to the method name: buildIndexer(). This is useful when you do not want the service id to match the service interface name (for example, when you have different services that implement the same interface), or when you need to avoid name collisions on the method name (Java allows only a single method with a given name and set of par ameters, even if the return types are different, so if you have two different service builder methods that take the same parameters, you should give them explicit service ids in the method name).</p><p>Tapestry IoC is <a href="tapestry-ioc-modules.html">case insensitive</a>; later we can refer to this service as "indexer" or "INDEXER" or any variation thereof, and connect to this service.</p><p>Service ids must be unique; if another module contributes a service with the id "Indexer" (or any case variation thereof) a runtime exception will occur when the Registry is created.</p><p>We could extend this example by adding additional service builder methods, or by showing how to inject dependencies. See <a href="tapestry-ioc-modules.html">the service documentation</a> for more details.</p><h1 id="TapestryIoCModules-AutobuildingServices">Autobuilding Services</h1><p>Main article: <a href="tapestry-ioc-modules.html">Tapestry IoC Modules</a></p><p>An alternate, and usually preferred, way to define a service is via a module's bind() method. The previous example can be rewritten as:</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;">package org.example.myapp.services; import org.apache.tapestry5.ioc.ServiceBinder; @@ -84,7 +97,7 @@ public class MyAppModule binder.bind(Indexer.class, IndexerImpl.class); } }</pre> -</div></div><p>For more details, see see <a href="defining-tapestry-ioc-services.html">Defining Tapestry IOC Services</a>. In most cases, autobuilding is the <em>preferred</em> approach.</p><p>Generally speaking, you should always bind and autobuild your services. The only exceptions are when:</p><ul><li>You wish to do more than just instantiate a class; for example, to register the class as an event listener with some other service.</li><li>There is <em>no implementation class</em>; in some cases, you can create your implementation on the fly using JDK dynamic proxies or bytecode generation.</li></ul><p>The bind() method must be static; an exception is thrown if the bind() method exists but is an instance method.</p><h1 id="TapestryIoCModules-Cacheing_ServicesCachingServices"><span class="confluence-anchor-link" id="TapestryIoCModules-Cacheing_Services"></span>Caching Services</h1><p>You will occasionally find yourself in the position of injecting the same services into your servi ce builder or service decorator methods repeatedly (this occurs much less often since the introduction of service autobuilding). This can result in quite a bit of redundant typing. Less code is better code, so as an alternative, you may define a <em>constructor</em> for your module that accepts annotated parameters (as with <a href="defining-tapestry-ioc-services.html">service builder injection</a>).</p><p>This gives you a chance to store common services in instance variables for later use inside service builder methods.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>For more details, see see <a href="tapestry-ioc-modules.html">Tapestry IoC Modules</a>. In most cases, autobuilding is the <em>preferred</em> approach.</p><p>Generally speaking, you should always bind and autobuild your services. The only exceptions are when:</p><ul><li>You wish to do more than just instantiate a class; for example, to register the class as an event listener with some other service.</li><li>There is <em>no implementation class</em>; in some cases, you can create your implementation on the fly using JDK dynamic proxies or bytecode generation.</li></ul><p>The bind() method must be static; an exception is thrown if the bind() method exists but is an instance method.</p><h1 id="TapestryIoCModules-Cacheing_ServicesCachingServices"><span class="confluence-anchor-link" id="TapestryIoCModules-Cacheing_Services"></span>Caching Services</h1><p>You will occasionally find yourself in the position of injecting the same services into your service builder or servic e decorator methods repeatedly (this occurs much less often since the introduction of service autobuilding). This can result in quite a bit of redundant typing. Less code is better code, so as an alternative, you may define a <em>constructor</em> for your module that accepts annotated parameters (as with <a href="tapestry-ioc-modules.html">service builder injection</a>).</p><p>This gives you a chance to store common services in instance variables for later use inside service builder methods.</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 MyModule { private final JobScheduler scheduler; @@ -105,7 +118,7 @@ public class MyAppModule return indexer; } }</pre> -</div></div><p>Notice that we've switched from <em>static</em> methods to <em>instance</em> methods. Since the builder methods are not static, the MyModule class will be instantiated so that the methods may be invoked. The constructor receives two common dependencies, which are stored into instance fields that may later be used inside service builder methods such as buildIndexer().</p><p>This approach is far from required; all the builder methods of your module can be static if you wish. It is used when you have many common dependencies and wish to avoid defining those dependencies as parameters to multiple methods.</p><p>Tapestry IoC automatically resolves the parameter type (JobScheduler and FileSystem, in the example) to the corresponding services that implement that type. When there's more than one service that implements the service interface, you'll get an error (but additional annotations and configuration can be used to ensure the correct service injected).</p><p>For modules , there are two additional parameter types that are used to refer to <em>resources</em> that can be provided to the module instance (rather than <em>services</em> which may be injected).</p><ul><li><a class="external-link" href="http://www.slf4j.org/api/org/slf4j/Logger.html"; rel="nofollow">org.slf4j.Logger</a>: logger for the module (derived from the module's class name)</li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>: access to other services<br clear="none"> Note that the fields are final: this is important. Tapestry IoC is thread-safe and you largely never have to think about concurrency issues. But in a busy application, different services may be built by different threads simultaneously. Each module class is a singleton, instantiated at most once, and making these fields final ensures that the values are available across multiple threads. Refer to Brian Goetz's <a class="externa l-link" href="http://www.javaconcurrencyinpractice.com/"; rel="nofollow">Java Concurrency in Practice</a> for a more complete explanation of the relationship between final fields, constructors, and threads ... or just trust us!</li></ul><p>Care should be taken with this approach: in some circumstances, you may force a situation in which the module constructor is dependent on itself. For example, if you invoke a method on any injected services defined within the same module from the module class' constructor, then the service implementation will be needed. Creating service implementations requires the module builder instance ... that's a recursive reference.</p><p>Tapestry detects these scenarios and throws a runtime exception to prevent an endless loop.</p><h1 id="TapestryIoCModules-ModuleClassImplementationNotes">Module Class Implementation Notes</h1><p>Module classes are designed to be very, very simple to implement.</p><p>Again, keep the methods very simple. Use <a href="defining -tapestry-ioc-services.html">parameter injection</a> to gain access to the dependencies you need.</p><p>Be careful about inheritance. Tapestry will see all <em>public</em> methods, even those inherited from base classes. Tapestry <em>only</em> sees public methods.</p><p>By convention, module class names end in Module and are final classes.</p><p>You don't <em>have</em> to define your methods as static. The use of static methods is only absolutely necessary in a few cases, where the constructor for a module is dependent on contributions from the same module (this creates a chicken-and-the-egg situation that is resolved through static methods).</p><h1 id="TapestryIoCModules-DefaultMarker">Default Marker</h1><p>Services are often referenced by a particular marker interface on the method or constructor parameter. Tapestry will use the intersection of services with that exact marker and assignable by type to find a unique service to inject.</p><p>Often, all services in a module should sh are a marker, this can be specified with a @Marker annotation on the module class. For example, the TapestryIOCModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl"> +</div></div><p>Notice that we've switched from <em>static</em> methods to <em>instance</em> methods. Since the builder methods are not static, the MyModule class will be instantiated so that the methods may be invoked. The constructor receives two common dependencies, which are stored into instance fields that may later be used inside service builder methods such as buildIndexer().</p><p>This approach is far from required; all the builder methods of your module can be static if you wish. It is used when you have many common dependencies and wish to avoid defining those dependencies as parameters to multiple methods.</p><p>Tapestry IoC automatically resolves the parameter type (JobScheduler and FileSystem, in the example) to the corresponding services that implement that type. When there's more than one service that implements the service interface, you'll get an error (but additional annotations and configuration can be used to ensure the correct service injected).</p><p>For modules , there are two additional parameter types that are used to refer to <em>resources</em> that can be provided to the module instance (rather than <em>services</em> which may be injected).</p><ul><li><a class="external-link" href="http://www.slf4j.org/api/org/slf4j/Logger.html"; rel="nofollow">org.slf4j.Logger</a>: logger for the module (derived from the module's class name)</li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html";>ObjectLocator</a>: access to other services<br clear="none"> Note that the fields are final: this is important. Tapestry IoC is thread-safe and you largely never have to think about concurrency issues. But in a busy application, different services may be built by different threads simultaneously. Each module class is a singleton, instantiated at most once, and making these fields final ensures that the values are available across multiple threads. Refer to Brian Goetz's <a class="externa l-link" href="http://www.javaconcurrencyinpractice.com/"; rel="nofollow">Java Concurrency in Practice</a> for a more complete explanation of the relationship between final fields, constructors, and threads ... or just trust us!</li></ul><p>Care should be taken with this approach: in some circumstances, you may force a situation in which the module constructor is dependent on itself. For example, if you invoke a method on any injected services defined within the same module from the module class' constructor, then the service implementation will be needed. Creating service implementations requires the module builder instance ... that's a recursive reference.</p><p>Tapestry detects these scenarios and throws a runtime exception to prevent an endless loop.</p><h1 id="TapestryIoCModules-ModuleClassImplementationNotes">Module Class Implementation Notes</h1><p>Module classes are designed to be very, very simple to implement.</p><p>Again, keep the methods very simple. Use <a href="tapestry -ioc-modules.html">parameter injection</a> to gain access to the dependencies you need.</p><p>Be careful about inheritance. Tapestry will see all <em>public</em> methods, even those inherited from base classes. Tapestry <em>only</em> sees public methods.</p><p>By convention, module class names end in Module and are final classes.</p><p>You don't <em>have</em> to define your methods as static. The use of static methods is only absolutely necessary in a few cases, where the constructor for a module is dependent on contributions from the same module (this creates a chicken-and-the-egg situation that is resolved through static methods).</p><h1 id="TapestryIoCModules-DefaultMarker">Default Marker</h1><p>Services are often referenced by a particular marker interface on the method or constructor parameter. Tapestry will use the intersection of services with that exact marker and assignable by type to find a unique service to inject.</p><p>Often, all services in a module should share a mark er, this can be specified with a @Marker annotation on the module class. For example, the TapestryIOCModule:</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;">@Marker(Builtin.class) public final class TapestryIOCModule {
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}