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>
