deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r948593 - in /websites/staging/deltaspike/trunk/content: ./ documentation/core.html
Date Tue, 21 Apr 2015 10:47:30 GMT
Author: buildbot
Date: Tue Apr 21 10:47:30 2015
New Revision: 948593

Log:
Staging update by buildbot for deltaspike

Modified:
    websites/staging/deltaspike/trunk/content/   (props changed)
    websites/staging/deltaspike/trunk/content/documentation/core.html

Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Apr 21 10:47:30 2015
@@ -1 +1 @@
-1675083
+1675085

Modified: websites/staging/deltaspike/trunk/content/documentation/core.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/documentation/core.html (original)
+++ websites/staging/deltaspike/trunk/content/documentation/core.html Tue Apr 21 10:47:30
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&#8217;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&#8217;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>&lt;MyServiceInterface&gt;
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&#8201;&#8212;&#8201;as
implied by their name&#8201;&#8212;&#8201;depend on the lifecycle of
+the contextual instance which declares them and get destroyed along with this declaring bean&#8217;s
instance.</p>
+</div>
+<div class="paragraph">
+<p>However, if dependent-scoped instances are obtained programmatically using <code>DependentProvider</code>,
there&#8217;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&lt;MyBean&gt;
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&#8201;&#8212;&#8201;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&lt;CurrentUser&gt;
<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>&lt;?
<span class="directive">extends</span> <span class="predefined-type">Annotation</span>&gt;
priorityAnnotationClass = ClassUtils.tryToLoadClassForName(<span class="string"><span
class="delimiter">&quot;</span><span class="content">javax.annotation.Priority</span><span
class="delimiter">&quot;</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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;uses
<code>findAnnotation</code> to obtain an <code>Annotation</code> from
a given <code>Method</code></p>
+</li>
+<li>
+<p><code>#extractAnnotationFromMethodOrClass</code>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;Extract
the qualifiers from a set of annotations.</p>
 </li>
 <li>
-<p><code>#extractAnnotation</code> - Extract the annotations.</p>
+<p><code>#extractAnnotation</code>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;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>&#8201;&#8212;&#8201;return true if
the String is null or empty ( <code>string.trim().isEmpty()</code> )</p>
 </li>
 </ul>
 </div>



Mime
View raw message