You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@deltaspike.apache.org by bu...@apache.org on 2013/01/07 19:46:54 UTC
svn commit: r845361 [1/3] - in /websites/staging/deltaspike/trunk/content:
./ deltaspike/container-control.html deltaspike/core.html
deltaspike/documentation.html deltaspike/jpa.html
deltaspike/resources/css/bootstrap.css deltaspike/security.html
Author: buildbot
Date: Mon Jan 7 18:46:54 2013
New Revision: 845361
Log:
Staging update by buildbot for deltaspike
Added:
websites/staging/deltaspike/trunk/content/deltaspike/container-control.html
Modified:
websites/staging/deltaspike/trunk/content/ (props changed)
websites/staging/deltaspike/trunk/content/deltaspike/core.html
websites/staging/deltaspike/trunk/content/deltaspike/documentation.html
websites/staging/deltaspike/trunk/content/deltaspike/jpa.html
websites/staging/deltaspike/trunk/content/deltaspike/resources/css/bootstrap.css
websites/staging/deltaspike/trunk/content/deltaspike/security.html
Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jan 7 18:46:54 2013
@@ -1 +1 @@
-1429162
+1429950
Added: websites/staging/deltaspike/trunk/content/deltaspike/container-control.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/container-control.html (added)
+++ websites/staging/deltaspike/trunk/content/deltaspike/container-control.html Mon Jan 7 18:46:54 2013
@@ -0,0 +1,181 @@
+<!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 - Container & Control</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="./../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>Container & Control</h1>
+ </div>
+ <div class="toc">
+<ul>
+<li><a href="#introduction">Introduction</a><ul>
+<li><a href="#cdicontainer">CdiContainer</a></li>
+<li><a href="#contextcontrol-usage">ContextControl usage</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<hr />
+<h1 id="introduction">Introduction</h1>
+<p>There are basically two parts:</p>
+<ul>
+<li>The <strong>CdiContainer</strong> interface allows to boot and shutdown the CDI container in SE applications.</li>
+<li>The <strong>ContextControl</strong> interface allows to control the life-cycle of the built-in contexts of the CDI container.</li>
+</ul>
+<h2 id="cdicontainer">CdiContainer</h2>
+<p>See the Java SE part <a href="#start-a-cdi-container-using-java-se">above</a>.</p>
+<h2 id="contextcontrol-usage">ContextControl usage</h2>
+<p>The <code>ContextControl</code> interface allows you to start and stop built-in standard Contexts like <code>@RequestScoped</code>, <code>@ConversationScoped</code>, <code>@SessionScoped</code>, etc. It is provided as <code>@Dependent</code> bean and can get injected in the classic CDI way. This is not only usable in Java SE projects but also very helpful in Servlets and Java EE containers.</p>
+<p><strong>Restarting the RequestContext in unit tests</strong></p>
+<p>In unit testing it can be necessary to test with attached and also with detached JPA entities. A very common approach for JPA is the <a href="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Web_Server/1.0/html/Hibernate_Entity_Manager_Reference_Guide/transactions.html">entitymanager-per-request approach</a> and thus have a producer method which creates a @RequestScoped EntityManager. Since a single unit test is usually treated as one ârequestâ a problem arises detaching entities.</p>
+<p>Using ContextControl to detach entities:</p>
+<div class="codehilite"><pre><span class="nd">@Test</span>
+<span class="kd">public</span> <span class="kt">void</span> <span class="nf">testMyBusinessLogic</span><span class="o">()</span>
+<span class="o">{</span>
+ <span class="n">doSomeJpaStuff</span><span class="o">()</span>
+ <span class="n">MyEntity</span> <span class="n">me</span> <span class="o">=</span> <span class="n">em</span><span class="o">.</span><span class="na">find</span><span class="o">(...);</span>
+
+ <span class="n">ContextControl</span> <span class="n">ctxCtrl</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">ContextControl</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+ <span class="c1">//stopping the request context will dispose the @RequestScoped EntityManager</span>
+ <span class="n">ctxCtrl</span><span class="o">.</span><span class="na">stopContext</span><span class="o">(</span><span class="n">RequestScoped</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+ <span class="c1">// and now immediately restart the context again</span>
+ <span class="n">ctxCtrl</span><span class="o">.</span><span class="na">startContext</span><span class="o">(</span><span class="n">RequestScoped</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+ <span class="c1">// the entity 'em' is now in a detached state!</span>
+ <span class="n">doSomeStuffWithTheDetachedEntity</span><span class="o">(</span><span class="n">em</span><span class="o">);</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Attaching a Request Context to a new thread in EE</p>
+<p>Accessing the <code>@RequestScoped</code> bean in a new thread will result in a <code>ContextNotActiveException</code>. The request-context usually gets started for a particular thread via a simple <code>ServletRequestListener</code>. So "no servlet-request" means that there is no Servlet-Context for the current (/new) Thread.
+You might face such issues, if you would like to reuse business services in e.g. a Quartz Job.</p>
+<p>Controlling the request-context for a Quartz-Job:</p>
+<div class="codehilite"><pre><span class="kd">public</span> <span class="kd">class</span> <span class="nc">CdiJob</span> <span class="kd">implements</span> <span class="n">org</span><span class="o">.</span><span class="na">quartz</span><span class="o">.</span><span class="na">Job</span>
+<span class="o">{</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span class="nf">execute</span><span class="o">(</span><span class="n">JobExecutionContext</span> <span class="n">context</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">JobExecutionException</span>
+ <span class="o">{</span>
+ <span class="n">ContextControl</span> <span class="n">ctxCtrl</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">ContextControl</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+ <span class="c1">//this will implicitly bind a new RequestContext to the current thread</span>
+ <span class="n">ctxCtrl</span><span class="o">.</span><span class="na">startContext</span><span class="o">(</span><span class="n">RequestScoped</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+
+ <span class="k">try</span>
+ <span class="o">{</span>
+ <span class="n">doYourWork</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="k">finally</span>
+ <span class="o">{</span>
+ <span class="c1">//stop the RequestContext to ensure that all request-scoped beans get cleaned up.</span>
+ <span class="n">ctxCtrl</span><span class="o">.</span><span class="na">stopContext</span><span class="o">(</span><span class="n">RequestScoped</span><span class="o">.</span><span class="na">class</span><span class="o">);</span>
+ <span class="o">}</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+ </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
Modified: websites/staging/deltaspike/trunk/content/deltaspike/core.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/core.html (original)
+++ websites/staging/deltaspike/trunk/content/deltaspike/core.html Mon Jan 7 18:46:54 2013
@@ -78,64 +78,129 @@
<div class="page-title">
<h1>Core</h1>
</div>
- <h1 id="core-api">Core - API</h1>
+ <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></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 & 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="n">getContextualReference</span><span class="p">(</span><span class="n">MyBean</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">false</span><span class="p">);</span>
+<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="n">getContextualReference</span><span class="p">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">true</span><span class="p">);</span>
+<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="nb">import</span> <span class="n">javax</span><span class="o">.</span><span class="n">enterprise</span><span class="o">.</span><span class="n">util</span><span class="o">.</span><span class="n">AnnotationLiteral</span><span class="p">;</span>
-<span class="sr">//</span><span class="o">...</span>
+<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="n">public</span> <span class="n">class</span> <span class="n">MyQualifierLiteral</span> <span class="n">extends</span> <span class="n">AnnotationLiteral</span><span class="sr"><MyQualifier></span> <span class="n">implements</span> <span class="n">MyQualifier</span>
-<span class="p">{</span>
-<span class="p">}</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"><</span><span class="n">MyQualifier</span><span class="o">></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="n">getContextualReference</span><span class="p">(</span><span class="n">MyBean</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">false</span><span class="p">,</span> <span class="k">new</span> <span class="n">MyQualifierLiteral</span><span class="p">());</span>
+<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="n">getContextualReference</span><span class="p">(</span><span class="s">"myBean"</span><span class="p">,</span> <span class="n">false</span><span class="p">);</span>
+<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">"myBean"</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="n">getContextualReference</span><span class="p">(</span><span class="s">"myBean"</span><span class="p">,</span> <span class="n">false</span><span class="p">,</span> <span class="n">MyBean</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+<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">"myBean"</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 -> 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="sr"><MyServiceInterface></span> <span class="n">myServiceList</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="n">getContextualReferences</span><span class="p">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">false</span><span class="p">);</span>
+<div class="codehilite"><pre><span class="n">List</span><span class="o"><</span><span class="n">MyServiceInterface</span><span class="o">></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="sr"><MyServiceInterface></span> <span class="n">myServiceList</span> <span class="o">=</span> <span class="n">BeanProvider</span><span class="o">.</span><span class="n">getContextualReferences</span><span class="p">(</span><span class="n">MyServiceInterface</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">false</span><span class="p">,</span> <span class="n">false</span><span class="p">);</span>
+<div class="codehilite"><pre><span class="n">List</span><span class="o"><</span><span class="n">MyServiceInterface</span><span class="o">></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="n">injectFields</span><span class="p">(</span><span class="n">myObject</span><span class="p">);</span>
+<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>
@@ -144,16 +209,14 @@
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="sr">//i</span><span class="n">n</span> <span class="n">most</span> <span class="n">cases</span> <span class="n">the</span> <span class="n">following</span> <span class="n">works</span> <span class="n">without</span> <span class="n">problems:</span>
-
-<span class="nv">@Inject</span>
-<span class="n">private</span> <span class="n">BeanManager</span> <span class="n">beanManager</span><span class="p">;</span>
+<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="sr">//</span><span class="k">use</span><span class="p">:</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="n">BeanManager</span> <span class="n">beanManager</span> <span class="o">=</span> <span class="n">BeanManagerProvider</span><span class="o">.</span><span class="n">getInstance</span><span class="p">()</span><span class="o">.</span><span class="n">getBeanManager</span><span class="p">();</span>
-
-<span class="sr">//i</span><span class="n">f</span> <span class="n">CDI</span> <span class="n">based</span> <span class="n">injection</span> <span class="n">is</span> <span class="ow">not</span> <span class="n">available</span><span class="o">.</span>
+<span class="c1">//if CDI based injection is not available.</span>
</pre></div>
@@ -170,12 +233,12 @@ If a simple but manual bean-lookup is ne
</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="nv">@Inject</span>
-<span class="n">private</span> <span class="n">ProjectStage</span> <span class="n">projectStage</span><span class="p">;</span>
+<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="sr">//</span><span class="o">...</span>
+<span class="c1">//...</span>
-<span class="n">boolean</span> <span class="n">isDevProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="n">Development</span><span class="o">.</span><span class="n">equals</span><span class="p">(</span><span class="n">this</span><span class="o">.</span><span class="n">projectStage</span><span class="p">);</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>
@@ -185,26 +248,26 @@ Therefore, you have to provide an implem
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="n">public</span> <span class="n">class</span> <span class="n">CustomProjectStageHolder</span> <span class="n">implements</span> <span class="n">ProjectStageHolder</span>
-<span class="p">{</span>
- <span class="n">public</span> <span class="n">static</span> <span class="n">final</span> <span class="n">class</span> <span class="n">CustomProjectStage</span> <span class="n">extends</span> <span class="n">ProjectStage</span>
- <span class="p">{</span>
- <span class="n">private</span> <span class="n">static</span> <span class="n">final</span> <span class="n">long</span> <span class="n">serialVersionUID</span> <span class="o">=</span> <span class="mi">1029094387976167179</span><span class="n">L</span><span class="p">;</span>
- <span class="p">}</span>
+<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="n">public</span> <span class="n">static</span> <span class="n">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="p">();</span>
-<span class="p">}</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="p">;</span>
-<span class="n">customProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="n">valueOf</span><span class="p">(</span><span class="s">"CustomProjectStage"</span><span class="p">);</span>
-<span class="sr">//o</span><span class="n">r</span>
-<span class="n">customProjectStage</span> <span class="o">=</span> <span class="n">CustomProjectStageHolder</span><span class="o">.</span><span class="n">CustomProjectStage</span><span class="p">;</span>
-<span class="sr">//o</span><span class="n">r</span>
-<span class="nv">@Exclude</span><span class="p">(</span><span class="n">ifProjectStage</span> <span class="o">=</span> <span class="n">CustomProjectStageHolder</span><span class="o">.</span><span class="n">CustomProjectStage</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+<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">"CustomProjectStage"</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>
@@ -215,7 +278,7 @@ It's required to provide a <code>public
<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="n">getPropertyValue</span><span class="p">(</span><span class="s">"myKey"</span><span class="p">);</span>
+<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">"myKey"</span><span class="o">);</span>
</pre></div>
@@ -252,57 +315,57 @@ Please note that a single <code>ConfigSo
<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="nv">@Exclude</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">NoBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
+<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="nv">@Exclude</span><span class="p">(</span><span class="n">ifProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="n">Development</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
+<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="nv">@Exclude</span><span class="p">(</span><span class="n">exceptIfProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="n">Development</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyDevBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
+<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="nv">@Exclude</span><span class="p">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">"db==prodDB"</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">DevDbBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
+<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">"db==prodDB"</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="nv">@Exclude</span><span class="p">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">"db eq prodDB"</span><span class="p">,</span> <span class="n">interpretedBy</span> <span class="o">=</span> <span class="n">SimpleExpressionInterpreter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">DevDbBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
-
-<span class="n">public</span> <span class="n">class</span> <span class="n">SimpleExpressionInterpreter</span> <span class="n">implements</span> <span class="n">ExpressionInterpreter</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Boolean</span><span class="o">></span>
-<span class="p">{</span>
- <span class="nv">@Override</span>
- <span class="n">public</span> <span class="n">Boolean</span> <span class="n">evaluate</span><span class="p">(</span><span class="n">String</span> <span class="n">expression</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="k">if</span><span class="p">(</span><span class="n">expression</span><span class="o">.</span><span class="n">contains</span><span class="p">(</span><span class="s">" eq "</span><span class="p">))</span>
- <span class="p">{</span>
- <span class="sr">//</span><span class="o">...</span>
- <span class="p">}</span>
- <span class="sr">//</span><span class="o">...</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<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">"db eq prodDB"</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"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Boolean</span><span class="o">></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">" eq "</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>
@@ -310,45 +373,45 @@ Please note that a single <code>ConfigSo
<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="nv">@Exclude</span><span class="p">(</span><span class="n">exceptIfProjectStage</span> <span class="o">=</span> <span class="n">ProjectStage</span><span class="o">.</span><span class="n">Development</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
-<span class="nv">@Alternative</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyDevBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
+<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="nv">@Alternative</span>
-<span class="nv">@Exclude</span><span class="p">(</span><span class="n">onExpression</span> <span class="o">=</span> <span class="s">"environment!=HSQL"</span><span class="p">,</span> <span class="n">interpretedBy</span> <span class="o">=</span> <span class="n">ConfigAwareExpressionInterpreter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">DevDbBean</span> <span class="n">implements</span> <span class="n">DbBean</span>
-<span class="p">{</span>
-<span class="p">}</span>
-
-<span class="n">public</span> <span class="n">class</span> <span class="n">ConfigAwareExpressionInterpreter</span> <span class="n">implements</span> <span class="n">ExpressionInterpreter</span><span class="o"><</span><span class="n">String</span><span class="p">,</span> <span class="n">Boolean</span><span class="o">></span>
-<span class="p">{</span>
- <span class="n">public</span> <span class="n">Boolean</span> <span class="n">evaluate</span><span class="p">(</span><span class="n">String</span> <span class="n">expression</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="k">if</span> <span class="p">(</span><span class="n">expression</span> <span class="o">==</span> <span class="n">null</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="k">return</span> <span class="n">false</span><span class="p">;</span>
- <span class="p">}</span>
-
- <span class="n">String</span><span class="o">[]</span> <span class="nb">values</span> <span class="o">=</span> <span class="n">expression</span><span class="o">.</span><span class="nb">split</span><span class="p">(</span><span class="s">"!="</span><span class="p">);</span>
-
- <span class="k">if</span> <span class="p">(</span><span class="nb">values</span><span class="o">.</span><span class="nb">length</span> <span class="o">!=</span> <span class="mi">2</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="n">throw</span> <span class="k">new</span> <span class="n">IllegalArgumentException</span><span class="p">(</span><span class="s">"'"</span> <span class="o">+</span> <span class="n">expression</span> <span class="o">+</span> <span class="s">"' isn't a supported syntax"</span><span class="p">);</span>
- <span class="p">}</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="n">getPropertyValue</span><span class="p">(</span><span class="nb">values</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">null</span><span class="p">);</span>
-
- <span class="sr">//</span><span class="n">exclude</span> <span class="k">if</span> <span class="n">null</span> <span class="ow">or</span> <span class="n">the</span> <span class="n">configured</span> <span class="n">value</span> <span class="n">is</span> <span class="n">different</span>
- <span class="k">return</span> <span class="n">configuredValue</span> <span class="o">==</span> <span class="n">null</span> <span class="o">||</span> <span class="o">!</span><span class="nb">values</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span><span class="o">.</span><span class="n">trim</span><span class="p">()</span><span class="o">.</span><span class="n">equalsIgnoreCase</span><span class="p">(</span><span class="n">configuredValue</span><span class="p">);</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<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">"environment!=HSQL"</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"><</span><span class="n">String</span><span class="o">,</span> <span class="n">Boolean</span><span class="o">></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">"!="</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">"'"</span> <span class="o">+</span> <span class="n">expression</span> <span class="o">+</span> <span class="s">"' isn't a supported syntax"</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>
@@ -356,8 +419,100 @@ For such cases a custom ExpressionInterp
<p>TODO (Overview)</p>
<h2 id="literals">Literals</h2>
<p>TODO</p>
-<h2 id="i18n">I18n</h2>
-<p>TODO</p>
+<h2 id="messages-i18n">Messages & 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">"Welcome to DeltaSpike"</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">"{welcome_to_deltaspike}"</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">-></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">"{welcome_to_deltaspike}"</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">"{welcome_to}"</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">"DeltaSpike"</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,
@@ -387,20 +542,20 @@ exception handling proccess.</p>
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="n">public</span> <span class="n">class</span> <span class="n">InventoryActions</span> <span class="p">{</span>
- <span class="nv">@PersistenceContext</span> <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">em</span><span class="p">;</span>
- <span class="nv">@Inject</span> <span class="n">private</span> <span class="n">Event</span><span class="sr"><ExceptionToCatchEvent></span> <span class="n">catchEvent</span><span class="p">;</span>
-
- <span class="n">public</span> <span class="n">Integer</span> <span class="n">queryForItem</span><span class="p">(</span><span class="n">Item</span> <span class="n">item</span><span class="p">)</span> <span class="p">{</span>
- <span class="n">try</span> <span class="p">{</span>
- <span class="n">Query</span> <span class="sx">q = </span><span class="n">em</span><span class="o">.</span><span class="n">createQuery</span><span class="p">(</span><span class="s">"SELECT i from Item i where i.id = :id"</span><span class="p">);</span>
- <span class="sx">q.setParameter("id", item.</span><span class="n">getId</span><span class="p">());</span>
- <span class="k">return</span> <span class="sx">q.getSingleResult();</span>
-<span class="sx"> } catch (PersistenceException e) {</span>
-<span class="sx"> catchEvent.</span><span class="n">fire</span><span class="p">(</span><span class="k">new</span> <span class="n">ExceptionToCatchEvent</span><span class="p">(</span><span class="n">e</span><span class="p">));</span>
- <span class="p">}</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<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"><</span><span class="n">ExceptionToCatchEvent</span><span class="o">></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">"SELECT i from Item i where i.id = :id"</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">"id"</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>
@@ -444,8 +599,8 @@ instructs the DeltaSpike exception handl
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="nv">@ExceptionHandler</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyHandlers</span> <span class="p">{}</span>
+<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>
@@ -459,16 +614,16 @@ deployment time.</p>
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="nv">@ExceptionHandler</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyHandlers</span>
-<span class="p">{</span>
- <span class="n">void</span> <span class="n">printExceptions</span><span class="p">(</span><span class="nv">@Handles</span> <span class="n">ExceptionEvent</span><span class="sr"><Throwable></span> <span class="n">evt</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s">"Something bad happened:"</span> <span class="o">+</span>
- <span class="n">evt</span><span class="o">.</span><span class="n">getException</span><span class="p">()</span><span class="o">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="n">evt</span><span class="o">.</span><span class="n">handleAndContinue</span><span class="p">();</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<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"><</span><span class="n">Throwable</span><span class="o">></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">"Something bad happened:"</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>
@@ -505,19 +660,19 @@ exception type. The default ordinal (if
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="nv">@ExceptionHandler</span>
-<span class="n">public</span> <span class="n">class</span> <span class="n">MyHandlers</span>
-<span class="p">{</span>
- <span class="n">void</span> <span class="n">logExceptions</span><span class="p">(</span><span class="nv">@BeforeHandles</span> <span class="nv">@WebRequest</span> <span class="n">ExceptionEvent</span><span class="sr"><Throwable></span> <span class="n">evt</span><span class="p">,</span> <span class="n">Logger</span> <span class="nb">log</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="nb">log</span><span class="o">.</span><span class="nb">warn</span><span class="p">(</span><span class="s">"Something bad happened: "</span> <span class="o">+</span> <span class="n">evt</span><span class="o">.</span><span class="n">getException</span><span class="p">()</span><span class="o">.</span><span class="n">getMessage</span><span class="p">());</span>
- <span class="p">}</span>
-
- <span class="n">void</span> <span class="n">logExceptions</span><span class="p">(</span><span class="nv">@Handles</span> <span class="nv">@WebRequest</span> <span class="n">ExceptionEvent</span><span class="sr"><Throwable></span> <span class="n">evt</span><span class="p">,</span> <span class="n">Logger</span> <span class="nb">log</span><span class="p">)</span>
- <span class="p">{</span>
- <span class="sr">//</span> <span class="n">possibly</span> <span class="nb">send</span> <span class="n">a</span> <span class="n">HTTP</span> <span class="n">Error</span> <span class="n">code</span>
- <span class="p">}</span>
-<span class="p">}</span>
+<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"><</span><span class="n">Throwable</span><span class="o">></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">"Something bad happened: "</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"><</span><span class="n">Throwable</span><span class="o">></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>
@@ -585,15 +740,15 @@ orders the handlers by ordinal. Handler
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="n">void</span> <span class="n">handleIOExceptionFirst</span><span class="p">(</span><span class="nv">@Handles</span><span class="p">(</span><span class="n">ordinal</span> <span class="o">=</span> <span class="mi">100</span><span class="p">)</span> <span class="n">ExceptionEvent</span><span class="sr"><IOException></span> <span class="n">evt</span><span class="p">)</span>
-<span class="p">{</span>
- <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="s">"Invoked first"</span><span class="p">);</span>
-<span class="p">}</span>
-
-<span class="n">void</span> <span class="n">handleIOExceptionSecond</span><span class="p">(</span><span class="nv">@Handles</span> <span class="n">ExceptionEvent</span><span class="sr"><IOException></span> <span class="n">evt</span><span class="p">)</span>
-<span class="p">{</span>
- <span class="n">System</span><span class="o">.</span><span class="n">out</span><span class="o">.</span><span class="n">println</span><span class="p">(</span><span class="err">â</span><span class="n">Invoked</span> <span class="n">second</span><span class="err">â</span><span class="p">);</span>
-<span class="p">}</span>
+<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"><</span><span class="n">IOException</span><span class="o">></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">"Invoked first"</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"><</span><span class="n">IOException</span><span class="o">></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>