You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by ra...@apache.org on 2014/11/26 21:18:04 UTC
svn commit: r1641919 [3/10] - in
/deltaspike/site/trunk/content/documentation-staging: ./ releasenotes/
Added: deltaspike/site/trunk/content/documentation-staging/core.html
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/documentation-staging/core.html?rev=1641919&view=auto
==============================================================================
--- deltaspike/site/trunk/content/documentation-staging/core.html (added)
+++ deltaspike/site/trunk/content/documentation-staging/core.html Wed Nov 26 20:18:03 2014
@@ -0,0 +1,1651 @@
+<!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">
+
+<title>Core</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">
+
+<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;
+}
+</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="http://deltaspike.apache.org/index.html">Apache
+ DeltaSpike</a>
+ <div class="nav-collapse">
+ <ul class="nav">
+ <li class="active"><a
+ href="http://deltaspike.apache.org/index.html">Home</a></li>
+ <li><a href="http://deltaspike.apache.org/documentation">Documentation</a></li>
+ <li><a href="http://deltaspike.apache.org/javadoc.html">Javadoc</a></li>
+ <li><a href="http://deltaspike.apache.org/documentation/source.html">Source</a></li>
+ <li><a href="http://deltaspike.apache.org/download.html">Download</a></li>
+ <li><a href="http://deltaspike.apache.org/community.html">Community</a></li>
+ <!-- <li><a href="./support.html">Support</a></li> -->
+ <li><a href="http://deltaspike.apache.org/news.html">News</a></li>
+ <li><a
+ href="http://deltaspike.apache.org/migration-guide.html">Migration</a></li>
+ </ul>
+ </div>
+ <!--/.nav-collapse -->
+ <form id="search-form" action="http://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">
+ <div class="span12">
+ <div class="page-title">
+ <h1>Core</h1>
+ </div>
+
+ <div id="toc" class="toc">
+ <ul class="sectlevel1">
+<li><a href="#_core_api">Core - API</a>
+<ul class="sectlevel2">
+<li><a href="#_deltaspike_configuration">DeltaSpike Configuration</a></li>
+<li><a href="#_beanprovider">BeanProvider</a></li>
+<li><a href="#_beanmanagerprovider">BeanManagerProvider</a></li>
+<li><a href="#_type_safe_projectstage">Type-safe ProjectStage</a></li>
+<li><a href="#__exclude">@Exclude</a>
+<ul class="sectlevel3">
+<li><a href="#_custom_expressioninterpreter">Custom ExpressionInterpreter</a></li>
+</ul>
+</li>
+<li><a href="#_type_safe_view_config">Type-safe View-Config</a></li>
+<li><a href="#_literals">Literals</a></li>
+<li><a href="#_messages_i18n">Messages & I18n</a></li>
+<li><a href="#_dynamic_message_builder">Dynamic Message Builder</a>
+<ul class="sectlevel3">
+<li><a href="#_creating_message_instances">Creating message instances</a></li>
+<li><a href="#_customizing_the_message_context">Customizing the message context</a></li>
+</ul>
+</li>
+<li><a href="#_injecting_resources">Injecting Resources</a></li>
+<li><a href="#_exception_control">Exception Control</a>
+<ul class="sectlevel3">
+<li><a href="#_usage">Usage</a></li>
+<li><a href="#_exception_handlers">Exception handlers</a></li>
+<li><a href="#_exception_chain_processing">Exception Chain Processing</a></li>
+<li><a href="#_apis_for_exception_information_and_flow_control">APIs for exception information and flow control</a></li>
+</ul>
+</li>
+<li><a href="#_scopes">Scopes</a>
+<ul class="sectlevel3">
+<li><a href="#__windowscoped">@WindowScoped</a></li>
+<li><a href="#__viewaccessscoped">@ViewAccessScoped</a></li>
+<li><a href="#__groupedconversationscoped">@GroupedConversationScoped</a></li>
+</ul>
+</li>
+<li><a href="#_creating_a_custom_cdi_scope">Creating a custom CDI Scope</a></li>
+<li><a href="#_deactivatable">Deactivatable</a></li>
+</ul>
+</li>
+<li><a href="#_core_utils">Core - Utils</a>
+<ul class="sectlevel2">
+<li><a href="#_arraysutils">ArraysUtils</a></li>
+<li><a href="#_beanutils">BeanUtils</a></li>
+<li><a href="#_classdeactivationutils">ClassDeactivationUtils</a></li>
+<li><a href="#_exceptionutils">ExceptionUtils</a></li>
+<li><a href="#_propertyfileutils">PropertyFileUtils</a></li>
+<li><a href="#_proxyutils">ProxyUtils</a></li>
+<li><a href="#_stringutils">StringUtils</a></li>
+</ul>
+</li>
+</ul>
+ <hr>
+
+ <div class="sect1">
+<h2 id="_core_api">Core - API</h2>
+<div class="sectionbody">
+<div class="sect2">
+<h3 id="_deltaspike_configuration">DeltaSpike Configuration</h3>
+<div class="paragraph">
+<p>This is described in an own chapter solely targeting our <a href="configuration.html">configuration</a> mechanics, API and SPI.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_beanprovider">BeanProvider</h3>
+<div class="paragraph">
+<p>The <code>BeanProvider</code> is a class which provides (static) util methods which
+allow to lookup beans if it isn’t possible to inject them via <code>@Inject</code>
+or if the lookup depends on dynamic conditions. Instead of using the
+term 'bean', the term 'contextual instance' is used because that’s the
+term used by CDI itself.</p>
+</div>
+<div class="paragraph">
+<p>The following example shows a simple lookup. With the second parameter
+it’s possible to specify if the contextual instance is optional. If it
+isn’t expected that the contextual instance is optional, but no instance
+has been found, an <code>IllegalStateException</code> will be thrown.</p>
+</div>
+<div class="paragraph">
+<p>Resolving a simple contextual instance:</p>
+</div>
+<div class="listingblock">
+<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 isn’t required or it isn’t
+required that there is an instance with the given qualifier (see the
+qualifier example for further details).</p>
+</div>
+<div class="paragraph">
+<p>Resolving an optional contextual instance:</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Literal implementation for '@MyQualifier':</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Resolving a simple contextual instance with qualifier:</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Resolving a simple contextual instance by name:</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Resolving a simple contextual instance by name and expected type:</p>
+</div>
+<div class="listingblock">
+<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’s essential to resolve all contextual instances which
+implement e.g. 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="paragraph">
+<p>Resolving all contextual instances of a given type:</p>
+</div>
+<div class="listingblock">
+<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 - esp. 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="paragraph">
+<p>Resolving all contextual instances of a given type without dependent
+scoped instances:</p>
+</div>
+<div class="listingblock">
+<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’s possible to trigger the injection of fields of any
+given instance, if it wasn’t 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="paragraph">
+<p>Manually inject fields:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java">BeanProvider.injectFields(myObject);</code></pre>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_beanmanagerprovider">BeanManagerProvider</h3>
+<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’s easier to use the <code>BeanProvider</code>.</p>
+</div>
+<div class="paragraph">
+<p>Resolving the Bean-Manager:</p>
+</div>
+<div class="listingblock">
+<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 an own approach to find the correct <code>BeanManager</code>,
+because a portable API for it is only available since 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 class="sect2">
+<h3 id="_type_safe_projectstage">Type-safe ProjectStage</h3>
+<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>
+<div class="sect2">
+<h3 id="__exclude">@Exclude</h3>
+<div class="paragraph">
+<p>With <code>@Exclude</code> it’s possible to annotate beans which should be ignored
+by CDI even if they are in a CDI enabled archive.</p>
+</div>
+<div class="paragraph">
+<p>Excluding a bean in any case:</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Excluding a bean in case of project-stage development:</p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p>Excluding a bean if the project-stage is different from development:</p>
+</div>
+<div class="listingblock">
+<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 config sources</a>).</p>
+</div>
+<div class="paragraph">
+<p>Excluding a bean based on an expression which eval. to true:</p>
+</div>
+<div class="listingblock">
+<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’s possible
+to provide a custom <code>ExpressionInterpreter</code> for interpreting custom
+expressions.</p>
+</div>
+<div class="paragraph">
+<p>Excluding a bean based on a custom expression:</p>
+</div>
+<div class="listingblock">
+<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’s 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’s required to configure the
+implementation as alternative in the beans.xml file. This config entry
+won’t be changed e.g. for different environments, because it just gets
+active if it isn’t excluded during the bootstrapping process.</p>
+</div>
+<div class="paragraph">
+<p>Excluding an alternative implementation if the project-stage is
+different from development:</p>
+</div>
+<div class="listingblock">
+<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="sect3">
+<h4 id="_custom_expressioninterpreter">Custom ExpressionInterpreter</h4>
+<div class="paragraph">
+<p>Per 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’s 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">' isn't 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 class="sect2">
+<h3 id="_type_safe_view_config">Type-safe View-Config</h3>
+<div class="paragraph">
+<p>TODO (Overview)</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_literals">Literals</h3>
+<div class="paragraph">
+<p>Literals allow the instantiation of annotations by extending the
+abstract class 'javax.enterprise.util.AnnotationLiteral'</p>
+</div>
+<div class="paragraph">
+<p><strong>Example</strong></p>
+</div>
+<div class="listingblock">
+<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 - e.g.:</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 class="sect2">
+<h3 id="_messages_i18n">Messages & I18n</h3>
+<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="paragraph">
+<p><strong>Simple type-safe message</strong></p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p><strong>Internationalized type-safe message</strong></p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p><strong>Internationalized type-safe message</strong></p>
+</div>
+<div class="listingblock">
+<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="paragraph">
+<p><strong>Internationalized type-safe message with parameter/s</strong></p>
+</div>
+<div class="listingblock">
+<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>
+<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 config 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 e.g. if it’s
+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 config 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 config 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 e.g. 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 config 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 class="sect2">
+<h3 id="_injecting_resources">Injecting Resources</h3>
+<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">"</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 files, from classpath or on your local file
+system, using two default implementations: <code>ClasspathResourceProvider</code>
+and <code>FileResourceProvider</code>. They can be extended as well by implementing
+the <code>InjectableResourceProvider</code> interface to allow reading from
+alternate sources, if needed (e.g. database LOBs, NoSQL storage areas).</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_exception_control">Exception Control</h3>
+<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="sect3">
+<h4 id="_usage">Usage</h4>
+<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’s 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="sect3">
+<h4 id="_exception_handlers">Exception handlers</h4>
+<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="sect4">
+<h5 id="__exceptionhandler">@ExceptionHandler</h5>
+<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="sect4">
+<h5 id="__handles_and_beforehandles">@Handles and @BeforeHandles</h5>
+<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’s 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’s 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="sect4">
+<h5 id="_ordinal">Ordinal</h5>
+<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="sect3">
+<h4 id="_exception_chain_processing">Exception Chain Processing</h4>
+<div class="paragraph">
+<p>When an exception is thrown, chances are it’s 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 doesn’t 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="sect3">
+<h4 id="_apis_for_exception_information_and_flow_control">APIs for exception information and flow control</h4>
+<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="sect4">
+<h5 id="_exceptionevent">ExceptionEvent</h5>
+<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’s explicitly marked as unmuted via
+the <code>unmute()</code> method on <code>ExceptionEvent</code>.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_scopes">Scopes</h3>
+<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="sect3">
+<h4 id="__windowscoped">@WindowScoped</h4>
+
+</div>
+<div class="sect3">
+<h4 id="__viewaccessscoped">@ViewAccessScoped</h4>
+
+</div>
+<div class="sect3">
+<h4 id="__groupedconversationscoped">@GroupedConversationScoped</h4>
+
+</div>
+</div>
+<div class="sect2">
+<h3 id="_creating_a_custom_cdi_scope">Creating a custom CDI Scope</h3>
+<div class="paragraph">
+<p>If you want to create a custom CDI scope to match your needs, you will
+need to follow these steps:</p>
+</div>
+<div class="paragraph">
+<p>First, create an Annotation with annotated with @javax.inject.Scope;
+Example:</p>
+</div>
+<div class="listingblock">
+<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>
+<div class="paragraph">
+<p>Second, create an Extension to add the scope and a context for it.
+Example:</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">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>
+<div class="paragraph">
+<p>Implement a javax.enterprise.context.spi.Context interface to hold the
+javax.enterprise.inject.spi.Bean instances according to your needs</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">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>
+</div>
+<div class="sect2">
+<h3 id="_deactivatable">Deactivatable</h3>
+<div class="paragraph">
+<p>DeltaSpike allows you to deactivate its own Extensions. You just need to
+implement your <a href="spi.html#_classdeactivator">ClassDeactivator</a>.</p>
+</div>
+<div class="paragraph">
+<p>The ClassDeactivator should be resolved by any ConfigSource using the
+key <code>org.apache.deltaspike.core.spi.activation.ClassDeactivator</code>. For
+example, we can disable SecurityExtension having the following 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">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>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_core_utils">Core - Utils</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="_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> - 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> - Extract the qualifiers from a set of annotations.</p>
+</li>
+<li>
+<p><code>#extractAnnotation</code> - Extract the annotations.</p>
+</li>
+<li>
+<p><code>#createInjectionPoints</code> - Given a method, and the bean on which the method is declared, create a collection of injection points representing the parameters of the method.</p>
+</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> - 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> - helper which allows to use a trick to throw a catched checked exception without a wrapping exception.</p>
+</li>
+<li>
+<p><code>#changeAndThrowException</code> - helper which allows to use a trick to throw a cached checked exception without a wrapping exception.</p>
+</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>
+<p><code>#resolvePropertyFiles</code> - Allows to lookup for resource bundle files.</p>
+</li>
+<li>
+<p><code>#loadProperties</code> - Load a Properties file from the given URL.</p>
+</li>
+<li>
+<p><code>#getResourceBundle</code> - Return the ResourceBundle for the current default Locale.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_proxyutils">ProxyUtils</h3>
+<div class="paragraph">
+<p>Helper for CDI proxies</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>#getUnproxiedClass</code> - Return class of the real implementation.</p>
+</li>
+<li>
+<p><code>#isProxiedClass</code> - Analyses if the given class is a generated proxy class.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_stringutils">StringUtils</h3>
+<div class="paragraph">
+<p>A collection of utilities for working with Strings.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p><code>#isEmpty</code> - return true if the String is null or empty ( <code>string.trim().isEmpty()</code> )</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+ </div>
+
+ <hr>
+
+ <footer>
+ <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.</p>
+ <p>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </footer>
+
+ </div>
+ <!-- /.container -->
+
+</body>
+</html>
\ No newline at end of file