You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by rs...@apache.org on 2015/04/21 12:47:22 UTC
svn commit: r1675085 - /deltaspike/site/trunk/content/documentation/core.html
Author: rsmeral
Date: Tue Apr 21 10:47:22 2015
New Revision: 1675085
URL: http://svn.apache.org/r1675085
Log:
Site checkin for project Apache DeltaSpike Documentation
Modified:
deltaspike/site/trunk/content/documentation/core.html
Modified: deltaspike/site/trunk/content/documentation/core.html
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/documentation/core.html?rev=1675085&r1=1675084&r2=1675085&view=diff
==============================================================================
--- deltaspike/site/trunk/content/documentation/core.html (original)
+++ deltaspike/site/trunk/content/documentation/core.html Tue Apr 21 10:47:22 2015
@@ -201,8 +201,13 @@ body {
<li><a href="#_core_api">Core - API</a>
<ul class="sectlevel3">
<li><a href="#_deltaspike_configuration">DeltaSpike Configuration</a></li>
-<li><a href="#_beanprovider">BeanProvider</a></li>
+<li><a href="#_beanprovider">BeanProvider</a>
+<ul class="sectlevel4">
+<li><a href="#_dependentprovider">DependentProvider</a></li>
+</ul>
+</li>
<li><a href="#_beanmanagerprovider">BeanManagerProvider</a></li>
+<li><a href="#_annotationinstanceprovider">AnnotationInstanceProvider</a></li>
<li><a href="#_type_safe_projectstage">Type-safe ProjectStage</a></li>
<li><a href="#__exclude">@Exclude</a>
<ul class="sectlevel4">
@@ -240,6 +245,7 @@ body {
</li>
<li><a href="#_core_utils">Core - Utils</a>
<ul class="sectlevel3">
+<li><a href="#_annotationutils">AnnotationUtils</a></li>
<li><a href="#_arraysutils">ArraysUtils</a></li>
<li><a href="#_beanutils">BeanUtils</a></li>
<li><a href="#_contextutils">ContextUtils</a></li>
@@ -284,11 +290,33 @@ body {
<div class="sect3">
<h4 id="_beanprovider">BeanProvider</h4>
<div class="paragraph">
-<p>The <code>BeanProvider</code> is a class which provides (static) util methods which
-allow to lookup beans if it is not possible to inject them via <code>@Inject</code>
-or if the lookup depends on dynamic conditions. Instead of using the
-term 'bean', the term 'contextual instance' is used because that’s the
-term used by CDI itself.</p>
+<p>The <code>BeanProvider</code> utility class provides static methods for manual lookup of bean instances in places where
+standard injection is not available or if the lookup depends on dynamic conditions.</p>
+</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
+<code>BeanProvider</code> is only used to look up normal-scoped contextual
+instances. To obtain instances of dependent-scoped beans, use <a href="#_dependentprovider">DependentProvider</a>.
+</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+The term 'contextual instance' is used instead of 'bean' because that’s the term used by CDI itself.
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
<p>The following example shows a simple lookup. With the second parameter
@@ -376,11 +404,8 @@ destroy them manually - especially if yo
can also call the previous util method with an additional parameter to
filter dependent scoped instances.</p>
</div>
-<div class="paragraph">
-<div class="title">Resolving All Contextual Instances of a Given Type without Dependent</div>
-<p>Scoped Instances</p>
-</div>
<div class="listingblock">
+<div class="title">Resolving All Contextual Instances of a Given Type without Dependent-scoped Instances</div>
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">List</span><MyServiceInterface> myServiceList = BeanProvider.getContextualReferences(MyServiceInterface.class, <span class="predefined-constant">false</span>, <span class="predefined-constant">false</span>);</code></pre>
</div>
@@ -397,6 +422,33 @@ fields.</p>
<pre class="CodeRay highlight"><code data-lang="java">BeanProvider.injectFields(myObject);</code></pre>
</div>
</div>
+<div class="sect4">
+<h5 id="_dependentprovider">DependentProvider</h5>
+<div class="paragraph">
+<p><code>DependentProvider</code> must be used instead of <code>BeanProvider</code> to obtain instances of dependent-scoped beans to allow for
+their proper destruction.</p>
+</div>
+<div class="paragraph">
+<p>When obtaining contextual instances using <code>@Inject</code>, the normal-scoped ones get destroyed along with their associated
+context. However, instances of dependent-scoped beans — as implied by their name — depend on the lifecycle of
+the contextual instance which declares them and get destroyed along with this declaring bean’s instance.</p>
+</div>
+<div class="paragraph">
+<p>However, if dependent-scoped instances are obtained programmatically using <code>DependentProvider</code>, there’s no
+"declaring bean" to speak of and they <strong>must be destroyed manually</strong>.</p>
+</div>
+<div class="listingblock">
+<div class="title">Obtaining and destroying an instance of a dependent-scoped bean using DependentProvider</div>
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">DependentProvider<MyBean> myBeanProvider = BeanProvider.getDependent(MyBean.class);
+MyBean myBean = myBeanProvider.get();
+
+<span class="comment">// ...work with myBean...</span>
+
+myBeanProvider.destroy();</code></pre>
+</div>
+</div>
+</div>
</div>
<div class="sect3">
<h4 id="_beanmanagerprovider">BeanManagerProvider</h4>
@@ -432,6 +484,57 @@ the lookup strategy you used before, you
</div>
</div>
<div class="sect3">
+<h4 id="_annotationinstanceprovider">AnnotationInstanceProvider</h4>
+<div class="paragraph">
+<p>Java EE provides a standard mechanism for obtaining annotation instances — the <code>AnnotationLiteral</code> class.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CurrentUserLiteral</span> <span class="directive">extends</span> AnnotationLiteral<CurrentUser> <span class="directive">implements</span> CurrentUser {}</code></pre>
+</div>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">CurrentUser user = <span class="keyword">new</span> CurrentUserLiteral() {};</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p><code>AnnotationLiteral</code> can however be used only if the annotation class name is known beforehand.
+<code>AnnotationInstanceProvider</code> is the solution for dynamic creation of annotation instances, with
+the option to provide a map of values for annotation members. That might be useful in many situations,
+especially for CDI extension authors. For example:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>avoiding a compile-time dependency on an annotation class</p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Class</span><? <span class="directive">extends</span> <span class="predefined-type">Annotation</span>> priorityAnnotationClass = ClassUtils.tryToLoadClassForName(<span class="string"><span class="delimiter">"</span><span class="content">javax.annotation.Priority</span><span class="delimiter">"</span></span>);
+priorityAnnotationInstance = AnnotationInstanceProvider.of(priorityAnnotationClass, mapOfMemberValues);</code></pre>
+</div>
+</div>
+</li>
+<li>
+<p>getting an instance of a dynamically obtained annotation class</p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Annotation</span> exceptionQualifier = AnnotationInstanceProvider.of(jsfModuleConfig.getExceptionQualifier());</code></pre>
+</div>
+</div>
+</li>
+<li>
+<p>or simply for the sake of a prettier syntax compared to <code>AnnotationLiteral</code></p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">CurrentUser principal = AnnotationInstanceProvider.of(CurrentUser.class);</code></pre>
+</div>
+</div>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect3">
<h4 id="_type_safe_projectstage">Type-safe ProjectStage</h4>
<div class="paragraph">
<p>The DeltaSpike <a href="projectstage.html">ProjectStage</a> mechanism allows to use configuration and implementations depending on the server environment you currently run on.</p>
@@ -1336,30 +1439,30 @@ chain or unmuting the current handler. F
<div class="ulist">
<ul>
<li>
-<p><code>abort()</code> - terminate all handling immediately after this handler,
+<p><code>abort()</code> — terminate all handling immediately after this handler,
does not mark the exception as handled, does not re-throw the exception.</p>
</li>
<li>
-<p><code>throwOriginal()</code> - continues through all handlers, but once all
+<p><code>throwOriginal()</code> — continues through all handlers, but once all
handlers have been called (assuming another handler does not call
abort() or handled()) the initial exception passed to DeltaSpike is
rethrown. Does not mark the exception as handled.</p>
</li>
<li>
-<p><code>handled()</code> - marks the exception as handled and terminates further
+<p><code>handled()</code> — marks the exception as handled and terminates further
handling.</p>
</li>
<li>
-<p><code>handleAndContinue()</code> - default. Marks the exception as handled and
+<p><code>handleAndContinue()</code> — default. Marks the exception as handled and
proceeds with the rest of the handlers.</p>
</li>
<li>
-<p><code>skipCause()</code> - marks the exception as handled, but proceeds to the
+<p><code>skipCause()</code> — marks the exception as handled, but proceeds to the
next cause in the cause container, without calling other handlers for
the current cause.</p>
</li>
<li>
-<p><code>rethrow(Throwable)</code> - Throw a new exception after this handler is
+<p><code>rethrow(Throwable)</code> — Throw a new exception after this handler is
invoked</p>
</li>
</ul>
@@ -1522,13 +1625,35 @@ other <a href="configuration.html#_confi
<div class="sect2">
<h3 id="_core_utils">Core - Utils</h3>
<div class="paragraph">
-<p>DeltaSpike provides many utility-classes (no constructor / static
+<p>DeltaSpike provides many utility classes (no constructor / static
methods) that can be useful for your project.</p>
</div>
<div class="paragraph">
<p>Below you can find an information about these classes.</p>
</div>
<div class="sect3">
+<h4 id="_annotationutils">AnnotationUtils</h4>
+<div class="paragraph">
+<p>Utilities for working with annotations on methods and classes.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>#findAnnotation</code> — obtains an <code>Annotation</code> instance of a given annotation <code>Class</code> from the given <code>Annotation[]</code>, recursing any possible stereotype tree along the way</p>
+</li>
+<li>
+<p><code>#extractAnnotationFromMethod</code> — uses <code>findAnnotation</code> to obtain an <code>Annotation</code> from a given <code>Method</code></p>
+</li>
+<li>
+<p><code>#extractAnnotationFromMethodOrClass</code> — uses <code>findAnnotation</code> to obtain an <code>Annotation</code> on either the given <code>Method</code> or the given <code>Class</code>, in that order</p>
+</li>
+<li>
+<p><code>#getQualifierHashCode</code> — computes the hashCode of a qualifier annotation, taking into account only the "binding" members (not annotated <code>@Nonbinding</code>)</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect3">
<h4 id="_arraysutils">ArraysUtils</h4>
<div class="paragraph">
<p>A collection of utilities for working with Arrays</p>
@@ -1536,7 +1661,7 @@ methods) that can be useful for your pro
<div class="ulist">
<ul>
<li>
-<p><code>#asSet</code> - Create a set from an array. If the array contains duplicate
+<p><code>#asSet</code> — Create a set from an array. If the array contains duplicate
objects, the last object in the array will be placed in resultant set.</p>
</li>
</ul>
@@ -1550,13 +1675,13 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#getQualifiers</code> - Extract the qualifiers from a set of annotations.</p>
+<p><code>#getQualifiers</code> — Extract the qualifiers from a set of annotations.</p>
</li>
<li>
-<p><code>#extractAnnotation</code> - Extract the annotations.</p>
+<p><code>#extractAnnotation</code> — Extract the annotations.</p>
</li>
<li>
-<p><code>#createInjectionPoints</code> - Given a method, and the bean on which the method is declared, create a collection of injection points representing the parameters of the method.</p>
+<p><code>#createInjectionPoints</code> — Given a method, and the bean on which the method is declared, create a collection of injection points representing the parameters of the method.</p>
</li>
</ul>
</div>
@@ -1569,7 +1694,7 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#isContextActive</code> - Checks if the context for the scope annotation is active.</p>
+<p><code>#isContextActive</code> — Checks if the context for the scope annotation is active.</p>
</li>
</ul>
</div>
@@ -1582,7 +1707,7 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#isActivated</code> - Evaluates if the given <code>Deactivatable</code> is active.</p>
+<p><code>#isActivated</code> — Evaluates if the given <code>Deactivatable</code> is active.</p>
</li>
</ul>
</div>
@@ -1598,10 +1723,10 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#throwAsRuntimeException</code> - helper which allows to use a trick to throw a catched checked exception without a wrapping exception.</p>
+<p><code>#throwAsRuntimeException</code> — helper which allows to use a trick to throw a catched checked exception without a wrapping exception.</p>
</li>
<li>
-<p><code>#changeAndThrowException</code> - helper which allows to use a trick to throw a cached checked exception without a wrapping exception.</p>
+<p><code>#changeAndThrowException</code> — helper which allows to use a trick to throw a cached checked exception without a wrapping exception.</p>
</li>
</ul>
</div>
@@ -1614,13 +1739,13 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#resolvePropertyFiles</code> - Allows to lookup for resource bundle files.</p>
+<p><code>#resolvePropertyFiles</code> — Allows to lookup for resource bundle files.</p>
</li>
<li>
-<p><code>#loadProperties</code> - Load a Properties file from the given URL.</p>
+<p><code>#loadProperties</code> — Load a Properties file from the given URL.</p>
</li>
<li>
-<p><code>#getResourceBundle</code> - Return the ResourceBundle for the current default Locale.</p>
+<p><code>#getResourceBundle</code> — Return the ResourceBundle for the current default Locale.</p>
</li>
</ul>
</div>
@@ -1633,10 +1758,10 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#getUnproxiedClass</code> - Return class of the real implementation.</p>
+<p><code>#getUnproxiedClass</code> — Return class of the real implementation.</p>
</li>
<li>
-<p><code>#isProxiedClass</code> - Analyses if the given class is a generated proxy class.</p>
+<p><code>#isProxiedClass</code> — Analyses if the given class is a generated proxy class.</p>
</li>
</ul>
</div>
@@ -1649,7 +1774,7 @@ objects, the last object in the array wi
<div class="ulist">
<ul>
<li>
-<p><code>#isEmpty</code> - return true if the String is null or empty ( <code>string.trim().isEmpty()</code> )</p>
+<p><code>#isEmpty</code> — return true if the String is null or empty ( <code>string.trim().isEmpty()</code> )</p>
</li>
</ul>
</div>