svn commit: r1060238 - in /websites/production/tapestry/content: cache/main.pageCache environmental-services.html

[bu...@apache.org]

Author: buildbot
Date: Thu May  7 12:19:55 2020
New Revision: 1060238

Log:
Production update by buildbot for tapestry

Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/environmental-services.html

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/tapestry/content/environmental-services.html
==============================================================================
--- websites/production/tapestry/content/environmental-services.html (original)
+++ websites/production/tapestry/content/environmental-services.html Thu May  7 12:19:55 2020
@@ -145,7 +145,7 @@
                             <div id="ConfluenceContent"><p></p><div class="navmenu" style="float:right; width:30%; background:#eee; margin:3px; padding:3px">
 <p>Environmental services represent yet another, distinct form of injection.</p>
 
-<p>Unlike service injection (injection via a service implementation's constructor) or normal component injection (directly into component fields, via the @Inject annotation) where the injected value is always the same, with environmental services, the injected value is very late bound and dynamic.</p></div><p><strong>Environmental services</strong> provide a conduit of communication between two components (usually a component and the components it encloses). The first component pushes an object of a certain type into the <em>environment</em>, and then the second component can access that object merely by defining an annotated property of the same type.</p><p></p><p>An example of how this works is Tapestry's built-in <em>form support</em>. The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a> component creates an object of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/
 org/apache/tapestry5/services/FormSupport.html">FormSupport</a> and pushes it into the environment. Then, the enclosed form components can use that FormSupport object to participate in both the rendering of the Form and the Form's eventual submission. This is how control names and client-side ids are determined, how fields register callbacks so that they can process their part of the submission, and how fields hook themselves to client-side validation.</p><h1 id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the @Environmental annotation</h1><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html">Environmental</a> annotation, when used in a component class, causes the associated field to be replaced at runtime with a read-only value obtained from an Environment service provided by an enclosing component.</p><p>A very common Environmental is <a class="external-link" href="http://tapestry.ap
 ache.org/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>, used when generating <a href="ajax-javascript.html">client-side JavaScript</a>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<p>Unlike service injection (injection via a service implementation's constructor) or normal component injection (directly into component fields, via the @Inject annotation) where the injected value is always the same, with environmental services, the injected value is very late bound and dynamic.</p></div><strong>Environmental services</strong> provide a conduit of communication between two components (usually a component and the components it encloses). The first component pushes an object of a certain type into the <em>environment</em>, and then the second component can access that object merely by defining an annotated property of the same type.<p></p><p>An example of how this works is Tapestry's built-in <em>form support</em>. The <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/corelib/components/Form.html">Form</a> component creates an object of type <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apa
 che/tapestry5/services/FormSupport.html">FormSupport</a> and pushes it into the environment. Then, the enclosed form components can use that FormSupport object to participate in both the rendering of the Form and the Form's eventual submission. This is how control names and client-side ids are determined, how fields register callbacks so that they can process their part of the submission, and how fields hook themselves to client-side validation.</p><h2 id="EnvironmentalServices-Usingthe@Environmentalannotation">Using the @Environmental annotation</h2><p>The @<a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/annotations/Environmental.html">Environmental</a> annotation, when used in a component class, causes the associated field to be replaced at runtime with a read-only value obtained from an Environment service provided by an enclosing component.</p><p>A very common Environmental is <a class="external-link" href="http://tapestry.apache.or
 g/current/apidocs/org/apache/tapestry5/services/javascript/JavaScriptSupport.html">JavaScriptSupport</a>, used when generating <a href="ajax-javascript.html">client-side JavaScript</a>.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
 <pre><code class="language-java">  @Inject @Path("${tapestry.scriptaculous}/dragdrop.js")
   private Asset dragDropLibrary;
 
@@ -158,7 +158,7 @@
   }
 
 </code></pre>
-</div></div><p>Environmental services are, by their nature, per-thread (and therefore per-request).</p><p>Accessing an environmental field causes a lookup, by type, against the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html">Environment</a> service.</p><p>Normally, an environmental of the specified type must be available in the Environment, or an exception is thrown when accessing the field. However, if the value of the Environmental annotation's value is false, then the environmental value is optional.</p><h1 id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the environment</h1><p>The Environment service has push() and pop() methods to put a value in the Environment, and discard it.</p><p>For example, say you were building a tab-based menu system and you needed to allow an outer TabGroup component to communicate with inner Tab components, to control various aspects of presentation.</
 p><p>The relevant information could be exposed as an interface, TabModel.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>TabGroup.java</b></div><div class="codeContent panelContent pdl">
+</div></div><p>Environmental services are, by their nature, per-thread (and therefore per-request).</p><p>Accessing an environmental field causes a lookup, by type, against the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/Environment.html">Environment</a> service.</p><p>Normally, an environmental of the specified type must be available in the Environment, or an exception is thrown when accessing the field. However, if the value of the Environmental annotation's value is false, then the environmental value is optional.</p><h2 id="EnvironmentalServices-Placingavalueintheenvironment">Placing a value in the environment</h2><p>The Environment service has push() and pop() methods to put a value in the Environment, and discard it.</p><p>For example, say you were building a tab-based menu system and you needed to allow an outer TabGroup component to communicate with inner Tab components, to control various aspects of presentation.</
 p><p>The relevant information could be exposed as an interface, TabModel.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeHeader panelHeader pdl" style="border-bottom-width: 1px;"><b>TabGroup.java</b></div><div class="codeContent panelContent pdl">
 <pre><code class="language-java">public class TabGroup
 {
   @Inject
@@ -186,7 +186,7 @@ public class Tab
   }
 }
 </code></pre>
