You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2020/02/05 11:59:54 UTC
svn commit: r1056146 [6/18] - in /websites/staging/deltaspike/trunk/content:
./ documentation/
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 Wed Feb 5 11:59:54 2020
@@ -1,2179 +1,2179 @@
-<!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>
-</div>
-<div class="sect1">
-<h2 id="_deltaspike_cipherservice">DeltaSpike CipherService</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Apache DeltaSpike also provides an <a href="encryption.html">Encryption</a> mechanism for handling secret values within your application.</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’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’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<MyQualifier> <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">"</span><span class="content">myBean</span><span class="delimiter">"</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">"</span><span class="content">myBean</span><span class="delimiter">"</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 → 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><MyServiceInterface> 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><MyServiceInterface> 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 — as implied by their name — depend on the lifecycle of
-the contextual instance which declares them and get destroyed along with this declaring bean’s instance.</p>
-</div>
-<div class="paragraph">
-<p>However, if dependent-scoped instances are obtained programmatically using <code>DependentProvider</code>, there’s no
-"declaring bean" to speak of and they <strong>must be destroyed manually</strong>.</p>
-</div>
-<div class="listingblock">
-<div class="title">Obtaining and destroying an instance of a dependent-scoped bean using DependentProvider</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">DependentProvider<MyBean> myBeanProvider = BeanProvider.getDependent(MyBean.class);
-MyBean myBean = myBeanProvider.get();
-
-<span class="comment">// ...work with myBean...</span>
-
-myBeanProvider.destroy();</code></pre>
-</div>
-</div>
-</div>
-</div>
-</div>
-<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 — the <code>AnnotationLiteral</code> class.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CurrentUserLiteral</span> <span class="directive">extends</span> AnnotationLiteral<CurrentUser> <span class="directive">implements</span> CurrentUser {}</code></pre>
-</div>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">CurrentUser user = <span class="keyword">new</span> CurrentUserLiteral() {};</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p><code>AnnotationLiteral</code> can however be used only if the annotation class name is known beforehand.
-<code>AnnotationInstanceProvider</code> is the solution for dynamic creation of annotation instances, with
-the option to provide a map of values for annotation members. That might be useful in many situations,
-especially for CDI extension authors. For example:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>avoiding a compile-time dependency on an annotation class</p>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Class</span><? <span class="directive">extends</span> <span class="predefined-type">Annotation</span>> priorityAnnotationClass = ClassUtils.tryToLoadClassForName(<span class="string"><span class="delimiter">"</span><span class="content">javax.annotation.Priority</span><span class="delimiter">"</span></span>);
-priorityAnnotationInstance = AnnotationInstanceProvider.of(priorityAnnotationClass, mapOfMemberValues);</code></pre>
-</div>
-</div>
-</li>
-<li>
-<p>getting an instance of a dynamically obtained annotation class</p>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Annotation</span> exceptionQualifier = AnnotationInstanceProvider.of(jsfModuleConfig.getExceptionQualifier());</code></pre>
-</div>
-</div>
-</li>
-<li>
-<p>or simply for the sake of a prettier syntax compared to <code>AnnotationLiteral</code></p>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">CurrentUser principal = AnnotationInstanceProvider.of(CurrentUser.class);</code></pre>
-</div>
-</div>
-</li>
-</ul>
-</div>
-</div>
-</div>
-<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’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">"</span><span class="content">db==prodDB</span><span class="delimiter">"</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">"</span><span class="content">db eq prodDB</span><span class="delimiter">"</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<<span class="predefined-type">String</span>, <span class="predefined-type">Boolean</span>>
-{
- <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">"</span><span class="content"> eq </span><span class="delimiter">"</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">"</span><span class="content">environment!=HSQL</span><span class="delimiter">"</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<<span class="predefined-type">String</span>, <span class="predefined-type">Boolean</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 == <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">"</span><span class="content">!=</span><span class="delimiter">"</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">"</span><span class="content">'</span><span class="delimiter">"</span></span> + expression + <span class="string"><span class="delimiter">"</span><span class="content">' is not a supported syntax</span><span class="delimiter">"</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<PayBy>
- <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">"</span><span class="content">Welcome to DeltaSpike</span><span class="delimiter">"</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">"</span><span class="content">{welcome_to_deltaspike}</span><span class="delimiter">"</span></span>)
- <span class="predefined-type">String</span> welcomeToDeltaSpike();
-}
-
-org.apache.deltaspike.example.message.SimpleMessage
-
-->
-
-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">"</span><span class="content">{welcome_to_deltaspike}</span><span class="delimiter">"</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">"</span><span class="content">{welcome_to}</span><span class="delimiter">"</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">"</span><span class="content">DeltaSpike</span><span class="delimiter">"</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">"</span><span class="content">Hello %s from %s</span><span class="delimiter">"</span></span>).argument(<span class="string"><span class="delimiter">"</span><span class="content">World</span><span class="delimiter">"</span></span>).argument(<span class="string"><span class="delimiter">"</span><span class="content">DeltaSpike</span><span class="delimiter">"</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">"</span><span class="content">org.apache.deltaspike.example.message.Messages</span><span class="delimiter">"</span></span>).message();
- write(message.template(<span class="string"><span class="delimiter">"</span><span class="content">{hello}</span><span class="delimiter">"</span></span>).argument(<span class="string"><span class="delimiter">"</span><span class="content">World</span><span class="delimiter">"</span></span>).argument(<span class="string"><span class="delimiter">"</span><span class="content">DeltaSpike</span><span class="delimiter">"</span></span>));
-}
-<span class="comment">//...</span>
-->
-
-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,…​ 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>(location=<span class="string"><span class="delimiter">"</span><span class="content">myfile.properties</span><span class="delimiter">"</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 — <code>ClasspathResourceProvider</code>
-and <code>FileResourceProvider</code> — 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’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’s exception handling is
-primarily used in your own try/catch blocks. It is very painless and also
-easy. Let’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><ExceptionToCatchEvent> 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">"</span><span class="content">SELECT i from Item i where i.id = :id</span><span class="delimiter">"</span></span>);
- q.setParameter(<span class="string"><span class="delimiter">"</span><span class="content">id</span><span class="delimiter">"</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’s exception
-handling), you’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’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’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<T extends Throwable></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’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’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’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<<span class="predefined-type">Throwable</span>> evt)
- {
- <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">"</span><span class="content">Something bad happened:</span><span class="delimiter">"</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<T extends Throwable></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<T extends Throwable></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’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<<span class="predefined-type">Throwable</span>> evt, <span class="predefined-type">Logger</span> log)
- {
- log.warn(<span class="string"><span class="delimiter">"</span><span class="content">Something bad happened: </span><span class="delimiter">"</span></span> + evt.getException().getMessage());
- }
-
- <span class="type">void</span> logExceptions(<span class="annotation">@Handles</span> <span class="annotation">@WebRequest</span> ExceptionEvent<<span class="predefined-type">Throwable</span>> 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’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’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<<span class="exception">IOException</span>> evt)
-{
- <span class="predefined-type">System</span>.out.println(<span class="string"><span class="delimiter">"</span><span class="content">Invoked first</span><span class="delimiter">"</span></span>);
-}
-
-<span class="type">void</span> handleIOExceptionSecond(<span class="annotation">@Handles</span> ExceptionEvent<<span class="exception">IOException</span>> 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’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’ve ever examined a server log, you’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’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’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’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> — 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
-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
-handling.</p>
-</li>
-<li>
-<p><code>handleAndContinue()</code> — default. Marks the exception as handled and
-proceeds with the rest of the handlers.</p>
-</li>
-<li>
-<p><code>skipCause()</code> — marks the exception as handled, but proceeds to the
-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
-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><? <span class="directive">extends</span> <span class="predefined-type">Annotation</span>> 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> <T> T get(Contextual<T> contextual, CreationalContext<T> 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> <T> T get(Contextual<T> 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,…​).
-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’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’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><? <span class="directive">extends</span> Deactivatable> 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’t possible to veto it, however, it isn’t processing beans (once deactivated)
-and therefore it’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’s possible, however, it isn’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><<span class="predefined-type">Class</span><?>> limitedExtensions =
- <span class="keyword">new</span> <span class="predefined-type">ArrayList</span><<span class="predefined-type">Class</span><?>>()
- {{
- 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><? <span class="directive">extends</span> Deactivatable> deactivatableClass)
- {
- <span class="keyword">return</span> !Extension.class.isAssignableFrom(deactivatableClass) ||
- limitedExtensions.contains(deactivatableClass);
- }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Instead it’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’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="__futureable_configuration">@Futureable configuration</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The strategy to find the <code>ExecutorService</code> associated to the <code>@Futureable</code> name is the following one:</p>
-</div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Check if there is a CDI bean of type <code>ExecutorService</code> with the name of the pool, if not try 2</p>
-</li>
-<li>
-<p>Check if there is a JNDI entry matching the pool name directly or prefixed with <code>java:app/</code>, <code>java:global/</code>, <code>java:global/threads/</code>, <code>java:global/deltaspike/</code>, <code>java:</code>, if not try 3</p>
-</li>
-<li>
-<p>Read the configuration and create a <code>ThreadPoolExecutor</code></p>
-</li>
-</ol>
-</div>
-<div class="admonitionblock important">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-important" title="Important"></i>
-</td>
-<td class="content">
-the instance is looked up only once so from the first time it was read you can’t change any configuration anymore.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>If you rely on the last option (configured executor) here are the keys you can set in DeltaSpike configuration:</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<colgroup>
-<col style="width: 33%;">
-<col style="width: 33%;">
-<col style="width: 33%;">
-</colgroup>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Key</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Description</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Default</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.coreSize</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The core size of the pool.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Number of available processors</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.maxSize</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The max size of the pool.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">coreSize value</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.keepAlive.value</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Pool keep alive (when a thread is released).</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">0</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.keepAlive.unit</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Unit of keepAlive.value. It must match a <code>TIMEUNIT</code> name.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">MILLISECONDS</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.queue.type</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The task queue type of the executor. Can be <code>ARRAY</code> to use an <code>ArrayBlockingQueue</code>, <code>LINKED</code> for a <code>LinkedBlockingQueue</code> or <code>SYNCHRONOUS</code> for a <code>SynchronousQueue</code>.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">LINKED</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">futureable.pool.<pool name>.queue.fair</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">For synchronous and array queue types, if the queue is fair.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">false</p></td>
-</tr>
-<tr>
[... 2496 lines stripped ...]