You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bo...@apache.org on 2017/09/16 01:54:20 UTC
svn commit: r1018226 [37/41] - in /websites/production/tapestry/content: ./
cache/ styles/
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 Sep 16 01:54:19 2017
@@ -27,6 +27,14 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css' rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,50 +75,134 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Tapestry IOC Configuration</strong> is the configuration of both the IOC services provided by Tapestry and those you write yourself. Both are configured in the same way: using Java, not XML.</p><parameter ac:name="style">float:right</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="class">aui-label</parameter><rich-text-body><parameter ac:name="showLabels">false</parameter><parameter ac:name="showSpace">false</parameter><parameter ac:name="title">Related Articles</parameter><parameter ac:name="cql">label = "configuration" and space = currentSpace()</parameter></rich-text-body><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><parameter ac:name="">java</parameter><plain-text-body> public static FileServiceDispatcher buildFileServicerDispatcher(Map<String,FileServicer> contributions)
+ <div id="ConfluenceContent"><p><strong>Tapestry IOC Configuration</strong> is the configuration of both the IOC services provided by Tapestry and those you write yourself. Both are configured in the same way: using Java, not XML.</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>
+
+
+<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">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public static FileServiceDispatcher buildFileServicerDispatcher(Map<String,FileServicer> contributions)
{
return new FileServiceDispatcherImpl(contributions);
- } </plain-text-body><p>In order to provide a value for the contribution parameter, Tapestry will <em>collect</em> contributions from service contribution methods. It will ensure that the keys and values match the generic types shown (String for the key, FileServicer for the value). The map will be assembled and passed into the service builder method, and from there, into the FileServiceDispatcherImpl constructor.</p><p>So where do the values come from? Your service contributor methods, methods whose names start with "contribute":</p><parameter ac:name="">java</parameter><plain-text-body> public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration)
+ } </pre>
+</div></div><p>In order to provide a value for the contribution parameter, Tapestry will <em>collect</em> contributions from service contribution methods. It will ensure that the keys and values match the generic types shown (String for the key, FileServicer for the value). The map will be assembled and passed into the service builder method, and from there, into the FileServiceDispatcherImpl constructor.</p><p>So where do the values come from? Your service contributor methods, methods whose names start with "contribute":</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)
{
configuration.add("txt", new TextFileServicer());
configuration.add("pdf", new PDFFileServicer());
- } </plain-text-body><p>Or, instead of instantiating those services ourselves, we could <a href="injection-in-detail.html">inject</a> them:</p><parameter ac:name="">java</parameter><plain-text-body> public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration,
+ } </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">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration,
@InjectService("TextFileServicer") FileServicer textFileServicer,
@InjectService("PDFFileServicer") FileServicer pdfFileServicer)
{
configuration.add("txt", textFileServicer);
configuration.add("pdf", pdfFileServicer);
- } </plain-text-body><p>The <strong>extensibility</strong> comes from the fact that multiple modules may all contribute to the same service configuration:</p><parameter ac:name="">java</parameter><plain-text-body> public static void contributeFileServicerDispatcher(MappedConfiguration<String,FileServicer> configuration)
+ } </pre>
+</div></div><p>The <strong>extensibility</strong> comes from the fact that multiple modules may all contribute to the same service configuration:</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)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
- } </plain-text-body><p>Now the FileServicerDispatcher builder method gets a Map with at least four entries in it.</p><p>Because Tapestry IoC is highly dynamic (it scans the visible JAR manifest files to identify module classes), the FileServicerDispatcher service may be in one module, and the other contributing modules (such as the one that contributes the Office file services) may be written at a much later date. With no change to the FileServicerDispatcher service or its module class, the new services "plug into" the overall solution, simply by having their JAR's on the runtime classpath.</p><h1 id="TapestryIoCConfiguration-Namingconventionsvs.Annotations">Naming conventions vs. Annotations</h1><p>
+ } </pre>
+</div></div><p>Now the FileServicerDispatcher builder method gets a Map with at least four entries in it.</p><p>Because Tapestry IoC is highly dynamic (it scans the visible JAR manifest files to identify module classes), the FileServicerDispatcher service may be in one module, and the other contributing modules (such as the one that contributes the Office file services) may be written at a much later date. With no change to the FileServicerDispatcher service or its module class, the new services "plug into" the overall solution, simply by having their JAR's on the runtime classpath.</p><h1 id="TapestryIoCConfiguration-Namingconventionsvs.Annotations">Naming conventions vs. Annotations</h1><p>
</p><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div>If you prefer annotations over naming conventions you can use the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Contribute.html">Contribute</a> annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with "contribute". The value of the annotation is the type of the service to contribute into.<p>The primary reasons to use @Contribute and marker annotations is twofold:</p><ul><li>There is no longer a linkage between the contribution method name and the service id, which is much more refactoring safe: if you change the service interface name, or the ID of the service, your method will still be invoked when using @Contribute.</li></ul><ul><li>It makes it much easier for an <a href="tapestry-ioc-configuration.html">override</a> of the service to get the configuration intended for the original service.</li></ul><p>The followin
g example is an annotation-based alternative for the contribution method above.</p><parameter ac:name="">java</parameter><plain-text-body>@Contribute(FileServiceDispatcher.class)
+<p> </p></div>If you prefer annotations over naming conventions you can use the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Contribute.html">Contribute</a> annotation. As of version 5.2 this annotation that may be placed on a contributor method of a module instead of starting the methods name with "contribute". The value of the annotation is the type of the service to contribute into.<p>The primary reasons to use @Contribute and marker annotations is twofold:</p><ul><li>There is no longer a linkage between the contribution method name and the service id, which is much more refactoring safe: if you change the service interface name, or the ID of the service, your method will still be invoked when using @Contribute.</li></ul><ul><li>It makes it much easier for an <a href="tapestry-ioc-configuration.html">override</a> of the service to get the configuration intended for the original service.</li></ul><p>The followin
g example is an annotation-based alternative for the contribution method above.</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;">@Contribute(FileServiceDispatcher.class)
public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
}
-</plain-text-body><p>If you have several implementations of a service interface, you have to disambiguate the services. For this purpose the marker annotations should be placed on the contributor method.</p><parameter ac:name="">java</parameter><plain-text-body>@Contribute(FileServiceDispatcher.class)
+</pre>
+</div></div><p>If you have several implementations of a service interface, you have to disambiguate the services. For this purpose the marker annotations should be placed on the contributor method.</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;">@Contribute(FileServiceDispatcher.class)
@Red @Blue
public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
}
-</plain-text-body><p>In this example, the method will only be invoked when constructing a service configuration where the service itself has both the Red and Blue marker annotations. Tapestry knows which annotations are marker annotations, and which marker annotations apply to the service, via the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Marker.html">Marker</a> annotation on the service implementation.</p><p>If the special @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Local.html">Local</a> annotation is present, then the contribution is made only to the configuration of a service being constructed in the same module.</p><p>Note that it <em>is</em> possible for the same contribution method to be invoked to contribute to the configuration of multiple different services.</p><parameter ac:name="">java</parameter><plain-text-body> @Contribute(FileServiceDisp
atcher.class)
+</pre>
+</div></div><p>In this example, the method will only be invoked when constructing a service configuration where the service itself has both the Red and Blue marker annotations. Tapestry knows which annotations are marker annotations, and which marker annotations apply to the service, via the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Marker.html">Marker</a> annotation on the service implementation.</p><p>If the special @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Local.html">Local</a> annotation is present, then the contribution is made only to the configuration of a service being constructed in the same module.</p><p>Note that it <em>is</em> possible for the same contribution method to be invoked to contribute to the configuration of multiple different services.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelConten
t pdl">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> @Contribute(FileServiceDispatcher.class)
@Local
public static void arbitraryMethodName(MappedConfiguration<String,FileServicer> configuration)
{
configuration.add("doc", new WordFileServicer());
configuration.add("ppt", new PowerPointFileServicer());
}
-</plain-text-body><h1 id="TapestryIoCConfiguration-ConfigurationTypes">Configuration Types</h1><p>There are three different styles of configurations (with matching contributions):</p><ul><li><strong>Unordered Collection</strong> – Contributions are simply added in and order is not important.</li><li><strong>Ordered List</strong> – Contributions are provided as an ordered list. Contributions must establish the order by giving each contributed object a unique id, by establishing forward and backward dependencies between the values.</li><li><strong>Map</strong> – Contributions provide unique keys and corresponding values.</li></ul><h2 id="TapestryIoCConfiguration-UnorderedCollection">Unordered Collection</h2><p>A service builder method can collect an unordered list of values by defining a parameter of type java.util.Collection. Further, you should parameterize the type of collection. Tapestry will identify the parameterized type and ensure that all contributions match
.</p><p>One thing to remember is that the order in which contributions occur is unspecified. There will be a possibly large number of modules, each having zero or more methods that contribute into the service. The order in which these methods are invoked is unknown.</p><p>For example, here's a kind of Startup service that needs some Runnable objects. It doesn't care what order the Runnable objects are executed in.</p><parameter ac:name="">java</parameter><plain-text-body> public static Runnable buildStartup(final Collection<Runnable> configuration)
+</pre>
+</div></div><h1 id="TapestryIoCConfiguration-ConfigurationTypes">Configuration Types</h1><p>There are three different styles of configurations (with matching contributions):</p><ul><li><strong>Unordered Collection</strong> – Contributions are simply added in and order is not important.</li><li><strong>Ordered List</strong> – Contributions are provided as an ordered list. Contributions must establish the order by giving each contributed object a unique id, by establishing forward and backward dependencies between the values.</li><li><strong>Map</strong> – Contributions provide unique keys and corresponding values.</li></ul><h2 id="TapestryIoCConfiguration-UnorderedCollection">Unordered Collection</h2><p>A service builder method can collect an unordered list of values by defining a parameter of type java.util.Collection. Further, you should parameterize the type of collection. Tapestry will identify the parameterized type and ensure that all contributions match.</p><
p>One thing to remember is that the order in which contributions occur is unspecified. There will be a possibly large number of modules, each having zero or more methods that contribute into the service. The order in which these methods are invoked is unknown.</p><p>For example, here's a kind of Startup service that needs some Runnable objects. It doesn't care what order the Runnable objects are executed in.</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 Collection<Runnable> configuration)
{
return new Runnable()
{
@@ -120,11 +212,15 @@ public static void arbitraryMethodName(M
contribution.run();
}
};
- } </plain-text-body><p>Here we don't even need a separate class for the implementation, we use an inner class for the implementation. The point is, the configuration is provided to the builder method, which passes it along to the implementation of the service.</p><p>On the contribution side, a service contribution method sees a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Configuration.html">Configuration</a> object:</p><parameter ac:name="">java</parameter><plain-text-body> public static void contributeStartup(Configuration<Runnable> configuration)
+ } </pre>
+</div></div><p>Here we don't even need a separate class for the implementation, we use an inner class for the implementation. The point is, the configuration is provided to the builder method, which passes it along to the implementation of the service.</p><p>On the contribution side, a service contribution method sees a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Configuration.html">Configuration</a> object:</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 contributeStartup(Configuration<Runnable> configuration)
{
configuration.add(new JMSStartup());
configuration.add(new FileSystemStartup());
- } </plain-text-body><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><parameter ac:name="">Ordered_List</parameter></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><parameter ac:name="">java</parameter><plain-text-body> public static Runnable buildStartup(final List<Runnable> configuration)
+ } </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">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public static Runnable buildStartup(final List<Runnable> configuration)
{
return new Runnable()
{
@@ -134,17 +230,20 @@ public static void arbitraryMethodName(M
contribution.run();
}
};
- } </plain-text-body><p>Notice that the service builder method is shielded from the details of how the items are ordered. It doesn't have to know about IDs and pre- and post-requisites. By using a parameter type of List, we've triggered Tapestry to collect all the ordering information.</p><p>For our service contribution methods, we must provide a parameter of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/OrderedConfiguration.html">OrderedConfiguration</a>:</p><parameter ac:name="">java</parameter><plain-text-body> public static void contributeStartup(OrderedConfiguration<Runnable> configuration)
+ } </pre>
+</div></div><p>Notice that the service builder method is shielded from the details of how the items are ordered. It doesn't have to know about IDs and pre- and post-requisites. By using a parameter type of List, we've triggered Tapestry to collect all the ordering information.</p><p>For our service contribution methods, we must provide a parameter of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/OrderedConfiguration.html">OrderedConfiguration</a>:</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 contributeStartup(OrderedConfiguration<Runnable> configuration)
{
configuration.add("JMS", new JMSStartup());
configuration.add("FileSystem", new FileSystemStartup(), "after:CacheSetup");
- } </plain-text-body><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 inc
lude any nulls). Again, they are allowed as placeholders, for the actual contributed objects to organize themselves around.
+ } </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.
</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>
<div class="error"><span class="error">Unknown macro: {div}</span>
<p>When using <code>add()</code> without any specific constraints, a default constraint is added: after the previously added element. These default constraints are only within a single contribution method, but makes it much easier to set the order of several related contributions. Note that the contributions will be ordered relative to each other and it's possible that contributions by some other module or method may be interspersed between them.</p>
-</div><h2 id="TapestryIoCConfiguration-MappedConfigurations">Mapped Configurations</h2><p>As discussed in the earlier examples, mapped configurations are also supported. The keys passed in must be unique. When conflicts occur, Tapestry will log warnings (identifying the source of the conflict, in terms of invoked methods), and ignore the conflicting value.</p><p>Neither the key nor the value may be null.</p><p>For mapped configurations where the key type is String, a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/CaseInsensitiveMap.html">CaseInsensitiveMap</a> will be automatically used (and passed to the service builder method), to help ensure that <a href="tapestry-ioc-configuration.html">case insensitivity</a> is automatic and pervasive.</p><h1 id="TapestryIoCConfiguration-InjectingClasses">Injecting Classes</h1><p>All three configuration interfaces have a second method, <code>addInstance()</code>. This method takes a cla
ss, not an instance. The class is instantiated and contributed. If the constructor for the class takes dependencies, those are injected as well.</p><h1 id="TapestryIoCConfiguration-InjectingResources">Injecting Resources</h1><p>In addition to injecting services into a contributor method (via the @InjectService and @Inject annotations), Tapestry will key off of the parameter type to allow other things to be injected.</p><ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html">ObjectLocator</a>: access to other services visible to the contributing module</li><li>org.slf4j.Logger: the Logger for the service being contributed to</li></ul><p>No annotation is needed for these cases.</p><p><parameter ac:name="">overrides</parameter></p><h1 id="TapestryIoCConfiguration-ConfigurationOverrides">Configuration Overrides</h1><p>
+</div><h2 id="TapestryIoCConfiguration-MappedConfigurations">Mapped Configurations</h2><p>As discussed in the earlier examples, mapped configurations are also supported. The keys passed in must be unique. When conflicts occur, Tapestry will log warnings (identifying the source of the conflict, in terms of invoked methods), and ignore the conflicting value.</p><p>Neither the key nor the value may be null.</p><p>For mapped configurations where the key type is String, a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/util/CaseInsensitiveMap.html">CaseInsensitiveMap</a> will be automatically used (and passed to the service builder method), to help ensure that <a href="tapestry-ioc-configuration.html">case insensitivity</a> is automatic and pervasive.</p><h1 id="TapestryIoCConfiguration-InjectingClasses">Injecting Classes</h1><p>All three configuration interfaces have a second method, <code>addInstance()</code>. This method takes a cla
ss, not an instance. The class is instantiated and contributed. If the constructor for the class takes dependencies, those are injected as well.</p><h1 id="TapestryIoCConfiguration-InjectingResources">Injecting Resources</h1><p>In addition to injecting services into a contributor method (via the @InjectService and @Inject annotations), Tapestry will key off of the parameter type to allow other things to be injected.</p><ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectLocator.html">ObjectLocator</a>: access to other services visible to the contributing module</li><li>org.slf4j.Logger: the Logger for the service being contributed to</li></ul><p>No annotation is needed for these cases.</p><p><span class="confluence-anchor-link" id="TapestryIoCConfiguration-overrides"></span></p><h1 id="TapestryIoCConfiguration-ConfigurationOverrides">Configuration Overrides</h1><p>
</p><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.1</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 Sep 16 01:54:19 2017
@@ -27,6 +27,14 @@
</title>
<link type="text/css" rel="stylesheet" href="/resources/space.css" />
+ <link href='/resources/highlighter/styles/shCoreCXF.css' rel='stylesheet' type='text/css' />
+ <link href='/resources/highlighter/styles/shThemeCXF.css' rel='stylesheet' type='text/css' />
+ <script src='/resources/highlighter/scripts/shCore.js' type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJava.js' type='text/javascript'></script>
+ <script>
+ SyntaxHighlighter.defaults['toolbar'] = false;
+ SyntaxHighlighter.all();
+ </script>
<link href="/styles/style.css" rel="stylesheet" type="text/css"/>
@@ -67,7 +75,8 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><rich-text-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></rich-text-body><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, 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 InputStre
am 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 dy
namically 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><parameter ac:name="">java</parameter><plain-text-body>package org.example.myapp.services;
+ <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">
+<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">package org.example.myapp.services;
import org.apache.tapestry5.ioc.services.LoggingDecorator;
import org.slf4j.Logger;
@@ -86,10 +95,14 @@ public class MyAppModule
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
}
-}</plain-text-body><p>The method decorateIndexer() is a service decorator method because it starts with the word "decorate". In this simple case, only the myapp.Indexer service will be decorated, even if there are other services in this module or others ... this is because of the name match ("decorateIndexer" and "buildIndexer"), but we'll shortly see how annotations can be used to target many services for decoration.</p><p>We are using the parameterized types here (the <T>), to reinforce the fact that the delegate object passed in (which will be the core service implementation, or some other interceptor) must implement the service interface, and that the decorator method must return an instance of the service interface.</p><p>The values that may be provided to a decorator method are exactly the same as for a builder method, with one addition: The underlying service will be passed in as a parameter of type java.lang.Object (after type erasure, the <code>T delegate</code> param
eter becomes <code>Object delegate</code>).</p><p>In the above example, the decorator method receives the core service implementation, the service interface for the Indexer service, the Log for the Indexer service, and an interceptor factory that generates logging interceptors.</p><p>The "heavy lifting" is provided by the factory, which will create a new interceptor that logs method entry before delegating to the core service implementation. The interceptor will also log method parameters, return values, and even log exceptions.</p><p>The return value of the method is the new interceptor. You may return null if your decorator method decides not to decorate the supplied service.</p><p>Alternately, when targetting services whose type is known at compile time, you may provide a parameter whose type matches the service interface. For example, decorateIndexer() will always be applied to the Indexer service, whose type (Indexer) is known. We could therefore rewrite decorateIndexer() as:</
p><parameter ac:name="">java</parameter><plain-text-body> public static Indexer decorateIndexer(Indexer delegate, Logger logger, LoggingDecorator decorator)
+}</pre>
+</div></div><p>The method decorateIndexer() is a service decorator method because it starts with the word "decorate". In this simple case, only the myapp.Indexer service will be decorated, even if there are other services in this module or others ... this is because of the name match ("decorateIndexer" and "buildIndexer"), but we'll shortly see how annotations can be used to target many services for decoration.</p><p>We are using the parameterized types here (the <T>), to reinforce the fact that the delegate object passed in (which will be the core service implementation, or some other interceptor) must implement the service interface, and that the decorator method must return an instance of the service interface.</p><p>The values that may be provided to a decorator method are exactly the same as for a builder method, with one addition: The underlying service will be passed in as a parameter of type java.lang.Object (after type erasure, the <code>T delegate</code> parameter be
comes <code>Object delegate</code>).</p><p>In the above example, the decorator method receives the core service implementation, the service interface for the Indexer service, the Log for the Indexer service, and an interceptor factory that generates logging interceptors.</p><p>The "heavy lifting" is provided by the factory, which will create a new interceptor that logs method entry before delegating to the core service implementation. The interceptor will also log method parameters, return values, and even log exceptions.</p><p>The return value of the method is the new interceptor. You may return null if your decorator method decides not to decorate the supplied service.</p><p>Alternately, when targetting services whose type is known at compile time, you may provide a parameter whose type matches the service interface. For example, decorateIndexer() will always be applied to the Indexer service, whose type (Indexer) is known. We could therefore rewrite decorateIndexer() 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;"> public static Indexer decorateIndexer(Indexer delegate, Logger logger, LoggingDecorator decorator)
{
return decorator.build(Indexer.class, delegate, "Indexer", logger);
- }</plain-text-body><p>Of course, nothing stops you from combining building with decorating inside the service builder method:</p><parameter ac:name="">java</parameter><plain-text-body>package org.example.myapp.services;
+ }</pre>
+</div></div><p>Of course, nothing stops you from combining building with decorating inside the service builder method:</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.services.LoggingDecorator;
import org.slf4j.Logger;
@@ -100,25 +113,31 @@ public class MyAppModule
{
return decorator.build(Indexer.class, logger, new IndexerImpl());
}
-}</plain-text-body><p>But as we'll see next, it's possible to have a single decorator method work on many different services by using annotations.</p><h1 id="TapestryIoCDecorators-TargetingMultipleServices">Targeting Multiple Services</h1><p>By using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Match.html">Match</a> annotation, you may identify which services are to be decorated.</p><p>The value specified in the Match annotation is one or more patterns. These patterns are used to match services. Patterns take two forms: glob patterns and regular expressions.</p><p>In a glob pattern, a "*" at the start or end of a string will match zero or more characters. Regular expressions provide a lot more matching power, but require a more involved syntax.</p><p>In either case, the matching is case insensitive.</p><p>For example, to target all the services in your module:</p><parameter ac:name="">java</parameter><plain-text
-body> @Match("*")
+}</pre>
+</div></div><p>But as we'll see next, it's possible to have a single decorator method work on many different services by using annotations.</p><h1 id="TapestryIoCDecorators-TargetingMultipleServices">Targeting Multiple Services</h1><p>By using the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Match.html">Match</a> annotation, you may identify which services are to be decorated.</p><p>The value specified in the Match annotation is one or more patterns. These patterns are used to match services. Patterns take two forms: glob patterns and regular expressions.</p><p>In a glob pattern, a "*" at the start or end of a string will match zero or more characters. Regular expressions provide a lot more matching power, but require a more involved syntax.</p><p>In either case, the matching is case insensitive.</p><p>For example, to target all the services in your module:</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("*")
public static <T> T decorateLogging(Class<T> serviceInterface, T delegate,
String serviceId, Logger logger,
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
- } </plain-text-body><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 inter
face. None of 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><parameter ac:name="">java</parameter><plain-text-body> @Match("*")
+ } </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">
+<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,
String serviceId, Logger logger,
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
- } </plain-text-body><p>"before:*" indicates that this decorator should come before any decorator in <em>any</em> module.</p><p><strong>Note:</strong> the ordering of decorators is in terms of the <em>effect</em> desired. Internally, the decorators are invoked last to first (since each once receives the "next" interceptor as its delegate). So the core service implementation is created (via a service builder method) and that is passed to the last decorator method. The interceptor created there is passed to the the next-to-last decorator method, and so forth.</p><p>It should now be evident that the delegate passed into a decorator method is sometimes the core service implementation, and some times an interceptor object created by some other decorator method.</p><h1 id="TapestryIoCDecorators-Annotationdrivendecorators">Annotation driven decorators</h1><p>
+ } </pre>
+</div></div><p>"before:*" indicates that this decorator should come before any decorator in <em>any</em> module.</p><p><strong>Note:</strong> the ordering of decorators is in terms of the <em>effect</em> desired. Internally, the decorators are invoked last to first (since each once receives the "next" interceptor as its delegate). So the core service implementation is created (via a service builder method) and that is passed to the last decorator method. The interceptor created there is passed to the the next-to-last decorator method, and so forth.</p><p>It should now be evident that the delegate passed into a decorator method is sometimes the core service implementation, and some times an interceptor object created by some other decorator method.</p><h1 id="TapestryIoCDecorators-Annotationdrivendecorators">Annotation driven decorators</h1><p>
</p><div class="confluence-information-macro confluence-information-macro-information"><p class="title">Added in 5.2</p><span class="aui-icon aui-icon-small aui-iconfont-info confluence-information-macro-icon"></span><div class="confluence-information-macro-body">
</div></div>
<div class="error"><span class="error">Unknown macro: {div}</span>
-<p> </p></div>Starting from version 5.2, Tapestry supports annotation-driven decorator methods. If the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html">@Decorate</a> annotation is present, the decorator method can be arbitrary named, as shown in the following example.<plain-text-body> @Decorate
+<p> </p></div>Starting from version 5.2, Tapestry supports annotation-driven decorator methods. If the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html">@Decorate</a> annotation is present, the decorator method can be arbitrary named, as shown in the following example.<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;"> @Decorate
@Match("*DAO")
public static <T> T byServiceId(Class<T> serviceInterface, T delegate,
String serviceId, Logger logger,
@@ -126,7 +145,9 @@ public class MyAppModule
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
}
-</plain-text-body><p>The decorator above is applied to any service whose id matches the "*DAO" pattern.</p><p>Alternatively, marker annotations can be placed on the decorate method to match a specific service.</p><plain-text-body> @Decorate
+</pre>
+</div></div><p>The decorator above is applied to any service whose id matches the "*DAO" pattern.</p><p>Alternatively, marker annotations can be placed on the decorate method to match a specific service.</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;"> @Decorate
@Blue
public static <T> T byMarkerAnnotation(Class<T> serviceInterface, T delegate,
String serviceId, Logger logger,
@@ -134,14 +155,18 @@ public class MyAppModule
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
}
-</plain-text-body><p>The decorator above is applied to any service that is marked by the @Blue annotation.</p><p>By default, <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html">@Decorate</a> annotation applies the decorator to any service matched by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Match.html">@Match</a> or marker annotations. You can limit the matching to a single service interface, as shown in the following example.</p><plain-text-body> @Decorate(serviceInterface=MyService.class)
+</pre>
+</div></div><p>The decorator above is applied to any service that is marked by the @Blue annotation.</p><p>By default, <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Decorate.html">@Decorate</a> annotation applies the decorator to any service matched by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Match.html">@Match</a> or marker annotations. You can limit the matching to a single service interface, as shown in the following 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;"> @Decorate(serviceInterface=MyService.class)
@Match("*DAO")
public static <T> T byServiceId(Class<T> serviceInterface, T delegate,
String serviceId, Logger logger,
LoggingDecorator decorator)
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
- }</plain-text-body><p>In the example above, the decorator is applied to any implementation of MyService interfaces whose id matches the "*DAO" pattern.</p><plain-text-body> @Decorate(serviceInterface=MyService.class)
+ }</pre>
+</div></div><p>In the example above, the decorator is applied to any implementation of MyService interfaces whose id matches the "*DAO" pattern.</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;"> @Decorate(serviceInterface=MyService.class)
@Blue
public static <T> T byMarkerAnnotation(Class<T> serviceInterface, T delegate,
String serviceId, Logger logger,
@@ -149,7 +174,9 @@ public class MyAppModule
{
return decorator.build(serviceInterface, delegate, serviceId, logger);
}
-</plain-text-body><p>The decorator above is applied to any implementation of the MyService interface that is marked by the @Blue annotation.</p><h1 id="TapestryIoCDecorators-CreatingyourownDecorators">Creating your own Decorators</h1><p>Decorators are a limited form of Aspect Oriented Programming, so we have borrowed some of that terminology here.</p><p>A decorator exists to create an <em>interceptor</em>. The interceptor wraps around the service (because these interceptors can get chained, we talk about the "delegate" and not the "service").</p><p>Each method of the interceptor will take <em>advice</em>. Advice is provided by a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/MethodAdvice.html">MethodAdvice</a> instance. The sole method, <code>advise()</code>, receives an <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Invocation.html">Invocation</a>. MethodAdvice gives you a chan
ce to see what the method invocation <em>is</em>; you can query the name of the method, and the types and values of the parameters.</p><p>The MethodAdvice can override the parameters if necessary, then invoke <code>proceed()</code>. This call invokes the corresponding method on the original object, the delegate.</p><p>If the method call throws a runtime exception, that exception is not caught. Your method advice can put a try ... catch block around the call to proceed() if interested in catching runtime exceptions.</p><p>Checked exceptions are not thrown (since they are not part of the proceed() method's signature). Instead the invocation's <code>isFail()</code> method will return true. You can then retrieve the exception or override it.</p><p>In the normal success case, you can ask for the return value and even override it before returning from the advise() method.</p><p>In other words, you have total control. Your MethodAdvice can query or change parameters, decide whether it proc
eed into the original code, it can intercept exceptions that are thrown and replace them, and can query or even replace the return value.</p><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/AspectDecorator.html">AspectDecorator</a> service is how you put your MethodAdvice into action.</p><p>By way of an example, we'll show an implementation of the LoggingDecorator service:</p><parameter ac:name="">java</parameter><plain-text-body>public class LoggingDecoratorImpl implements LoggingDecorator
+</pre>
+</div></div><p>The decorator above is applied to any implementation of the MyService interface that is marked by the @Blue annotation.</p><h1 id="TapestryIoCDecorators-CreatingyourownDecorators">Creating your own Decorators</h1><p>Decorators are a limited form of Aspect Oriented Programming, so we have borrowed some of that terminology here.</p><p>A decorator exists to create an <em>interceptor</em>. The interceptor wraps around the service (because these interceptors can get chained, we talk about the "delegate" and not the "service").</p><p>Each method of the interceptor will take <em>advice</em>. Advice is provided by a <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/MethodAdvice.html">MethodAdvice</a> instance. The sole method, <code>advise()</code>, receives an <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/Invocation.html">Invocation</a>. MethodAdvice gives you a chance to
see what the method invocation <em>is</em>; you can query the name of the method, and the types and values of the parameters.</p><p>The MethodAdvice can override the parameters if necessary, then invoke <code>proceed()</code>. This call invokes the corresponding method on the original object, the delegate.</p><p>If the method call throws a runtime exception, that exception is not caught. Your method advice can put a try ... catch block around the call to proceed() if interested in catching runtime exceptions.</p><p>Checked exceptions are not thrown (since they are not part of the proceed() method's signature). Instead the invocation's <code>isFail()</code> method will return true. You can then retrieve the exception or override it.</p><p>In the normal success case, you can ask for the return value and even override it before returning from the advise() method.</p><p>In other words, you have total control. Your MethodAdvice can query or change parameters, decide whether it proceed in
to the original code, it can intercept exceptions that are thrown and replace them, and can query or even replace the return value.</p><p>The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/AspectDecorator.html">AspectDecorator</a> service is how you put your MethodAdvice into action.</p><p>By way of an example, we'll show an implementation of the LoggingDecorator service:</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 LoggingDecoratorImpl implements LoggingDecorator
{
private final AspectDecorator aspectDecorator;
@@ -203,7 +230,8 @@ public class MyAppModule
String.format("<Logging interceptor for %s(%s)>", serviceId,
serviceInterface.getName()));
}
-}</plain-text-body><p><em>The actual code has been refactored slightly since this documentation was written.</em></p><p>Most of the logging logic occurs inside the ServiceLogger object, the MethodAdvice exists to call the right methods at the right time. A Logger doesn't <em>change</em> parameter values (or thrown exceptions, or the result), it just captures and logs the data.</p><p>Notice that for runtime exceptions, we catch the exception, log it, and rethrow it.</p><p>For checked exceptions, we use isFail() and getThrown().</p><p>The AspectDecorator service can also be used in more complicated ways: it is possible to only advise some of the methods and not others, or use different advice for different methods. Check the JavaDoc for more details.</p><p> </p><p></p></div>
+}</pre>
+</div></div><p><em>The actual code has been refactored slightly since this documentation was written.</em></p><p>Most of the logging logic occurs inside the ServiceLogger object, the MethodAdvice exists to call the right methods at the right time. A Logger doesn't <em>change</em> parameter values (or thrown exceptions, or the result), it just captures and logs the data.</p><p>Notice that for runtime exceptions, we catch the exception, log it, and rethrow it.</p><p>For checked exceptions, we use isFail() and getThrown().</p><p>The AspectDecorator service can also be used in more complicated ways: it is possible to only advise some of the methods and not others, or use different advice for different methods. Check the JavaDoc for more details.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>