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 2012/07/02 12:40:39 UTC
svn commit: r824059 [3/3] - in /websites/staging/deltaspike/trunk/content:
./ deltaspike/
Added: websites/staging/deltaspike/trunk/content/deltaspike/jpa.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/jpa.html (added)
+++ websites/staging/deltaspike/trunk/content/deltaspike/jpa.html Mon Jul 2 10:40:37 2012
@@ -0,0 +1,319 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+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.
+-->
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="resources/site.css"/>
+ <title>Apache DeltaSpike - </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. -->
+</head>
+<body>
+<div id="page" class="container_16">
+ <div id="header" class="grid_8 omega">
+ <img src="http://www.apache.org/images/feather-small.gif" alt="The Apache Software Foundation">
+ <h1>Apache DeltaSpike</h1>
+ </div>
+ <div id="nav" class="grid_8 omega">
+ <ul>
+ <!-- <li><a href="/" title="Welcome!">Home</a></li> -->
+ <li><a href="http://www.apache.org/foundation/" title="The Foundation">Foundation</a></li>
+ <li><a href="http://projects.apache.org" title="The Projects">Projects</a></li>
+ <li><a href="http://people.apache.org" title="The People">People</a></li>
+ <li><a href="http://www.apache.org/foundation/getinvolved.html" title="Get Involved">Get Involved</a></li>
+ <li><a href="http://www.apache.org/dyn/closer.cgi" title="Download">Download</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Support Apache">Support Apache</a></li>
+ </ul>
+ <p id="breadcrumb"><a href="/">Home</a> » <a href="/deltaspike/">Deltaspike</a></p>
+
+ </div>
+
+ <div class="grid_16">
+ <h1></h1>
+ </div>
+
+ <h1 id="jpa-module">JPA Module</h1>
+<h2 id="transactional">@Transactional</h2>
+<p>This annotation is an alternative to transactional EJBs which allows to execute a method within a transaction.
+Before it's possible to start using the annotation, it's required to implement a CDI producer for an {{EntityManager}} and it's needed to inject the {{EntityManager}} in the bean which uses {{@Transactional}}. As shown later on it's also possible to use multiple qualifiers for using different {{EntityManager}}s.</p>
+<p>The following example shows a simple producer for an {{EntityManager}} and the corresponding dispose-method.
+Producing it as request scoped bean means that the dispose method will be called on finishing the request.
+As an alternative it's possible to use a special scope called {{@TransactionScoped}} provided by the same DeltaSpike module.</p>
+<div class="codehilite"><pre><span class="n">Producer</span> <span class="k">for</span> <span class="n">the</span> <span class="n">default</span> <span class="n">EntityManager</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">EntityManagerProducer</span>
+<span class="p">{</span>
+ <span class="sr">//o</span><span class="n">r</span> <span class="n">manual</span> <span class="n">bootstrapping</span>
+ <span class="nv">@PersistenceContext</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="nv">@Produces</span>
+ <span class="nv">@RequestScoped</span>
+ <span class="n">protected</span> <span class="n">EntityManager</span> <span class="n">createEntityManager</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">this</span><span class="o">.</span><span class="n">entityManager</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">protected</span> <span class="n">void</span> <span class="n">closeEntityManager</span><span class="p">(</span><span class="nv">@Disposes</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">entityManager</span><span class="o">.</span><span class="n">isOpen</span><span class="p">())</span>
+ <span class="p">{</span>
+ <span class="n">entityManager</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The following examples show how to use the {{EntityManager}} produced by the example above.</p>
+<div class="codehilite"><pre><span class="n">Beans</span> <span class="n">with</span> <span class="n">transactional</span> <span class="n">method</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">TransactionalBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="n">Simple</span> <span class="n">transactional</span> <span class="n">bean</span> <span class="p">(</span><span class="n">all</span> <span class="n">methods</span> <span class="n">transactional</span><span class="p">)</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="nv">@Transactional</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">TransactionalBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="sr">//</span><span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>As illustrated in the following example it's also possible to use {{@Transactional}} for stereotypes.</p>
+<div class="codehilite"><pre><span class="n">Stereotype</span> <span class="k">for</span> <span class="n">transactional</span> <span class="n">beans</span> <span class="p">(</span><span class="o">+</span> <span class="n">usage</span><span class="p">)</span>
+<span class="nv">@Stereotype</span>
+<span class="nv">@Transactional</span>
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="nv">@interface</span> <span class="n">Repository</span>
+<span class="p">{</span>
+<span class="p">}</span>
+
+<span class="sr">//</span><span class="o">...</span>
+<span class="nv">@Repository</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">TransactionalBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="sr">//</span><span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Besides such simple usages, it's also supported to use qualifiers to access multiple persistence-units in parallel.
+The default qualifier for {{@Transactional}} is {{@Any}}. Therefore a transaction for every injected entity manager will be started.
+The example afterwards shows how to change this default behaviour.</p>
+<div class="codehilite"><pre><span class="n">Producer</span> <span class="k">for</span> <span class="n">multiple</span> <span class="n">entity</span> <span class="n">managers</span> <span class="p">(</span><span class="o">+</span> <span class="n">usage</span><span class="p">)</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">EntityManagerProducer</span>
+<span class="p">{</span>
+ <span class="nv">@PersistenceContext</span><span class="p">(</span><span class="n">unitName</span> <span class="o">=</span> <span class="s">"firstDB"</span><span class="p">)</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">firstEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@PersistenceContext</span><span class="p">(</span><span class="n">unitName</span> <span class="o">=</span> <span class="s">"secondDB"</span><span class="p">)</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">secondEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Produces</span>
+ <span class="nv">@First</span>
+ <span class="nv">@RequestScoped</span>
+ <span class="n">protected</span> <span class="n">EntityManager</span> <span class="n">createFirstEntityManager</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">this</span><span class="o">.</span><span class="n">firstEntityManager</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">protected</span> <span class="n">void</span> <span class="n">closeFirstEntityManager</span><span class="p">(</span><span class="nv">@Disposes</span> <span class="nv">@First</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">firstEntityManager</span><span class="o">.</span><span class="n">isOpen</span><span class="p">())</span>
+ <span class="p">{</span>
+ <span class="n">firstEntityManager</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+
+ <span class="nv">@Produces</span>
+ <span class="nv">@Second</span>
+ <span class="nv">@RequestScoped</span>
+ <span class="n">protected</span> <span class="n">EntityManager</span> <span class="n">createSecondEntityManager</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">this</span><span class="o">.</span><span class="n">secondEntityManager</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">protected</span> <span class="n">void</span> <span class="n">closeSecondEntityManager</span><span class="p">(</span><span class="nv">@Disposes</span> <span class="nv">@Second</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">secondEntityManager</span><span class="o">.</span><span class="n">isOpen</span><span class="p">())</span>
+ <span class="p">{</span>
+ <span class="n">secondEntityManager</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">FirstLevelTransactionBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="nv">@First</span> <span class="n">EntityManager</span> <span class="n">firstEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">NestedTransactionBean</span> <span class="n">nestedTransactionBean</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="n">this</span><span class="o">.</span><span class="n">nestedTransactionBean</span><span class="o">.</span><span class="n">executeInTransaction</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">NestedTransactionBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="nv">@Second</span> <span class="n">EntityManager</span> <span class="n">secondEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The following example shows how to use only the specified {{EntityManager}}/s</p>
+<div class="codehilite"><pre><span class="n">Activating</span> <span class="n">entity</span> <span class="n">managers</span> <span class="n">manually</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MultiTransactionBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">defaultEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="nv">@First</span> <span class="n">EntityManager</span> <span class="n">firstEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="nv">@Second</span> <span class="n">EntityManager</span> <span class="n">secondEntityManager</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span><span class="p">(</span><span class="n">qualifier</span> <span class="o">=</span> <span class="n">Default</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInDefaultTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="p">}</span>
+
+ <span class="nv">@Transactional</span><span class="p">(</span><span class="n">qualifier</span> <span class="o">=</span> <span class="n">First</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInFirstTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="p">}</span>
+
+ <span class="nv">@Transactional</span><span class="p">(</span><span class="n">qualifier</span> <span class="o">=</span> <span class="n">Second</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInSecondTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="p">}</span>
+
+ <span class="nv">@Transactional</span><span class="p">(</span><span class="n">qualifier</span> <span class="o">=</span> <span class="p">{</span><span class="n">First</span><span class="o">.</span><span class="n">class</span><span class="p">,</span> <span class="n">Second</span><span class="o">.</span><span class="n">class</span><span class="p">})</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInFirstAndSecondTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>All examples also work with nested calls. In the following example the transaction handling is done on the entry point (after FirstLevelTransactionBean#executeInTransaction).</p>
+<div class="codehilite"><pre><span class="n">Joining</span> <span class="n">existing</span> <span class="n">transaction</span> <span class="n">in</span> <span class="n">nested</span> <span class="n">call</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">FirstLevelTransactionBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">NestedTransactionBean</span> <span class="n">nestedTransactionBean</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="n">this</span><span class="o">.</span><span class="n">nestedTransactionBean</span><span class="o">.</span><span class="n">executeInTransaction</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">NestedTransactionBean</span>
+<span class="p">{</span>
+ <span class="nv">@Inject</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="nv">@Transactional</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">executeInTransaction</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>The final transaction handling for all {{EntityManager}} s is also done after the outermost transactional method if {{NestedTransactionBean}} uses a different {{EntityManager}}.
+So it's possible to catch an exception in {{FirstLevelTransactionBean}} e.g. to try an optional path instead of an immediate rollback.</p>
+<h2 id="transactionscoped">@TransactionScoped</h2>
+<p>{{@Transactional}} also starts a context which is available as long as the transaction started by {{@Transactional}}. Besides other beans you can use this scope for the {{EntityManager}} itself. That means the {{EntityManager}} will be closed after leaving the method annotated with {{@Transactional}}.</p>
+<div class="codehilite"><pre><span class="n">Producer</span> <span class="k">for</span> <span class="n">the</span> <span class="n">default</span> <span class="n">EntityManager</span> <span class="n">which</span> <span class="n">should</span> <span class="n">be</span> <span class="n">used</span> <span class="n">only</span> <span class="k">for</span> <span class="n">one</span> <span class="n">transaction</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">EntityManagerProducer</span>
+<span class="p">{</span>
+ <span class="sr">//o</span><span class="n">r</span> <span class="n">manual</span> <span class="n">bootstrapping</span>
+ <span class="nv">@PersistenceContext</span>
+ <span class="n">private</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">;</span>
+
+ <span class="nv">@Produces</span>
+ <span class="nv">@TransactionScoped</span>
+ <span class="n">protected</span> <span class="n">EntityManager</span> <span class="n">createEntityManager</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">this</span><span class="o">.</span><span class="n">entityManager</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">protected</span> <span class="n">void</span> <span class="n">closeEntityManager</span><span class="p">(</span><span class="nv">@Disposes</span> <span class="n">EntityManager</span> <span class="n">entityManager</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">entityManager</span><span class="o">.</span><span class="n">isOpen</span><span class="p">())</span>
+ <span class="p">{</span>
+ <span class="n">entityManager</span><span class="o">.</span><span class="nb">close</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+ <div id="copyright" class="container_16">
+ <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </div>
+</div>
+</body>
+</html>
Added: websites/staging/deltaspike/trunk/content/deltaspike/security.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/security.html (added)
+++ websites/staging/deltaspike/trunk/content/deltaspike/security.html Mon Jul 2 10:40:37 2012
@@ -0,0 +1,251 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+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.
+-->
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="resources/site.css"/>
+ <title>Apache DeltaSpike - </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. -->
+</head>
+<body>
+<div id="page" class="container_16">
+ <div id="header" class="grid_8 omega">
+ <img src="http://www.apache.org/images/feather-small.gif" alt="The Apache Software Foundation">
+ <h1>Apache DeltaSpike</h1>
+ </div>
+ <div id="nav" class="grid_8 omega">
+ <ul>
+ <!-- <li><a href="/" title="Welcome!">Home</a></li> -->
+ <li><a href="http://www.apache.org/foundation/" title="The Foundation">Foundation</a></li>
+ <li><a href="http://projects.apache.org" title="The Projects">Projects</a></li>
+ <li><a href="http://people.apache.org" title="The People">People</a></li>
+ <li><a href="http://www.apache.org/foundation/getinvolved.html" title="Get Involved">Get Involved</a></li>
+ <li><a href="http://www.apache.org/dyn/closer.cgi" title="Download">Download</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Support Apache">Support Apache</a></li>
+ </ul>
+ <p id="breadcrumb"><a href="/">Home</a> » <a href="/deltaspike/">Deltaspike</a></p>
+
+ </div>
+
+ <div class="grid_16">
+ <h1></h1>
+ </div>
+
+ <h1 id="security-module">Security Module</h1>
+<h2 id="securitybinding-for-class-and-method-invocations">SecurityBinding for class and method invocations</h2>
+<p>This feature of the security module functions by intercepting method calls, and performing a security check before invocation is allowed to proceed.</p>
+<p>In order to use the DeltaSpike security module, you must first have installed the proper dependencies into your POM file. Once this is complete, you may proceed to create a security parameter binding annotation. This is what we will use to add security behavior to our business classes and methods.</p>
+<div class="codehilite"><pre><span class="n">Create</span> <span class="n">the</span> <span class="n">SecurityBinding</span>
+<span class="nv">@Retention</span><span class="p">(</span><span class="n">value</span> <span class="o">=</span> <span class="n">RUNTIME</span><span class="p">)</span>
+<span class="nv">@Target</span><span class="p">({</span><span class="n">TYPE</span><span class="p">,</span> <span class="n">METHOD</span><span class="p">})</span>
+<span class="nv">@Documented</span>
+<span class="nv">@SecurityBindingType</span>
+<span class="n">public</span> <span class="nv">@interface</span> <span class="n">CustomSecurityBinding</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Next, we must define an Authorizer class to implement behavior for our custom SecurityBindingType. This class is simply a CDI bean which declares a @Secures method, qualified with the security binding annotation we created in the first step.</p>
+<p>This method has access to the InvocationContext of the method call, so if we need to access parameter arguments, we can do so using the given context. Note that we may also inject other beans into the parameter list of our @Secures method.</p>
+<div class="codehilite"><pre><span class="n">Create</span> <span class="n">the</span> <span class="n">Authorizer</span>
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">CustomAuthorizer</span>
+<span class="p">{</span>
+ <span class="nv">@Secures</span>
+ <span class="nv">@CustomSecurityBinding</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">doSecuredCheck</span><span class="p">(</span><span class="n">InvocationContext</span> <span class="n">invocationContext</span><span class="p">,</span> <span class="n">BeanManager</span> <span class="n">manager</span><span class="p">,</span> <span class="nv">@LoggedIn</span> <span class="n">User</span> <span class="n">user</span><span class="p">)</span> <span class="n">throws</span> <span class="n">Exception</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">user</span><span class="o">.</span><span class="n">isLoggedIn</span><span class="p">();</span> <span class="sr">//</span> <span class="n">perform</span> <span class="n">security</span> <span class="n">check</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>We can then use our new annotation to secure business or bean methods. This binding annotation may be placed on the entire class (securing all methods,) or on individual methods that you wish to secure.</p>
+<div class="codehilite"><pre><span class="n">Secure</span> <span class="n">a</span> <span class="n">bean</span> <span class="n">method</span>
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">SecuredBean1</span>
+<span class="p">{</span>
+ <span class="nv">@CustomSecurityBinding</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">doSomething</span><span class="p">(</span><span class="n">Thing</span> <span class="n">thing</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">thing</span><span class="o">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Next, we may access parameter values from the method invocation directly in our authorizer bean by creating custom @SecurityParameterBinding types; this is a simple step once we have completed the work above:</p>
+<div class="codehilite"><pre><span class="n">Create</span> <span class="n">a</span> <span class="n">parameter</span> <span class="n">binding</span> <span class="n">annotation</span>
+<span class="nv">@Retention</span><span class="p">(</span><span class="n">value</span> <span class="o">=</span> <span class="n">RUNTIME</span><span class="p">)</span>
+<span class="nv">@Target</span><span class="p">({</span><span class="n">PARAMETER</span><span class="p">})</span>
+<span class="nv">@Documented</span>
+<span class="nv">@SecurityParameterBinding</span>
+<span class="n">public</span> <span class="nv">@interface</span> <span class="n">CurrentThing</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Now, when a secured method is invoked, we can inject actual parameter values as arguments into our authorizer method, providing domain-level security in our applications:</p>
+<div class="codehilite"><pre><span class="n">Update</span> <span class="n">the</span> <span class="n">Authorizer</span> <span class="n">to</span> <span class="k">use</span> <span class="n">parameter</span> <span class="n">binding</span>
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">CustomAuthorizer</span>
+<span class="p">{</span>
+ <span class="nv">@Secures</span>
+ <span class="nv">@CustomSecurityBinding</span>
+ <span class="n">public</span> <span class="n">boolean</span> <span class="n">doSecuredCheck</span><span class="p">(</span><span class="n">InvocationContext</span> <span class="n">invocationContext</span><span class="p">,</span> <span class="n">BeanManager</span> <span class="n">manager</span><span class="p">,</span> <span class="nv">@LoggedIn</span> <span class="n">User</span> <span class="n">user</span><span class="p">,</span> <span class="nv">@CurrentThing</span> <span class="n">Thing</span> <span class="n">thing</span><span class="p">)</span> <span class="n">throws</span> <span class="n">Exception</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="n">thing</span><span class="o">.</span><span class="n">hasMember</span><span class="p">(</span><span class="n">user</span><span class="p">);</span> <span class="sr">//</span> <span class="n">perform</span> <span class="n">security</span> <span class="n">check</span> <span class="n">against</span> <span class="k">our</span> <span class="n">method</span> <span class="n">parameter</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Note that our business method must also be annotated.</p>
+<div class="codehilite"><pre><span class="n">Complete</span> <span class="n">the</span> <span class="n">parameter</span> <span class="n">binding</span>
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">SecuredBean1</span>
+<span class="p">{</span>
+ <span class="nv">@CustomSecurityBinding</span>
+ <span class="n">public</span> <span class="n">void</span> <span class="n">doSomething</span><span class="p">(</span><span class="nv">@CurrentThing</span> <span class="n">Thing</span> <span class="n">thing</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">thing</span><span class="o">.</span><span class="n">doSomething</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Our method is now secured, and we are able to use given parameter values as part of our security authorizer!</p>
+<h2 id="integrating-3rd-party-security-frameworks">Integrating 3rd party security frameworks</h2>
+<h3 id="secured">@Secured</h3>
+<p>{{@Secured}} is build on {{@SecurityBindingType}} and a very simple alternative to the rest of the security module.
+It's a basic hook to integrate a custom security concept, 3rd party frameworks,... . It doesn't provide a full blown security concept like the rest of the security module, but other DeltaSpike modules ensure that the security concepts are integrated properly (e.g. correct behaviour within custom scope implementations,...). It just allows to integrate other security frameworks easily.</p>
+<p>(In MyFaces CODI it was originally a CDI interceptor. This part changed a bit, because between the interceptor and {{@Secured}} is the {{@SecurityBindingType}} concept which triggers {{@Secured}} as on possible approach. Therefore the basic behaviour remains the same and you can think about it like an interceptor.)</p>
+<div class="codehilite"><pre><span class="n">Securing</span> <span class="n">all</span> <span class="n">intercepted</span> <span class="n">methods</span> <span class="n">of</span> <span class="n">a</span> <span class="n">CDI</span> <span class="n">bean</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="nv">@Secured</span><span class="p">(</span><span class="n">CustomAccessDecisionVoter</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">SecuredBean</span>
+<span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>or</p>
+<div class="codehilite"><pre><span class="n">Securing</span> <span class="n">specific</span> <span class="n">methods</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">SecuredBean</span>
+<span class="p">{</span>
+ <span class="nv">@Secured</span><span class="p">(</span><span class="n">CustomAccessDecisionVoter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+ <span class="n">public</span> <span class="n">String</span> <span class="n">getResult</span><span class="p">()</span>
+ <span class="p">{</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<h3 id="accessdecisionvoter">AccessDecisionVoter</h3>
+<p>This interface is (besides the {{Secured}} annotation) the most important part of the concept. Both artifact types are also the only required parts.</p>
+<div class="codehilite"><pre><span class="n">public</span> <span class="n">class</span> <span class="n">CustomAccessDecisionVoter</span> <span class="n">implements</span> <span class="n">AccessDecisionVoter</span>
+<span class="p">{</span>
+ <span class="nv">@Override</span>
+ <span class="n">public</span> <span class="n">Set</span><span class="sr"><SecurityViolation></span> <span class="n">checkPermission</span><span class="p">(</span><span class="n">AccessDecisionVoterContext</span> <span class="n">accessDecisionVoterContext</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">Method</span> <span class="n">method</span> <span class="o">=</span> <span class="n">accessDecisionVoterContext</span><span class="o">.</span><span class="sr"><InvocationContext></span><span class="n">getSource</span><span class="p">()</span><span class="o">.</span><span class="n">getMethod</span><span class="p">();</span>
+
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>[TODO] hint about the changed parameter/s</p>
+<h3 id="securityviolation">SecurityViolation</h3>
+<p>In case of a detected violation a {{SecurityViolation}} has to be added to the result returned by the {{AccessDecisionVoter}}.</p>
+<p>[TODO] AbstractAccessDecisionVoter</p>
+<h3 id="secured-and-stereotypes-with-custom-meta-data">@Secured and Stereotypes with custom Meta-data</h3>
+<p>If there are multiple {{AccessDecisionVoter}} and maybe in different constellations, it's easier to provide an expressive CDI stereotypes for it. Later on that also allows to change the behaviour in a central place.</p>
+<div class="codehilite"><pre><span class="n">Stereotype</span> <span class="n">support</span> <span class="n">of</span> <span class="nv">@Secured</span><span class="p">}</span>
+<span class="nv">@Named</span>
+<span class="nv">@Admin</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyBean</span> <span class="n">implements</span> <span class="n">Serializable</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="nv">@Stereotype</span>
+<span class="nv">@Secured</span><span class="p">(</span><span class="n">RoleAccessDecisionVoter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+<span class="n">public</span> <span class="nv">@interface</span> <span class="n">Admin</span>
+<span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Furthermore, it's possible to provide custom meta-data easily.</p>
+<div class="codehilite"><pre><span class="n">Stereotype</span> <span class="n">of</span> <span class="nv">@Secured</span> <span class="n">with</span> <span class="n">custom</span> <span class="n">meta</span><span class="o">-</span><span class="n">data</span><span class="p">}</span>
+<span class="nv">@Named</span>
+<span class="nv">@Admin</span><span class="p">(</span><span class="n">securityLevel</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">MyBean</span> <span class="n">implements</span> <span class="n">Serializable</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="nv">@Stereotype</span>
+<span class="nv">@Secured</span><span class="p">(</span><span class="n">RoleAccessDecisionVoter</span><span class="o">.</span><span class="n">class</span><span class="p">)</span>
+<span class="n">public</span> <span class="nv">@interface</span> <span class="n">Admin</span>
+<span class="p">{</span>
+ <span class="nb">int</span> <span class="n">securityLevel</span><span class="p">();</span>
+<span class="p">}</span>
+
+<span class="nv">@ApplicationScoped</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">RoleAccessDecisionVoter</span> <span class="n">implements</span> <span class="n">AccessDecisionVoter</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="o">-</span><span class="mi">8007511215776345835</span><span class="n">L</span><span class="p">;</span>
+
+ <span class="n">public</span> <span class="n">Set</span><span class="sr"><SecurityViolation></span> <span class="n">checkPermission</span><span class="p">(</span><span class="n">AccessDecisionVoterContext</span> <span class="n">voterContext</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="n">Admin</span> <span class="n">admin</span> <span class="o">=</span> <span class="n">voterContext</span><span class="o">.</span><span class="n">getMetaDataFor</span><span class="p">(</span><span class="n">Admin</span><span class="o">.</span><span class="n">class</span><span class="o">.</span><span class="n">getName</span><span class="p">(),</span> <span class="n">Admin</span><span class="o">.</span><span class="n">class</span><span class="p">);</span>
+ <span class="nb">int</span> <span class="n">level</span> <span class="o">=</span> <span class="n">admin</span><span class="o">.</span><span class="n">securityLevel</span><span class="p">();</span>
+ <span class="sr">//</span><span class="o">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>{code}</p>
+<h2 id="accessdecisionvotercontext">AccessDecisionVoterContext</h2>
+<p>[TODO]</p>
+<h2 id="securitystrategy-spi">SecurityStrategy SPI</h2>
+<p>[TODO]</p>
+
+ <div id="copyright" class="container_16">
+ <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </div>
+</div>
+</body>
+</html>
Added: websites/staging/deltaspike/trunk/content/deltaspike/source.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/source.html (added)
+++ websites/staging/deltaspike/trunk/content/deltaspike/source.html Mon Jul 2 10:40:37 2012
@@ -0,0 +1,70 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+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.
+-->
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="resources/site.css"/>
+ <title>Apache DeltaSpike - </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. -->
+</head>
+<body>
+<div id="page" class="container_16">
+ <div id="header" class="grid_8 omega">
+ <img src="http://www.apache.org/images/feather-small.gif" alt="The Apache Software Foundation">
+ <h1>Apache DeltaSpike</h1>
+ </div>
+ <div id="nav" class="grid_8 omega">
+ <ul>
+ <!-- <li><a href="/" title="Welcome!">Home</a></li> -->
+ <li><a href="http://www.apache.org/foundation/" title="The Foundation">Foundation</a></li>
+ <li><a href="http://projects.apache.org" title="The Projects">Projects</a></li>
+ <li><a href="http://people.apache.org" title="The People">People</a></li>
+ <li><a href="http://www.apache.org/foundation/getinvolved.html" title="Get Involved">Get Involved</a></li>
+ <li><a href="http://www.apache.org/dyn/closer.cgi" title="Download">Download</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Support Apache">Support Apache</a></li>
+ </ul>
+ <p id="breadcrumb"><a href="/">Home</a> » <a href="/deltaspike/">Deltaspike</a></p>
+
+ </div>
+
+ <div class="grid_16">
+ <h1></h1>
+ </div>
+
+ <h1 id="checking-out-from-github-repo-anonymous">Checking out from GitHub repo (anonymous)</h1>
+<div class="codehilite"><pre><span class="n">gir</span> <span class="n">clone</span> <span class="n">git:</span><span class="sr">//gi</span><span class="n">thub</span><span class="o">.</span><span class="n">com</span><span class="sr">/apache/i</span><span class="n">ncubator</span><span class="o">-</span><span class="n">deltaspike</span><span class="o">.</span><span class="n">git</span> <span class="o">./</span>
+</pre></div>
+
+
+<h1 id="checking-out-for-members">Checking out for members</h1>
+<div class="codehilite"><pre><span class="n">git</span> <span class="n">clone</span> <span class="n">https:</span><span class="sr">//gi</span><span class="n">thub</span><span class="o">.</span><span class="n">com</span><span class="sr">/apache/i</span><span class="n">ncubator</span><span class="o">-</span><span class="n">deltaspike</span> <span class="o">./</span>
+</pre></div>
+
+ <div id="copyright" class="container_16">
+ <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </div>
+</div>
+</body>
+</html>
Added: websites/staging/deltaspike/trunk/content/deltaspike/spi.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/deltaspike/spi.html (added)
+++ websites/staging/deltaspike/trunk/content/deltaspike/spi.html Mon Jul 2 10:40:37 2012
@@ -0,0 +1,106 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<!--
+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.
+-->
+<html>
+<head>
+ <META http-equiv="Content-Type" content="text/html;charset=UTF-8" />
+ <link rel="stylesheet" type="text/css" media="screen" href="http://www.apache.org/css/code.css">
+ <link rel="stylesheet" type="text/css" media="screen" href="resources/site.css"/>
+ <title>Apache DeltaSpike - </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. -->
+</head>
+<body>
+<div id="page" class="container_16">
+ <div id="header" class="grid_8 omega">
+ <img src="http://www.apache.org/images/feather-small.gif" alt="The Apache Software Foundation">
+ <h1>Apache DeltaSpike</h1>
+ </div>
+ <div id="nav" class="grid_8 omega">
+ <ul>
+ <!-- <li><a href="/" title="Welcome!">Home</a></li> -->
+ <li><a href="http://www.apache.org/foundation/" title="The Foundation">Foundation</a></li>
+ <li><a href="http://projects.apache.org" title="The Projects">Projects</a></li>
+ <li><a href="http://people.apache.org" title="The People">People</a></li>
+ <li><a href="http://www.apache.org/foundation/getinvolved.html" title="Get Involved">Get Involved</a></li>
+ <li><a href="http://www.apache.org/dyn/closer.cgi" title="Download">Download</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html" title="Support Apache">Support Apache</a></li>
+ </ul>
+ <p id="breadcrumb"><a href="/">Home</a> » <a href="/deltaspike/">Deltaspike</a></p>
+
+ </div>
+
+ <div class="grid_16">
+ <h1></h1>
+ </div>
+
+ <h1 id="deltaspike-spi">DeltaSpike-SPI</h1>
+<h2 id="deactivatable">Deactivatable</h2>
+<p>This interface is just a marker interface which is implemented by all pre-configured DeltaSpike artifacts which can be deactivated manually (e.g. to improve the performance if a part isn't needed, to provide a custom implementation if the default implementation isn't pluggable by default or to bypass an implementation which causes an issue (in this case please also <em>contact us</em> and we will fix it). This mechanism is only used for artifacts <em>like</em> implementations of ({{javax.enterprise.inject.spi.Extension}}) which <em>can't</em> be deactivated with std. CDI mechanisms.</p>
+<p>To deactivate a class it's required to implement {{ClassDeactivator}}. Returning 'false' or 'true' allows to de-/activate the class in question. Retuning null means that the current class-deactivator doesn't have information about the class in question and can't provide a result. Since {{ClassDeactivator}} implementations are configured with the low-level config of DeltaSpike, the class-deactivator with the highest ordinal has the final decision. DeltaSpike itself doesn't deactivate an implementation, however, an add-on or a 3rd party portable CDI extension based on DeltaSpike (Core+) can use the concept to deactivate a default implementation of DeltaSpike in favour of its own implementation. (<em>Attention</em>: due to the ordinal feature of the low-level config approach it's possible that a class-deactivator with a higher ordinal, e.g. used in a concrete project, can re-activate a deactivated implementation. <em>Please note</em> that you might have to deactivate the par
ts of the add-on or 3rd party CDI extension which relies on its own implementation. Therefore, you should <em>be really careful with re-activation</em>.) The implementation should be stateless because the result will be cached and as soon as everything is initialized the class-deactivators won't be used any longer.</p>
+<div class="codehilite"><pre><span class="x">Deactivate classes via ClassDeactivator</span>
+<span class="x">//This class needs to be configured via one of the supported config sources!</span>
+<span class="x">public class CustomClassDeactivator extends ClassDeactivator</span>
+<span class="x">{</span>
+<span class="x"> @Override</span>
+<span class="x"> public Boolean isActivated(Class</span><span class="cp"><?</span> <span class="k">extends</span> <span class="nx">Deactivatable</span><span class="o">></span> <span class="nx">targetClass</span><span class="p">)</span>
+ <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="nx">targetClass</span><span class="o">.</span><span class="nx">equals</span><span class="p">(</span><span class="nx">MyClass</span><span class="o">.</span><span class="nx">class</span><span class="p">))</span>
+ <span class="p">{</span>
+ <span class="k">return</span> <span class="nx">Boolean</span><span class="o">.</span><span class="k">FALSE</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="k">null</span><span class="p">;</span> <span class="c1">//no result for the given class</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>A {{ClassDeactivator}} needs to be configured (see the supported config sources [TODO: link]). The key is the fully qualified name of the interface ({{org.apache.deltaspike.core.api.activation.ClassDeactivator}})</p>
+<h2 id="classdeactivation">ClassDeactivation</h2>
+<p>This helper is <em>not</em> intended to be used by users. DeltaSpike (and CDI extensions can) use/s it to check if a given class is activated. (Furthermore, it's optimized and callers don't have to care about synchronization,...)
+The method {{isActivated}} needs to be called manually to evaluate if a (non-CDI- or low-level-) class should be used. That means the pre-configured class <em>which uses</em> this helper won't disappear, instead it falls e.g. back to a minimal implementation which doesn't execute the target logic of the class itself or uses one of the other implementations (if there are multiple).</p>
+<p>h1. Global Alternative</p>
+<p>There are several application servers (using CDI 1.0) which can't handle alternative CDI beans correctly (e.g. due to a too strict interpretation or a broken implementation). Therefore, DeltaSpike allows to use the std. {{@Alternative}} annotation and an additional config entry for DeltaSpike which allows to use the alternative implementation as a global alternative.</p>
+<div class="codehilite"><pre><span class="n">Std</span><span class="o">.</span> <span class="n">CDI</span> <span class="n">alternative</span> <span class="n">implementation</span> <span class="p">(</span><span class="n">without</span> <span class="n">the</span> <span class="n">required</span> <span class="n">XML</span> <span class="n">config</span><span class="p">)</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">CustomBean</span>
+<span class="p">{</span>
+<span class="p">}</span>
+
+<span class="nv">@Alternative</span>
+<span class="sr">//</span><span class="o">...</span>
+<span class="n">public</span> <span class="n">class</span> <span class="n">AlternativeCustomBean</span> <span class="n">extends</span> <span class="n">CustomBean</span>
+<span class="p">{</span>
+<span class="p">}</span>
+<span class="p">{</span><span class="n">code</span><span class="p">}</span>
+</pre></div>
+
+
+<p>Instead of configuring the alternative in the beans.xml, a global alternative needs to be configured in /META-INF/apache-deltaspike.properties. CDI 1.1 should fix this issue and migrating to it means to remove the config entry for DeltaSpike again and move to the std. CDI config approach.</p>
+<div class="codehilite"><pre><span class="n">custom</span><span class="o">.</span><span class="n">CustomBean</span><span class="o">=</span><span class="n">custom</span><span class="o">.</span><span class="n">AlternativeCustomBean</span>
+</pre></div>
+
+ <div id="copyright" class="container_16">
+ <p>Copyright © 20011-2012 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.<br/>Apache and the Apache feather logo are trademarks of The Apache Software Foundation.</p>
+ </div>
+</div>
+</body>
+</html>