Modified: websites/production/tapestry/content/logging.html
==============================================================================
--- websites/production/tapestry/content/logging.html (original)
+++ websites/production/tapestry/content/logging.html Wed Sep 20 12:29:16 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"/>
@@ -36,26 +44,13 @@
<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">Logging</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">Logging</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,8 +62,23 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Logging</strong>
involves the automatic recording of progress as an application runs. Tapestry
makes extensive use of <a class="external-link" href="http://www.slf4j.org/";
rel="nofollow">SLF4J</a> to log details about the creation and operation of
your page and component classes.</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 = "logging" and space =
currentSpace()</parameter></rich-text-body><p>The default configuration for
logging uses <a class="external-link"
href="http://logging.apache.org/log4j/";>Log4J</a> as the logging toolkit,
though <a href="logging-in-tapestry.html">this can be changed</a>.</p><h1
id="Logging-Class
toLogger">Class to Logger</h1><p>The logger name for a page or component
matches the fully qualified class name. You can configure this in
log4j.properties:</p><plain-text-body>log4j.category.org.apache.tapestry5.integration.app1.pages.MerryChristmas=trace
-</plain-text-body><h1 id="Logging-InjectingLoggers">Injecting
Loggers</h1><p>You may mark a field of type <a class="external-link"
href="http://www.slf4j.org/api/org/slf4j/Logger.html"; rel="nofollow">Logger</a>
with the @Inject annotation. The proper Logger for your page or component will
be injected.</p><plain-text-body>public class MyPage
+ <div id="ConfluenceContent"><p><strong>Logging</strong>
involves the automatic recording of progress as an application runs. Tapestry
makes extensive use of <a class="external-link" href="http://www.slf4j.org/";
rel="nofollow">SLF4J</a> to log details about the creation and operation of
your page and component classes.</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="logging-in-tapestry.html">Logging in Tapestry</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="logging.html">Logging</a>
+ </div> </li></ul></div><p>The default configuration for logging uses <a
class="external-link" href="http://logging.apache.org/log4j/";>Log4J</a> as the
logging toolkit, though <a href="logging-in-tapestry.html">this can be
changed</a>.</p><h1 id="Logging-ClasstoLogger">Class to Logger</h1><p>The
logger name for a page or component matches the fully qualified class name. You
can configure this in log4j.properties:</p><div class="preformatted panel"
style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>log4j.category.org.apache.tapestry5.integration.app1.pages.MerryChristmas=trace
+</pre>
+</div></div><h1 id="Logging-InjectingLoggers">Injecting Loggers</h1><p>You may
mark a field of type <a class="external-link"
href="http://www.slf4j.org/api/org/slf4j/Logger.html"; rel="nofollow">Logger</a>
with the @Inject annotation. The proper Logger for your page or component will
be injected.</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 MyPage
{
@Inject
private Logger logger;
@@ -79,7 +89,9 @@
{
logger.info("Changes saved successfully");
}
-</plain-text-body><h1 id="Logging-@Logannotation">@Log annotation</h1><p>You
may mark any component method with the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Log.html";>Log</a>
annotation. Method entry, exit (and any thrown exceptions) will be logged at
DEBUG level, along with parameter values and the method's return value. This is
very convenient for debugging, especially when placed on event handler
methods.</p><h1 id="Logging-ComponentTransformationDebugging">Component
Transformation Debugging</h1><p>Tapestry performs a transformation on your
classes as they are loaded, and sometimes you want to gain insight into what it
has done. Tapestry uses a secondary logger, consisting of the class name with
the prefix "tapestry.transformer.", to log (at debug level) the results of
transforming the class.</p><p>Example:</p><plain-text-body>[DEBUG] Index //
class version 49.0 (49)
+</pre>
+</div></div><h1 id="Logging-@Logannotation">@Log annotation</h1><p>You may
mark any component method with the @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Log.html";>Log</a>
annotation. Method entry, exit (and any thrown exceptions) will be logged at
DEBUG level, along with parameter values and the method's return value. This is
very convenient for debugging, especially when placed on event handler
methods.</p><h1 id="Logging-ComponentTransformationDebugging">Component
Transformation Debugging</h1><p>Tapestry performs a transformation on your
classes as they are loaded, and sometimes you want to gain insight into what it
has done. Tapestry uses a secondary logger, consisting of the class name with
the prefix "tapestry.transformer.", to log (at debug level) the results of
transforming the class.</p><p>Example:</p><div class="preformatted panel"
style="border-width: 1px;"><div class="preformattedContent panelContent">
+<pre>[DEBUG] Index // class version 49.0 (49)
// access flags 0x11
public final class
org/apache/tapestry5/integration/app1/pages/Index$Invocation_containingPageDidLoad_123fd9264de3fa20
extends org/apache/tapestry5/internal/plastic/AbstractMethodInvocation
implements org/apache/tapestry5/plastic/MethodInvocation {
@@ -103,12 +115,16 @@ public final class org/apache/tapestry5/
. . .
-</plain-text-body><p>Essentially, this output is a dissasembly of the bytecode
transformed or created by Tapestry for the component. Is this helpful? Probably
only if you are developing your own code that integrates into the component
class transformation chain; for example, to support your own field and method
annotations, and even then, not as much in Tapestry 5.3 as in earlier versions
of Tapestry (because of the introduction of the plastic library).</p><h1
id="Logging-ComponentEventDebugging">Component Event Debugging</h1><p>Tapestry
can also debug component event logic. The component's logger, with a
"tapestry.events." prefix, is used at debug level. The debugging output
identifies the event name and event source, and identifies any methods that are
invoked.</p><p>Note that events that are not handled by a component will bubble
up to the component's container; further logging for the same event will occur
using the logger associated with the container. The page containing the i
nitial component is the final step when
logging.</p><p>Examples:</p><plain-text-body>[DEBUG] ActionLink Dispatch event:
ComponentEvent[action from (self)]
+</pre>
+</div></div><p>Essentially, this output is a dissasembly of the bytecode
transformed or created by Tapestry for the component. Is this helpful? Probably
only if you are developing your own code that integrates into the component
class transformation chain; for example, to support your own field and method
annotations, and even then, not as much in Tapestry 5.3 as in earlier versions
of Tapestry (because of the introduction of the plastic library).</p><h1
id="Logging-ComponentEventDebugging">Component Event Debugging</h1><p>Tapestry
can also debug component event logic. The component's logger, with a
"tapestry.events." prefix, is used at debug level. The debugging output
identifies the event name and event source, and identifies any methods that are
invoked.</p><p>Note that events that are not handled by a component will bubble
up to the component's container; further logging for the same event will occur
using the logger associated with the container. The page containing the initial
component is the final step when logging.</p><p>Examples:</p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+<pre>[DEBUG] ActionLink Dispatch event: ComponentEvent[action from (self)]
[DEBUG] ActionDemo Dispatch event: ComponentEvent[action from actionlink]
[DEBUG] ActionDemo Invoking:
org.apache.tapestry5.integration.app1.pages.nested.ActionDemo.onAction(java.lang.Long)
(at ActionDemo.java:28)
[DEBUG] ActionDemo Dispatch event: ComponentEvent[passivate from (self)]
[DEBUG] ActionDemo Invoking:
org.apache.tapestry5.integration.app1.pages.nested.ActionDemo.onPassivate() (at
ActionDemo.java:38)
-</plain-text-body><h1 id="Logging-RenderQueueDebugging">Render Queue
Debugging</h1><p>Occasionally it is useful to get debugging output of all the
steps involved in rendering a page. In Tapestry, rendering involves a series of
rendering commands passed through a rendering queue (most commands will operate
by queuing up additional commands). A rendering command may represent an
element or attribute from a component template, or some template text, or it
may represent one render phase when rendering a component.</p><p>The logger is
the page's logger prefixed with "tapestry.render.".</p><p>This debugging is
most useful when you get a rendering exception about unbalanced open and close
tags.</p><p>Most logging is at the trace level, except for a debug-level entry
at the end identifying the number of commands and the elapsed
time.</p><plain-text-body> . . .
+</pre>
+</div></div><h1 id="Logging-RenderQueueDebugging">Render Queue
Debugging</h1><p>Occasionally it is useful to get debugging output of all the
steps involved in rendering a page. In Tapestry, rendering involves a series of
rendering commands passed through a rendering queue (most commands will operate
by queuing up additional commands). A rendering command may represent an
element or attribute from a component template, or some template text, or it
may represent one render phase when rendering a component.</p><p>The logger is
the page's logger prefixed with "tapestry.render.".</p><p>This debugging is
most useful when you get a rendering exception about unbalanced open and close
tags.</p><p>Most logging is at the trace level, except for a debug-level entry
at the end identifying the number of commands and the elapsed time.</p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+<pre> . . .
[TRACE] ActionDemo Executing: Text[Apache Software Foundation]
[TRACE] ActionDemo Executing: End
@@ -137,7 +153,8 @@ public final class org/apache/tapestry5/
[TRACE] ActionDemo Executing: CleanupRender[nested/ActionDemo]
[TRACE] ActionDemo Executing:
org.apache.tapestry5.internal.structure.ComponentPageElementImpl$1@7efc0795
[DEBUG] ActionDemo Executed 276 rendering commands (max queue depth: 141) in
0.025 seconds
-</plain-text-body></div>
+</pre>
+</div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/maven-support-faq.html
==============================================================================
--- websites/production/tapestry/content/maven-support-faq.html (original)
+++ websites/production/tapestry/content/maven-support-faq.html Wed Sep 20
12:29:16 2017
@@ -27,6 +27,16 @@
</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 src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.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 +77,8 @@
</div>
<div id="content">
- <div
id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2
id="MavenSupportFAQ-MavenSupport">Maven Support</h2><h3
id="MavenSupportFAQ-WhydoMavenprojectnamesandotherdetailsshowupinmypages?">Why
do Maven project names and other details show up in my pages?</h3><p>Tapestry
and maven both use the same syntax for dynamic portions of files: the
<code>${...</code>} syntax. When Maven is copying resources from
<code>src/main/resources</code>, and when filtering is <em>enabled</em> (which
is not the default), then any expansions in <em>Tapestry templates</em> that
match against Maven project properties are substituted. If you look at the
deployed application you'll see that <code>${name</code>} is gone, replaced
with your project's name!</p><p>The solution is to update your
<code>pom.xml</code> and ignore any .tml files when copying and
filtering:</p><parameter ac:name="language">xml</parameter><parameter
ac:name="title">pom.xml (partial)</parameter><plain
-text-body> <resource>
+ <div id="ConfluenceContent"><h2
id="MavenSupportFAQ-MavenSupport">Maven Support</h2><h3
id="MavenSupportFAQ-WhydoMavenprojectnamesandotherdetailsshowupinmypages?">Why
do Maven project names and other details show up in my pages?</h3><p>Tapestry
and maven both use the same syntax for dynamic portions of files: the
<code>${...</code>} syntax. When Maven is copying resources from
<code>src/main/resources</code>, and when filtering is <em>enabled</em> (which
is not the default), then any expansions in <em>Tapestry templates</em> that
match against Maven project properties are substituted. If you look at the
deployed application you'll see that <code>${name</code>} is gone, replaced
with your project's name!</p><p>The solution is to update your
<code>pom.xml</code> and ignore any .tml files when copying and
filtering:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>pom.xml
(partial)</b>
</div><div class="codeContent panelContent pdl">
+<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"> <resource>
<directory>src/main/resources</directory>
<excludes>
<exclude>**/*.tml</exclude>
@@ -82,7 +93,8 @@
</includes>
<filtering>false</filtering>
</resource>
-</plain-text-body><plain-text-body>{scrollbar}</plain-text-body></div>
+</pre>
+</div></div></div>
</div>
<div class="clearer"></div>
Modified:
websites/production/tapestry/content/meta-programming-page-content.html
==============================================================================
--- websites/production/tapestry/content/meta-programming-page-content.html
(original)
+++ websites/production/tapestry/content/meta-programming-page-content.html Wed
Sep 20 12:29:16 2017
@@ -27,6 +27,17 @@
</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 src='/resources/highlighter/scripts/shBrushXml.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushJScript.js'
type='text/javascript'></script>
+ <script src='/resources/highlighter/scripts/shBrushPlain.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 +78,8 @@
</div>
<div id="content">
- <div
id="ConfluenceContent"><p><plain-text-body>{scrollbar}</plain-text-body></p><parameter
ac:name="hidden">true</parameter><parameter
ac:name="atlassian-macro-output-type">BLOCK</parameter><rich-text-body><p>Adding
an Annotation and a Filter to customize Tapestry's page
rendering</p></rich-text-body><h1
id="Meta-ProgrammingPageContent-Meta-ProgrammingPageContent">Meta-Programming
Page Content</h1><p>It is likely that you have some cross-cutting concerns
across your pages, specific features you would like to "mix in" to your pages
without getting tied into knots by inheritance. This is one of those areas
where Tapestry shines.</p><p>This specific example is adapted from a real
client requirement: the client was concerned about other sites wrapping his
content in a frameset and making the site content appear to be theirs. Not all
pages (in some cases, that would be an advantage) but specific pages in the
application. For those pages, the following behaviors were requ
ired:</p><ul><li>Set the X-Frame-Options response header to
"DENY"</li><li>Include JavaScript to "pop" the page out of a frame, if in
one</li></ul><p>Again, this <em>could</em> be done by having a specific
base-class that included a <code>beginRender()</code> method, but the
meta-programming approach is nearly as easy and much more flexible.</p><h2
id="Meta-ProgrammingPageContent-ComponentMeta-Data">Component
Meta-Data</h2><p>In Tapestry, every component (and remember, pages are
components) has <em>meta data</em>: an extra set of key/value pairs stored in
the component's <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>.</p><p>By
hooking into the component class transformation pipeline, we can change an
annotation into meta-data that can be accessed by a filter.</p><h2
id="Meta-ProgrammingPageContent-DefiningtheAnnotation">Defining the
Annotation</h2><parameter ac:name="language">java</para
meter><parameter
ac:name="title">ForbidFraming.java</parameter><plain-text-body>package
com.fnord.annotations;
+ <div id="ConfluenceContent"><h1
id="Meta-ProgrammingPageContent-Meta-ProgrammingPageContent">Meta-Programming
Page Content</h1><p>It is likely that you have some cross-cutting concerns
across your pages, specific features you would like to "mix in" to your pages
without getting tied into knots by inheritance. This is one of those areas
where Tapestry shines.</p><p>This specific example is adapted from a real
client requirement: the client was concerned about other sites wrapping his
content in a frameset and making the site content appear to be theirs. Not all
pages (in some cases, that would be an advantage) but specific pages in the
application. For those pages, the following behaviors were
required:</p><ul><li>Set the X-Frame-Options response header to
"DENY"</li><li>Include JavaScript to "pop" the page out of a frame, if in
one</li></ul><p>Again, this <em>could</em> be done by having a specific
base-class that included a <code>beginRender()</code> method, but the
meta-programming approach is nearly as easy and much more flexible.</p><h2
id="Meta-ProgrammingPageContent-ComponentMeta-Data">Component
Meta-Data</h2><p>In Tapestry, every component (and remember, pages are
components) has <em>meta data</em>: an extra set of key/value pairs stored in
the component's <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html";>ComponentResources</a>.</p><p>By
hooking into the component class transformation pipeline, we can change an
annotation into meta-data that can be accessed by a filter.</p><h2
id="Meta-ProgrammingPageContent-DefiningtheAnnotation">Defining the
Annotation</h2><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ForbidFraming.java</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.fnord.annotations;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
@@ -86,7 +98,9 @@ import java.lang.annotation.Target;
public @interface ForbidFraming {
}
-</plain-text-body><p>This annotation presence is all that's needed; there
aren't any additional attributes to configure it.</p><h2
id="Meta-ProgrammingPageContent-ConvertingtheAnnotationintoMeta-Data">Converting
the Annotation into Meta-Data</h2><p>This is in three parts:</p><ul><li>Define
the meta-data key, and define a constant for that key</li><li>Set a default
meta-data value for the key</li><li>Set a different value for the key when the
annotation is present</li></ul><p>Our key is just "forbid-framing", with values
"true" and "false". The default is "false".</p><h3
id="Meta-ProgrammingPageContent-DefiningtheConstant">Defining the
Constant</h3><parameter ac:name="language">java</parameter><parameter
ac:name="title">FnordSymbols.java</parameter><plain-text-body>package com.fnord;
+</pre>
+</div></div><p>This annotation presence is all that's needed; there aren't any
additional attributes to configure it.</p><h2
id="Meta-ProgrammingPageContent-ConvertingtheAnnotationintoMeta-Data">Converting
the Annotation into Meta-Data</h2><p>This is in three parts:</p><ul><li>Define
the meta-data key, and define a constant for that key</li><li>Set a default
meta-data value for the key</li><li>Set a different value for the key when the
annotation is present</li></ul><p>Our key is just "forbid-framing", with values
"true" and "false". The default is "false".</p><h3
id="Meta-ProgrammingPageContent-DefiningtheConstant">Defining the
Constant</h3><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>FnordSymbols.java</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.fnord;
import org.apache.tapestry5.services.BaseURLSource;
@@ -104,7 +118,9 @@ public class FnordSymbols {
public static final String FORBID_FRAMING = "forbid-framing";
}
-</plain-text-body><h3
id="Meta-ProgrammingPageContent-SettingtheMeta-DataDefault">Setting the
Meta-Data Default</h3><p>Next, we'll create a module just for the logic
directly related to framing. In the module, we'll define the default value for
the meta-data.</p><parameter ac:name="language">java</parameter><parameter
ac:name="title">ForbidFramingModule.class</parameter><plain-text-body>package
com.fnord.services.forbidframing;
+</pre>
+</div></div><h3
id="Meta-ProgrammingPageContent-SettingtheMeta-DataDefault">Setting the
Meta-Data Default</h3><p>Next, we'll create a module just for the logic
directly related to framing. In the module, we'll define the default value for
the meta-data.</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ForbidFramingModule.class</b></div><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.fnord.services.forbidframing;
import org.apache.tapestry5.ioc.MappedConfiguration;
import org.apache.tapestry5.ioc.annotations.Contribute;
@@ -122,20 +138,26 @@ public class ForbidFramingModule {
configuration.add(FnordSymbols.FORBID_FRAMING, "false");
}
}
-</plain-text-body><h3
id="Meta-ProgrammingPageContent-MappingtheAnnotation">Mapping the
Annotation</h3><p>Most of the work has already been done for us: we just have
to make a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/MetaWorker.html";>MetaWorker</a>
service, which is already plugged into the component class transformation
pipeline. MetaWorker spots the annotations we define and uses a second object,
a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/MetaDataExtractor.html";>MetaDataExtractor</a>
we provide, to convert the annotation into a meta-data value.</p><parameter
ac:name="language">java</parameter><parameter
ac:name="lang">java</parameter><parameter
ac:name="title">ForbidFramingModule.java (partial)</parameter><plain-text-body>
@Contribute(MetaWorker.class)
+</pre>
+</div></div><h3 id="Meta-ProgrammingPageContent-MappingtheAnnotation">Mapping
the Annotation</h3><p>Most of the work has already been done for us: we just
have to make a contribution to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/MetaWorker.html";>MetaWorker</a>
service, which is already plugged into the component class transformation
pipeline. MetaWorker spots the annotations we define and uses a second object,
a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/MetaDataExtractor.html";>MetaDataExtractor</a>
we provide, to convert the annotation into a meta-data value.</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeHeader
panelHeader pdl" style="border-bottom-width: 1px;"><b>ForbidFramingModule.java
(partial)</b></div><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> @Contribute(MetaWorker.class)
public static void mapAnnotationsToMetaDataValue(
MappedConfiguration<Class, MetaDataExtractor> configuration) {
configuration
.add(ForbidFraming.class, new FixedExtractor<ForbidFraming>(
FnordSymbols.FORBID_FRAMING));
}
-</plain-text-body><p>If the ForbidFraming annotation had attributes, we would
have provided an implementation of MetaDataExtractor that examined those
attributes to set the meta-data value. Since it has no attributes, the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/FixedExtractor.html";>FixedExtractor</a>
class can be used. The argument is the meta-data key, and the default value is
"true".</p><h2
id="Meta-ProgrammingPageContent-PluggingIntoPageRendering">Plugging Into Page
Rendering</h2><p>The work we ultimately want to do occurs when rendering a
page. Tapestry defines a <a href="pipelinebuilder-service.html">pipeline</a>
for that overall process. The point of a pipeline is that we can add filters to
it. We'll add a filter that checks for the meta-data key and adds the response
header and JavaScript.</p><p>The service is <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/s
ervices/MarkupRenderer.html">MarkupRenderer</a>, which (being a pipeline
service), takes a configuration of filters (in this case, <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a>.</p><p>We
contribute into the pipeline; the order is important: since the filter will
need to write JavaScript, it must be added <em>after</em> the built-in filter
that provides the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>
environmental object.</p><parameter
ac:name="language">java</parameter><parameter
ac:name="lang">java</parameter><parameter
ac:name="title">ForbidFramingModule.java (partial)</parameter><plain-text-body>
@Contribute(MarkupRenderer.class)
+</pre>
+</div></div><p>If the ForbidFraming annotation had attributes, we would have
provided an implementation of MetaDataExtractor that examined those attributes
to set the meta-data value. Since it has no attributes, the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/FixedExtractor.html";>FixedExtractor</a>
class can be used. The argument is the meta-data key, and the default value is
"true".</p><h2
id="Meta-ProgrammingPageContent-PluggingIntoPageRendering">Plugging Into Page
Rendering</h2><p>The work we ultimately want to do occurs when rendering a
page. Tapestry defines a <a href="pipelinebuilder-service.html">pipeline</a>
for that overall process. The point of a pipeline is that we can add filters to
it. We'll add a filter that checks for the meta-data key and adds the response
header and JavaScript.</p><p>The service is <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/service
s/MarkupRenderer.html">MarkupRenderer</a>, which (being a pipeline service),
takes a configuration of filters (in this case, <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html";>MarkupRendererFilter</a>.</p><p>We
contribute into the pipeline; the order is important: since the filter will
need to write JavaScript, it must be added <em>after</em> the built-in filter
that provides the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html";>JavaScriptSupport</a>
environmental object.</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>ForbidFramingModule.java (partial)</b></div><div class="codeContent
panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;"> @Contribute(MarkupRenderer.class)
public static void addFilter(
OrderedConfiguration<MarkupRendererFilter> configuration) {
configuration.addInstance("ForbidFraming", ForbidFramingFilter.class,
"after:JavascriptSupport");
}
-</plain-text-body><p>How do you know what filters are built-in and where to
add your own? The right starting point is the JavaDoc for the method of
TapestryModule that contributes the base set: <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/modules/TapestryModule.html";>contributeMarkupRenderer()</a></p><h2
id="Meta-ProgrammingPageContent-ImplementingtheFilter">Implementing the
Filter</h2><p>Everything comes together in the filter:</p><parameter
ac:name="language">java</parameter><parameter
ac:name="title">ForbidFramingFilter.java</parameter><plain-text-body>package
com.fnord.services.forbidframing;
+</pre>
+</div></div><p>How do you know what filters are built-in and where to add your
own? The right starting point is the JavaDoc for the method of TapestryModule
that contributes the base set: <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/modules/TapestryModule.html";>contributeMarkupRenderer()</a></p><h2
id="Meta-ProgrammingPageContent-ImplementingtheFilter">Implementing the
Filter</h2><p>Everything comes together in the filter:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>ForbidFramingFilter.java</b></div><div
class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">package com.fnord.services.forbidframing;
import org.apache.tapestry5.MarkupWriter;
import org.apache.tapestry5.ioc.annotations.Inject;
@@ -183,13 +205,16 @@ public class ForbidFramingFilter impleme
}
}
-</plain-text-body><p>There's a bit going on in this short piece of code. The
heart of the code is the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MetaDataLocator.html";>MetaDataLocator</a>
service; given a meta-data key and a page name, it can not only extract the
value, but then <a href="ioc-coerce.html">coerce</a> it to a desired type, all
in one go.</p><p>How do we know which page is being rendered? Before Tapestry
5.2 that was a small challenge, but 5.2 adds a method to <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html#getActivePageName()">RequestGlobals</a>
for this exact purpose.</p><p>Both Request and JavaScriptSupport are
per-thread/per-request services. You don't see that here, because that's part
of the service definition, and invisible to the consumer code, as
here.</p><p>Of course, it is vitally important that the filter re-invoke <code>
markup()</code> on the next renderer in the pipeline (you can see that as the
last line of the method).</p><p>This code makes one assumption: that the fnord
application's Layout component added fnord.js to every page. That's necessary
for the JavaScript that's added:</p><parameter
ac:name="language">js</parameter><parameter
ac:name="lang">javascript</parameter><parameter ac:name="title">fnord.js
(partial)</parameter><plain-text-body>Fnord = {
+</pre>
+</div></div><p>There's a bit going on in this short piece of code. The heart
of the code is the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MetaDataLocator.html";>MetaDataLocator</a>
service; given a meta-data key and a page name, it can not only extract the
value, but then <a href="ioc-coerce.html">coerce</a> it to a desired type, all
in one go.</p><p>How do we know which page is being rendered? Before Tapestry
5.2 that was a small challenge, but 5.2 adds a method to <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html#getActivePageName()">RequestGlobals</a>
for this exact purpose.</p><p>Both Request and JavaScriptSupport are
per-thread/per-request services. You don't see that here, because that's part
of the service definition, and invisible to the consumer code, as
here.</p><p>Of course, it is vitally important that the filter re-invoke
<code>markup
()</code> on the next renderer in the pipeline (you can see that as the last
line of the method).</p><p>This code makes one assumption: that the fnord
application's Layout component added fnord.js to every page. That's necessary
for the JavaScript that's added:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeHeader panelHeader pdl"
style="border-bottom-width: 1px;"><b>fnord.js (partial)</b></div><div
class="codeContent panelContent pdl">
+<pre class="brush: js; gutter: false; theme: Default"
style="font-size:12px;">Fnord = {
popOutOfFrame : function() {
if (top != self)
top.location.replace(location);
}
}
-</plain-text-body><h2
id="Meta-ProgrammingPageContent-Conclusion">Conclusion</h2><p>That's it: with
the above code, simply adding the @ForbidFraming annotation to a page will add
the response header and associated JavaScript; no inheritance hassles. This
basic pattern can be applied to a wide range of cross-cutting concerns, such as
security, transaction management, logging, or virtually any other kind of
situation that would normally be solved with inheritance or ugly boilerplate
code.</p><rich-text-body><p>The code in this example was designed for Tapestry
version 5.2 and later.</p></rich-text-body></div>
+</pre>
+</div></div><h2
id="Meta-ProgrammingPageContent-Conclusion">Conclusion</h2><p>That's it: with
the above code, simply adding the @ForbidFraming annotation to a page will add
the response header and associated JavaScript; no inheritance hassles. This
basic pattern can be applied to a wide range of cross-cutting concerns, such as
security, transaction management, logging, or virtually any other kind of
situation that would normally be solved with inheritance or ugly boilerplate
code.</p><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The code in this example was
designed for Tapestry version 5.2 and later.</p></div></div></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/object-providers.html
==============================================================================
--- websites/production/tapestry/content/object-providers.html (original)
+++ websites/production/tapestry/content/object-providers.html Wed Sep 20
12:29:16 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"/>
@@ -36,26 +44,13 @@
<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">Object Providers</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">Object Providers</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,16 +62,22 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>When you don't provide the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html";>InjectService</a>
annotation on a parameter (to a service builder method or constructor),
Tapestry will resolve the parameter automatically.</p><p>This is called
<em>object injection</em>, rather than <em>service injection</em>, because the
value that will ultimately be injected is not necessarily a service; it may be
some arbitrary object.</p><p>If this sounds vague, its because there is not
just one <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectProvider.html";>ObjectProvider</a>;
there's a whole set of them, forming a <a
href="chainbuilder-service.html">chain of command</a>. The commands in the
chain may provide an object based on the parameter type, or based on additional
annotations on the parameter.</p><p>There are
several built-in object providers:</p><ul><li>Check for @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Value</a>
annotation</li><li>Check for @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Symbol.html";>Symbol</a>
annotation</li><li>Check for a <em>unique</em> service in the Registry whose
service interface matches the parameter type<br clear="none"> Usually, the
@Inject annotation is supplemented by an additional annotation which triggers a
specific ObjectProvider to provide the value.</li></ul><h1
id="ObjectProviders-@ValueAnnotationProvider">@Value Annotation
Provider</h1><p>The Value annotation allows a literal value to be injected.
When combined with <a href="symbols.html">symbols</a>, they represent a way
for parts of the overall service network to be spot-configured. For
example:</p><parameter ac:name="">java</parameter><plain-text-bo
dy> public MyService build(@Value("${max-seconds}") long maxSeconds)
+ <div id="ConfluenceContent"><p>When you don't provide the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/InjectService.html";>InjectService</a>
annotation on a parameter (to a service builder method or constructor),
Tapestry will resolve the parameter automatically.</p><p>This is called
<em>object injection</em>, rather than <em>service injection</em>, because the
value that will ultimately be injected is not necessarily a service; it may be
some arbitrary object.</p><p>If this sounds vague, its because there is not
just one <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/ObjectProvider.html";>ObjectProvider</a>;
there's a whole set of them, forming a <a
href="chainbuilder-service.html">chain of command</a>. The commands in the
chain may provide an object based on the parameter type, or based on additional
annotations on the parameter.</p><p>There are
several built-in object providers:</p><ul><li>Check for @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Value.html";>Value</a>
annotation</li><li>Check for @<a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Symbol.html";>Symbol</a>
annotation</li><li>Check for a <em>unique</em> service in the Registry whose
service interface matches the parameter type<br clear="none"> Usually, the
@Inject annotation is supplemented by an additional annotation which triggers a
specific ObjectProvider to provide the value.</li></ul><h1
id="ObjectProviders-@ValueAnnotationProvider">@Value Annotation
Provider</h1><p>The Value annotation allows a literal value to be injected.
When combined with <a href="symbols.html">symbols</a>, they represent a way
for parts of the overall service network to be spot-configured. 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 MyService build(@Value("${max-seconds}") long
maxSeconds)
{
return new MyServiceImpl(maxSeconds);
- }</plain-text-body><p>Here, the MyService service requires a configuration
of a number of seconds. The value is supplied as a symbol, with a factory
default that may be overwritten with an application default.</p><p>Usually, the
symbol reference is only part of the string, i.e.
<code>@Value("${report.dir}/${report.name}.txt")</code></p><h1
id="ObjectProviders-@SymbolAnnotationProvider">@Symbol Annotation
Provider</h1><p>This is closely related to the @Value annotation approach,
except that the annotation directly specifies a symbol name.</p><parameter
ac:name="">java</parameter><plain-text-body> public MyService
build(@Symbol("max-seconds") long maxSeconds)
+ }</pre>
+</div></div><p>Here, the MyService service requires a configuration of a
number of seconds. The value is supplied as a symbol, with a factory default
that may be overwritten with an application default.</p><p>Usually, the symbol
reference is only part of the string, i.e.
<code>@Value("${report.dir}/${report.name}.txt")</code></p><h1
id="ObjectProviders-@SymbolAnnotationProvider">@Symbol Annotation
Provider</h1><p>This is closely related to the @Value annotation approach,
except that the annotation directly specifies a symbol name.</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 MyService build(@Symbol("max-seconds") long
maxSeconds)
{
return new MyServiceImpl(maxSeconds);
- }</plain-text-body><h1 id="ObjectProviders-ServiceProvider">Service
Provider</h1><p>This is always that last object provider checked.</p><p>A
<em>single</em> service must exist whose service interface matches the
parameter type. This is <em>not</em> an exact match: a search is made for any
and all services whose service interface is a super class of the parameter
type.</p><p>An exception is thrown if there are no matches, or if there are
multiple matches.</p><h1 id="ObjectProviders-AliasObjectProvider">Alias Object
Provider</h1><p>The tapestry-core module defines the <a
href="aliases.html">Alias object provider</a>, which is used as a way to
override services or disambiguate services (when multiple services implement
the same interface).</p><h1 id="ObjectProviders-DefiningNewProviders">Defining
New Providers</h1><p>New providers can be specified by contributing to the
MasterObjectProvider service's configuration. The configuration is mapped, with
the keys being the provider prefi
x, and the values being the object provider
implementation.</p><p>Example:</p><parameter
ac:name="">java</parameter><plain-text-body> public void
contributeMasterObjectProvider(OrderedConfiguration<ObjectProvider>
configuration)
+ }</pre>
+</div></div><h1 id="ObjectProviders-ServiceProvider">Service
Provider</h1><p>This is always that last object provider checked.</p><p>A
<em>single</em> service must exist whose service interface matches the
parameter type. This is <em>not</em> an exact match: a search is made for any
and all services whose service interface is a super class of the parameter
type.</p><p>An exception is thrown if there are no matches, or if there are
multiple matches.</p><h1 id="ObjectProviders-AliasObjectProvider">Alias Object
Provider</h1><p>The tapestry-core module defines the <a
href="aliases.html">Alias object provider</a>, which is used as a way to
override services or disambiguate services (when multiple services implement
the same interface).</p><h1 id="ObjectProviders-DefiningNewProviders">Defining
New Providers</h1><p>New providers can be specified by contributing to the
MasterObjectProvider service's configuration. The configuration is mapped, with
the keys being the provider prefix, and th
e values being the object provider implementation.</p><p>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 void
contributeMasterObjectProvider(OrderedConfiguration<ObjectProvider>
configuration)
{
configuration.add("MyObject", new MyObjectProvider());
- }</plain-text-body><p>This establishes a name for the object provider
(useful if the exact order of execution of the provider, relative to other
providers, is relevant).</p><p>Of course, this is a simplified example. In a
real scenario, the provider is most likely a service with its own
dependencies.</p><p> </p><p></p></div>
+ }</pre>
+</div></div><p>This establishes a name for the object provider (useful if the
exact order of execution of the provider, relative to other providers, is
relevant).</p><p>Of course, this is a simplified example. In a real scenario,
the provider is most likely a service with its own
dependencies.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/ordering-by-constraints.html
==============================================================================
--- websites/production/tapestry/content/ordering-by-constraints.html (original)
+++ websites/production/tapestry/content/ordering-by-constraints.html Wed Sep
20 12:29:16 2017
@@ -36,26 +36,13 @@
<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">Ordering by Constraints</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">Ordering by Constraints</h1></div></div>
<div class="clearer"></div>
</div>
@@ -67,7 +54,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p>Tapestry IoC has two specific
areas where it must put some form of contribution into a specific
order:</p><ul><li><a href="tapestry-ioc-configuration.html">Ordered
Configurations</a>, where different modules may contribute into a service's
configuration</li><li><a href="tapestry-ioc-decorators.html">Service
Decorators</a> which must be applied to services from a number of modules.<br
clear="none"> In both these cases, objects (either contributions to a
configuration, or decorators) are assigning qualified IDs, simple IDs qualified
with the containing/contributing module's ID.</li></ul><p>Because the
contributions can come from different modules, and there isn't a specific order
in which the service contribution methods are invoked, there is no natural
ordering of the contributed objects.</p><p>To resolve this,
<em>constraints</em> are applied to each contribution. These constraints
control what other objects must come before a contrib
ution or after it.</p><p>The constraints are specified using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Order.html";>Order</a>
annotation (for service decorator methods), or as variable arguments at the
end of the add() method for ordered configurations.</p><p>Often a single
contribution will have more than one constraint.</p><h1
id="OrderingbyConstraints-ConstraintTypes">Constraint Types</h1><p>Each
constraint string begins with a prefix, <code>before:</code> or
<code>after:</code>, used to identify the type of constraint.</p><p>The
remainder of the constraint string is a comma-separated list of
<em>patterns</em>. The contributed object will be ordered before or after the
contributions identified by the patterns.</p><p><parameter
ac:name="">Match_Patterns</parameter></p><h1
id="OrderingbyConstraints-ConstraintMatchPatterns">Constraint Match
Patterns</h1><p>A constraint match pattern is used to select one or mo
re objects by their ID.</p><p>Match patterns support a very simple kind of
wildcard matching. A <code>*</code> (asterisk character) may appear at the
start and/or end of the pattern, and it will match zero or more characters
there. Thus you can have patterns such as <code>Data*</code> or
<code>*Logic</code> or even <code>*User*</code>.</p><p>Matching is <a
href="case-insensitivity.html">case
insensitive</a>.</p><p> </p><p></p></div>
+ <div id="ConfluenceContent"><p>Tapestry IoC has two specific
areas where it must put some form of contribution into a specific
order:</p><ul><li><a href="tapestry-ioc-configuration.html">Ordered
Configurations</a>, where different modules may contribute into a service's
configuration</li><li><a href="tapestry-ioc-decorators.html">Service
Decorators</a> which must be applied to services from a number of modules.<br
clear="none"> In both these cases, objects (either contributions to a
configuration, or decorators) are assigning qualified IDs, simple IDs qualified
with the containing/contributing module's ID.</li></ul><p>Because the
contributions can come from different modules, and there isn't a specific order
in which the service contribution methods are invoked, there is no natural
ordering of the contributed objects.</p><p>To resolve this,
<em>constraints</em> are applied to each contribution. These constraints
control what other objects must come before a contrib
ution or after it.</p><p>The constraints are specified using the @<a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Order.html";>Order</a>
annotation (for service decorator methods), or as variable arguments at the
end of the add() method for ordered configurations.</p><p>Often a single
contribution will have more than one constraint.</p><h1
id="OrderingbyConstraints-ConstraintTypes">Constraint Types</h1><p>Each
constraint string begins with a prefix, <code>before:</code> or
<code>after:</code>, used to identify the type of constraint.</p><p>The
remainder of the constraint string is a comma-separated list of
<em>patterns</em>. The contributed object will be ordered before or after the
contributions identified by the patterns.</p><p><span
class="confluence-anchor-link"
id="OrderingbyConstraints-Match_Patterns"></span></p><h1
id="OrderingbyConstraints-ConstraintMatchPatterns">Constraint Match
Patterns</h1><p>A constraint mat
ch pattern is used to select one or more objects by their ID.</p><p>Match
patterns support a very simple kind of wildcard matching. A <code>*</code>
(asterisk character) may appear at the start and/or end of the pattern, and it
will match zero or more characters there. Thus you can have patterns such as
<code>Data*</code> or <code>*Logic</code> or even
<code>*User*</code>.</p><p>Matching is <a href="case-insensitivity.html">case
insensitive</a>.</p><p> </p><p></p></div>
</div>
<div class="clearer"></div>
![http://tapestry.apache.org/images/tapestry_small.png"](http://tapestry.apache.org/images/tapestry_small.png"){kind=link}