deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r995350 [6/18] - in /websites/staging/deltaspike/trunk/content: ./ documentation/
Date Thu, 18 Aug 2016 00:38:02 GMT
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 Thu Aug 18 00:38:02 2016
@@ -1,2069 +1,2069 @@
-<!DOCTYPE html>
-<head>
-    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="description" content="deltaspike-generate-pages">
-    <meta name="author" content="chm">
-    <!-- No caching headers -->
-    <meta http-equiv="cache-control" content="no-cache"/>
-    <meta http-equiv="pragma" content="no-cache"/>
-    <meta http-equiv="expires" content="-1"/>
-
-    <title>Core Module</title>
-
-    <!--
-        Licensed to the Apache Software Foundation (ASF) under one
-        or more contributor license agreements.  See the NOTICE file
-        distributed with this work for additional information
-        regarding copyright ownership.  The ASF licenses this file
-        to you under the Apache License, Version 2.0 (the
-        "License"); you may not use this file except in compliance
-        with the License.  You may obtain a copy of the License at
-
-        http://www.apache.org/licenses/LICENSE-2.0
-
-        Unless required by applicable law or agreed to in writing,
-        software distributed under the License is distributed on an
-        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-        KIND, either express or implied.  See the License for the
-        specific language governing permissions and limitations
-        under the License.
-    -->
-
-    <!-- Styles -->
-    <link href="https://deltaspike.apache.org/resources/css/bootstrap.css" rel="stylesheet">
-    <link href="https://deltaspike.apache.org/resources/css/bootstrap-responsive.css" rel="stylesheet">
-    <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/3.1.0/css/font-awesome.min.css" rel="stylesheet">
-
-    
-
-    
-        <!-- Tocify - nice dynamic autoscrolling TOC -->
-        <link href="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/stylesheets/jquery.tocify.min.css" rel="stylesheet">
-        <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
-        <script src="https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>
-        <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery.tocify/1.9.0/javascripts/jquery.tocify.min.js"></script>
-
-
-        <script type="text/javascript">
-            $(function () {
-                $("#toc").tocify({
-                    scrollTo: 50,
-                    extendPage: true,
-                    context: "#doc-content",
-                    selectors: "h2,h3,h4,h5"
-                });
-                $(".fallback-toc").hide();
-            });
-        </script>
-    
-
-    <style type="text/css">
-        /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
-/*pre.CodeRay {background-color:#f7f7f8;}*/
-.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
-.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
-.CodeRay .line-numbers strong{font-weight: normal}
-table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
-table.CodeRay td{vertical-align: top}
-table.CodeRay td.line-numbers{text-align:right}
-table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
-table.CodeRay td.code{padding:0 0 0 .5em}
-table.CodeRay td.code>pre{padding:0}
-.CodeRay .debug{color:#fff !important;background:#000080 !important}
-.CodeRay .annotation{color:#007}
-.CodeRay .attribute-name{color:#000080}
-.CodeRay .attribute-value{color:#700}
-.CodeRay .binary{color:#509}
-.CodeRay .comment{color:#998;font-style:italic}
-.CodeRay .char{color:#04d}
-.CodeRay .char .content{color:#04d}
-.CodeRay .char .delimiter{color:#039}
-.CodeRay .class{color:#458;font-weight:bold}
-.CodeRay .complex{color:#a08}
-.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
-.CodeRay .color{color:#099}
-.CodeRay .class-variable{color:#369}
-.CodeRay .decorator{color:#b0b}
-.CodeRay .definition{color:#099}
-.CodeRay .delimiter{color:#000}
-.CodeRay .doc{color:#970}
-.CodeRay .doctype{color:#34b}
-.CodeRay .doc-string{color:#d42}
-.CodeRay .escape{color:#666}
-.CodeRay .entity{color:#800}
-.CodeRay .error{color:#808}
-.CodeRay .exception{color:inherit}
-.CodeRay .filename{color:#099}
-.CodeRay .function{color:#900;font-weight:bold}
-.CodeRay .global-variable{color:#008080}
-.CodeRay .hex{color:#058}
-.CodeRay .integer,.CodeRay .float{color:#099}
-.CodeRay .include{color:#555}
-.CodeRay .inline{color:#00}
-.CodeRay .inline .inline{background:#ccc}
-.CodeRay .inline .inline .inline{background:#bbb}
-.CodeRay .inline .inline-delimiter{color:#d14}
-.CodeRay .inline-delimiter{color:#d14}
-.CodeRay .important{color:#555;font-weight:bold}
-.CodeRay .interpreted{color:#b2b}
-.CodeRay .instance-variable{color:#008080}
-.CodeRay .label{color:#970}
-.CodeRay .local-variable{color:#963}
-.CodeRay .octal{color:#40e}
-.CodeRay .predefined{color:#369}
-.CodeRay .preprocessor{color:#579}
-.CodeRay .pseudo-class{color:#555}
-.CodeRay .directive{font-weight:bold}
-.CodeRay .type{font-weight:bold}
-.CodeRay .predefined-type{color:inherit}
-.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
-.CodeRay .key{color:#808}
-.CodeRay .key .delimiter{color:#606}
-.CodeRay .key .char{color:#80f}
-.CodeRay .value{color:#088}
-.CodeRay .regexp .delimiter{color:#808}
-.CodeRay .regexp .content{color:#808}
-.CodeRay .regexp .modifier{color:#808}
-.CodeRay .regexp .char{color:#d14}
-.CodeRay .regexp .function{color:#404;font-weight:bold}
-.CodeRay .string{color:#d20}
-.CodeRay .string .string .string{background:#ffd0d0}
-.CodeRay .string .content{color:#d14}
-.CodeRay .string .char{color:#d14}
-.CodeRay .string .delimiter{color:#d14}
-.CodeRay .shell{color:#d14}
-.CodeRay .shell .delimiter{color:#d14}
-.CodeRay .symbol{color:#990073}
-.CodeRay .symbol .content{color:#a60}
-.CodeRay .symbol .delimiter{color:#630}
-.CodeRay .tag{color:#008080}
-.CodeRay .tag-special{color:#d70}
-.CodeRay .variable{color:#036}
-.CodeRay .insert{background:#afa}
-.CodeRay .delete{background:#faa}
-.CodeRay .change{color:#aaf;background:#007}
-.CodeRay .head{color:#f8f;background:#505}
-.CodeRay .insert .insert{color:#080}
-.CodeRay .delete .delete{color:#800}
-.CodeRay .change .change{color:#66f}
-.CodeRay .head .head{color:#f4f}
-
-        body {
-            padding-top: 60px;
-            padding-bottom: 40px;
-        }
-
-        .toc-like {
-            border-radius: 6px;
-            border: 1px solid #ccc;
-        }
-
-        .toc-like li {
-            line-height: 30px;
-            text-indent: 10px;
-        }
-
-        .toc-like li.custom-toc-header {
-            font-weight: bold;
-            background: #666;
-            color: white;
-            cursor: initial !important;
-            padding: 5px;
-        }
-
-        .toc-like li.custom-toc-header a {
-            color: white;
-            font-style: normal;
-            text-shadow: none;
-            padding: 0;
-        }
-
-        .toc-like li.custom-toc-header:hover a {
-            background: #666;
-        }
-
-        .page-title {
-            text-align: left;
-        }
-
-        #doc-content h2,
-        #doc-content h3,
-        #doc-content h4,
-        #doc-content h5,
-        #doc-content h6 {
-            padding-top: 0;
-            margin-top: 25px;
-            margin-bottom: 10px;
-            line-height: 1.4em;
-        }
-
-        #doc-content h2 {
-            border-bottom: 1px solid lightgrey;
-        }
-
-
-    </style>
-
-    <script type="text/javascript">
-
-        var _gaq = _gaq || [];
-        _gaq.push(['_setAccount', 'UA-36103647-1']);
-        _gaq.push(['_trackPageview']);
-
-        (function () {
-            var ga = document.createElement('script');
-            ga.type = 'text/javascript';
-            ga.async = true;
-            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-            var s = document.getElementsByTagName('script')[0];
-            s.parentNode.insertBefore(ga, s);
-        })();
-
-    </script>
-</head>
-
-<body>
-
-<div class="navbar navbar-fixed-top">
-    <div class="navbar-inner">
-        <div class="container">
-            <a class="btn btn-navbar" data-toggle="collapse"
-               data-target=".nav-collapse"> <span class="icon-bar"></span> <span
-            class="icon-bar"></span> <span class="icon-bar"></span>
-            </a>
-            <a class="brand logocolor" href="../index.html">Apache DeltaSpike</a>
-
-            <div class="nav-collapse">
-
-                
-                <ul class="nav">
-                    <li><a href="../index.html">Home</a></li>
-                    <li class="active"><a href="../documentation">Documentation</a></li>
-                    <li  ><a href="../javadoc.html">Javadoc</a></li>
-                    <li ><a href="../source.html">Source</a></li>
-                    <li ><a href="../download.html">Download</a></li>
-                    <li ><a href="../community.html">Community</a></li>
-                    <!-- <li><a href="./support.html">Support</a></li>  -->
-                    <li ><a href="../news.html">News</a></li>
-                </ul>
-            </div>
-            <!--/.nav-collapse -->
-            <form id="search-form" action="https://www.google.com/search"
-                  method="get" class="navbar-search pull-right">
-                <input value="deltaspike.apache.org" name="sitesearch"
-                       type="hidden"> <input class="search-query" name="q"
-                                             id="query" type="text">
-            </form>
-        </div>
-    </div>
-</div>
-
-<div class="container">
-    <div class="row-fluid">
-
-        
-
-        <div class="span8">
-            <div class="page-title">
-                <h1>Core Module</h1>
-            </div>
-
-            <div id="doc-content">
-                <div id="preamble">
-<div class="sectionbody">
-<div class="paragraph">
-<p>The Core module provides fundamental and defining DeltaSpike API and utility classes. As such, this module must be included in every project that uses DeltaSpike.
-Instructions for configuring your projects to use the DeltaSpike Core module are detailed in
-<a href="configure.html">Configure DeltaSpike in Your Projects</a> as part of the general instructions for configuring your projects for DeltaSpike.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_project_setup">Project Setup</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Add Core-API and Core-Impl to your project as detailed in <a href="configure.html">Configure DeltaSpike Core in Your Projects</a>. For Maven-independent projects, see <a href="configure.html#config-maven-indep">Configure DeltaSpike Core in Maven-independent Projects</a>.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_deltaspike_configuration">DeltaSpike Configuration</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>DeltaSpike provides a very flexible application configuration mechanism. Its main goal is to make it possible
-to never have to rebuild a project just for the sake of adjusting configuration values. It respects the usual
-software development cycle and takes into account project stages, various configuration sources and resolution
-mechanisms. Configuration can be overridden just by dropping a JAR into the classpath.</p>
-</div>
-<div class="paragraph">
-<p>Detailed documentation is available on a separate page: <a href="configuration.html">Configuration</a>.</p>
-</div>
-<div class="sect2">
-<h3 id="_internal_configuration">Internal configuration</h3>
-<div class="paragraph">
-<p>The functionality of DeltaSpike itself and its modules is adjustable using the same mechanism. There are two main
-types of internal configuration:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><strong>static configuration:</strong> certain configurable options, like the maximum number of windows in the window scope or the
-priority for DeltaSpike&#8217;s global interceptors, are defined using the DeltaSpike configuration mechanism and can be
-adjusted by redefining their value in the <code>apache-deltaspike.properties</code> file, as described in the
-<a href="configuration.html">documentation</a>. All of these configuration options and their corresponding properties can be
-found as members of interfaces extending <code>DeltaSpikeBaseConfig</code>, e.g. <code>CoreBaseConfig</code> which configures the core
- module.</p>
-</li>
-<li>
-<p><strong>dynamic configuration:</strong> certain values can change dynamically during runtime and some may differ even among
-contexts. For example, much of the behaviour of the JSF module is configured in <code>JsfModuleConfig</code>. To override any of
- the default configuration options, the <code>JsfModuleConfig</code> bean can be overridden using a custom implementation of
- <code>JsfModuleConfig</code> which would be annotated <code>@Alternative</code> or <code>@Specializes</code>. All of the dynamic CDI-based
- configuration beans can be found as implementations of the <code>DeltaSpikeConfig</code> interface.</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_beanprovider">BeanProvider</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<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
-it is possible to specify if the contextual instance is optional. If it
-is not expected that the contextual instance is optional, but no instance
-has been found, an <code>IllegalStateException</code> will be thrown.</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving a Simple Contextual Instance</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">MyBean myBean = BeanProvider.getContextualReference(MyBean.class, <span class="predefined-constant">false</span>);</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Pass <code>true</code> as second argument, if you look for an implementation of the
-given interface and an implementation is not required or it is not
-required that there is an instance with the given qualifier (see the
-qualifier example for further details).</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving an Optional Contextual Instance</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">MyServiceInterface optionalService = BeanProvider.getContextualReference(MyServiceInterface.class, <span class="predefined-constant">true</span>);</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Optionally you can provide a qualifier for the contextual instance in
-question. CDI qualifiers are annotations, therefore you need to
-implement a corresponding literal for providing an instance.</p>
-</div>
-<div class="listingblock">
-<div class="title">Literal Implementation for '@MyQualifier'</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">javax.enterprise.util.AnnotationLiteral</span>;
-<span class="comment">//...</span>
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyQualifierLiteral</span> <span class="directive">extends</span> AnnotationLiteral&lt;MyQualifier&gt; <span class="directive">implements</span> MyQualifier
-{
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The following example will return a contextual instance with the
-qualifier <code>@MyQualifier</code>.</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving a Simple Contextual Instance with Qualifier</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">MyBean myBean = BeanProvider.getContextualReference(MyBean.class, <span class="predefined-constant">false</span>, <span class="keyword">new</span> MyQualifierLiteral());</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>@Named</code> qualifier has a special role and allows to specify a string
-based name (e.g. for referencing CDI beans in EL-expressions). However,
-the following examples show how to do a manual lookup by name.</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving a Simple Contextual Instance by Name</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Object</span> myBean = BeanProvider.getContextualReference(<span class="string"><span class="delimiter">&quot;</span><span class="content">myBean</span><span class="delimiter">&quot;</span></span>, <span class="predefined-constant">false</span>);</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="title">Resolving a Simple Contextual Instance by Name and Expected Type</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">MyBean myBean = BeanProvider.getContextualReference(<span class="string"><span class="delimiter">&quot;</span><span class="content">myBean</span><span class="delimiter">&quot;</span></span>, <span class="predefined-constant">false</span>, MyBean.class);</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Sometimes it is essential to resolve all contextual instances which
-implement for example an interface or all beans with the same type but a
-different qualifier. The following example shows how to do such a lookup
-which returns all contextual instances (independent of the scope &#8594; also
-dependent scoped instances).</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving All Contextual Instances of a Given Type</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>);</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Since dependent scoped beans have a special role in CDI (you have to
-destroy them manually - especially if you get them via a manual lookup), you
-can also call the previous util method with an additional parameter to
-filter dependent 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>
-</div>
-<div class="paragraph">
-<p>Furthermore, it is possible to trigger the injection of fields of any
-given instance, if it was not done by the container (e.g. because the
-class is in a jar-file without beans.xml) and <code>@Inject</code> is used for 1-n
-fields.</p>
-</div>
-<div class="listingblock">
-<div class="title">Manually Inject Fields</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">BeanProvider.injectFields(myObject);</code></pre>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_dependentprovider">DependentProvider</h3>
-<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>
-<div class="sect1">
-<h2 id="_beanmanagerprovider">BeanManagerProvider</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This mechanism provides access to the <code>BeanManager</code> by registering the
-current <code>BeanManager</code> during the startup. This is really handy if you
-like to access CDI functionality from places where no CDI based
-injection is available. If a simple but manual bean-lookup is needed,
-it is easier to use the <code>BeanProvider</code>.</p>
-</div>
-<div class="listingblock">
-<div class="title">Resolving the BeanManager</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="comment">//in most cases the following works without problems:</span>
-<span class="annotation">@Inject</span>
-<span class="directive">private</span> BeanManager beanManager;
-
-<span class="comment">//use</span>
-BeanManager beanManager = BeanManagerProvider.getInstance().getBeanManager();
-
-<span class="comment">//if CDI based injection is not available.</span></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p><code>BeanManagerProvider</code> uses a different approach to find the correct <code>BeanManager</code>,
-because a portable API for it has only been available from CDI 1.1.
-However, once you are using CDI 1.1+ DeltaSpike delegates the lookup to the CDI container
-instead of using its own approach.
-If you migrate from CDI 1.0 to a later version of CDI and you would like to keep
-the lookup strategy you used before, you can deactivate the delegation to the container by adding
-<code>deltaspike.bean-manager.delegate_lookup=false</code> to your config-source
-(e.g. in <code>/META-INF/apache-deltaspike.properties</code>).</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_annotationinstanceprovider">AnnotationInstanceProvider</h2>
-<div class="sectionbody">
-<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>
-<div class="sect1">
-<h2 id="_type_safe_projectstage">Type-safe ProjectStage</h2>
-<div class="sectionbody">
-<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>
-</div>
-<div class="paragraph">
-<p>DeltaSpike provides some pre-defined <a href="projectstage.html#_introduction">ProjectStages</a> but it&#8217;s also possible to create your own <a href="projectstage.html#_custom_project_stages">Custom Project Stage</a>, Please, check the <a href="projectstage.html">DeltaSpike ProjectStage</a> page for more details.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="__exclude">@Exclude</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>With <code>@Exclude</code> it is possible to annotate beans which should be ignored
-by CDI even if they are in a CDI enabled archive.</p>
-</div>
-<div class="listingblock">
-<div class="title">Excluding a Bean in any Case</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">NoBean</span>
-{
-}</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="title">Excluding a Bean in Case of ProjectStageDevelopment</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>(ifProjectStage = ProjectStage.Development.class)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyBean</span>
-{
-}</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="title">Excluding a Bean if the ProjectStage is different from Development</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>(exceptIfProjectStage = ProjectStage.Development.class)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyDevBean</span>
-{
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The following usage allows to exclude a bean based on a configured value
-(see the <a href="configuration.html#_configsources_provided_by_default">supported configuration sources</a>).</p>
-</div>
-<div class="listingblock">
-<div class="title">Excluding a Bean based on an Expression which Evaluates to True</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>(onExpression = <span class="string"><span class="delimiter">&quot;</span><span class="content">db==prodDB</span><span class="delimiter">&quot;</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DevDbBean</span>
-{
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>By default a simple syntax is supported ([TODO]), however, it is possible
-to provide a custom <code>ExpressionInterpreter</code> for interpreting custom
-expressions.</p>
-</div>
-<div class="listingblock">
-<div class="title">Excluding a Bean based on a Custom Expression</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>(onExpression = <span class="string"><span class="delimiter">&quot;</span><span class="content">db eq prodDB</span><span class="delimiter">&quot;</span></span>, interpretedBy = SimpleExpressionInterpreter.class)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DevDbBean</span>
-{
-}
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SimpleExpressionInterpreter</span> <span class="directive">implements</span> ExpressionInterpreter&lt;<span class="predefined-type">String</span>, <span class="predefined-type">Boolean</span>&gt;
-{
-    <span class="annotation">@Override</span>
-    <span class="directive">public</span> <span class="predefined-type">Boolean</span> evaluate(<span class="predefined-type">String</span> expression)
-    {
-        <span class="keyword">if</span>(expression.contains(<span class="string"><span class="delimiter">&quot;</span><span class="content"> eq </span><span class="delimiter">&quot;</span></span>))
-        {
-            <span class="comment">//...</span>
-        }
-        <span class="comment">//...</span>
-    }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>In several cases it is also useful to combine this feature with the <code>@Alternative</code> annotation provided by CDI.</p>
-</div>
-<div class="paragraph">
-<p>In addition to the following snippet, it is required to configure the
-implementation as alternative in the beans.xml file. This configuration entry
-will not be changed, for example for different environments, because it just gets
-active if it is not excluded during the bootstrapping process.</p>
-</div>
-<div class="listingblock">
-<div class="title">Excluding an Alternative implementation if the ProjectStage is different from Development</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Exclude</span>(exceptIfProjectStage = ProjectStage.Development.class)
-<span class="annotation">@Alternative</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyDevBean</span>
-{
-}</code></pre>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_custom_expressioninterpreter">Custom ExpressionInterpreter</h3>
-<div class="paragraph">
-<p>By default only a very simple and limited syntax is supported. In real
-projects there are usually quite concrete requirements. Since it would
-be very complex to support most of them, it is easier for users to
-implement an optimized syntax. For such cases a custom
-ExpressionInterpreter is needed:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Alternative</span>
-<span class="annotation">@Exclude</span>(onExpression = <span class="string"><span class="delimiter">&quot;</span><span class="content">environment!=HSQL</span><span class="delimiter">&quot;</span></span>, interpretedBy = ConfigAwareExpressionInterpreter.class)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DevDbBean</span> <span class="directive">implements</span> DbBean
-{
-}
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">ConfigAwareExpressionInterpreter</span> <span class="directive">implements</span> ExpressionInterpreter&lt;<span class="predefined-type">String</span>, <span class="predefined-type">Boolean</span>&gt;
-{
-    <span class="directive">public</span> <span class="predefined-type">Boolean</span> evaluate(<span class="predefined-type">String</span> expression)
-    {
-        <span class="keyword">if</span> (expression == <span class="predefined-constant">null</span>)
-        {
-            <span class="keyword">return</span> <span class="predefined-constant">false</span>;
-        }
-
-        <span class="predefined-type">String</span><span class="type">[]</span> values = expression.split(<span class="string"><span class="delimiter">&quot;</span><span class="content">!=</span><span class="delimiter">&quot;</span></span>);
-
-        <span class="keyword">if</span> (values.length != <span class="integer">2</span>)
-        {
-            <span class="keyword">throw</span> <span class="keyword">new</span> <span class="exception">IllegalArgumentException</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">'</span><span class="delimiter">&quot;</span></span> + expression + <span class="string"><span class="delimiter">&quot;</span><span class="content">' is not a supported syntax</span><span class="delimiter">&quot;</span></span>);
-        }
-
-        <span class="predefined-type">String</span> configuredValue = ConfigResolver.getPropertyValue(values[<span class="integer">0</span>], <span class="predefined-constant">null</span>);
-
-        <span class="comment">//exclude if null or the configured value is different</span>
-        <span class="keyword">return</span> configuredValue == <span class="predefined-constant">null</span> || !values[<span class="integer">1</span>].trim().equalsIgnoreCase(configuredValue);
-    }
-}</code></pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_type_safe_view_config">Type-safe View-Config</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>TODO (Overview)</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_literals">Literals</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Literals allow the instantiation of annotations by extending the
-abstract class <code>javax.enterprise.util.AnnotationLiteral</code></p>
-</div>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">PayByQualifier</span>
-       <span class="directive">extends</span> AnnotationLiteral&lt;PayBy&gt;
-       <span class="directive">implements</span> PayBy {}
-
- PayBy paybyCheque = <span class="keyword">new</span> PayByQualifier() { <span class="directive">public</span> PaymentMethod value() { <span class="keyword">return</span> CHEQUE; } };</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>DeltaSpike provides many annotation literals that you can use, including the following:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>AlternativeLiteral</p>
-</li>
-<li>
-<p>AnyLiteral</p>
-</li>
-<li>
-<p>ApplicationScopedLiteral</p>
-</li>
-<li>
-<p>ConversationScopedLiteral</p>
-</li>
-<li>
-<p>DefaultLiteral</p>
-</li>
-<li>
-<p>DependentScopeLiteral</p>
-</li>
-<li>
-<p>ModelLiteral</p>
-</li>
-<li>
-<p>NamedLiteral</p>
-</li>
-<li>
-<p>NewLiteral</p>
-</li>
-<li>
-<p>RequestedScopeLiteral</p>
-</li>
-<li>
-<p>SessionScopeLiteral</p>
-</li>
-<li>
-<p>Singleton</p>
-</li>
-<li>
-<p>SpecializesLiteral</p>
-</li>
-<li>
-<p>TypedLiteral</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_messages_and_i18n">Messages and i18n</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The following implementation is the minimal effort to use type-safe
-messages (which are hardcoded in this case).</p>
-</div>
-<div class="listingblock">
-<div class="title">Simple Type-safe Message</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@MessageBundle</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SimpleMessage</span>
-{
-    <span class="annotation">@MessageTemplate</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">Welcome to DeltaSpike</span><span class="delimiter">&quot;</span></span>)
-    <span class="predefined-type">String</span> welcomeToDeltaSpike();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The following implementation uses the key <code>welcome_to_deltaspike</code> to do
-a lookup in the default message bundle. The default bundle has the same
-name as the interface (but .properties instead of .java (/.class) as
-file extension).</p>
-</div>
-<div class="listingblock">
-<div class="title">Internationalized Type-safe Message</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@MessageBundle</span>
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SimpleMessage</span>
-{
-    <span class="annotation">@MessageTemplate</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">{welcome_to_deltaspike}</span><span class="delimiter">&quot;</span></span>)
-    <span class="predefined-type">String</span> welcomeToDeltaSpike();
-}
-
-org.apache.deltaspike.example.message.SimpleMessage
-
--&gt;
-
-org/apache/deltaspike/example/message/SimpleMessage.properties
-org/apache/deltaspike/example/message/SimpleMessage_en.properties
-org/apache/deltaspike/example/message/SimpleMessage_de.properties
-...
-
-<span class="comment">//content (as usual in message bundle files):</span>
-welcome_to_deltaspike=Welcome to DeltaSpike</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The following implementation uses the key <code>welcome_to_deltaspike</code> to do
-a lookup in a custom message bundle known by <code>CustomMessageResolver</code>.</p>
-</div>
-<div class="listingblock">
-<div class="title">Internationalized Type-safe Message</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@MessageBundle</span>
-<span class="annotation">@MessageContextConfig</span>(messageResolver = CustomMessageResolver.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SimpleMessage</span>
-{
-    <span class="annotation">@MessageTemplate</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">{welcome_to_deltaspike}</span><span class="delimiter">&quot;</span></span>)
-    <span class="predefined-type">String</span> welcomeToDeltaSpike();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p><code>@MessageContextConfig</code> allows to provide a custom <code>MessageResolver</code>,
-<code>MessageInterpolator</code> and <code>LocaleResolver</code>.</p>
-</div>
-<div class="paragraph">
-<p>The following implementation shows the usage of an internationalized
-simple type-safe message.</p>
-</div>
-<div class="listingblock">
-<div class="title">Internationalized Type-safe Message with Parameter/s</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@MessageBundle</span>
-<span class="annotation">@MessageContextConfig</span>(messageInterpolator = CustomMessageInterpolator.class)
-<span class="directive">public</span> <span class="type">interface</span> <span class="class">SimpleMessage</span>
-{
-    <span class="comment">//in the message bundle: welcome_to=Welcome to %s</span>
-
-    <span class="annotation">@MessageTemplate</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">{welcome_to}</span><span class="delimiter">&quot;</span></span>)
-    <span class="predefined-type">String</span> welcomeTo(<span class="predefined-type">String</span> name);
-}
-
-<span class="comment">//...</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyBean</span>
-{
-    <span class="annotation">@Inject</span>
-    <span class="directive">private</span> SimpleMessage messages;
-
-    <span class="directive">public</span> <span class="predefined-type">String</span> welcomeToDeltaSpike
-    {
-        <span class="keyword">return</span> <span class="local-variable">this</span>.messages.welcomeTo(<span class="string"><span class="delimiter">&quot;</span><span class="content">DeltaSpike</span><span class="delimiter">&quot;</span></span>);
-    }
-}</code></pre>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_dynamic_message_builder">Dynamic Message Builder</h3>
-<div class="sect3">
-<h4 id="_creating_message_instances">Creating Message Instances</h4>
-<div class="paragraph">
-<p>The following implementation creates an instance of <code>Message</code> for the
-key <code>hello</code>. The final text will be resolved and interpolated lazily.
-Later on it might be supported to provide a different <code>MessageContext</code>
-via <code>#toString(MessageContext)</code> like it is in MyFaces CODI right now.</p>
-</div>
-<div class="paragraph">
-<p>You can use <code>#argument(String)</code> to pass these arguments to the message
-template specified on <code>#template(String)</code> method. The template pattern
-uses printf-style format strings.</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">MyBean</span>
-{
-
-    <span class="annotation">@Inject</span>
-    <span class="directive">private</span> MessageContext messageContext;
-
-    <span class="directive">public</span> <span class="type">void</span> action()
-    {
-        Message message = <span class="local-variable">this</span>.messageContext.message();
-        write(message.template(<span class="string"><span class="delimiter">&quot;</span><span class="content">Hello %s from %s</span><span class="delimiter">&quot;</span></span>).argument(<span class="string"><span class="delimiter">&quot;</span><span class="content">World</span><span class="delimiter">&quot;</span></span>).argument(<span class="string"><span class="delimiter">&quot;</span><span class="content">DeltaSpike</span><span class="delimiter">&quot;</span></span>));
-    }
-    <span class="comment">//...</span>
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Besides the static configuration via <code>@MessageContextConfig#messageSource</code>, you
-can also specify the message sources dynamically.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Inject</span>
-<span class="directive">private</span> MessageContext messageContext;
-
-<span class="directive">public</span> <span class="type">void</span> action()
-{
-    Message message = <span class="local-variable">this</span>.messageContext.messageSource(<span class="string"><span class="delimiter">&quot;</span><span class="content">org.apache.deltaspike.example.message.Messages</span><span class="delimiter">&quot;</span></span>).message();
-    write(message.template(<span class="string"><span class="delimiter">&quot;</span><span class="content">{hello}</span><span class="delimiter">&quot;</span></span>).argument(<span class="string"><span class="delimiter">&quot;</span><span class="content">World</span><span class="delimiter">&quot;</span></span>).argument(<span class="string"><span class="delimiter">&quot;</span><span class="content">DeltaSpike</span><span class="delimiter">&quot;</span></span>));
-}
-<span class="comment">//...</span>
--&gt;
-
-org/apache/deltaspike/example/message/Messages.properties
-org/apache/deltaspike/example/message/Messages_en.properties
-org/apache/deltaspike/example/message/Messages_de.properties
-...
-
-<span class="comment">//content (as usual) in message bundle files:</span>
-hello=Hello %s from %s</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_customizing_the_message_context">Customizing the Message Context</h4>
-<div class="sect4">
-<h5 id="_messageresolver">MessageResolver</h5>
-<div class="paragraph">
-<p>A message-resolver is responsible for creating the message-text based on
-the message-descriptor (key or inline-text), the current locale (and in
-some cases the message-payload). (The supported format, for example, if it is
-required to escape a key, if inline-text is supported,&#8230;&#8203; depends on the
-concrete implementation.) In case of a message-key, the message-resolver
-has to transform it to the message-text by looking it up in a message
-source like a resource-bundle.</p>
-</div>
-<div class="paragraph">
-<p><strong>Configuration of a message-resolver</strong></p>
-</div>
-<div class="paragraph">
-<p>Besides the static configuration via <code>@MessageContextConfig#messageResolver</code>,
-you can use it dynamically via passing a custom message-resolver
-instance to the current messageContext:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Inject</span>
-<span class="directive">private</span> MessageContext messageContext;
-
-<span class="comment">//...</span>
-
-Message message = <span class="local-variable">this</span>.messageContext.messageResolver(<span class="keyword">new</span> CustomMessageResolver()).message();</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The result of a <code>MessageResolver</code> is the message-text. The text might
-contain placeholders which are processed by a <code>MessageInterpolator</code></p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_messageinterpolator">MessageInterpolator</h5>
-<div class="paragraph">
-<p>A <code>MessageInterpolator</code> replaces the placeholders in a message-text with
-the arguments of the message.</p>
-</div>
-<div class="paragraph">
-<p><strong>Configuration of a message-interpolator</strong></p>
-</div>
-<div class="paragraph">
-<p>Besides the static configuration via
-`@MessageContextConfig#messageInterpolator, you can use it dynamically
-via passing a custom message-interpolator instance to the current
-messageContext:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Inject</span>
-<span class="directive">private</span> MessageContext messageContext;
-
-<span class="comment">//...</span>
-Message message = <span class="local-variable">this</span>.messageContext.messageInterpolator(<span class="keyword">new</span> CustomMessageInterpolator()).message();</code></pre>
-</div>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_localeresolver">LocaleResolver</h5>
-<div class="paragraph">
-<p>A locale resolver provides the current locale. The locale is, for example, used
-to by a <code>MessageResolver</code> to choose the correct language for the
-message-text.</p>
-</div>
-<div class="paragraph">
-<p><strong>Configuration of a locale-resolver</strong></p>
-</div>
-<div class="paragraph">
-<p>Besides the static configuration via `@MessageContextConfig#localeResolver, you
-can use it dynamically via passing a custom locale-resolver instance to
-the current messageContext:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>@Inject
-private MessageContext messageContext;
-
-//...
-Message message = this.messageContext.localeResolver(new CustomLocaleResolver()).message();</pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_injecting_resources">Injecting Resources</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>DeltaSpike has simple APIs for performing basic resource loading and
-property file reading.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Inject</span>
-<span class="annotation">@InjectableResource</span>(<span class="string"><span class="delimiter">&quot;</span><span class="content">myfile.properties</span><span class="delimiter">&quot;</span></span>)
-<span class="directive">private</span> <span class="predefined-type">InputStream</span> inputStream;</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This can be used to read resources from the classpath or from the file
-system using the two default implementations&#8201;&#8212;&#8201;<code>ClasspathResourceProvider</code>
-and <code>FileResourceProvider</code>&#8201;&#8212;&#8201;or from any other source using a custom provider.</p>
-</div>
-<div class="sect2">
-<h3 id="_custom_resource_providers">Custom resource providers</h3>
-<div class="paragraph">
-<p>The <code>InjectableResourceProvider</code> interface can be implemented to allow reading from
-alternate sources if needed (e.g. database LOBs, NoSQL storage areas). A base class called <code>AbstractResourceProvider</code>
-is provided by DeltaSpike and contains most of the methods for potential implementations. The only method which must be
-provided is the <code>readStream(InjectableResource)</code> which returns an InputStream.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_exception_control">Exception Control</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Exception handling in DeltaSpike is based around the CDI eventing model.
-While the implementation of exception handlers may not be the same as a
-CDI event, and the programming model is not exactly the same as
-specifying a CDI event observer, the concepts are very similar.
-DeltaSpike makes use of events for many of its features. Eventing is
-actually the only way to start using DeltaSpike&#8217;s exception handling.</p>
-</div>
-<div class="paragraph">
-<p>This event is fired either by the application or a DeltaSpike exception
-handling integration. DeltaSpike then hands the exception off to a chain
-of registered handlers, which deal with the exception appropriately. The
-use of CDI events to connect exceptions to handlers makes this strategy
-of exception handling non-invasive and minimally coupled to the
-exception handling infrastructure.</p>
-</div>
-<div class="paragraph">
-<p>The exception handling process remains mostly transparent to the
-developer. In most cases, you register an exception handler simply by
-annotating a handler method. Alternatively, you can handle an exception
-programmatically, just as you would observe an event in CDI.</p>
-</div>
-<div class="sect2">
-<h3 id="_usage">Usage</h3>
-<div class="paragraph">
-<p>The entire exception handling process starts with an event. This helps
-keep your application minimally coupled to DeltaSpike, but also allows
-for further extension. Exception handling in DeltaSpike is all about
-letting you take care of exceptions the way that makes the most sense
-for your application Events provide this delicate balance. Firing the
-event is the main way of starting the exception handling proccess.</p>
-</div>
-<div class="paragraph">
-<p>Manually firing an event to use DeltaSpike&#8217;s exception handling is
-primarily used in your own try/catch blocks. It is very painless and also
-easy. Let&#8217;s examine a sample that might exist inside of a simple
-business logic lookup into an inventory database:</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">InventoryActions</span> {
-    <span class="annotation">@PersistenceContext</span> <span class="directive">private</span> EntityManager em;
-    <span class="annotation">@Inject</span> <span class="directive">private</span> <span class="predefined-type">Event</span>&lt;ExceptionToCatchEvent&gt; catchEvent;
-
-    <span class="directive">public</span> <span class="predefined-type">Integer</span> queryForItem(Item item) {
-        <span class="keyword">try</span> {
-          <span class="predefined-type">Query</span> q = em.createQuery(<span class="string"><span class="delimiter">&quot;</span><span class="content">SELECT i from Item i where i.id = :id</span><span class="delimiter">&quot;</span></span>);
-          q.setParameter(<span class="string"><span class="delimiter">&quot;</span><span class="content">id</span><span class="delimiter">&quot;</span></span>, item.getId());
-          <span class="keyword">return</span> q.getSingleResult();
-        } <span class="keyword">catch</span> (PersistenceException e) {
-          catchEvent.fire(<span class="keyword">new</span> ExceptionToCatchEvent(e));
-        }
-    }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>Event</code> of generic type <code>ExceptionToCatchEvent</code> is injected into
-your class for use later within a try/catch block.</p>
-</div>
-<div class="paragraph">
-<p>The event is fired with a new instance of <code>ExceptionToCatchEvent</code>
-constructed with the exception to be handled.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_exception_handlers">Exception Handlers</h3>
-<div class="paragraph">
-<p>As an application developer (i.e., an end user of DeltaSpike&#8217;s exception
-handling), you&#8217;ll be focused on writing exception handlers. An exception
-handler is a method on a CDI bean that is invoked to handle a specific
-type of exception. Within that method, you can implement any logic
-necessary to handle or respond to the exception.</p>
-</div>
-<div class="paragraph">
-<p><strong>If there are no exception handlers for an exception, the exception is
-rethrown - except <code>ExceptionToCatchEvent#optinal</code> is set to true</strong></p>
-</div>
-<div class="paragraph">
-<p>Given that exception handler beans are CDI beans, they can make use of
-dependency injection, be scoped, have interceptors or decorators and any
-other functionality available to CDI beans.</p>
-</div>
-<div class="paragraph">
-<p>Exception handler methods are designed to follow the syntax and
-semantics of CDI observers, with some special purpose exceptions
-explained in this guide. The advantage of this design is that exception
-handlers will be immediately familiar to you if you are studying or
-well-versed in CDI.</p>
-</div>
-<div class="paragraph">
-<p>In this and subsequent sections, you&#8217;ll learn how to define an exception
-handler, explore how and when it gets invoked, modify an exception and a
-stack trace, and even extend exception handling further through events
-that are fired during the handling workflow. We&#8217;ll begin by covering the
-two annotations that are used to declare an exception handler,
-<code>@ExceptionHandler</code> and <code>@Handles</code>, and <code>@BeforeHandles</code> to create a
-callback before the handler is called.</p>
-</div>
-<div class="paragraph">
-<p>Exception handlers are considered equal if they both handle the same
-exception class, have the same qualifiers, the same ordinal and the same
-value for <code>isBeforeHandler()</code>.</p>
-</div>
-<div class="paragraph">
-<p>Exception handlers are contained within exception handler beans, which
-are CDI beans annotated with <code>@ExceptionHandler</code>. Exception handlers are
-methods which have a parameter which is an instance of
-<code>ExceptionEvent&lt;T extends Throwable&gt;</code> annotated with the <code>@Handles</code>
-annotation.</p>
-</div>
-<div class="sect3">
-<h4 id="__exceptionhandler">@ExceptionHandler</h4>
-<div class="paragraph">
-<p>The <code>@ExceptionHandler</code> annotation is simply a marker annotation that
-instructs the DeltaSpike exception handling CDI extension to scan the
-bean for handler methods.</p>
-</div>
-<div class="paragraph">
-<p>Let&#8217;s designate a CDI bean as an exception handler by annotating it with
-<code>@ExceptionHandler</code>.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ExceptionHandler</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyHandlers</span> {}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>That&#8217;s all there is to it. Now we can begin defining exception handling
-methods on this bean.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="__handles_and_beforehandles">@Handles and @BeforeHandles</h4>
-<div class="paragraph">
-<p><code>@Handles</code> is a method parameter annotation that designates a method as
-an exception handler. Exception handler methods are registered on beans
-annotated with <code>@ExceptionHandler</code>. DeltaSpike will discover all such
-methods at deployment time.</p>
-</div>
-<div class="paragraph">
-<p>Let&#8217;s look at an example. The following method is invoked for every
-exception that DeltaSpike processes and prints the exception message to
-stdout. (<code>Throwable</code> is the base exception type in Java and thus
-represents all exceptions).</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ExceptionHandler</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyHandlers</span>
-{
-    <span class="type">void</span> printExceptions(<span class="annotation">@Handles</span> ExceptionEvent&lt;<span class="predefined-type">Throwable</span>&gt; evt)
-    {
-        <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">&quot;</span><span class="content">Something bad happened:</span><span class="delimiter">&quot;</span></span> +
-        evt.getException().getMessage());
-        evt.handleAndContinue();
-    }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>@Handles</code> annotation on the first parameter designates this method
-as an exception handler (though it is not required to be the first
-parameter). This parameter must be of type
-<code>ExceptionEvent&lt;T extends Throwable&gt;</code>, otherwise it is detected as a
-definition error. The type parameter designates which exception the
-method should handle. This method is notified of all exceptions
-(requested by the base exception type <code>Throwable</code>).</p>
-</div>
-<div class="paragraph">
-<p>The <code>ExceptionEvent</code> instance provides access to information about the
-exception and can be used to control exception handling flow. In this
-case, it is used to read the current exception being handled in the
-exception chain, as returned by <code>getException()</code>.</p>
-</div>
-<div class="paragraph">
-<p>This handler does not modify the invocation of subsequent handlers, as
-designated by invoking <code>handleAndContinue()</code> on <code>ExceptionEvent</code>. As
-this is the default behavior, this line could be omitted.</p>
-</div>
-<div class="paragraph">
-<p>The <code>@Handles</code> annotation must be placed on a parameter of the method,
-which must be of type <code>ExceptionEvent&lt;T extends Throwable&gt;</code>. Handler
-methods are similar to CDI observers and, as such, follow the same
-principles and guidelines as observers (such as invocation, injection of
-parameters, qualifiers, etc) with the following exceptions:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>a parameter of a handler method must be a <code>ExceptionEvent</code></p>
-</li>
-<li>
-<p>handlers are ordered before they are invoked (invocation order of
-observers is non-deterministic)</p>
-</li>
-<li>
-<p>any handler can prevent subsequent handlers from being invoked</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>In addition to designating a method as exception handler, the <code>@Handles</code>
-annotation specifies an <code>ordinal</code> about when the method should be
-invoked relative to other handler methods of the same type. Handlers
-with higher ordinal are invoked before handlers with a lower ordinal
-that handle the same exception type. The default ordinal (if not
-specified) is 0.</p>
-</div>
-<div class="paragraph">
-<p>The <code>@BeforeHandles</code> designates a method as a callback to happen before
-handlers are called.</p>
-</div>
-<div class="paragraph">
-<p>Let&#8217;s take a look at more sophisticated example that uses all the
-features of handlers to log all exceptions.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ExceptionHandler</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">MyHandlers</span>
-{
-   <span class="type">void</span> logExceptions(<span class="annotation">@BeforeHandles</span> <span class="annotation">@WebRequest</span> ExceptionEvent&lt;<span class="predefined-type">Throwable</span>&gt; evt, <span class="predefined-type">Logger</span> log)
-   {
-      log.warn(<span class="string"><span class="delimiter">&quot;</span><span class="content">Something bad happened: </span><span class="delimiter">&quot;</span></span> + evt.getException().getMessage());
-   }
-
-   <span class="type">void</span> logExceptions(<span class="annotation">@Handles</span> <span class="annotation">@WebRequest</span> ExceptionEvent&lt;<span class="predefined-type">Throwable</span>&gt; evt, <span class="predefined-type">Logger</span> log)
-   {
-      <span class="comment">// possibly send a HTTP Error code</span>
-   }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This handler has a default ordinal of 0 (the default value of the
-ordinal attribute on <code>@Handles</code>).</p>
-</div>
-<div class="paragraph">
-<p>This handler is qualified with <code>@WebRequest</code>. When DeltaSpike calculates
-the handler chain, it filters handlers based on the exception type and
-qualifiers. This handler will only be invoked for exceptions passed to
-DeltaSpike that carry the <code>@WebRequest</code> qualifier. We&#8217;ll assume this
-qualifier distinguishes a web page request from a REST request.</p>
-</div>
-<div class="paragraph">
-<p>Any additional parameters of a handler method are treated as injection
-points. These parameters are injected into the handler when it is
-invoked by DeltaSpike. In this case, we are injecting a <code>Logger</code> bean
-that must be defined within the application (or by an extension).</p>
-</div>
-<div class="paragraph">
-<p>A handler is guaranteed to only be invoked once per exception
-(automatically muted), unless it re-enables itself by invoking the
-<code>unmute()</code> method on the <code>ExceptionEvent</code> instance.</p>
-</div>
-<div class="paragraph">
-<p>Handlers must not throw checked exceptions, and should avoid throwing
-unchecked exceptions. Should a handler throw an unchecked exception it
-will propagate up the stack and all handling done via DeltaSpike will
-cease. Any exception that was being handled will be lost.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ordinal">Ordinal</h4>
-<div class="paragraph">
-<p>When DeltaSpike finds more than one handler for the same exception type,
-it orders the handlers by ordinal. Handlers with higher ordinal are
-executed before handlers with a lower ordinal. If DeltaSpike detects two
-handlers for the same type with the same ordinal, the order is
-non-deterministic.</p>
-</div>
-<div class="paragraph">
-<p>Let&#8217;s define two handlers with different ordinals:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="type">void</span> handleIOExceptionFirst(<span class="annotation">@Handles</span>(ordinal = <span class="integer">100</span>) ExceptionEvent&lt;<span class="exception">IOException</span>&gt; evt)
-{
-   <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">&quot;</span><span class="content">Invoked first</span><span class="delimiter">&quot;</span></span>);
-}
-
-<span class="type">void</span> handleIOExceptionSecond(<span class="annotation">@Handles</span> ExceptionEvent&lt;<span class="exception">IOException</span>&gt; evt)
-{
- <span class="predefined-type">System</span>.out.println(<span class="error">“</span>Invoked second<span class="error">”</span>);
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The first method is invoked first since it has a higher ordinal (100)
-than the second method, which has the default ordinal (0).</p>
-</div>
-<div class="paragraph">
-<p>To summarize, here&#8217;s how DeltaSpike determines the order of handlers to
-invoke (until a handler marks exception as handled):</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Unwrap exception stack</p>
-</li>
-<li>
-<p>Begin processing root cause</p>
-</li>
-<li>
-<p>Invoke any callback methods annotated with @BeforeHandles for the closest type to the exception</p>
-</li>
-<li>
-<p>Find handler for the closest type to the exception</p>
-</li>
-<li>
-<p>If multiple handlers for same type, invoke handlers with higher ordinal first</p>
-</li>
-<li>
-<p>Continue above steps for each exception in stack</p>
-</li>
-</ol>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_exception_chain_processing">Exception Chain Processing</h3>
-<div class="paragraph">
-<p>When an exception is thrown, chances are it is nested (wrapped) inside
-other exceptions. (If you&#8217;ve ever examined a server log, you&#8217;ll
-appreciate this fact). The collection of exceptions in its entirety is
-termed an exception chain.</p>
-</div>
-<div class="paragraph">
-<p>The outermost exception of an exception chain (e.g., EJBException,
-ServletException, etc) is probably of little use to exception handlers.
-That&#8217;s why DeltaSpike does not simply pass the exception chain directly
-to the exception handlers. Instead, it intelligently unwraps the chain
-and treats the root exception cause as the primary exception.</p>
-</div>
-<div class="paragraph">
-<p>The first exception handlers to be invoked by DeltaSpike are those that
-match the type of root cause. Thus, instead of seeing a vague
-<code>EJBException</code>, your handlers will instead see an meaningful exception
-such as <code>ConstraintViolationException</code>. <em>This feature, alone, makes
-DeltaSpike&#8217;s exception handling a worthwhile tool.</em></p>
-</div>
-<div class="paragraph">
-<p>DeltaSpike continues to work through the exception chain, notifying
-handlers of each exception in the stack, until a handler flags the
-exception as handled or the whole exception chain has been iterated.
-Once an exception is marked as handled, DeltaSpike stops processing the
-exception chain. If a handler instructs DeltaSpike to rethrow the
-exception (by invoking <code>ExceptionEvent#throwOriginal()</code>, DeltaSpike will
-rethrow the exception outside the DeltaSpike exception handling
-infrastructure. Otherwise, it simply returns flow control to the caller.</p>
-</div>
-<div class="paragraph">
-<p>Consider a exception chain containing the following nested causes (from
-outer cause to root cause):</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>EJBException</p>
-</li>
-<li>
-<p>PersistenceException</p>
-</li>
-<li>
-<p>SQLGrammarException</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>DeltaSpike will unwrap this exception and notify handlers in the
-following order:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>SQLGrammarException</p>
-</li>
-<li>
-<p>PersistenceException</p>
-</li>
-<li>
-<p>EJBException</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>If there&#8217;s a handler for <code>PersistenceException</code>, it will likely prevent
-the handlers for <code>EJBException</code> from being invoked, which is a good
-thing since what useful information can really be obtained from
-<code>EJBException</code>?</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_apis_for_exception_information_and_flow_control">APIs for Exception Information and Flow Control</h3>
-<div class="paragraph">
-<p>There are two APIs provided by DeltaSpike that should be familiar to
-application developers:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>ExceptionEvent</code></p>
-</li>
-<li>
-<p><code>ExceptionStackEvent</code></p>
-</li>
-</ul>
-</div>
-<div class="sect3">
-<h4 id="_exceptionevent">ExceptionEvent</h4>
-<div class="paragraph">
-<p>In addition to providing information about the exception being handled,
-the <code>ExceptionEvent</code> object contains methods to control the exception
-handling process, such as rethrowing the exception, aborting the handler
-chain or unmuting the current handler. Five methods exist on the
-<code>ExceptionEvent</code> object to give flow control to the handler</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<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>&#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>&#8201;&#8212;&#8201;marks the exception as handled and terminates further
-handling.</p>
-</li>
-<li>
-<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>&#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>&#8201;&#8212;&#8201;Throw a new exception after this handler is
-invoked</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Once a handler is invoked it is muted, meaning it will not be run again
-for that exception chain, unless it is explicitly marked as unmuted via
-the <code>unmute()</code> method on <code>ExceptionEvent</code>.</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_scopes">Scopes</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>DeltaSpike Core provides the API and SPI for several scopes. Currently
-all scopes are only implemented in the <a href="jsf.html#_scopes">JSF module</a>.</p>
-</div>
-<div class="sect2">
-<h3 id="__windowscoped">@WindowScoped</h3>
-
-</div>
-<div class="sect2">
-<h3 id="__viewaccessscoped">@ViewAccessScoped</h3>
-
-</div>
-<div class="sect2">
-<h3 id="__groupedconversationscoped">@GroupedConversationScoped</h3>
-
-</div>
-<div class="sect2">
-<h3 id="_creating_a_custom_cdi_scope">Creating a Custom CDI Scope</h3>
-<div class="paragraph">
-<p>To create a custom CDI scope to match your needs, complete the following steps:</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Create an Annotation with annotated with @javax.inject.Scope;</p>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Scope</span>
-<span class="annotation">@Retention</span>(<span class="predefined-type">RetentionPolicy</span>.RUNTIME)
-<span class="annotation">@Target</span>({<span class="predefined-type">ElementType</span>.TYPE,<span class="predefined-type">ElementType</span>.METHOD,<span class="predefined-type">ElementType</span>.FIELD})
-<span class="directive">public</span> <span class="annotation">@interface</span> ACustomScope {}</code></pre>
-</div>
-</div>
-</li>
-<li>
-<p>Create an Extension to add the scope and a context for it.</p>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ACustomScopeExtension</span> <span class="directive">implements</span> Extension, <span class="predefined-type">Serializable</span> {
-
-    <span class="directive">public</span> <span class="type">void</span> addACustomScope(<span class="annotation">@Observes</span> <span class="directive">final</span> BeforeBeanDiscovery event) {
-        event.addScope(ACustomScope.class, <span class="predefined-constant">true</span>, <span class="predefined-constant">false</span>);
-    }
-
-    <span class="directive">public</span> <span class="type">void</span> registerACustomScopeContext(<span class="annotation">@Observes</span> <span class="directive">final</span> AfterBeanDiscovery event) {
-        event.addContext(<span class="keyword">new</span> ACustomScopeContext());
-    }
-}</code></pre>
-</div>
-</div>
-</li>
-<li>
-<p>Implement a javax.enterprise.context.spi.Context interface to hold the
-javax.enterprise.inject.spi.Bean instances according to your needs.</p>
-<div class="listingblock">
-<div class="title">Example</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">ACustomScopeContext</span> <span class="directive">implements</span> <span class="predefined-type">Context</span>, <span class="predefined-type">Serializable</span> {
-
-  <span class="comment">// Get the scope type of the context object.</span>
-    <span class="directive">public</span> <span class="predefined-type">Class</span>&lt;? <span class="directive">extends</span> <span class="predefined-type">Annotation</span>&gt; getScope() {
-        <span class="keyword">return</span> ACustomScope.class;
-    }
-
-    <span class="comment">// Return an existing instance of certain contextual type or create a new instance by calling</span>
-    <span class="comment">// javax.enterprise.context.spi.Contextual.create(CreationalContext) and return the new instance.</span>
-    <span class="directive">public</span> &lt;T&gt; T get(Contextual&lt;T&gt; contextual, CreationalContext&lt;T&gt; creationalContext) {
-        Bean bean = (Bean) contextual;
-        <span class="comment">// you can store the bean somewhere</span>
-        <span class="keyword">if</span> (somewhere.containsKey(bean.getName())) {
-            <span class="keyword">return</span> (T) somewhere.get(bean.getName());
-        } <span class="keyword">else</span> {
-            T t = (T) bean.create(creationalContext);
-            somewhere.put(bean.getName(), t);
-            <span class="keyword">return</span> t;
-        }
-    }
-
-    <span class="comment">// Return an existing instance of a certain contextual type or a null value.</span>
-    <span class="directive">public</span> &lt;T&gt; T get(Contextual&lt;T&gt; contextual) {
-        Bean bean = (Bean) contextual;
-        <span class="comment">// you can store the bean somewhere</span>
-        <span class="keyword">if</span> (somewhere.containsKey(bean.getName())) {
-            <span class="keyword">return</span> (T) somewhere.get(bean.getName());
-        } <span class="keyword">else</span> {
-            <span class="keyword">return</span> <span class="predefined-constant">null</span>;
-        }
-    }
-
-  <span class="comment">// Determines if the context object is active.</span>
-    <span class="directive">public</span> <span class="type">boolean</span> isActive() {
-        <span class="keyword">return</span> <span class="predefined-constant">true</span>;
-    }
-
-}</code></pre>
-</div>
-</div>
-</li>
-</ol>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_deactivatable">Deactivatable</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>DeltaSpike allows you to deactivate its own pre-configured parts (like Extensions, event-broadcasters,&#8230;&#8203;).
-Therefore DeltaSpike offers <code>org.apache.deltaspike.core.spi.activation.ClassDeactivator</code> and
-<code>org.apache.deltaspike.core.spi.activation.Deactivatable</code>.</p>
-</div>
-<div class="paragraph">
-<p>A <code>ClassDeactivator</code> allows to specify deactivated classes (if they implement <code>Deactivatable</code>)
-which can&#8217;t be deactivated/customized via std. CDI mechanisms
-(like the veto-method or alternative/specialized CDI-beans).
-This might be the case e.g. for CDI Extensions because CDI mechanisms are not available at startup time.</p>
-</div>
-<div class="paragraph">
-<p>Use it mainly to deactivate specific parts <strong>explicitly</strong> (blacklist approach),
-if there is an issue with such parts (and waiting for the next release isn&#8217;t an option).</p>
-</div>
-<div class="paragraph">
-<p>You just need to implement your <a href="spi.html#_classdeactivator">ClassDeactivator</a>.</p>
-</div>
-<div class="paragraph">
-<p>The <code>ClassDeactivator</code> should be resolved by any ConfigSource using the
-key <code>org.apache.deltaspike.core.spi.activation.ClassDeactivator</code>. For
-example, if we need to provide our own version of the SecurityExtension,
-we can disable the SecurityExtension provided by DeltaSpike with the following <code>ClassDeactivator</code>:</p>
-</div>
-<div class="listingblock">
-<div class="title">Disable a specific extension</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CustomClassDeactivator</span> <span class="directive">implements</span> ClassDeactivator
-{
-    <span class="directive">private</span> <span class="directive">static</span> <span class="directive">final</span> <span class="type">long</span> serialVersionUID = <span class="integer">1L</span>;
-
-    <span class="annotation">@Override</span>
-    <span class="directive">public</span> <span class="predefined-type">Boolean</span> isActivated(<span class="predefined-type">Class</span>&lt;? <span class="directive">extends</span> Deactivatable&gt; targetClass)
-    {
-        <span class="keyword">if</span> (targetClass.equals(SecurityExtension.class))
-        {
-            <span class="keyword">return</span> <span class="predefined-type">Boolean</span>.FALSE;
-        }
-        <span class="keyword">return</span> <span class="predefined-constant">null</span>; <span class="comment">//no result for the given class</span>
-    }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Now, we can use the file <code>/META-INF/apache-deltaspike.properties</code> (or any
-other <a href="configuration.html#_configsources_provided_by_default">ConfigSource</a>) with the following key/value:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>org.apache.deltaspike.core.spi.activation.ClassDeactivator=org.test.CustomClassDeactivator</pre>
-</div>
-</div>
-<div class="paragraph">
-<p>SecurityExtension still gets started, because it isn&#8217;t possible to veto it, however, it isn&#8217;t processing beans (once deactivated)
-and therefore it&#8217;s e.g. possible to extend and customize the default implementation provided by DeltaSpike.</p>
-</div>
-<div class="paragraph">
-<p>The following listing shows how to enable only a minimal set of extensions.
-Technically that&#8217;s possible, however, it isn&#8217;t suggested to use such an approach,
-because you might disable mechanisms need later on (in your project).</p>
-</div>
-<div class="listingblock">
-<div class="title">Possible but not suggested</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">WhitelistFilter</span> <span class="directive">implements</span> ClassDeactivator
-{
-    <span class="directive">private</span> <span class="predefined-type">List</span>&lt;<span class="predefined-type">Class</span>&lt;?&gt;&gt; limitedExtensions =
-      <span class="keyword">new</span> <span class="predefined-type">ArrayList</span>&lt;<span class="predefined-type">Class</span>&lt;?&gt;&gt;()
-    {{
-        add(ConfigurationExtension.class);
-        add(PartialBeanBindingExtension.class);
-        add(RepositoryExtension.class);
-    }};
-
-    <span class="annotation">@Override</span>
-    <span class="directive">public</span> <span class="predefined-type">Boolean</span> isActivated(
-      <span class="predefined-type">Class</span>&lt;? <span class="directive">extends</span> Deactivatable&gt; deactivatableClass)
-    {
-        <span class="keyword">return</span> !Extension.class.isAssignableFrom(deactivatableClass) ||
-            limitedExtensions.contains(deactivatableClass);
-    }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Instead it&#8217;s better to disable the part you really like to deactivate (see <code>CustomClassDeactivator</code>).</p>
-</div>
-<div class="sect2">
-<h3 id="_deactivate_deactivatable_classes_via_config">Deactivate Deactivatable-Classes via Config</h3>
-<div class="paragraph">
-<p>The default implementation of <code>ClassDeactivator</code> allows to deactivate classes by adding config-entries to one of your config-sources (like <code>META-INF\apache-deltaspike.properties</code>).
-The following example shows how it would look like e.g. in case of the SecurityExtension:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>deactivate.org.apache.deltaspike.security.impl.extension.SecurityExtension=true</pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_asynchronous_operations">Asynchronous Operations</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>DeltaSpike provides support for executing code in an asynchronous manner.  The behavior is implemented as three different interceptors for your beans.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>@Futureable</code> - Designed for bean methods that return <code>Future&#8217;s</code> of some form.  The method call will automatically be submitted to an <code>ExecutorService</code></p>
-</li>
-<li>
-<p><code>@Locked</code> - Ability to prevent concurrent access to a method based on its usage of reads/writes.</p>
-</li>
-<li>
-<p><code>@Throttled</code> - Ability to limit how frequently a method can be invoked.</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_utilities">Utilities</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<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="sect2">
-<h3 id="_annotationutils">AnnotationUtils</h3>
-<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="sect2">
-<h3 id="_arraysutils">ArraysUtils</h3>
-<div class="paragraph">
-<p>A collection of utilities for working with Arrays</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<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>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_beanutils">BeanUtils</h3>
-<div class="paragraph">
-<p>A set of utility methods for working with beans.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>#getQualifiers</code>&#8201;&#8212;&#8201;Extract the qualifiers from a set of annotations.</p>
-</li>
-<li>
-<p><code>#extractAnnotation</code>&#8201;&#8212;&#8201;Extract the annotations.</p>
-</li>
-<li>
-<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>
-</div>
-<div class="sect2">
-<h3 id="_contextutils">ContextUtils</h3>
-<div class="paragraph">
-<p>A set of utility methods for working with contexts.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>#isContextActive</code>&#8201;&#8212;&#8201;Checks if the context for the scope annotation is active.</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_classdeactivationutils">ClassDeactivationUtils</h3>
-<div class="paragraph">
-<p>Helper methods for <code>ClassDeactivator</code></p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>#isActivated</code>&#8201;&#8212;&#8201;Evaluates if the given <code>Deactivatable</code> is active.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>To add a custom <code>ClassDeactivator</code> add <code>org.apache.deltaspike.core.spi.activation.ClassDeactivator=my.CustomClassDeactivator</code> to <code>META-INF\apache-deltaspike.properties</code>. Or configure it via a custom <code>ConfigSource</code>.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_exceptionutils">ExceptionUtils</h3>
-<div class="paragraph">
-<p>Helper methods to deal with Exceptions</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<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>&#8201;&#8212;&#8201;helper which allows to use a trick to throw a cached checked exception without a wrapping exception.</p>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_propertyfileutils">PropertyFileUtils</h3>
-<div class="paragraph">
-<p>Helper methods for Property files</p>
-</div>
-<div class="ulist">
-<ul>
-<li>

[... 2243 lines stripped ...]


Mime
View raw message