-</div></div><p>Notice that when pushing a value into the Environment, you identify its type as well as the instance. Environment maintains a number of stacks, one for each type. Thus, pushing a TabModel into the environment won't disturb the RenderSupport or other environmentals already there.</p><p>What's important here is that the code that pushes a environmental onto a stack should also pop it off.</p><p>The enclosed class, Tab, has full access to whatever object was pushed onto the stack by the TabGroup.</p><p>The reason why Environment is a stack is so that a component can, when it makes sense, easily replace or intercept access to an Environmental.</p><h1 id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental Environmentals</h1><p>Not all environmentals are pushed into the Environment by components.</p><p>A number of environmentals are initialized as part of page rendering, even before the first component starts to render. This initialization is accomplished with <a 
 class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html">MarkupRendererFilter</a> contributions to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html">MarkupRenderer</a> service.</p><h1 id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing Environmentals in Services</h1><p>The Environmental annotation only works inside components.</p><p>To access an Environmental inside a service implementation, you must inject the Environment service and obtain values from it using the peek() method.</p><p>If this is something that will occur frequently, it is possible to create a service implementation that is "backed" by the Environment. For example, RenderSupport is accessible as a normal injection, because a service is built for it in TapestryModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent p
 anelContent pdl">
+</div></div><p>Notice that when pushing a value into the Environment, you identify its type as well as the instance. Environment maintains a number of stacks, one for each type. Thus, pushing a TabModel into the environment won't disturb the RenderSupport or other environmentals already there.</p><p>What's important here is that the code that pushes a environmental onto a stack should also pop it off.</p><p>The enclosed class, Tab, has full access to whatever object was pushed onto the stack by the TabGroup.</p><p>The reason why Environment is a stack is so that a component can, when it makes sense, easily replace or intercept access to an Environmental.</p><h2 id="EnvironmentalServices-FundamentalEnvironmentals">Fundamental Environmentals</h2><p>Not all environmentals are pushed into the Environment by components.</p><p>A number of environmentals are initialized as part of page rendering, even before the first component starts to render. This initialization is accomplished with <a 
 class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRendererFilter.html">MarkupRendererFilter</a> contributions to the <a class="external-link" href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/MarkupRenderer.html">MarkupRenderer</a> service.</p><h2 id="EnvironmentalServices-AccessingEnvironmentalsinServices">Accessing Environmentals in Services</h2><p>The Environmental annotation only works inside components.</p><p>To access an Environmental inside a service implementation, you must inject the Environment service and obtain values from it using the peek() method.</p><p>If this is something that will occur frequently, it is possible to create a service implementation that is "backed" by the Environment. For example, RenderSupport is accessible as a normal injection, because a service is built for it in TapestryModule:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent p
 anelContent pdl">
 <pre><code class="language-java">  public RenderSupport buildRenderSupport(EnvironmentalShadowBuilder builder)
   {
     return builder.build(RenderSupport.class);