deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r864998 [3/15] - in /websites/staging/deltaspike/trunk/content: ./ deltaspike/ deltaspike/draft/ deltaspike/resources/ draft/ resources/ resources/css/ resources/files/ resources/images/ resources/js/
Date Sun, 09 Jun 2013 09:26:33 GMT
Added: websites/staging/deltaspike/trunk/content/core.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/core.html (added)
+++ websites/staging/deltaspike/trunk/content/core.html Sun Jun  9 09:26:31 2013
@@ -0,0 +1,849 @@
+<!DOCTYPE html>
+<html lang="en">
+<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>Apache DeltaSpike - 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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="./deltaspike/resources/css/bootstrap.css" rel="stylesheet">    
+    <!--<link href="./deltaspike/resources/css/prettify.css" rel="stylesheet" /> -->
+    <link href="./deltaspike/resources/css/codehilite.css" rel="stylesheet" />
+    <link href="./deltaspike/resources/css/bootstrap-responsive.css" rel="stylesheet">
+    <style type="text/css">
+        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" href="index.html"><img src="./deltaspike/resources/images/deltaspike-logo-medium.png"/></a>
+                <div class="nav-collapse">
+                    <ul class="nav">
+                        <li class="active"><a href="./deltaspike/index.html">Home</a></li>
+                        <li><a href="./deltaspike/documentation.html">Documentation</a></li>
+                        <li><a href="./deltaspike/source.html">Source</a></li>
+                        <!-- <li><a href="./deltaspike/download.html">Download</a></li> -->
+                        <li><a href="./deltaspike/community.html">Community</a></li>
+                        <!-- <li><a href="./deltaspike/support.html">Support</a></li>  -->
+                        <li><a href="./deltaspike/news.html">News</a></li>
+                        <li><a href="./deltaspike/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="incubator.apache.org/deltaspike" 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 class="toc">
+<ul>
+<li><a href="#core-api">Core - API</a><ul>
+<li><a href="#beanprovider">BeanProvider</a></li>
+<li><a href="#beanmanagerprovider">BeanManagerProvider</a></li>
+<li><a href="#type-safe-projectstage">Type-safe ProjectStage</a><ul>
+<li><a href="#custom-project-stages">Custom Project Stages</a></li>
+</ul>
+</li>
+<li><a href="#projectstageproducer-for-3rd-party-portable-extensions">ProjectStageProducer (for 3rd party portable extensions)</a><ul>
+<li><a href="#setting-the-active-projectstage">Setting the active ProjectStage</a></li>
+</ul>
+</li>
+<li><a href="#low-level-configurations">Low-level configurations</a><ul>
+<li><a href="#configresolver">ConfigResolver</a></li>
+<li><a href="#propertyfileconfig">PropertyFileConfig</a></li>
+<li><a href="#configsource">ConfigSource</a></li>
+<li><a href="#reordering-of-the-default-order-of-config-sources">Reordering of the default order of Config-Sources</a></li>
+<li><a href="#custom-config-sources">Custom Config-Sources</a></li>
+</ul>
+</li>
+<li><a href="#type-safe-config">Type-safe config</a><ul>
+<li><a href="#configproperty">@ConfigProperty</a></li>
+</ul>
+</li>
+<li><a href="#exclude">@Exclude</a><ul>
+<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 &amp; I18n</a></li>
+<li><a href="#dynamic-message-builder">Dynamic Message Builder</a><ul>
+<li><a href="#creating-message-instances">Creating message instances</a></li>
+<li><a href="#customizing-the-message-context">Customizing the message context</a><ul>
+<li><a href="#messageresolver">MessageResolver</a></li>
+<li><a href="#messageinterpolator">MessageInterpolator</a></li>
+<li><a href="#localeresolver">LocaleResolver</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#exception-control">Exception Control</a></li>
+<li><a href="#exception-handling-usage">Exception Handling - Usage</a><ul>
+<li><a href="#eventing-into-the-exception-handling-framework">Eventing into the exception handling framework</a></li>
+</ul>
+</li>
+<li><a href="#exception-handlers">Exception handlers</a><ul>
+<li><a href="#exception-handler-annotations">Exception handler annotations</a><ul>
+<li><a href="#exceptionhandler">@ExceptionHandler</a></li>
+<li><a href="#handles-and-beforehandles">@Handles and @BeforeHandles</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="#exception-chain-processing">Exception Chain Processing</a></li>
+<li><a href="#handler-ordinal">Handler ordinal</a></li>
+<li><a href="#apis-for-exception-information-and-flow-control">APIs for exception information and flow control</a><ul>
+<li><a href="#exceptionevent">ExceptionEvent</a></li>
+</ul>
+</li>
+<li><a href="#scopes">Scopes</a></li>
+</ul>
+</li>
+<li><a href="#core-utils">Core - Utils</a></li>
+</ul>
+</div>
+<hr />
+<h1 id="core-api">Core - API</h1>
+<h2 id="beanprovider">BeanProvider</h2>
+<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>
+<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>
+<p>Resolving a simple contextual instance:</p>
+<div class="codehilite"><pre><span class="n">MyBean</span> <span class="n">myBean</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReference</span><span class="o">(</span><span class="n">MyBean</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+</pre></div>
+
+
+<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>
+<p>Resolving an optional contextual instance:</p>
+<div class="codehilite"><pre><span class="n">MyServiceInterface</span> <span class="n">optionalService</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReference</span><span class="o">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="kc">true</span><span class="o">);</span>
+</pre></div>
+
+
+<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>
+<p>Literal implementation for '@MyQualifier':</p>
+<div class="codehilite"><pre><span class="kn">import</span> <span class="nn">javax.enterprise.util.AnnotationLiteral</span><span class="o">;</span>
+<span class="c1">//...</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyQualifierLiteral</span> <span class="kd">extends</span> <span class="n">AnnotationLiteral</span><span class="o">&lt;</span><span class="n">MyQualifier</span><span class="o">&gt;</span> <span class="kd">implements</span> <span class="n">MyQualifier</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The following example will return a contextual instance with the qualifier <code>@MyQualifier</code></p>
+<p>Resolving a simple contextual instance with qualifier:</p>
+<div class="codehilite"><pre><span class="n">MyBean</span> <span class="n">myBean</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReference</span><span class="o">(</span><span class="n">MyBean</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="kc">false</span><span class="o">,</span> <span class="k">new</span> <span class="n">MyQualifierLiteral</span><span class="o">());</span>
+</pre></div>
+
+
+<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>
+<p>Resolving a simple contextual instance by name:</p>
+<div class="codehilite"><pre><span class="n">Object</span> <span class="n">myBean</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReference</span><span class="o">(</span><span class="s">&quot;myBean&quot;</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+</pre></div>
+
+
+<p>Resolving a simple contextual instance by name and expected type:</p>
+<div class="codehilite"><pre><span class="n">MyBean</span> <span class="n">myBean</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReference</span><span class="o">(</span><span class="s">&quot;myBean&quot;</span><span class="o">,</span> <span class="kc">false</span><span class="o">,</span> <span class="n">MyBean</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+</pre></div>
+
+
+<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 -&gt; also dependent scoped instances).</p>
+<p>Resolving all contextual instances of a given type:</p>
+<div class="codehilite"><pre><span class="n">List</span><span class="o">&lt;</span><span class="n">MyServiceInterface</span><span class="o">&gt;</span> <span class="n">myServiceList</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReferences</span><span class="o">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+</pre></div>
+
+
+<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>
+<p>Resolving all contextual instances of a given type without dependent scoped instances:</p>
+<div class="codehilite"><pre><span class="n">List</span><span class="o">&lt;</span><span class="n">MyServiceInterface</span><span class="o">&gt;</span> <span class="n">myServiceList</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="na">getContextualReferences</span><span class="o">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="na">class</span><span class="o">,</span> <span class="kc">false</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+</pre></div>
+
+
+<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>
+<p>Manually inject fields:</p>
+<div class="codehilite"><pre><span class="n">BeanProvider</span><span class="o">.</span><span class="na">injectFields</span><span class="o">(</span><span class="n">myObject</span><span class="o">);</span>
+</pre></div>
+
+
+<h2 id="beanmanagerprovider">BeanManagerProvider</h2>
+<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>
+<p>Resolving the Bean-Manager:</p>
+<div class="codehilite"><pre><span class="c1">//in most cases the following works without problems:</span>
+<span class="nd">@Inject</span>
+<span class="kd">private</span> <span class="n">BeanManager</span> <span class="n">beanManager</span><span class="o">;</span>
+
+<span class="c1">//use</span>
+<span class="n">BeanManager</span> <span class="n">beanManager</span> <span class="o">=</span> <span class="n">BeanManagerProvider</span><span class="o">.</span><span class="na">getInstance</span><span class="o">().</span><span class="na">getBeanManager</span><span class="o">();</span>
+
+<span class="c1">//if CDI based injection is not available.</span>
+</pre></div>
+
+
+<h2 id="type-safe-projectstage">Type-safe ProjectStage</h2>
+<p>Project stages allow to use implementations depending on the current environment. E.g. you can implement a bean which creates sample-data for system tests which gets activated only in case of project-stage <code>SystemTest</code>.</p>
+<p><em>Besides custom project-stages</em> it's possible to use the following pre-defined project-stages:</p>
+<ul>
+<li>UnitTest</li>
+<li>Development</li>
+<li>SystemTest</li>
+<li>IntegrationTest</li>
+<li>Staging</li>
+<li>Production</li>
+</ul>
+<p>The core provides a pluggable and type-safe approach for using project stages in a project (it's also used within the framework). Furthermore, <code>@Exclude</code> allows to use e.g. implementations annotated with <code>javax.enterprise.inject.Alternative</code> for specific project-stages. Besides the out-of-the-box project-stages it's possible to implement <em>custom but type-safe</em> project-stages which will be exposed by DeltaSpike.</p>
+<p>Resolving and using the Project-Stage:</p>
+<div class="codehilite"><pre><span class="nd">@Inject</span>
+<span class="kd">private</span> <span class="n">ProjectStage</span> <span class="n">projectStage</span><span class="o">;</span>
+
+<span class="c1">//...</span>
+
+<span class="kt">boolean</span> <span class="n">isDevProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="na">Development</span><span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="k">this</span><span class="o">.</span><span class="na">projectStage</span><span class="o">);</span>
+</pre></div>
+
+
+<h3 id="custom-project-stages">Custom Project Stages</h3>
+<p>It's possible to provide custom project stage implementations.
+Therefore, you have to provide an implementation of the <code>ProjectStageHolder</code> interface.
+In this class you nest the custom project-stage implementations which have to be <code>public static final class</code> and it's required to extend <code>ProjectStage</code>.
+It's required to provide a <code>public static final</code> instance even though, you won't use it directly.</p>
+<p>ProjectStageHolder for custom project stage implementations:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">CustomProjectStageHolder</span> <span class="kd">implements</span> <span class="n">ProjectStageHolder</span>
+<span class="o">{</span>
+    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kd">class</span> <span class="nc">CustomProjectStage</span> <span class="kd">extends</span> <span class="n">ProjectStage</span>
+    <span class="o">{</span>
+        <span class="kd">private</span> <span class="kd">static</span> <span class="kd">final</span> <span class="kt">long</span> <span class="n">serialVersionUID</span> <span class="o">=</span> <span class="mi">1029094387976167179L</span><span class="o">;</span>
+    <span class="o">}</span>
+
+    <span class="kd">public</span> <span class="kd">static</span> <span class="kd">final</span> <span class="n">CustomProjectStage</span> <span class="n">CustomProjectStage</span> <span class="o">=</span> <span class="k">new</span> <span class="n">CustomProjectStage</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Configure your custom <code>ProjectStageHolder</code> in <code>META-INF/services/org.apache.deltaspike.core.api.projectstage.ProjectStageHolder</code>. The file has to provide the <em>fully qualified</em> class name of the custom implementation of the <code>ProjectStageHolder</code> interface.</p>
+<p>Usage of a custom project stage:</p>
+<div class="codehilite"><pre><span class="n">ProjectStage</span> <span class="n">customProjectStage</span><span class="o">;</span>
+<span class="n">customProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="na">valueOf</span><span class="o">(</span><span class="s">&quot;CustomProjectStage&quot;</span><span class="o">);</span>
+<span class="c1">//or</span>
+<span class="n">customProjectStage</span> <span class="o">=</span> <span class="n">CustomProjectStageHolder</span><span class="o">.</span><span class="na">CustomProjectStage</span><span class="o">;</span>
+<span class="c1">//or</span>
+<span class="nd">@Exclude</span><span class="o">(</span><span class="n">ifProjectStage</span> <span class="o">=</span> <span class="n">CustomProjectStageHolder</span><span class="o">.</span><span class="na">CustomProjectStage</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+</pre></div>
+
+
+<h2 id="projectstageproducer-for-3rd-party-portable-extensions">ProjectStageProducer (for 3rd party portable extensions)</h2>
+<p><code>ProjectStageProducer</code> provides the producer method which allows to inject the current project-stage. However, in some cases it's needed to use project-stages also during the bootstrapping process of the CDI container and you can't use injection. In such cases you can use <code>ProjectStageProducer.getInstance().getProjectStage()</code> to resolve the current project-stage. This helper also contains helpers for unit-tests - e.g. <code>#setProjectStage</code>. However, those methods shouldn't be needed for users (we just need them for testing different project-stage scenarios).</p>
+<h3 id="setting-the-active-projectstage">Setting the active ProjectStage</h3>
+<p>For setting the ProjectStage which shall get used in your application you can specify
+it in a few ways. The underlying mechanism used to determine the string is the ConfigResolver.
+E.g.:</p>
+<div class="codehilite"><pre><span class="o">-</span><span class="n">Dorg</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">deltaspike</span><span class="o">.</span><span class="na">ProjectStage</span><span class="o">=</span><span class="n">Development</span>
+</pre></div>
+
+
+<h2 id="low-level-configurations">Low-level configurations</h2>
+<h3 id="configresolver">ConfigResolver</h3>
+<p>In some cases low-level configs are needed e.g. during the bootstrapping process of the CDI container. (Currently it's e.g. used for configuring the value of the current project-stage, configured values which can be used in the expressions for <code>@Exclude</code>,...) Usually it isn't used by users directly, but DeltaSpike needs such a low-level approach for several features. Therefore it's possible to use a so called <code>ConfigResolver</code> which resolves and caches <code>ConfigSource</code>s per application.
+The method <code>ConfigResolver#getPropertyValue</code> allows to provide a string based key and returns the configured value as <code>String</code> or <code>null</code> if no value has been found (<code>#getAllPropertyValues</code> has a similar contract but it returns a list which might be empty if there are no configured values for the given key). Optionally it's possible to provide a default value which gets retured instead of <code>null</code>.</p>
+<p>Simple lookup in the low-level config:</p>
+<div class="codehilite"><pre><span class="n">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyValue</span><span class="o">(</span><span class="s">&quot;myKey&quot;</span><span class="o">);</span>
+</pre></div>
+
+
+<h3 id="propertyfileconfig">PropertyFileConfig</h3>
+<p>TODO</p>
+<h3 id="configsource">ConfigSource</h3>
+<p>A <code>ConfigResolver</code> uses all configured implementations of <code>ConfigSource</code> to lookup the property in question.</p>
+<p>Per default there are implementations for the following config sources (listed in the lookup order):</p>
+<ul>
+<li>System properties</li>
+<li>Environment properties</li>
+<li>JNDI values</li>
+<li>Properties file values (apache-deltaspike.properties)</li>
+</ul>
+<p><strong>It's possible to change this order and to add custom config sources.</strong></p>
+<p><strong>Note:</strong> Important Hints esp. for custom implementations:
+  - The config-source with the highest ordinal gets used first.
+  - If a custom implementation should be invoked <em>before</em> the default implementations, use an ordinal-value &gt; 400
+  - If a custom implementation should be invoked <em>after</em> the default implementations, use an ordinal-value &lt; 100</p>
+<h3 id="reordering-of-the-default-order-of-config-sources">Reordering of the default order of Config-Sources</h3>
+<p>To change the lookup order, you have to configure the ordinal in the corresponding config source (e.g. to change the config ordinal of the config source for system properties, you have to set the system property with the ordinal key 'deltaspike_ordinal' and the new value).</p>
+<p>Example with <code>/META-INF/apache-deltaspike.properties</code>: If the properties file/s should be used <strong>before</strong> the other implementations, you have to configure an ordinal &gt; 400. That means, you have to add e.g. <code>deltaspike_ordinal=401</code>.</p>
+<p><strong>Hint:</strong></p>
+<p>In case of <strong>property files</strong> which are supported by default (<code>/META-INF/apache-deltaspike.properties</code>) every file is handled as independent config-source, but all of them have ordinal 400 by default (and can be reordered in a fine-grained manner).</p>
+<h3 id="custom-config-sources">Custom Config-Sources</h3>
+<p>To add a custom config-source, you have to implement the interface <code>ConfigSourceProvider</code> (and <code>ConfigSource</code>) and activate the implementation of <code>ConfigSourceProvider</code> with the std. SPI mechanism provided by Java via the <code>ServiceLoader</code> (that means you have to create <code>/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSourceProvider</code> which contains the fully qualified class name of the custom implementation/s).</p>
+<p>If you have a simple standalone <code>ConfigSource</code> you can also register it directly by creating a file <code>/META-INF/services/org.apache.deltaspike.core.spi.config.ConfigSource</code> which contains the fully qualified class name of your <code>ConfigSource</code>.
+Please note that a single <code>ConfigSource</code> should be either registered directly or via a <code>ConfigSourceProvider</code>, but never both ways. </p>
+<p><strong>Important Hint:</strong></p>
+<p>Have a look at the abstract base-implementation of <code>ConfigSource</code> DeltaSpike is using internally, if a custom implementation should load the ordinal value from the config-source like the default implementations provided by DeltaSpike do.</p>
+<h2 id="type-safe-config">Type-safe config</h2>
+<h3 id="configproperty">@ConfigProperty</h3>
+<p>TODO</p>
+<h2 id="exclude">@Exclude</h2>
+<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>
+<p>Excluding a bean in any case:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">NoBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Excluding a bean in case of project-stage development:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span><span class="o">(</span><span class="n">ifProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="na">Development</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Excluding a bean if the project-stage is different from development:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span><span class="o">(</span><span class="n">exceptIfProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="na">Development</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyDevBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The following usage allows to exclude a bean based on a configured value (see the supported config sources [TODO]).</p>
+<p>Excluding a bean based on an expression which eval. to true:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span><span class="o">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">&quot;db==prodDB&quot;</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DevDbBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<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>
+<p>Excluding a bean based on a custom expression:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span><span class="o">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">&quot;db eq prodDB&quot;</span><span class="o">,</span> <span class="n">interpretedBy</span> <span class="o">=</span> <span class="n">SimpleExpressionInterpreter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DevDbBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">SimpleExpressionInterpreter</span> <span class="kd">implements</span> <span class="n">ExpressionInterpreter</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="n">Boolean</span><span class="o">&gt;</span>
+<span class="o">{</span>
+    <span class="nd">@Override</span>
+    <span class="kd">public</span> <span class="n">Boolean</span> <span class="nf">evaluate</span><span class="o">(</span><span class="n">String</span> <span class="n">expression</span><span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">if</span><span class="o">(</span><span class="n">expression</span><span class="o">.</span><span class="na">contains</span><span class="o">(</span><span class="s">&quot; eq &quot;</span><span class="o">))</span>
+        <span class="o">{</span>
+            <span class="c1">//...</span>
+        <span class="o">}</span>
+        <span class="c1">//...</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>In several cases it's also useful to combine this feature with the <code>@Alternative</code> annotation provided by CDI.</p>
+<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>
+<p>Excluding an alternative implementation if the project-stage is different from development:</p>
+<div class="codehilite"><pre><span class="nd">@Exclude</span><span class="o">(</span><span class="n">exceptIfProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="na">Development</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="nd">@Alternative</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyDevBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h3 id="custom-expressioninterpreter">Custom ExpressionInterpreter</h3>
+<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 class="codehilite"><pre><span class="nd">@Alternative</span>
+<span class="nd">@Exclude</span><span class="o">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">&quot;environment!=HSQL&quot;</span><span class="o">,</span> <span class="n">interpretedBy</span> <span class="o">=</span> <span class="n">ConfigAwareExpressionInterpreter</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">DevDbBean</span> <span class="kd">implements</span> <span class="n">DbBean</span>
+<span class="o">{</span>
+<span class="o">}</span>
+
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">ConfigAwareExpressionInterpreter</span> <span class="kd">implements</span> <span class="n">ExpressionInterpreter</span><span class="o">&lt;</span><span class="n">String</span><span class="o">,</span> <span class="n">Boolean</span><span class="o">&gt;</span>
+<span class="o">{</span>
+    <span class="kd">public</span> <span class="n">Boolean</span> <span class="nf">evaluate</span><span class="o">(</span><span class="n">String</span> <span class="n">expression</span><span class="o">)</span>
+    <span class="o">{</span>
+        <span class="k">if</span> <span class="o">(</span><span class="n">expression</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span>
+        <span class="o">{</span>
+            <span class="k">return</span> <span class="kc">false</span><span class="o">;</span>
+        <span class="o">}</span>
+
+        <span class="n">String</span><span class="o">[]</span> <span class="n">values</span> <span class="o">=</span> <span class="n">expression</span><span class="o">.</span><span class="na">split</span><span class="o">(</span><span class="s">&quot;!=&quot;</span><span class="o">);</span>
+
+        <span class="k">if</span> <span class="o">(</span><span class="n">values</span><span class="o">.</span><span class="na">length</span> <span class="o">!=</span> <span class="mi">2</span><span class="o">)</span>
+        <span class="o">{</span>
+            <span class="k">throw</span> <span class="k">new</span> <span class="nf">IllegalArgumentException</span><span class="o">(</span><span class="s">&quot;&#39;&quot;</span> <span class="o">+</span> <span class="n">expression</span> <span class="o">+</span> <span class="s">&quot;&#39; isn&#39;t a supported syntax&quot;</span><span class="o">);</span>
+        <span class="o">}</span>
+
+        <span class="n">String</span> <span class="n">configuredValue</span> <span class="o">=</span> <span class="n">ConfigResolver</span><span class="o">.</span><span class="na">getPropertyValue</span><span class="o">(</span><span class="n">values</span><span class="o">[</span><span class="mi">0</span><span class="o">],</span> <span class="kc">null</span><span class="o">);</span>
+
+        <span class="c1">//exclude if null or the configured value is different</span>
+        <span class="k">return</span> <span class="n">configuredValue</span> <span class="o">==</span> <span class="kc">null</span> <span class="o">||</span> <span class="o">!</span><span class="n">values</span><span class="o">[</span><span class="mi">1</span><span class="o">].</span><span class="na">trim</span><span class="o">().</span><span class="na">equalsIgnoreCase</span><span class="o">(</span><span class="n">configuredValue</span><span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="type-safe-view-config">Type-safe View-Config</h2>
+<p>TODO (Overview)</p>
+<h2 id="literals">Literals</h2>
+<p>TODO</p>
+<h2 id="messages-i18n">Messages &amp; I18n</h2>
+<p>The following implementation is the minimal effort to use type-safe messages (which are hardcoded in this case).</p>
+<p><strong>Simple type-safe message</strong></p>
+<div class="codehilite"><pre><span class="nd">@MessageBundle</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">SimpleMessage</span>
+<span class="o">{</span>
+    <span class="nd">@MessageTemplate</span><span class="o">(</span><span class="s">&quot;Welcome to DeltaSpike&quot;</span><span class="o">)</span>
+    <span class="n">String</span> <span class="nf">welcomeToDeltaSpike</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<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>
+<p><strong>Internationalized type-safe message</strong></p>
+<div class="codehilite"><pre><span class="nd">@MessageBundle</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">SimpleMessage</span>
+<span class="o">{</span>
+    <span class="nd">@MessageTemplate</span><span class="o">(</span><span class="s">&quot;{welcome_to_deltaspike}&quot;</span><span class="o">)</span>
+    <span class="n">String</span> <span class="nf">welcomeToDeltaSpike</span><span class="o">();</span>
+<span class="o">}</span>
+
+<span class="n">org</span><span class="o">.</span><span class="na">apache</span><span class="o">.</span><span class="na">deltaspike</span><span class="o">.</span><span class="na">example</span><span class="o">.</span><span class="na">message</span><span class="o">.</span><span class="na">SimpleMessage</span>
+
+<span class="o">-&gt;</span>
+
+<span class="n">org</span><span class="o">/</span><span class="n">apache</span><span class="o">/</span><span class="n">deltaspike</span><span class="o">/</span><span class="n">example</span><span class="o">/</span><span class="n">message</span><span class="o">/</span><span class="n">SimpleMessage</span><span class="o">.</span><span class="na">properties</span>
+<span class="n">org</span><span class="o">/</span><span class="n">apache</span><span class="o">/</span><span class="n">deltaspike</span><span class="o">/</span><span class="n">example</span><span class="o">/</span><span class="n">message</span><span class="o">/</span><span class="n">SimpleMessage_en</span><span class="o">.</span><span class="na">properties</span>
+<span class="n">org</span><span class="o">/</span><span class="n">apache</span><span class="o">/</span><span class="n">deltaspike</span><span class="o">/</span><span class="n">example</span><span class="o">/</span><span class="n">message</span><span class="o">/</span><span class="n">SimpleMessage_de</span><span class="o">.</span><span class="na">properties</span>
+<span class="o">...</span>
+
+<span class="c1">//content (as usual in message bundle files:</span>
+<span class="n">welcome_to_deltaspike</span><span class="o">=</span><span class="n">Welcome</span> <span class="n">to</span> <span class="n">DeltaSpike</span>
+</pre></div>
+
+
+<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>
+<p><strong>Internationalized type-safe message</strong></p>
+<div class="codehilite"><pre><span class="nd">@MessageBundle</span>
+<span class="nd">@MessageContextConfig</span><span class="o">(</span><span class="n">messageResolver</span> <span class="o">=</span> <span class="n">CustomMessageResolver</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">SimpleMessage</span>
+<span class="o">{</span>
+    <span class="nd">@MessageTemplate</span><span class="o">(</span><span class="s">&quot;{welcome_to_deltaspike}&quot;</span><span class="o">)</span>
+    <span class="n">String</span> <span class="nf">welcomeToDeltaSpike</span><span class="o">();</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p><code>@MessageContextConfig</code> allows to provide a custom <code>MessageResolver</code>, <code>MessageInterpolator</code> and <code>LocaleResolver</code>.</p>
+<p>The following implementation shows the usage of an internationalized simple type-safe message.</p>
+<p><strong>Internationalized type-safe message with parameter/s</strong></p>
+<div class="codehilite"><pre><span class="nd">@MessageBundle</span>
+<span class="nd">@MessageContextConfig</span><span class="o">(</span><span class="n">messageInterpolator</span> <span class="o">=</span> <span class="n">CustomMessageInterpolator</span><span class="o">.</span><span class="na">class</span><span class="o">)</span>
+<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">SimpleMessage</span>
+<span class="o">{</span>
+    <span class="c1">//in the message bundle: welcome_to=Welcome to %s</span>
+
+    <span class="nd">@MessageTemplate</span><span class="o">(</span><span class="s">&quot;{welcome_to}&quot;</span><span class="o">)</span>
+    <span class="n">String</span> <span class="nf">welcomeTo</span><span class="o">(</span><span class="n">String</span> <span class="n">name</span><span class="o">);</span>
+<span class="o">}</span>
+
+<span class="c1">//...</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyBean</span>
+<span class="o">{</span>
+    <span class="nd">@Inject</span>
+    <span class="kd">private</span> <span class="n">SimpleMessage</span> <span class="n">messages</span><span class="o">;</span>
+
+    <span class="kd">public</span> <span class="n">String</span> <span class="n">welcomeToDeltaSpike</span>
+    <span class="o">{</span>
+        <span class="k">return</span> <span class="k">this</span><span class="o">.</span><span class="na">messages</span><span class="o">.</span><span class="na">welcomeTo</span><span class="o">(</span><span class="s">&quot;DeltaSpike&quot;</span><span class="o">);</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<h2 id="dynamic-message-builder">Dynamic Message Builder</h2>
+<h3 id="creating-message-instances">Creating message instances</h3>
+<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>
+<p>[TODO]</p>
+<h3 id="customizing-the-message-context">Customizing the message context</h3>
+<h4 id="messageresolver">MessageResolver</h4>
+<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>
+<p><strong>Configuration of a message-resolver</strong></p>
+<p>[TODO]</p>
+<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>
+<h4 id="messageinterpolator">MessageInterpolator</h4>
+<p>A <code>MessageInterpolator</code> replaces the placeholders in a message-text with the arguments of the message.</p>
+<p><strong>Configuration of a message-interpolator</strong></p>
+<p>[TODO]</p>
+<h4 id="localeresolver">LocaleResolver</h4>
+<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>
+<p><strong>Configuration of a locale-resolver</strong></p>
+<p>[TODO]</p>
+<h2 id="exception-control">Exception Control</h2>
+<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>
+<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>
+<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>
+<h2 id="exception-handling-usage">Exception Handling - Usage</h2>
+<h3 id="eventing-into-the-exception-handling-framework">Eventing into the exception handling framework</h3>
+<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>
+<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 class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">InventoryActions</span> <span class="o">{</span>
+    <span class="nd">@PersistenceContext</span> <span class="kd">private</span> <span class="n">EntityManager</span> <span class="n">em</span><span class="o">;</span>
+    <span class="nd">@Inject</span> <span class="kd">private</span> <span class="n">Event</span><span class="o">&lt;</span><span class="n">ExceptionToCatchEvent</span><span class="o">&gt;</span> <span class="n">catchEvent</span><span class="o">;</span>
+
+    <span class="kd">public</span> <span class="n">Integer</span> <span class="nf">queryForItem</span><span class="o">(</span><span class="n">Item</span> <span class="n">item</span><span class="o">)</span> <span class="o">{</span>
+        <span class="k">try</span> <span class="o">{</span>
+          <span class="n">Query</span> <span class="n">q</span> <span class="o">=</span> <span class="n">em</span><span class="o">.</span><span class="na">createQuery</span><span class="o">(</span><span class="s">&quot;SELECT i from Item i where i.id = :id&quot;</span><span class="o">);</span>
+          <span class="n">q</span><span class="o">.</span><span class="na">setParameter</span><span class="o">(</span><span class="s">&quot;id&quot;</span><span class="o">,</span> <span class="n">item</span><span class="o">.</span><span class="na">getId</span><span class="o">());</span>
+          <span class="k">return</span> <span class="n">q</span><span class="o">.</span><span class="na">getSingleResult</span><span class="o">();</span>
+        <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">PersistenceException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+          <span class="n">catchEvent</span><span class="o">.</span><span class="na">fire</span><span class="o">(</span><span class="k">new</span> <span class="n">ExceptionToCatchEvent</span><span class="o">(</span><span class="n">e</span><span class="o">));</span>
+        <span class="o">}</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<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>
+<p>The event is fired with a new instance of <code>ExceptionToCatchEvent</code> constructed
+with the exception to be handled.</p>
+<h2 id="exception-handlers">Exception handlers</h2>
+<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>
+<p><strong>If there are no exception handlers for an exception, the exception is
+rethrown.</strong></p>
+<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>
+<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>
+<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>
+<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>
+<h3 id="exception-handler-annotations">Exception handler annotations</h3>
+<p>Exception handlers are contained within exception handler beans, which are CDI
+beans annotated with <code>@ExceptionHandler</code>. Exception handlers are methods
+which have a parameter which is an instance of <code>ExceptionEvent&lt;T extends
+Throwable&gt;</code> annotated with the <code>@Handles</code> annotation.</p>
+<h4 id="exceptionhandler"><code>@ExceptionHandler</code></h4>
+<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>
+<p>Let's designate a CDI bean as an exception handler by annotating it with
+<code>@ExceptionHandler</code>.</p>
+<div class="codehilite"><pre><span class="nd">@ExceptionHandler</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyHandlers</span> <span class="o">{}</span>
+</pre></div>
+
+
+<p>That's all there is to it. Now we can begin defining exception handling methods on this bean.</p>
+<h4 id="handles-and-beforehandles"><code>@Handles</code> and <code>@BeforeHandles</code></h4>
+<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>
+<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 class="codehilite"><pre><span class="nd">@ExceptionHandler</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyHandlers</span>
+<span class="o">{</span>
+    <span class="kt">void</span> <span class="nf">printExceptions</span><span class="o">(</span><span class="nd">@Handles</span> <span class="n">ExceptionEvent</span><span class="o">&lt;</span><span class="n">Throwable</span><span class="o">&gt;</span> <span class="n">evt</span><span class="o">)</span>
+    <span class="o">{</span>
+        <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Something bad happened:&quot;</span> <span class="o">+</span>
+        <span class="n">evt</span><span class="o">.</span><span class="na">getException</span><span class="o">().</span><span class="na">getMessage</span><span class="o">());</span>
+        <span class="n">evt</span><span class="o">.</span><span class="na">handleAndContinue</span><span class="o">();</span>
+    <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The <code>@Handles</code> annotation on the first parameter designates this method as an
+exception handler (though it is not required to be the first parameter).  This
+parameter must be of type <code>ExceptionEvent&lt;T extends Throwable&gt;</code>, otherwise
+it'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>
+<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>
+<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>
+<p>The <code>@Handles</code> annotation must be placed on a parameter of the method, which
+must be of type <code>ExceptionEvent&lt;T extends Throwable&gt;</code>. Handler methods are
+similar to CDI observers and, as such, follow the same principles and
+guidelines as observers (such as invocation, injection of parameters,
+qualifiers, etc) with the following exceptions:</p>
+<ul>
+<li>a parameter of a handler method must be a <code>ExceptionEvent</code></li>
+<li>handlers are ordered before they are invoked (invocation order of
+    observers is non-deterministic)</li>
+<li>any handler can prevent subsequent handlers from being invoked</li>
+</ul>
+<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>
+<p>The <code>@BeforeHandles</code> designates a method as a callback to happen before
+handlers are called.</p>
+<p>Let's take a look at more sophisticated example that uses all the features of
+handlers to log all exceptions.</p>
+<div class="codehilite"><pre><span class="nd">@ExceptionHandler</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="nc">MyHandlers</span>
+<span class="o">{</span>
+   <span class="kt">void</span> <span class="nf">logExceptions</span><span class="o">(</span><span class="nd">@BeforeHandles</span> <span class="nd">@WebRequest</span> <span class="n">ExceptionEvent</span><span class="o">&lt;</span><span class="n">Throwable</span><span class="o">&gt;</span> <span class="n">evt</span><span class="o">,</span> <span class="n">Logger</span> <span class="n">log</span><span class="o">)</span>
+   <span class="o">{</span>
+      <span class="n">log</span><span class="o">.</span><span class="na">warn</span><span class="o">(</span><span class="s">&quot;Something bad happened: &quot;</span> <span class="o">+</span> <span class="n">evt</span><span class="o">.</span><span class="na">getException</span><span class="o">().</span><span class="na">getMessage</span><span class="o">());</span>
+   <span class="o">}</span>
+
+   <span class="kt">void</span> <span class="nf">logExceptions</span><span class="o">(</span><span class="nd">@Handles</span> <span class="nd">@WebRequest</span> <span class="n">ExceptionEvent</span><span class="o">&lt;</span><span class="n">Throwable</span><span class="o">&gt;</span> <span class="n">evt</span><span class="o">,</span> <span class="n">Logger</span> <span class="n">log</span><span class="o">)</span>
+   <span class="o">{</span>
+      <span class="c1">// possibly send a HTTP Error code</span>
+   <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>This handler has a default ordinal of 0 (the default value of the ordinal
+attribute on <code>@Handles</code>).</p>
+<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>
+<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>
+<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>
+<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>
+<h2 id="exception-chain-processing">Exception Chain Processing</h2>
+<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>
+<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>
+<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>
+<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>
+<p>Consider a exception chain containing the following nested causes (from outer
+cause to root cause):</p>
+<ul>
+<li>EJBException</li>
+<li>PersistenceException</li>
+<li>SQLGrammarException</li>
+</ul>
+<p>DeltaSpike will unwrap this exception and notify handlers in the following
+order:</p>
+<ul>
+<li>SQLGrammarException</li>
+<li>PersistenceException</li>
+<li>EJBException</li>
+</ul>
+<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>
+<h2 id="handler-ordinal">Handler ordinal</h2>
+<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>
+<p>Let's define two handlers with different ordinals:</p>
+<div class="codehilite"><pre><span class="kt">void</span> <span class="nf">handleIOExceptionFirst</span><span class="o">(</span><span class="nd">@Handles</span><span class="o">(</span><span class="n">ordinal</span> <span class="o">=</span> <span class="mi">100</span><span class="o">)</span> <span class="n">ExceptionEvent</span><span class="o">&lt;</span><span class="n">IOException</span><span class="o">&gt;</span> <span class="n">evt</span><span class="o">)</span>
+<span class="o">{</span>
+   <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">&quot;Invoked first&quot;</span><span class="o">);</span>
+<span class="o">}</span>
+
+<span class="kt">void</span> <span class="nf">handleIOExceptionSecond</span><span class="o">(</span><span class="nd">@Handles</span> <span class="n">ExceptionEvent</span><span class="o">&lt;</span><span class="n">IOException</span><span class="o">&gt;</span> <span class="n">evt</span><span class="o">)</span>
+<span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="err">“</span><span class="n">Invoked</span> <span class="n">second</span><span class="err">”</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<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>
+<p>To summarize, here's how DeltaSpike determines the order of handlers to invoke
+(until a handler marks exception as handled):</p>
+<ol>
+<li>Unwrap exception stack</li>
+<li>Begin processing root cause</li>
+<li>Invoke any callback methods annotated with @BeforeHandles for the
+    closest type to the exception</li>
+<li>Find handler for the closest type to the exception</li>
+<li>If multiple handlers for same type, invoke handlers with higher
+    ordinal first</li>
+<li>Continue above steps for each exception in stack</li>
+</ol>
+<h2 id="apis-for-exception-information-and-flow-control">APIs for exception information and flow control</h2>
+<p>There are two APIs provided by DeltaSpike that should be familiar to
+application developers:</p>
+<ul>
+<li><code>ExceptionEvent</code></li>
+<li><code>ExceptionStackEvent</code></li>
+</ul>
+<h3 id="exceptionevent">ExceptionEvent</h3>
+<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>
+<ul>
+<li><code>abort()</code> - terminate all handling immediately after this handler,
+    does not mark the exception as handled, does not re-throw the
+    exception.</li>
+<li><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.</li>
+<li><code>handled()</code> - marks the exception as handled and terminates
+    further handling.</li>
+<li><code>handleAndContinue()</code> - default. Marks the exception as handled
+    and proceeds with the rest of the handlers.</li>
+<li><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.</li>
+<li><code>rethrow(Throwable)</code> - Throw a new exception after this handler is
+    invoked</li>
+</ul>
+<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>
+<h2 id="scopes">Scopes</h2>
+<h1 id="core-utils">Core - Utils</h1>
+<p>TODO</p>
+          </div>
+      </div>
+
+      <hr>
+
+      <footer>
+        <p>Copyright © 20011-2012 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 -->
+
+    <!-- Javascript
+    ================================================== -->
+    <!-- Placed at the end of the document so the pages load faster -->
+    <!--<script src="./deltaspike/resources/js/prettyfy.js"></script> -->
+    <script src="./deltaspike/resources/js/prettyprint.js"></script>
+    <script src="./deltaspike/resources/js/jquery.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-transition.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-alert.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-modal.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-dropdown.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-scrollspy.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-tab.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-tooltip.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-popover.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-button.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-collapse.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-carousel.js"></script>
+    <script src="./deltaspike/resources/js/bootstrap-typeahead.js"></script>
+
+</body>
+</html>
\ No newline at end of file



Mime
View raw message