You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tapestry.apache.org by bu...@apache.org on 2017/09/26 19:20:28 UTC
svn commit: r1018755 [6/15] - in /websites/production/tapestry/content: ./
cache/
Modified: websites/production/tapestry/content/general-questions.html
==============================================================================
--- websites/production/tapestry/content/general-questions.html (original)
+++ websites/production/tapestry/content/general-questions.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,16 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h2 id="GeneralQuestions-GeneralQuestions">General Questions</h2><p><style type="text/css">/*<![CDATA[*/
-div.rbtoc1499639545088 {padding: 0px;}
-div.rbtoc1499639545088 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1499639545088 li {margin-left: 0px;padding-left: 0px;}
-
-/*]]>*/</style></p><div class="toc-macro rbtoc1499639545088">
-<ul class="toc-indentation"><li><a href="#GeneralQuestions-GeneralQuestions">General Questions</a>
-<ul class="toc-indentation"><li><a href="#GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get started with Tapestry?</a></li><li><a href="#GeneralQuestions-WhydoesTapestryusePrototype?WhynotinsertfavoriteJavaScriptlibraryhere?">Why does Tapestry use Prototype? Why not insert favorite JavaScript library here?</a></li><li><a href="#GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why does Tapestry have its own Inversion of Control Container? Why not Spring or Guice?</a></li><li><a href="#GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I upgrade from Tapestry 4 to Tapestry 5?</a></li><li><a href="#GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How do I upgrade from one version of Tapestry 5 to another?</a></li></ul>
-</li></ul>
-</div><h3 id="GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get started with Tapestry?</h3><p>The easiest way to get started is to use <a class="external-link" href="http://maven.apache.org">Apache Maven</a> to create your initial project; Maven can use an <em>archetype</em> (a kind of project template) to create a bare-bones Tapestry application for you. See the <a href="getting-started.html">Getting Started</a> page for more details.</p><p>Even without Maven, Tapestry is quite easy to set up. You just need to <a href="download.html">download</a> the binaries and setup your build to place them inside your WAR's WEB-INF/lib folder. The rest is just some one-time <a href="configuration.html">configuration of the web.xml deployment descriptor</a>.</p><h3 id="GeneralQuestions-WhydoesTapestryusePrototype?WhynotinsertfavoriteJavaScriptlibraryhere?">Why does Tapestry use Prototype? Why not <em>insert favorite JavaScript library here</em>?</h3><p>An important goal for Tapest
ry is seamless DHTML and Ajax integration. To serve that goal, it was important that the built in components be capable of Ajax operations, such as dynamically re-rendering parts of the page. Because of that, it made sense to bundle a well-known JavaScript library as part of Tapestry.</p><p>At the time (this would be 2006-ish), Prototype and Scriptaculous were well known and well documented, and jQuery was just getting started.</p><p>The intent has always been to make this aspect of Tapestry pluggable. Tapestry 5.4 includes the option of either Prototype or jQuery Tapestry 5.5 will remove Prototype as an option..</p><h3 id="GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why does Tapestry have its own Inversion of Control Container? Why not Spring or Guice?</h3><p>An Inversion of Control Container is <em>the</em> key piece of Tapestry's infrastructure. It is absolutely necessary to create software as robust, performant ,and extensible as T
apestry.</p><p>Tapestry IoC includes a number of features that distinguish itself from other containers:</p><ul><li>Configured in code, not XML</li><li>Built-in extension mechanism for services: configurations and contributions</li><li>Built-in aspect oriented programming model (service decorations and advice)</li><li>Easy modularization</li><li>Best-of-breed exception reporting</li></ul><p>Because Tapestry is implemented on top of its IoC container, and because the container makes it easy to extend or replace any service inside the container, it is possible to make the small changes to Tapestry needed to customize it to any project's needs.</p><h3 id="GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I upgrade from Tapestry 4 to Tapestry 5?</h3><p>There is no existing tool that supports upgrading from Tapestry 4 to Tapestry 5; Tapestry 5 is a complete rewrite.</p><p>Many of the basic concepts in Tapestry 4 are still present in Tapestry 5, but refactored, improved, str
eamlined, and simplified. The basic concept of pages, templates and components are largely the same. Other aspects, such as server-side event handling, is markedly different.</p><h3 id="GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How do I upgrade from one version of Tapestry 5 to another?</h3><p>A lot of effort goes into making an upgrade from one Tapestry 5 release to another go smoothly. In the general case, it is just a matter of updating the version number in your Maven <code>build.xml</code> or Gradle <code>build.gradle</code> file and executing the appropriate commands (e.g., <code>gradle idea</code> or <code>mvn eclipse:eclipse</code>) to bring your local workspace up to date with the latest binaries.</p><p>After changing dependencies, you should always perform a clean recompile of your application.</p><p>We make every effort to ensure backwards-compatibility. Tapestry is mostly coded in terms of interfaces; those interfaces are stable to a point: inter
faces your code is expected to implement are usually completely frozen; interfaces your code is expected to invoke, such as the interfaces to IoC services, are stable, but may have new methods added in a release; existing methods are not changed.</p><p>In <em>rare</em> cases a choice is necessary between fixing bugs (or adding essential functionality) and maintaining complete backwards compatibility; in those cases, an incompatible change may be introduced. These are always discussed in detail in the <a href="release-notes.html">Release Notes</a> for the specific release. You should always read the release notes before attempting an upgrade, and always (really, <em>always</em>) be prepared to retest your application afterwards.</p><p>Note that you should be careful any time you make use of <strong>internal</strong> APIs (you can tell an API is internal by the package name, <code>org.apache.tapestry5.internal...</code>. Internal APIs may change <em>at any time</em>; there's no guara
ntee of backwards compatibility. Please always check on the documentation, or consult the user mailing list, to see if there's a stable, public alternative. If you do make use of internal APIs, be sure to get a discussion going so that your needs can be met in the future by a stable, public API.</p><p><span style="color: rgb(83,145,38);font-size: 16.0px;line-height: 1.5625;">Why are there both Request and HttpServletRequest?</span></p><p>Tapestry's Request interface is <em>very</em> close to the standard HttpServletRequest interface. It differs in a few ways, omitting some unneeded methods, and adding a couple of new methods (such as <code>isXHR()</code>), as well as changing how some existing methods operate. For example, <code>getParameterNames()</code> returns a sorted List of Strings; HttpServletRequest returns an Enumeration, which is a very dated approach.</p><p>However, the stronger reason for Request (and the related interfaces Response and Session) is to enable the support
for Portlets at some point in the future. By writing code in terms of Tapestry's Request, and not HttpServletRequest, you can be assured that the same code will operate in both Servlet Tapestry and Portlet Tapestry.</p></div>
+ <div id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2 id="GeneralQuestions-GeneralQuestions">General Questions</h2><p></p><h3 id="GeneralQuestions-HowdoIgetstartedwithTapestry?">How do I get started with Tapestry?</h3><p>The easiest way to get started is to use <a class="external-link" href="http://maven.apache.org">Apache Maven</a> to create your initial project; Maven can use an <em>archetype</em> (a kind of project template) to create a bare-bones Tapestry application for you. See the <a href="getting-started.html">Getting Started</a> page for more details.</p><p>Even without Maven, Tapestry is quite easy to set up. You just need to <a href="download.html">download</a> the binaries and setup your build to place them inside your WAR's WEB-INF/lib folder. The rest is just some one-time <a href="configuration.html">configuration of the web.xml deployment descriptor</a>.</p><h3 id="GeneralQuestions-WhydoesTapestryusePrototype?Whynotinsertfa
voriteJavaScriptlibraryhere?">Why does Tapestry use Prototype? Why not <em>insert favorite JavaScript library here</em>?</h3><p>An important goal for Tapestry is seamless DHTML and Ajax integration. To serve that goal, it was important that the built in components be capable of Ajax operations, such as dynamically re-rendering parts of the page. Because of that, it made sense to bundle a well-known JavaScript library as part of Tapestry.</p><p>At the time (this would be 2006-ish), Prototype and Scriptaculous were well known and well documented, and jQuery was just getting started.</p><p>The intent has always been to make this aspect of Tapestry pluggable. Tapestry 5.4 includes the option of either Prototype or jQuery Tapestry 5.5 will remove Prototype as an option..</p><h3 id="GeneralQuestions-WhydoesTapestryhaveitsownInversionofControlContainer?WhynotSpringorGuice?">Why does Tapestry have its own Inversion of Control Container? Why not Spring or Guice?</h3><p>An Inversion of Contro
l Container is <em>the</em> key piece of Tapestry's infrastructure. It is absolutely necessary to create software as robust, performant ,and extensible as Tapestry.</p><p>Tapestry IoC includes a number of features that distinguish itself from other containers:</p><ul><li>Configured in code, not XML</li><li>Built-in extension mechanism for services: configurations and contributions</li><li>Built-in aspect oriented programming model (service decorations and advice)</li><li>Easy modularization</li><li>Best-of-breed exception reporting</li></ul><p>Because Tapestry is implemented on top of its IoC container, and because the container makes it easy to extend or replace any service inside the container, it is possible to make the small changes to Tapestry needed to customize it to any project's needs.</p><h3 id="GeneralQuestions-HowdoIupgradefromTapestry4toTapestry5?">How do I upgrade from Tapestry 4 to Tapestry 5?</h3><p>There is no existing tool that supports upgrading from Tapestry 4 to
Tapestry 5; Tapestry 5 is a complete rewrite.</p><p>Many of the basic concepts in Tapestry 4 are still present in Tapestry 5, but refactored, improved, streamlined, and simplified. The basic concept of pages, templates and components are largely the same. Other aspects, such as server-side event handling, is markedly different.</p><h3 id="GeneralQuestions-HowdoIupgradefromoneversionofTapestry5toanother?">How do I upgrade from one version of Tapestry 5 to another?</h3><p>A lot of effort goes into making an upgrade from one Tapestry 5 release to another go smoothly. In the general case, it is just a matter of updating the version number in your Maven <code>build.xml</code> or Gradle <code>build.gradle</code> file and executing the appropriate commands (e.g., <code>gradle idea</code> or <code>mvn eclipse:eclipse</code>) to bring your local workspace up to date with the latest binaries.</p><p>After changing dependencies, you should always perform a clean recompile of your application.<
/p><p>We make every effort to ensure backwards-compatibility. Tapestry is mostly coded in terms of interfaces; those interfaces are stable to a point: interfaces your code is expected to implement are usually completely frozen; interfaces your code is expected to invoke, such as the interfaces to IoC services, are stable, but may have new methods added in a release; existing methods are not changed.</p><p>In <em>rare</em> cases a choice is necessary between fixing bugs (or adding essential functionality) and maintaining complete backwards compatibility; in those cases, an incompatible change may be introduced. These are always discussed in detail in the <a href="release-notes.html">Release Notes</a> for the specific release. You should always read the release notes before attempting an upgrade, and always (really, <em>always</em>) be prepared to retest your application afterwards.</p><p>Note that you should be careful any time you make use of <strong>internal</strong> APIs (you can
tell an API is internal by the package name, <code>org.apache.tapestry5.internal...</code>. Internal APIs may change <em>at any time</em>; there's no guarantee of backwards compatibility. Please always check on the documentation, or consult the user mailing list, to see if there's a stable, public alternative. If you do make use of internal APIs, be sure to get a discussion going so that your needs can be met in the future by a stable, public API.</p><p><span style="color: rgb(83,145,38);font-size: 16.0px;line-height: 1.5625;">Why are there both Request and HttpServletRequest?</span></p><p>Tapestry's Request interface is <em>very</em> close to the standard HttpServletRequest interface. It differs in a few ways, omitting some unneeded methods, and adding a couple of new methods (such as <code>isXHR()</code>), as well as changing how some existing methods operate. For example, <code>getParameterNames()</code> returns a sorted List of Strings; HttpServletRequest returns an Enumeration
, which is a very dated approach.</p><p>However, the stronger reason for Request (and the related interfaces Response and Session) is to enable the support for Portlets at some point in the future. By writing code in terms of Tapestry's Request, and not HttpServletRequest, you can be assured that the same code will operate in both Servlet Tapestry and Portlet Tapestry.</p><plain-text-body>{scrollbar}</plain-text-body></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/injection-faq.html
==============================================================================
--- websites/production/tapestry/content/injection-faq.html (original)
+++ websites/production/tapestry/content/injection-faq.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,22 +67,13 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h2 id="InjectionFAQ-Injection">Injection</h2><p>Main article: <a href="injection.html">Injection</a></p><h3 id="InjectionFAQ-What'sthedifferencebetweenthe@Componentand@InjectComponentannotations?">What's the difference between the <code>@Component</code> and <code>@InjectComponent</code> annotations?</h3><p>The <code>@Component</code> annotation is used to define the <em>type</em> of component, and its parameter bindings. When using <code>@Component</code>, the template must not define the type, and any parameter bindings are merged in:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> <a t:id="home" class="nav">Back to home</a>
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @Component(parameters={ "page=index" })
+ <div id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2 id="InjectionFAQ-Injection">Injection</h2><p>Main article: <a href="injection.html">Injection</a></p><h3 id="InjectionFAQ-What'sthedifferencebetweenthe@Componentand@InjectComponentannotations?">What's the difference between the <code>@Component</code> and <code>@InjectComponent</code> annotations?</h3><p>The <code>@Component</code> annotation is used to define the <em>type</em> of component, and its parameter bindings. When using <code>@Component</code>, the template must not define the type, and any parameter bindings are merged in:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> <a t:id="home" class="nav">Back to home</a>
+</plain-text-body><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @Component(parameters={ "page=index" })
private PageLink home;
-</pre>
-</div></div><p>Here the type of component is defined by the field type. The field name is matched against the <code>t:id</code> in the template. The <code>page</code> parameter is set in the Java class, and the informal <code>class</code> parameter is set in the template. If the tag in the template was <code><t:pagelink></code>, or if the template tag included the attribute <code>t:type="pagelink"</code>, then you would see an exception.</p><p>By contrast, <code>@InjectComponent</code> expects the component to be already defined, and doesn't allow any configuration of it:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> <t:form t:id="login"> .... </t:form>
-</pre>
-</div></div><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @InjectComponent
+</plain-text-body><p>Here the type of component is defined by the field type. The field name is matched against the <code>t:id</code> in the template. The <code>page</code> parameter is set in the Java class, and the informal <code>class</code> parameter is set in the template. If the tag in the template was <code><t:pagelink></code>, or if the template tag included the attribute <code>t:type="pagelink"</code>, then you would see an exception.</p><p>By contrast, <code>@InjectComponent</code> expects the component to be already defined, and doesn't allow any configuration of it:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> <t:form t:id="login"> .... </t:form>
+</plain-text-body><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @InjectComponent
private Form login;
-</pre>
-</div></div><p>Again, we're matching the field name to the component id, and you would get an error if the component is not defined in the template.</p><h3 id="InjectionFAQ-What'sthedifferencebetweenthe@InjectPageand@InjectContainerannotations?">What's the difference between the <code>@InjectPage</code> and <code>@InjectContainer</code> annotations?</h3><p>The <code>@InjectPage</code> annotation is used to inject some page in the application into a field of some other page. You often see it used from event handler methods:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @InjectPage
+</plain-text-body><p>Again, we're matching the field name to the component id, and you would get an error if the component is not defined in the template.</p><h3 id="InjectionFAQ-What'sthedifferencebetweenthe@InjectPageand@InjectContainerannotations?">What's the difference between the <code>@InjectPage</code> and <code>@InjectContainer</code> annotations?</h3><p>The <code>@InjectPage</code> annotation is used to inject some page in the application into a field of some other page. You often see it used from event handler methods:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @InjectPage
private ConfirmRegistration confirmRegistration;
Object onSuccessFromRegistrationForm()
@@ -102,31 +83,21 @@
return confirmRegistration;
}
-</pre>
-</div></div><p>This code pattern is used to configure peristent properties of a page before returning it; Tapestry will send a client redirect to the page to present the data.</p><p><code>@InjectContainer</code> can be used inside a component or a mixin. In a component, it injects the immediate container of the component; this is often the top-level page object.</p><p>In a mixin, it injects the component to which the mixin is attached.</p><h3 id="InjectionFAQ-IgetanexceptionbecauseIhavetwoserviceswiththesameinterface,howdoIhandlethis?">I get an exception because I have two services with the same interface, how do I handle this?</h3><p>It's not uncommon to have two or more services that implement the exact same interface. When you inject, you might start by just identifying the type of service to inject:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @Inject
+</plain-text-body><p>This code pattern is used to configure peristent properties of a page before returning it; Tapestry will send a client redirect to the page to present the data.</p><p><code>@InjectContainer</code> can be used inside a component or a mixin. In a component, it injects the immediate container of the component; this is often the top-level page object.</p><p>In a mixin, it injects the component to which the mixin is attached.</p><h3 id="InjectionFAQ-IgetanexceptionbecauseIhavetwoserviceswiththesameinterface,howdoIhandlethis?">I get an exception because I have two services with the same interface, how do I handle this?</h3><p>It's not uncommon to have two or more services that implement the exact same interface. When you inject, you might start by just identifying the type of service to inject:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @Inject
private ComponentEventResultProcessor processor;
-</pre>
-</div></div><p>Which results in the error: <strong>Service interface org.apache.tapestry5.services.ComponentEventResultProcessor is matched by 3 services: AjaxComponentEventResultProcessor, ComponentEventResultProcessor, ComponentInstanceResultProcessor. Automatic dependency resolution requires that exactly one service implement the interface.</strong></p><p>We need more information than just the service interface type in order to identify which of the three services to inject. One possibility is to inject with the correct service id:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @InjectService("ComponentEventResultProcessor")
+</plain-text-body><p>Which results in the error: <strong>Service interface org.apache.tapestry5.services.ComponentEventResultProcessor is matched by 3 services: AjaxComponentEventResultProcessor, ComponentEventResultProcessor, ComponentInstanceResultProcessor. Automatic dependency resolution requires that exactly one service implement the interface.</strong></p><p>We need more information than just the service interface type in order to identify which of the three services to inject. One possibility is to inject with the correct service id:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @InjectService("ComponentEventResultProcessor")
private ComponentEventResultProcessor processor;
-</pre>
-</div></div><p>This works ... but it is clumsy. If the service id, "ComponentEventResultProcessor", ever changes, this code will break. It's not <em>refactoring safe</em>.</p><p>Instead, we should use marker annotations. If we look at <code>TapestryModule</code>, where the ComponentEventResultProcessor service is defined, we'll see it identifies the necessary markers:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @Marker(
+</plain-text-body><p>This works ... but it is clumsy. If the service id, "ComponentEventResultProcessor", ever changes, this code will break. It's not <em>refactoring safe</em>.</p><p>Instead, we should use marker annotations. If we look at <code>TapestryModule</code>, where the ComponentEventResultProcessor service is defined, we'll see it identifies the necessary markers:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @Marker(
{ Primary.class, Traditional.class })
public ComponentEventResultProcessor buildComponentEventResultProcessor(
Map<Class, ComponentEventResultProcessor> configuration)
{
return constructComponentEventResultProcessor(configuration);
}
-</pre>
-</div></div><p>When a service has marker annotations, the annotations present at the <em>point of injection</em> (the field, method parameter, or constructor parameter) are used to select a matching service. The list of services that match by type is then filtered to only include services that have all of the marker annotations present at the point of injection.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"> @Inject
+</plain-text-body><p>When a service has marker annotations, the annotations present at the <em>point of injection</em> (the field, method parameter, or constructor parameter) are used to select a matching service. The list of services that match by type is then filtered to only include services that have all of the marker annotations present at the point of injection.</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body> @Inject
@Traditional @Primary
private ComponentEventResultProcessor processor;
-</pre>
-</div></div><p>The two marker annotations, <code>@Traditional</code> and <code>@Primary</code>, ensure that only a single service matches.</p><h3 id="InjectionFAQ-What'sthedifferencebetween@Injectand@Environmental?">What's the difference between <code>@Inject</code> and <code>@Environmental</code>?</h3><p><code>@Inject</code> is relatively general; it can be used to inject resources specific to a page or component (such as ComponentResources, Logger, or Messages), or it can inject services or other objects obtained from the Tapestry IoC container. Once the page is loaded, the values for these injections never change.</p><p><code>@Environmental</code> is different; it exposes a request-scoped, dynamically bound value:</p><ul><li>"Request scoped": different threads (processing different requests) will see different values when reading the field.</li><li>"Dynamically bound": the value is explicitly placed into the Environment, and can be overridden at any time.</li></ul><p>Environmenta
ls are a form of loosely connected communication between an outer component (or even a service) and an inner component. Example: the Form component places a <code>FormSupport</code> object into the environment. Other components, such as TextField, use the <code>FormSupport</code> when rendering to perform functions such as allocate unique control names or register client-side validations. The TextField doesn't require that the Form component be the immediate container component, or even an ancestor: a Form on one page may, indirectly, communicate with a TextField on some entirely different page. Neither component directly links to the other, the <code>FormSupport</code> is the conduit that connects them.</p><p>The term "Environmental" was chosen as the value "comes from the environment".</p><h3 id="InjectionFAQ-Butwait...IseeIusedthe@Injectannotationanditstillworked.Whatgives?">But wait ... I see I used the <code>@Inject</code> annotation and it still worked. What gives?</h3><p>In c
ertain cases, Tapestry exposes a service (which can be injected) that is a proxy to the environmental; this is primarily for common environmentals, such as <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>, that may be needed outside of component classes. You can see this in TapestryModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>TapestryModule.java (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> /**
+</plain-text-body><p>The two marker annotations, <code>@Traditional</code> and <code>@Primary</code>, ensure that only a single service matches.</p><h3 id="InjectionFAQ-What'sthedifferencebetween@Injectand@Environmental?">What's the difference between <code>@Inject</code> and <code>@Environmental</code>?</h3><p><code>@Inject</code> is relatively general; it can be used to inject resources specific to a page or component (such as ComponentResources, Logger, or Messages), or it can inject services or other objects obtained from the Tapestry IoC container. Once the page is loaded, the values for these injections never change.</p><p><code>@Environmental</code> is different; it exposes a request-scoped, dynamically bound value:</p><ul><li>"Request scoped": different threads (processing different requests) will see different values when reading the field.</li><li>"Dynamically bound": the value is explicitly placed into the Environment, and can be overridden at any time.</li></ul><p>Enviro
nmentals are a form of loosely connected communication between an outer component (or even a service) and an inner component. Example: the Form component places a <code>FormSupport</code> object into the environment. Other components, such as TextField, use the <code>FormSupport</code> when rendering to perform functions such as allocate unique control names or register client-side validations. The TextField doesn't require that the Form component be the immediate container component, or even an ancestor: a Form on one page may, indirectly, communicate with a TextField on some entirely different page. Neither component directly links to the other, the <code>FormSupport</code> is the conduit that connects them.</p><p>The term "Environmental" was chosen as the value "comes from the environment".</p><h3 id="InjectionFAQ-Butwait...IseeIusedthe@Injectannotationanditstillworked.Whatgives?">But wait ... I see I used the <code>@Inject</code> annotation and it still worked. What gives?</h3><
p>In certain cases, Tapestry exposes a service (which can be injected) that is a proxy to the environmental; this is primarily for common environmentals, such as <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>, that may be needed outside of component classes. You can see this in TapestryModule:</p><parameter ac:name="">Java</parameter><parameter ac:name="title">TapestryModule.java (partial)</parameter><plain-text-body> /**
* Builds a proxy to the current {@link JavaScriptSupport} inside this thread's {@link Environment}.
*
* @since 5.2.0
@@ -135,14 +106,11 @@
{
return environmentalBuilder.build(JavaScriptSupport.class);
}
-</pre>
-</div></div><p>This kind of logic is based on the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/EnvironmentalShadowBuilder.html">EnvironmentalShadowBuilder</a> service.</p><h3 id="InjectionFAQ-Ok,butRequestisasingletonservice,notanenvironmental,andIcaninjectthat.IsTapestryreallythreadsafe?">Ok, but Request is a singleton service, not an environmental, and I can inject that. Is Tapestry really thread safe?</h3><p>Yes, of course Tapestry is thread safe. The Request service is another special case, as seen in TapestryModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>TapestryModule.java (partial)</b></div><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;"> public Request buildRequest()
+</plain-text-body><p>This kind of logic is based on the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/EnvironmentalShadowBuilder.html">EnvironmentalShadowBuilder</a> service.</p><h3 id="InjectionFAQ-Ok,butRequestisasingletonservice,notanenvironmental,andIcaninjectthat.IsTapestryreallythreadsafe?">Ok, but Request is a singleton service, not an environmental, and I can inject that. Is Tapestry really thread safe?</h3><p>Yes, of course Tapestry is thread safe. The Request service is another special case, as seen in TapestryModule:</p><parameter ac:name="">Java</parameter><parameter ac:name="title">TapestryModule.java (partial)</parameter><plain-text-body> public Request buildRequest()
{
return shadowBuilder.build(requestGlobals, "request", Request.class);
}
-</pre>
-</div></div><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html">RequestGlobals</a> is a per-thread service. The Request service is a global singleton created by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/PropertyShadowBuilder.html">PropertyShadowBuilder</a> service, but is just a proxy. It has no internal state; invoking a method on the Request service just turns around and extracts the Request object from the per-thread RequestGlobals and invokes the same method there.</p><h3 id="InjectionFAQ-Iuse@Injectonafieldtoinjectaservice,butthefieldisstillnull,whathappened?">I use <code>@Inject</code> on a field to inject a service, but the field is still null, what happened?</h3><p>This can happen when you use the wrong <code>@Inject</code> annotation; for example, com.google.inject.Inject instead of org.apache.tapestry5.ioc.annotations.Inject. T
his can occur when you have TestNG on the classpath, for example, and your IDE is too helpful. Double check your imports when things seem weird.</p><p>Also remember that <code>@Inject</code> on fields works for components and for service implementations or other objects that Tapestry instantiates, but not on arbitrary objects (that are created via Java's new keyword).</p></div>
+</plain-text-body><p><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/RequestGlobals.html">RequestGlobals</a> is a per-thread service. The Request service is a global singleton created by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/PropertyShadowBuilder.html">PropertyShadowBuilder</a> service, but is just a proxy. It has no internal state; invoking a method on the Request service just turns around and extracts the Request object from the per-thread RequestGlobals and invokes the same method there.</p><h3 id="InjectionFAQ-Iuse@Injectonafieldtoinjectaservice,butthefieldisstillnull,whathappened?">I use <code>@Inject</code> on a field to inject a service, but the field is still null, what happened?</h3><p>This can happen when you use the wrong <code>@Inject</code> annotation; for example, com.google.inject.Inject instead of org.apache.tapestry5.ioc.annotations.Inj
ect. This can occur when you have TestNG on the classpath, for example, and your IDE is too helpful. Double check your imports when things seem weird.</p><p>Also remember that <code>@Inject</code> on fields works for components and for service implementations or other objects that Tapestry instantiates, but not on arbitrary objects (that are created via Java's new keyword).</p><plain-text-body>{scrollbar}</plain-text-body></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/injection.html
==============================================================================
--- websites/production/tapestry/content/injection.html (original)
+++ websites/production/tapestry/content/injection.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,84 +67,42 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><p><strong>Injection</strong> is Tapestry's way of making a dependency – such as a resource, asset, component, block or service – available in a page, component, mixin or service class.</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="injection-in-detail.html">Injection in Detail</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="injection-faq.html">Injection FAQ</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="injection.html">Injection</a>
-
-
- </div>
- </li></ul>
-</div>
-
-
-<p>Injection is a key concept in Tapestry, and it is used in several different but related ways.</p><h2 id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC Services</h2><p>Main Article: <a href="tapestry-ioc-overview.html">Tapestry IoC Overview</a></p><p>The Tapestry IoC container makes use of injection primarily through constructors and via parameters to service builder methods.</p><h2 id="Injection-InjectioninComponentClasses">Injection in Component Classes</h2><p>For components, however, Tapestry takes a completely different tack: injection directly into component fields.</p><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html">Inject</a> annotation is used to identify fields that will contain injected services and other resources.</p><p>Tapestry allows for two kinds of injection:</p><ul><li><strong>Default injection</strong>, where Tapestry determines the object to inject into the
field based on its type.</li><li><strong>Explicit injection</strong>, where the particular service to be injected is specified.</li></ul><p>In both cases, the field is transformed into a read only value. As elsewhere in Tapestry, this transformation occurs at runtime (which is very important in terms of being able to test your components). Attempting to update an injected field will result in a runtime exception.</p><p>In addition, there are a few special cases that are triggered by specific field types, or additional annotations, in addition, to @Inject, on a field.</p><h3 id="Injection-BlockInjection">Block Injection</h3><p>For field type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Block</a>, the value of the Inject annotation is the id of the <a href="component-templates.html"><t:block></a> element within the component's template. Normally, the id of the block is determined from the field name (after strippin
g out any leading "_" and "$" characters):</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Inject
+ <div id="ConfluenceContent"><p><strong>Injection</strong> is Tapestry's way of making a dependency – such as a resource, asset, component, block or service – available in a page, component, mixin or service class.</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 = "injection" and space = currentSpace()</parameter></rich-text-body><p>Injection is a key concept in Tapestry, and it is used in several different but related ways.</p><h2 id="Injection-InjectioninTapestryIOCServices">Injection in Tapestry IOC Services</h2><p>Main Article: <a href="tapestry-ioc-overview.html">Tapestry IoC Overview</a></p><p>The Tapestry IoC container makes use of injection prima
rily through constructors and via parameters to service builder methods.</p><h2 id="Injection-InjectioninComponentClasses">Injection in Component Classes</h2><p>For components, however, Tapestry takes a completely different tack: injection directly into component fields.</p><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/annotations/Inject.html">Inject</a> annotation is used to identify fields that will contain injected services and other resources.</p><p>Tapestry allows for two kinds of injection:</p><ul><li><strong>Default injection</strong>, where Tapestry determines the object to inject into the field based on its type.</li><li><strong>Explicit injection</strong>, where the particular service to be injected is specified.</li></ul><p>In both cases, the field is transformed into a read only value. As elsewhere in Tapestry, this transformation occurs at runtime (which is very important in terms of being able to test your c
omponents). Attempting to update an injected field will result in a runtime exception.</p><p>In addition, there are a few special cases that are triggered by specific field types, or additional annotations, in addition, to @Inject, on a field.</p><h3 id="Injection-BlockInjection">Block Injection</h3><p>For field type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/Block.html">Block</a>, the value of the Inject annotation is the id of the <a href="component-templates.html"><t:block></a> element within the component's template. Normally, the id of the block is determined from the field name (after stripping out any leading "_" and "$" characters):</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
private Block foo;
-</pre>
-</div></div><p>Where that is not appropriate, an @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html">Id</a> annotation can be supplied:</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;">@Inject
+</plain-text-body><p>Where that is not appropriate, an @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Id.html">Id</a> annotation can be supplied:</p><plain-text-body>@Inject
@Id("bar")
private Block barBlock;
-</pre>
-</div></div><p>The first injection will inject the Block with id "foo" (as always, case is ignored). The second injection will inject the Block with id "bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For a particular set of field types, Tapestry will inject a <em>resource</em> related to the component, such as its Locale.</p><p>A very common example occurs when a component needs access to its <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">resources</a>. The component can define a field of the appropriate type and use the <code>@Inject</code> annotation without a value:</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;">@Inject
+</plain-text-body><p>The first injection will inject the Block with id "foo" (as always, case is ignored). The second injection will inject the Block with id "bar".</p><h3 id="Injection-ResourceInjection">Resource Injection</h3><p>For a particular set of field types, Tapestry will inject a <em>resource</em> related to the component, such as its Locale.</p><p>A very common example occurs when a component needs access to its <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ComponentResources.html">resources</a>. The component can define a field of the appropriate type and use the <code>@Inject</code> annotation without a value:</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
private ComponentResources resources;
-</pre>
-</div></div><p>Tapestry uses the type of the field, ComponentResources, to determine what to inject into this field.</p><p>The following types are supported for resources injection:</p><ul><li><strong>java.lang.String</strong> – The complete id of the component, which incorporates the complete class name of the containing page and the nested id of the component within the page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for the component (all components within a page use the same locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger instance configured for the component, based on the component's class name. <a class="external-link" href="http://www.slf4j.org/" rel="nofollow">SLF4J</a> is a wrapper around Log4J or other logging toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong> – The resources for the component, often used to generate links related to the component.</li></ul><ul><li><stron
g>org.apache.tapestry5.ioc.Messages</strong> – The component message catalog for the component, from which <a href="injection.html">localized</a> messages can be generated.</li></ul><h3 id="Injection-AssetInjection">Asset Injection</h3><p>Main Article: <a href="assets.html">Assets</a></p><p>When the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html">Path</a> annotation is also present, then the injected value (relative to the component) will be a localized asset.</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;">@Inject
+</plain-text-body><p>Tapestry uses the type of the field, ComponentResources, to determine what to inject into this field.</p><p>The following types are supported for resources injection:</p><ul><li><strong>java.lang.String</strong> – The complete id of the component, which incorporates the complete class name of the containing page and the nested id of the component within the page.</li></ul><ul><li><strong>java.util.Locale</strong> – The locale for the component (all components within a page use the same locale).</li></ul><ul><li><strong>org.slf4j.Logger</strong> – A Logger instance configured for the component, based on the component's class name. <a class="external-link" href="http://www.slf4j.org/" rel="nofollow">SLF4J</a> is a wrapper around Log4J or other logging toolkits.</li></ul><ul><li><strong>org.apache.tapestry5.ComponentResources</strong> – The resources for the component, often used to generate links related to the component.</li></ul><ul><li>
<strong>org.apache.tapestry5.ioc.Messages</strong> – The component message catalog for the component, from which <a href="injection.html">localized</a> messages can be generated.</li></ul><h3 id="Injection-AssetInjection">Asset Injection</h3><p>Main Article: <a href="assets.html">Assets</a></p><p>When the @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Path.html">Path</a> annotation is also present, then the injected value (relative to the component) will be a localized asset.</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
@Path("context:images/top_banner.png")
private Asset banner;
-</pre>
-</div></div><p>Symbols in the annotation value are expanded.</p><h3 id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom EmployeeService service is injected, but any custom or built-in service may be injected in the same way.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">@Inject
+</plain-text-body><p>Symbols in the annotation value are expanded.</p><h3 id="Injection-ServiceInjection">Service Injection</h3><p>Here, a custom EmployeeService service is injected, but any custom or built-in service may be injected in the same way.</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
private EmployeeService employeeService;
-</pre>
-</div></div><p>A large number of services are provided by Tapestry. See the following packages:</p><div class="navmenu" style="float:left; width:15em; background:white; margin:3px; padding:3px">
-<ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html">Core Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html">AJAX Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html">Assets Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html">Dynamic Component Services</a></li></ul>
-</div><div class="navmenu" style="float:left; width:15em; background:white; margin:3px; padding:3px">
-<ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html">JavaScript Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html">Link Transformation Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html">Message Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html">Component Metadata Services</a></li></ul>
-</div><div class="navmenu" style="float:left; width:15em; background:white; margin:3px; padding:3px">
-<ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html">Page Loading Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html">Security Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html">Template Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html">Class Transformation Services</a></li></ul>
-</div><div class="navmenu" style="float:left; width:15em; background:white; margin:3px; padding:3px">
-<ul><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html">Tapestry IOC Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html">Tapestry IOC Cron Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html">Kaptcha Services</a></li><li><a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html">File Upload Services</a></li></ul>
-</div><div style="clear:both"></div> <h3 id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here, a specific object is requested. A @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html">Service</a> annotation is used to identify the service 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;">@Inject
+</plain-text-body><p>A large number of services are provided by Tapestry. See the following packages:<plain-text-body>{float:left|width=15em}
+* [Core Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/package-summary.html]
+* [AJAX Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ajax/package-summary.html]
+* [Assets Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/assets/package-summary.html]
+* [Dynamic Component Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/dynamic/package-summary.html]
+{float}</plain-text-body><plain-text-body>{float:left|width=15em}
+* [JavaScript Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/javascript/package-summary.html]
+* [Link Transformation Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/linktransform/package-summary.html]
+* [Message Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/messages/package-summary.html]
+* [Component Metadata Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/meta/package-summary.html]
+{float}</plain-text-body><plain-text-body>{float:left|width=15em}
+* [Page Loading Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/pageload/package-summary.html]
+* [Security Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/security/package-summary.html]
+* [Template Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/templates/package-summary.html]
+* [Class Transformation Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/transform/package-summary.html]
+{float}</plain-text-body><plain-text-body>{float:left|width=15em}
+* [Tapestry IOC Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/package-summary.html]
+* [Tapestry IOC Cron Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/cron/package-summary.html]
+* [Kaptcha Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/kaptcha/services/package-summary.html]
+* [File Upload Services|http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/upload/services/package-summary.html]
+{float}</plain-text-body><parameter ac:name="atlassian-macro-output-type">INLINE</parameter><plain-text-body><div style="clear:both"></div></plain-text-body> </p><h3 id="Injection-ExplicitServiceInjection">Explicit Service Injection</h3><p>Here, a specific object is requested. A @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Service.html">Service</a> annotation is used to identify the service name.</p><parameter ac:name="">java</parameter><plain-text-body>@Inject
@Service("Request")
private Request request;
-</pre>
-</div></div><p>This is generally not necessary; you should always be able to identify the service to be injected just by type, not by explicit id. Explicit ids have the disadvantage of not being refactoring-safe: this won't happen with the Request service, but perhaps in your own code ... if you rename the service interface and rename the service id to match, your existing injections using the explicit service id will break.</p><h2 id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or other annotations are not sufficient to identify the object or service to inject, Tapestry falls back on two remaining steps. It assumes that the field type will be used to identify a service, by the service interface.</p><p>First, the object provider created by the Alias service is consulted. This object provider is used to disambiguate injections when there is more than one service that implements the same service interface.</p><p>Second, a search for a unique service that imp
lements the interface occurs. This will fail if either there are no services that implement the interface, or there is more than one. In the latter case, you must disambiguate, either with a contribution to the Alias service, or by explicitly identifying the service with the @Service annotation.</p><h2 id="Injection-DefiningNewInjectionLogic">Defining New Injection Logic</h2><p>Anonymous injection is controlled by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html">InjectionProvider</a> service. The configuration for this service is a <a href="chainbuilder-service.html">chain of command</a> for handling component injections.</p></div>
+</plain-text-body><p>This is generally not necessary; you should always be able to identify the service to be injected just by type, not by explicit id. Explicit ids have the disadvantage of not being refactoring-safe: this won't happen with the Request service, but perhaps in your own code ... if you rename the service interface and rename the service id to match, your existing injections using the explicit service id will break.</p><h2 id="Injection-DefaultInjection">Default Injection</h2><p>When the type and/or other annotations are not sufficient to identify the object or service to inject, Tapestry falls back on two remaining steps. It assumes that the field type will be used to identify a service, by the service interface.</p><p>First, the object provider created by the Alias service is consulted. This object provider is used to disambiguate injections when there is more than one service that implements the same service interface.</p><p>Second, a search for a unique service th
at implements the interface occurs. This will fail if either there are no services that implement the interface, or there is more than one. In the latter case, you must disambiguate, either with a contribution to the Alias service, or by explicitly identifying the service with the @Service annotation.</p><h2 id="Injection-DefiningNewInjectionLogic">Defining New Injection Logic</h2><p>Anonymous injection is controlled by the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/InjectionProvider.html">InjectionProvider</a> service. The configuration for this service is a <a href="chainbuilder-service.html">chain of command</a> for handling component injections.</p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/integration-with-existing-applications.html
==============================================================================
--- websites/production/tapestry/content/integration-with-existing-applications.html (original)
+++ websites/production/tapestry/content/integration-with-existing-applications.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,8 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent"><h2 id="Integrationwithexistingapplications-Integrationwithexistingapplications">Integration with existing applications</h2><p>You may have an existing JSP (or Struts, Spring MVC, etc.) application that you want to migrate to Tapestry. It's quite common to do this in stages, moving some functionality into Tapestry and leaving other parts, initially, in the other system. <a href="request-processing-faq.html">You may need to prevent Tapestry from handling certain requests</a>.</p><h3 id="Integrationwithexistingapplications-HowdoImakeaformonaJSPsubmitintoTapestry?">How do I make a form on a JSP submit into Tapestry?</h3><p>Tapestry's Form component does a lot of work while an HTML form is rendering to store all the information needed to handle the form submission in a later request; this is all very specific to Tapestry and the particular construction of your pages and forms; it can't be reproduced from a JSP.</p><p>Fortunately, that isn't n
ecessary: you can have a standard HTML Form submit to a Tapestry page, you just don't get to use all of Tapestry's built in conversion and validation logic.</p><p>All you need to know is how Tapestry converts page class names to page names (that appear in the URL). It's basically a matter of stripping off the <em>root-package</em>.<code>pages</code> prefix from the fully qualified class name. So, for example, if you are building a login screen as a JSP, you might want to have a Tapestry page to receive the user name and password. Let's assume the Tapestry page class is <code>com.example.myapp.pages.LoginForm</code>; the page name will be <code>loginform (although, since </code><span style="line-height: 1.4285715;">Tapestry is case insensitive, LoginForm would work just as well)</span><span style="line-height: 1.4285715;">, and the URL will be </span><code style="line-height: 1.4285715;">/loginform</code><span style="line-height: 1.4285715;">.</span></p><p> </p><div class="
code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;"><form method="post" action="/loginform">
+ <div id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body><h2 id="Integrationwithexistingapplications-Integrationwithexistingapplications">Integration with existing applications</h2><p>You may have an existing JSP (or Struts, Spring MVC, etc.) application that you want to migrate to Tapestry. It's quite common to do this in stages, moving some functionality into Tapestry and leaving other parts, initially, in the other system. <a href="request-processing-faq.html">You may need to prevent Tapestry from handling certain requests</a>.</p><h3 id="Integrationwithexistingapplications-HowdoImakeaformonaJSPsubmitintoTapestry?">How do I make a form on a JSP submit into Tapestry?</h3><p>Tapestry's Form component does a lot of work while an HTML form is rendering to store all the information needed to handle the form submission in a later request; this is all very specific to Tapestry and the particular construction of your pages and forms; it can't be reproduc
ed from a JSP.</p><p>Fortunately, that isn't necessary: you can have a standard HTML Form submit to a Tapestry page, you just don't get to use all of Tapestry's built in conversion and validation logic.</p><p>All you need to know is how Tapestry converts page class names to page names (that appear in the URL). It's basically a matter of stripping off the <em>root-package</em>.<code>pages</code> prefix from the fully qualified class name. So, for example, if you are building a login screen as a JSP, you might want to have a Tapestry page to receive the user name and password. Let's assume the Tapestry page class is <code>com.example.myapp.pages.LoginForm</code>; the page name will be <code>loginform (although, since </code><span style="line-height: 1.4285715;">Tapestry is case insensitive, LoginForm would work just as well)</span><span style="line-height: 1.4285715;">, and the URL will be </span><code style="line-height: 1.4285715;">/loginform</code><span style="line-height: 1.4
285715;">.</span></p><p> </p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body><form method="post" action="/loginform">
<input type="text" value="userName"/>
<br/>
@@ -87,24 +76,19 @@
<input type="submit" value="Login"/>
</form>
-</pre>
-</div></div><p>On the Tapestry side, we can expect that the LoginForm page will be activated; this means that its activate event handler will be invoked. We can leverage this, and Tapestry's RequestParameter annotation:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;">public class LoginForm
+</plain-text-body><p>On the Tapestry side, we can expect that the LoginForm page will be activated; this means that its activate event handler will be invoked. We can leverage this, and Tapestry's RequestParameter annotation:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body>public class LoginForm
{
void onActivate(@RequestParameter("userName") String userName, @RequestParameter("password") String password)
{
// Validate and store credentials, etc.
}
}
-</pre>
-</div></div><p>The RequestParameter annotation extracts the named query parameter from the request, coerces its type from String to the parameter type (here, also String) and passes it into the method.</p><h3 id="Integrationwithexistingapplications-HowdoIshareinformationbetweenaJSPapplicationandtheTapestryapplication?">How do I share information between a JSP application and the Tapestry application?</h3><p>From the servlet container's point of view, there's no difference between a servlet, a JSP, and an entire Tapestry application. They all share the same ServletContext, and (once created), the same HttpSession.</p><p>On the Tapestry side, it is very easy to read and write session attributes:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: true; theme: Default" style="font-size:12px;">public class ShowSearchResults
+</plain-text-body><p>The RequestParameter annotation extracts the named query parameter from the request, coerces its type from String to the parameter type (here, also String) and passes it into the method.</p><h3 id="Integrationwithexistingapplications-HowdoIshareinformationbetweenaJSPapplicationandtheTapestryapplication?">How do I share information between a JSP application and the Tapestry application?</h3><p>From the servlet container's point of view, there's no difference between a servlet, a JSP, and an entire Tapestry application. They all share the same ServletContext, and (once created), the same HttpSession.</p><p>On the Tapestry side, it is very easy to read and write session attributes:</p><parameter ac:name="controls">true</parameter><parameter ac:name="linenumbers">true</parameter><plain-text-body>public class ShowSearchResults
{
@SessionAttribute
private SearchResults searchResults;
}
-</pre>
-</div></div><p>Reading the instance variable <code>searchResults</code> is instrumented to instead read the corresponding HttpSession attribute named "searchResults". You can also specify the <code>value</code> attribute of the SessionAttribute annotation to override the default attribute name.</p><p>Writing to the field causes the corresponding HttpSession attribute to be modified.</p><p>The session is automatically created as needed.</p><h3 id="Integrationwithexistingapplications-HowdoIputtheTapestryapplicationinsideafolder,toavoidconflicts?">How do I put the Tapestry application inside a folder, to avoid conflicts?</h3><p>Support for this was added in 5.3; see the notes on the <a href="configuration.html">configuration page</a>.</p><p> </p><p> </p><p> </p></div>
+</plain-text-body><p>Reading the instance variable <code>searchResults</code> is instrumented to instead read the corresponding HttpSession attribute named "searchResults". You can also specify the <code>value</code> attribute of the SessionAttribute annotation to override the default attribute name.</p><p>Writing to the field causes the corresponding HttpSession attribute to be modified.</p><p>The session is automatically created as needed.</p><h3 id="Integrationwithexistingapplications-HowdoIputtheTapestryapplicationinsideafolder,toavoidconflicts?">How do I put the Tapestry application inside a folder, to avoid conflicts?</h3><p>Support for this was added in 5.3; see the notes on the <a href="configuration.html">configuration page</a>.</p><plain-text-body>{scrollbar}</plain-text-body><p> </p><p> </p><p> </p></div>
</div>
<div class="clearer"></div>
Modified: websites/production/tapestry/content/ioc-cookbook-basic-services-and-injection.html
==============================================================================
--- websites/production/tapestry/content/ioc-cookbook-basic-services-and-injection.html (original)
+++ websites/production/tapestry/content/ioc-cookbook-basic-services-and-injection.html Tue Sep 26 19:20:27 2017
@@ -27,16 +27,6 @@
</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"/>
@@ -77,7 +67,7 @@
</div>
<div id="content">
- <div id="ConfluenceContent">
+ <div id="ConfluenceContent"><plain-text-body>{scrollbar}</plain-text-body>
<p>The starting point for Tapestry IOC services and injection is knowing a few conventions: what to name your classes, what packages to put them in and so forth.</p>
@@ -99,21 +89,18 @@
<p>The PropertyAccess service is defined inside TapestryIOCModule's bind() 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;">
+<plain-text-body>
public static void bind(ServiceBinder binder)
{
. . .
binder.bind(PropertyAccess.class, PropertyAccessImpl.class);
binder.bind(ExceptionAnalyzer.class, ExceptionAnalyzerImpl.class);
. . .
- }</pre>
-</div></div>
+ }</plain-text-body>
<p>This example includes <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/ioc/services/ExceptionAnalyzer.html">ExceptionAnalyzer</a>, because it has a dependency on PropertyAccess:</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;">
+<plain-text-body>
public class ExceptionAnalyzerImpl implements ExceptionAnalyzer
{
private final PropertyAccess propertyAccess;
@@ -123,8 +110,7 @@ public class ExceptionAnalyzerImpl imple
}
. . .
-}</pre>
-</div></div>
+}</plain-text-body>
<p>And that's the essence of Tapestry IoC right there; the bind() plus the constructor is <em>all</em> that's necessary.</p>
@@ -146,8 +132,7 @@ public class ExceptionAnalyzerImpl imple
<p>Tapestry defines two such services, in the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/TapestryModule.html">TapestryModule</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;">
+<plain-text-body>
@Marker(ClasspathProvider.class)
public AssetFactory buildClasspathAssetFactory(ResourceCache resourceCache,
@@ -164,8 +149,7 @@ public class ExceptionAnalyzerImpl imple
public AssetFactory buildContextAssetFactory(ApplicationGlobals globals)
{
return new ContextAssetFactory(request, globals.getContext());
- }</pre>
-</div></div>
+ }</plain-text-body>
<p>Service builder methods are used here for two purposes: For the ClasspathAssetFactory, we are registering the new service as a listener of events from another service. For the ContextAssetFactory, we are extracting a value from an injected service and passing <em>that</em> to the constructor.</p>
@@ -175,8 +159,7 @@ public class ExceptionAnalyzerImpl imple
<p>Here's an example. Again, we've jumped the gun with this <em>service contributor method</em> (we'll get into the why and how of these later), but you can see how Tapestry is figuring out which service to inject based on the presence of those annotations:</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;">
+<plain-text-body>
public void contributeAssetSource(MappedConfiguration<String, AssetFactory> configuration,
@ContextProvider
AssetFactory contextAssetFactory,
@@ -186,11 +169,11 @@ public class ExceptionAnalyzerImpl imple
{
configuration.add("context", contextAssetFactory);
configuration.add("classpath", classpathAssetFactory);
- }</pre>
-</div></div>
+ }</plain-text-body>
<p>This is far from the final word on injection and disambiguation; we'll be coming back to this concept repeatedly. And in later chapters of the cookbook, we'll also go into more detail about the many other concepts present in this example. The important part is that Tapestry <em>primarily</em> works off the parameter type (at the point of injection), but when that is insufficient (you'll know ... there will be an error) you can provide additional information, in the form of annotations, to straighten things out.</p>
-</div>
+
+<plain-text-body>{scrollbar}</plain-text-body></div>
</div>
<div class="clearer"></div>