Modified: websites/staging/deltaspike/trunk/content/retired/data.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/data.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/data.html Sat Aug 1
21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Data Module</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#installation">Installation</a><ul>
@@ -147,7 +158,7 @@
</ul>
</div>
<hr />
-<h1 id="introduction">Introduction</h1>
+<h1 id="introduction">Introduction<a class="headerlink" href="#introduction"
title="Permanent link">¶</a></h1>
<p>The repository pattern used to be one of the core J2EE patterns and could
be found in
most enterprise applications reading and writing data to persistent stores.
While the Java Persistence API (JPA) as part of Java EE 5+ has replaced many
aspects of the
@@ -184,8 +195,8 @@ can focus on the though things.</p>
<p>The implementation of the method is done automatically by the CDI
extension.
A client can declare a dependency to the interface only. The details on how to
use those
features are outlines in the following chapters.</p>
-<h1 id="installation">Installation</h1>
-<h2 id="prerequisites">Prerequisites</h2>
+<h1 id="installation">Installation<a class="headerlink" href="#installation"
title="Permanent link">¶</a></h1>
+<h2 id="prerequisites">Prerequisites<a class="headerlink"
href="#prerequisites" title="Permanent link">¶</a></h2>
<p>The simplest way using the DeltaSpike Data module is to run your
application in a Java EE container
supporting at least the Java EE 6 Web Profile. Other configurations like
running it inside Tomcat or
even a Java SE application should be possible - you need to include a JPA
provider as well as a CDI container
@@ -196,7 +207,7 @@ of the <a href="http://www.javassist.org
<blockquote>
<p>Using DeltaSpike Data in an EAR deployment is currently restricted to
annotation-based entities.</p>
</blockquote>
-<h2 id="maven-dependency-configuration">Maven Dependency Configuration</h2>
+<h2 id="maven-dependency-configuration">Maven Dependency Configuration<a
class="headerlink" href="#maven-dependency-configuration" title="Permanent
link">¶</a></h2>
<p>If you are using Maven as your build tool, you can add the following
dependencies to your <code>pom.xml</code>
file to include the DeltaSpike data module:</p>
<div class="codehilite"><pre><span class="nt"><dependency></span>
@@ -222,7 +233,7 @@ substitution so you can centrally manage
</blockquote>
<p>Including the API at compile time and only include the implementation at
runtime protects you from
inadvertantly depending on an implementation class.</p>
-<h2 id="setup-your-application">Setup your application</h2>
+<h2 id="setup-your-application">Setup your application<a class="headerlink"
href="#setup-your-application" title="Permanent link">¶</a></h2>
<p>DeltaSpike Data requires an <code>EntityManager</code> exposed via a CDI
producer - which is common practice
in Java EE 6 applications.</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">EntityManagerProducer</span>
@@ -263,8 +274,8 @@ in a following section.</p>
<p>You're now ready to use repositories in your application!</p>
-<h1 id="core-concepts">Core Concepts</h1>
-<h2 id="repositories">Repositories</h2>
+<h1 id="core-concepts">Core Concepts<a class="headerlink"
href="#core-concepts" title="Permanent link">¶</a></h1>
+<h2 id="repositories">Repositories<a class="headerlink" href="#repositories"
title="Permanent link">¶</a></h2>
<p>With the DeltaSpike Data module, it is possible to make a repository out of
basically any
abstract class or interface (using a concrete class will work too, but you
won't be able to use
most of the CDI extension features). All that is required is to mark the type
as such with a
@@ -286,7 +297,7 @@ Any method defined on the repository wil
require to set the entity class (we'll see later why) but if there are just
plain classes or
interfaces this is the only way to tell the framework what entity the
repository relates to.
In order to simplify this, DeltaSpike Data provides several base types.</p>
-<h3 id="the-entityrepository-interface">The <code>EntityRepository</code>
interface</h3>
+<h3 id="the-entityrepository-interface">The <code>EntityRepository</code>
interface<a class="headerlink" href="#the-entityrepository-interface"
title="Permanent link">¶</a></h3>
<p>Although mainly intended to hold complex query logic, working with both a
repository and an <code>EntityManager</code>
in the service layer might unnecessarily clutter code. In order to avoid this
for the most common cases,
DeltaSpike Data provides base types which can be used to replace the entity
manager.</p>
@@ -340,7 +351,7 @@ interface adding some more common method
It needs to go on each concrete repository. The same is not true if a base
class is introduced,
as we see in the next chapter. </p>
</blockquote>
-<h3 id="the-abstractentityrepository-class">The
<code>AbstractEntityRepository</code> class</h3>
+<h3 id="the-abstractentityrepository-class">The
<code>AbstractEntityRepository</code> class<a class="headerlink"
href="#the-abstractentityrepository-class" title="Permanent
link">¶</a></h3>
<p>This class is an implementation of the <code>EntityRepository</code>
interface and provides additional functionality
when custom query logic needs also to be implemented in the repository.</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">abstract</span> <span class="kd">class</span> <span
class="nc">PersonRepository</span> <span class="kd">extends</span> <span
class="n">AbstractEntityRepository</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">Long</span><span class="o">></span>
@@ -357,7 +368,7 @@ when custom query logic needs also to be
</pre></div>
-<h2 id="using-multiple-entitymanager">Using Multiple
<code>EntityManager</code></h2>
+<h2 id="using-multiple-entitymanager">Using Multiple
<code>EntityManager</code><a class="headerlink"
href="#using-multiple-entitymanager" title="Permanent link">¶</a></h2>
<p>While most applications will run just fine with a single
<code>EntityManager</code>, there might be setups
where multiple data sources are used. This can be configured with the
<code>EntityManagerConfig</code> annotation:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
@@ -383,7 +394,7 @@ where multiple data sources are used. Th
<p>Again, note that annotations on interfaces do not inherit, so it's not
possible to create something like a base
<code>CrmRepository</code> interface with the
<code>@EntityManagerConfig</code> and then extending / implementing this
interface.</p>
-<h2 id="other-entitymanager-methods">Other <code>EntityManager</code>
methods</h2>
+<h2 id="other-entitymanager-methods">Other <code>EntityManager</code>
methods<a class="headerlink" href="#other-entitymanager-methods"
title="Permanent link">¶</a></h2>
<p>While the <code>EntityRepository</code> methods should cover most
interactions normally done with an <code>EntityManager</code>,
for some specific cases it might still be useful to have one or the other
method available. For this case,
it's possible to extend / implement the <code>EntityManagerDelegate</code>
interface for repositories, which offers
@@ -396,11 +407,11 @@ most other methods available in a JPA 2.
</pre></div>
-<h1 id="query-method-expressions">Query Method Expressions</h1>
+<h1 id="query-method-expressions">Query Method Expressions<a
class="headerlink" href="#query-method-expressions" title="Permanent
link">¶</a></h1>
<p>Good naming is a difficult aspects in software engineering. A good method
name usually makes
comments unnecessary and states exactly what the method does. And with method
expressions, the
method name is actually the implementation!</p>
-<h2 id="using-method-expressions">Using method expressions</h2>
+<h2 id="using-method-expressions">Using method expressions<a
class="headerlink" href="#using-method-expressions" title="Permanent
link">¶</a></h2>
<p>Let's start by looking at a (simplified for readability) example:</p>
<div class="codehilite"><pre><span class="nd">@Entity</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">Person</span>
@@ -468,7 +479,7 @@ the query implementation out of it (in E
<p>Note that DeltaSpike will validate those expressions during startup, so you
will notice early in case you have a typo
in those expressions.</p>
-<h2 id="query-ordering">Query Ordering</h2>
+<h2 id="query-ordering">Query Ordering<a class="headerlink"
href="#query-ordering" title="Permanent link">¶</a></h2>
<p>Beside comparators it's also possible to sort queries by using the
<code>OrderBy</code> keyword, followed
by the attribute name and the direction (<code>Asc</code> or
<code>Desc</code>).</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
@@ -481,7 +492,7 @@ by the attribute name and the direction
</pre></div>
-<h2 id="nested-properties">Nested Properties</h2>
+<h2 id="nested-properties">Nested Properties<a class="headerlink"
href="#nested-properties" title="Permanent link">¶</a></h2>
<p>To create a comparison on a nested property, the traversal parts can be
separated by a <code>_</code>:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
<span class="kd">public</span> <span class="kd">interface</span> <span
class="nc">PersonRepository</span> <span class="kd">extends</span> <span
class="n">EntityRepository</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">Long</span><span class="o">></span>
@@ -493,7 +504,7 @@ by the attribute name and the direction
</pre></div>
-<h2 id="query-options">Query Options</h2>
+<h2 id="query-options">Query Options<a class="headerlink"
href="#query-options" title="Permanent link">¶</a></h2>
<p>DeltaSpike supports query options on method expressions. If you want to
page a query,
you can change the first result as well as the maximum number of results
returned:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
@@ -506,7 +517,7 @@ you can change the first result as well
</pre></div>
-<h2 id="method-prefix">Method Prefix</h2>
+<h2 id="method-prefix">Method Prefix<a class="headerlink"
href="#method-prefix" title="Permanent link">¶</a></h2>
<p>In case the <code>findBy</code> prefix does not comply with your team
conventions, this can be adapted:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span><span
class="o">(</span><span class="n">methodPrefix</span> <span class="o">=</span>
<span class="s">"fetchWith"</span><span class="o">)</span>
<span class="kd">public</span> <span class="kd">interface</span> <span
class="nc">PersonRepository</span> <span class="kd">extends</span> <span
class="n">EntityRepository</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">Long</span><span class="o">></span>
@@ -518,12 +529,12 @@ you can change the first result as well
</pre></div>
-<h1 id="query-annotations">Query Annotations</h1>
+<h1 id="query-annotations">Query Annotations<a class="headerlink"
href="#query-annotations" title="Permanent link">¶</a></h1>
<p>While method expressions are fine for simple queries, they will often reach
their limit once things
get slightly more complex. Another aspect is the way you want to use JPA: The
recommended approach
using JPA for best performance is over named queries. To help incorporate
those use cases, the
DeltaSpike Data module supports also annotating methods for more control on
the generated query.</p>
-<h2 id="using-query-annotations">Using Query Annotations</h2>
+<h2 id="using-query-annotations">Using Query Annotations<a class="headerlink"
href="#using-query-annotations" title="Permanent link">¶</a></h2>
<p>The simples way to define a specific query is by annotating a method and
providing the JPQL query
string which has to be executed. In code, this looks like the following
sample:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">interface</span> <span class="nc">PersonRepository</span> <span
class="kd">extends</span> <span class="n">EntityRepository</span><span
class="o"><</span><span class="n">Person</span><span class="o">,</span>
<span class="n">Long</span><span class="o">></span>
@@ -606,7 +617,7 @@ which flags that the query is not JPQL b
</pre></div>
-<h2 id="annotation-options">Annotation Options</h2>
+<h2 id="annotation-options">Annotation Options<a class="headerlink"
href="#annotation-options" title="Permanent link">¶</a></h2>
<p>Beside providing a query string or reference, the <code>@Query</code>
annotation provides also two more attributes:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
<span class="kd">public</span> <span class="kd">interface</span> <span
class="nc">PersonRepository</span> <span class="kd">extends</span> <span
class="n">EntityRepository</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">Long</span><span class="o">></span>
@@ -630,7 +641,7 @@ which flags that the query is not JPQL b
</table>
<p>Note that these options can also be applied to method expressions.</p>
-<h2 id="query-options_1">Query Options</h2>
+<h2 id="query-options_1">Query Options<a class="headerlink"
href="#query-options_1" title="Permanent link">¶</a></h2>
<p>All the query options you have seen so far are more or less static. But
sometimes you might want
to apply certain query options dynamically. For example, sorting criteria
could come from a user
selection so they cannot be known beforehand. DeltaSpike allows you to apply
query options at runtime by
@@ -661,7 +672,7 @@ using the <code>QueryResult</code> resul
<p>Note that sorting is only applicable to method expressions or non-named
queries. For named queries it might be possible, but is currently only
supported for Hibernate, EclipseLink and OpenJPA.</p>
</blockquote>
<p>Note that the <code>QueryResult</code> return type can also be used with
method expressions.</p>
-<h2 id="pagination">Pagination</h2>
+<h2 id="pagination">Pagination<a class="headerlink" href="#pagination"
title="Permanent link">¶</a></h2>
<p>We introduced the <code>QueryResult</code> type in the last chapter, which
can also be used for pagination:</p>
<div class="codehilite"><pre><span class="c1">// Query API style</span>
<span class="n">QueryResult</span><span class="o"><</span><span
class="n">Person</span><span class="o">></span> <span class="n">paged</span>
<span class="o">=</span> <span class="n">personRepository</span><span
class="o">.</span><span class="na">findByAge</span><span
class="o">(</span><span class="n">age</span><span class="o">)</span>
@@ -677,7 +688,7 @@ using the <code>QueryResult</code> resul
</pre></div>
-<h2 id="bulk-operations">Bulk Operations</h2>
+<h2 id="bulk-operations">Bulk Operations<a class="headerlink"
href="#bulk-operations" title="Permanent link">¶</a></h2>
<p>While reading entities and updating them one by one might be fine for many
use cases, applying bulk
updates or deletes is also a common usage scenario for repositories.
DeltaSpike supports this with a special
marking annotation <code>@Modifying</code>:</p>
@@ -695,13 +706,13 @@ marking annotation <code>@Modifying</cod
<p>Bulk operation query methods can either return void or int, which counts
the number of entities affected
by the bulk operation. </p>
-<h2 id="optional-query-results">Optional Query Results</h2>
+<h2 id="optional-query-results">Optional Query Results<a class="headerlink"
href="#optional-query-results" title="Permanent link">¶</a></h2>
<p>The JPA spec requires to throw exceptions in case the
<code>getSingleResult()</code> method does either return
no or more than one result. This can result in tedious handling with try-catch
blocks or have potential
impact on your transaction (as the <code>RuntimeException</code> might roll it
back).</p>
<p>DeltaSpike Data gives the option to change this to the way it makes most
sense for the current usecase.
While the default behavior is still fully aligned with JPA, it's also possible
to request optional query results.</p>
-<h2 id="zero-or-one-result">Zero or One Result</h2>
+<h2 id="zero-or-one-result">Zero or One Result<a class="headerlink"
href="#zero-or-one-result" title="Permanent link">¶</a></h2>
<p>With this option, the query returns <code>null</code> instead of throwing a
<code>NoResultException</code> when there is no
result returned. It's usable with method expressions, <code>Query</code>
annotations and <code>QueryResult<E></code> calls.</p>
<div class="codehilite"><pre><span class="nd">@Repository</span><span
class="o">(</span><span class="n">forEntity</span> <span class="o">=</span>
<span class="n">Person</span><span class="o">.</span><span
class="na">class</span><span class="o">)</span>
@@ -720,7 +731,7 @@ result returned. It's usable with method
<p>For method expressions, the <code>findOptionalBy</code> prefix can be used.
For <code>@Query</code> annotations, the <code>singleResult</code>
attribute can be overridden with the <code>SingleResultType.OPTIONAL</code>
enum.</p>
<p>In case the query returns more than one result, a
<code>NonUniqueResultException</code> is still thrown.</p>
-<h2 id="any-result">Any Result</h2>
+<h2 id="any-result">Any Result<a class="headerlink" href="#any-result"
title="Permanent link">¶</a></h2>
<p>If the caller does not really mind what kind if result is returned, it's
also possible to request any
result from the query. If there is no result, same as for optional queries
<code>null</code> is returned. In case
there is more than one result, any result is returned, or more concretely the
first result out of the
@@ -741,7 +752,7 @@ result list.</p>
<p>For method expressions, the <code>findAnyBy</code> prefix can be used. For
<code>@Query</code> annotations, the <code>singleResult</code>
attribute can be overridden with the <code>SingleResultType.ANY</code>
enum.</p>
<p>This option will not throw an exception.</p>
-<h1 id="transactions">Transactions</h1>
+<h1 id="transactions">Transactions<a class="headerlink" href="#transactions"
title="Permanent link">¶</a></h1>
<p>If you call any method expression, <code>@Query</code>-annotated method or
a method from the <code>EntityRepository</code>, the
repository will figure out if a transaction is needed or not, and if so, if
there is already one ongoing.
The Data module uses the <code>TransactionStrategy</code> provided by the <a
href="http://deltaspike.apache.org/jpa"; title="JPA module">JPA Module</a> for
this. See the JPA module
@@ -775,8 +786,8 @@ We will think about providing an accepta
<p>Repositories can then implement the <code>TxRepository</code> interface and
call their queries in the
<code>transactional</code> method (where the callback implementation can be
e.g. in an anonymous class).</p>
-<h1 id="extensions">Extensions</h1>
-<h2 id="query-delegates">Query Delegates</h2>
+<h1 id="extensions">Extensions<a class="headerlink" href="#extensions"
title="Permanent link">¶</a></h1>
+<h2 id="query-delegates">Query Delegates<a class="headerlink"
href="#query-delegates" title="Permanent link">¶</a></h2>
<p>While repositories defines several base interfaces, there might still be
the odd convenience
method that is missing. This is actually intentional - things should not get
overloaded for each and
every use case. That's why in DeltaSpike you can define your own reusable
methods.</p>
@@ -796,7 +807,7 @@ every use case. That's why in DeltaSpike
</pre></div>
-<h2 id="implementing-the-query-delegate">Implementing the Query Delegate</h2>
+<h2 id="implementing-the-query-delegate">Implementing the Query Delegate<a
class="headerlink" href="#implementing-the-query-delegate" title="Permanent
link">¶</a></h2>
<p>The first step is to define an interface which contains the extra methods
for your repositories
(as shown above):</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">interface</span> <span class="nc">QueryDslSupport</span>
@@ -829,7 +840,7 @@ an empty marker interface):</p>
like accessing the current <code>EntityManager</code> and entity class.
</p>
<p>Note that, if you define multiple extensions with equivalent method
signatures, there is no specific
order in which the implementation is selected.</p>
-<h1 id="mapping">Mapping</h1>
+<h1 id="mapping">Mapping<a class="headerlink" href="#mapping" title="Permanent
link">¶</a></h1>
<p>While repositories are primarily intended to work with Entities, it might
be preferable in some
cases to have an additional mapping layer on top of them, e.g. because the
Entities are quite complex
but the service layer needs only a limited view on it, or because the Entities
are exposed over a
@@ -901,7 +912,7 @@ refers to the mapper class directly, the
<p>In this case, the <code>forEntity</code> attribute in the
<code>@Repository</code> annotation is mandatory. Also it is up
to the mapper to convert parameters correctly (in this example, a conversion
from a <code>PersonDto</code>
parameter to <code>Person</code> entity and from <code>PersonId</code> to
<code>Long</code> is necessary).</p>
-<h2 id="simple-mappings">Simple Mappings</h2>
+<h2 id="simple-mappings">Simple Mappings<a class="headerlink"
href="#simple-mappings" title="Permanent link">¶</a></h2>
<p>In many cases it's just required to map a DTO object back and forth. For
this case, the <code>SimpleQueryInOutMapperBase</code> class
can be subclassed, which only requires to override two methods:</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">class</span> <span class="nc">PersonMapper</span> <span
class="kd">extends</span> <span
class="n">SimpleQueryInOutMapperBase</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">PersonDto</span><span class="o">></span>
@@ -933,7 +944,7 @@ If there is a primary key in the DTO, Da
so the entity to be mapped is <strong>attached to the persistence
context</strong>. If there is no primary key, a new
instance of the Entity is created. In any case, there is no need to map the
primary key to the entity (it either
does not exist or is already populated for an existing entity).</p>
-<h1 id="jpa-criteria-api-support">JPA Criteria API Support</h1>
+<h1 id="jpa-criteria-api-support">JPA Criteria API Support<a
class="headerlink" href="#jpa-criteria-api-support" title="Permanent
link">¶</a></h1>
<p>Beside automatic query generation, the DeltaSpike Data module also provides
a DSL-like API to create JPA 2 Criteria queries.
It takes advantage of the JPA 2 meta model, which helps creating type safe
queries.</p>
<p><strong>TIP:</strong></p>
@@ -945,7 +956,7 @@ provide such a processor, which can be i
API that should make life easier on the most common cases for a custom query.
The JPA criteria API's
strongest point is certainly its type safety - which comes at the cost of
readability. We're trying to
provide a middle way here. A less powerful API, but still type safe and
readable.</p>
-<h2 id="api-usage">API Usage</h2>
+<h2 id="api-usage">API Usage<a class="headerlink" href="#api-usage"
title="Permanent link">¶</a></h2>
<p>The API is centered around the Criteria class and is targeted to provide a
fluent interface
to write criteria queries:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span><span
class="o">(</span><span class="n">forEntity</span> <span class="o">=</span>
<span class="n">Person</span><span class="o">.</span><span
class="na">class</span><span class="o">)</span>
@@ -1003,7 +1014,7 @@ to write criteria queries:</p>
<p>Once all comparators and query options are applied, the
<code>createQuery()</code> method is called.
This creates a JPA TypedQuery object for the repository entity. If required,
further processing can be applied here.</p>
-<h2 id="joins">Joins</h2>
+<h2 id="joins">Joins<a class="headerlink" href="#joins" title="Permanent
link">¶</a></h2>
<p>For simple cases, restricting on the repository entity only works out fine,
but once the Data model
gets more complicated, the query will have to consider relations to other
entities. The module's criteria
API therefore supports joins as shown in the sample below:</p>
@@ -1043,7 +1054,7 @@ API therefore supports joins as shown in
</pre></div>
-<h2 id="boolean-operators">Boolean Operators</h2>
+<h2 id="boolean-operators">Boolean Operators<a class="headerlink"
href="#boolean-operators" title="Permanent link">¶</a></h2>
<p>By default, all query operators are concatenated as an and conjunction to
the query. The DeltaSpike
criteria API also allows to add groups of disjunctions.</p>
<div class="codehilite"><pre><span class="kd">public</span> <span
class="kd">abstract</span> <span class="kd">class</span> <span
class="nc">PersonRepository</span> <span class="kd">extends</span> <span
class="n">AbstractEntityRepository</span><span class="o"><</span><span
class="n">Person</span><span class="o">,</span> <span
class="n">Long</span><span class="o">></span>
@@ -1067,7 +1078,7 @@ criteria API also allows to add groups o
</pre></div>
-<h2 id="selections">Selections</h2>
+<h2 id="selections">Selections<a class="headerlink" href="#selections"
title="Permanent link">¶</a></h2>
<p>It might not always be appropriate to retrieve full entities - you might
also be interested
in scalar values or by modified entity attributes. The Criteria interface
allows this with the
selection method:</p>
@@ -1118,7 +1129,7 @@ selection method:</p>
<tr><td>currTStamp()</td><td>The DB sysdate. Returns a Timestamp object.
</td></tr>
</table>
-<h1 id="auditing">Auditing</h1>
+<h1 id="auditing">Auditing<a class="headerlink" href="#auditing"
title="Permanent link">¶</a></h1>
<p>A common requirement for entities is tracking what is being done with them.
DeltaSpike provides
a convenient way to support this requirement.</p>
<p><strong>TIP:</strong></p>
@@ -1126,7 +1137,7 @@ a convenient way to support this require
<p>DeltaSpike does not support creating revisions of entities. If this is a
requirement for your audits,
have a look at Hibernate Envers.</p>
</blockquote>
-<h2 id="activating-auditing">Activating Auditing</h2>
+<h2 id="activating-auditing">Activating Auditing<a class="headerlink"
href="#activating-auditing" title="Permanent link">¶</a></h2>
<p>DeltaSpike uses an entity listener to update auditing data before entities
get created or update.
The entity listener must be activated before it can be used. This can either
be done globally for
all entities of a persistent unit or per entity.</p>
@@ -1159,9 +1170,9 @@ all entities of a persistent unit or per
<p>Note that for this variant, you need a compile dependency on the impl
module. Alternatively, also the per
entity listener can be configured by XML.</p>
-<h2 id="using-auditing-annotations">Using Auditing Annotations</h2>
+<h2 id="using-auditing-annotations">Using Auditing Annotations<a
class="headerlink" href="#using-auditing-annotations" title="Permanent
link">¶</a></h2>
<p>All that has to be done now is annotating the entity properties which are
used to audit the entity.</p>
-<h3 id="updating-timestamps">Updating Timestamps</h3>
+<h3 id="updating-timestamps">Updating Timestamps<a class="headerlink"
href="#updating-timestamps" title="Permanent link">¶</a></h3>
<p>To keep track on creation and modification times, following annotations can
be used:</p>
<div class="codehilite"><pre><span class="nd">@Entity</span>
<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">AuditedEntity</span>
@@ -1188,7 +1199,7 @@ entity listener can be configured by XML
</pre></div>
-<h3 id="whos-changing-my-entities">Who's Changing My Entities?</h3>
+<h3 id="whos-changing-my-entities">Who's Changing My Entities?<a
class="headerlink" href="#whos-changing-my-entities" title="Permanent
link">¶</a></h3>
<p>Beside keeping track of when a change has happened, it's also often
critical to track who's responsible
for the change. Annotate a user tracking field with the following
annotation:</p>
<div class="codehilite"><pre><span class="nd">@Entity</span>
@@ -1239,7 +1250,7 @@ target entity.</p>
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/documentation.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/documentation.html
(original)
+++ websites/staging/deltaspike/trunk/content/retired/documentation.html Sat
Aug 1 21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Documentation</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#sources">Sources</a></li>
<li><a href="#format">Format</a></li>
@@ -90,11 +101,11 @@
</ul>
</div>
<hr />
-<h1 id="sources">Sources</h1>
+<h1 id="sources">Sources<a class="headerlink" href="#sources" title="Permanent
link">¶</a></h1>
<p><a href="/documentation/">DeltaSpike Documentation</a> is available with <a
href="documentation/source.html">DeltaSpike Source</a>.</p>
-<h1 id="format">Format</h1>
+<h1 id="format">Format<a class="headerlink" href="#format" title="Permanent
link">¶</a></h1>
<p>The format used for DeltaSpike documentation is <a
href="http://www.methods.co.nz/asciidoc/";>ASCIIDOC</a> because it's easily
exportable to PDF, HTML, and it's also easy to contribute. It can be used to
export also to epub and also be used to write books</p>
-<h1 id="rendering-documentation-as-html">Rendering documentation as HTML</h1>
+<h1 id="rendering-documentation-as-html">Rendering documentation as HTML<a
class="headerlink" href="#rendering-documentation-as-html" title="Permanent
link">¶</a></h1>
<p><em>Requirenment:</em> Have <a href="http://maven.apache.org/";>Maven</a>
installed.</p>
<p>If you cloned the source repository and want to render the documentation as
HTML, you just need to run the following command:</p>
<div class="codehilite"><pre>$ <span class="n">cd</span> <span
class="n">REPO_ROOT</span><span class="o">/</span><span
class="n">documentation</span>
@@ -103,9 +114,9 @@ $ <span class="n">mvn</span> <span class
<p>The generate documentation will be available at
<code>REPO_ROOT/documentation/target/site</code></p>
-<h1 id="contribute">Contribute</h1>
+<h1 id="contribute">Contribute<a class="headerlink" href="#contribute"
title="Permanent link">¶</a></h1>
<p>If you would like to submit a documentation patch through Jira, you can
have a look at the <a href="suggested-git-workflows.html">suggested
approach</a>.</p>
-<h1 id="publish-procedure-for-committers-only">Publish procedure (for
committers only)</h1>
+<h1 id="publish-procedure-for-committers-only">Publish procedure (for
committers only)<a class="headerlink"
href="#publish-procedure-for-committers-only" title="Permanent
link">¶</a></h1>
<p>If you're a committer and want to publish the documentation at <a
href="http://deltaspike.apache.org/documentation/";>DeltaSpike Site</a> you have
do the following steps:</p>
<p>Put the following information in your ~/.m2/settings.xml file</p>
<div class="codehilite"><pre><span class="nt"><server></span>
@@ -128,7 +139,7 @@ $ <span class="n">mvn</span> <span class
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/download.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/download.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/download.html Sat Aug 1
21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Download</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#latest-release">Latest Release</a></li>
<li><a href="#binary-distribution">Binary Distribution</a></li>
@@ -91,9 +102,9 @@
</ul>
</div>
<hr />
-<h1 id="latest-release">Latest Release</h1>
+<h1 id="latest-release">Latest Release<a class="headerlink"
href="#latest-release" title="Permanent link">¶</a></h1>
<p>v1.2.0</p>
-<h1 id="binary-distribution">Binary Distribution</h1>
+<h1 id="binary-distribution">Binary Distribution<a class="headerlink"
href="#binary-distribution" title="Permanent link">¶</a></h1>
<p><a
href="http://www.apache.org/dyn/closer.cgi/deltaspike/1.2.0/distribution-full-1.2.0.zip";
target="_blank">distribution-full-1.2.0.zip</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/distribution-full-1.2.0.zip.asc";
target="_blank">distribution-full-1.2.0.zip.asc</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/distribution-full-1.2.0.zip.md5";
target="_blank">distribution-full-1.2.0.zip.md5</a><br/>
@@ -102,16 +113,16 @@
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/distribution-full-1.2.0.tar.gz.asc";
target="_blank">distribution-full-1.2.0.tar.gz.asc</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/distribution-full-1.2.0.tar.gz.md5";
target="_blank">distribution-full-1.2.0.tar.gz.md5</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/distribution-full-1.2.0.tar.gz.sha1";
target="_blank">distribution-full-1.2.0.tar.gz.sha1</a><br/></p>
-<h1 id="source-distribution">Source Distribution</h1>
+<h1 id="source-distribution">Source Distribution<a class="headerlink"
href="#source-distribution" title="Permanent link">¶</a></h1>
<p><a
href="http://www.apache.org/dyn/closer.cgi/deltaspike/1.2.0/deltaspike-project-1.2.0-source-release.zip";
target="_blank">deltaspike-project-1.2.0-source-release.zip</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/deltaspike-project-1.2.0-source-release.zip.asc";
target="_blank">deltaspike-project-1.2.0-source-release.zip.asc</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/deltaspike-project-1.2.0-source-release.zip.md5";
target="_blank">deltaspike-project-1.2.0-source-release.zip.md5</a><br/>
<a
href="http://www.apache.org/dist/deltaspike/1.2.0/deltaspike-project-1.2.0-source-release.zip.sha1";
target="_blank">deltaspike-project-1.2.0-source-release.zip.sha1</a></p>
-<h1 id="maven-dependencies">Maven Dependencies</h1>
+<h1 id="maven-dependencies">Maven Dependencies<a class="headerlink"
href="#maven-dependencies" title="Permanent link">¶</a></h1>
<p>Details are available <a
href="documentation/#_project_configuration_without_maven">here</a>.</p>
-<h1 id="previous-releases">Previous Releases</h1>
+<h1 id="previous-releases">Previous Releases<a class="headerlink"
href="#previous-releases" title="Permanent link">¶</a></h1>
<p>See <a href="http://archive.apache.org/dist/deltaspike/";
target="_blank">Release-Archive</a></p>
-<h1 id="verifying-releases">Verifying Releases</h1>
+<h1 id="verifying-releases">Verifying Releases<a class="headerlink"
href="#verifying-releases" title="Permanent link">¶</a></h1>
<p>It is essential that you verify the integrity of any downloaded files using
the PGP or MD5 signatures. For more information on signing artifacts and
why we do it, check out the
@@ -144,7 +155,7 @@ Then verify the signatures using e.g.:</
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/examples.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/examples.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/examples.html Sat Aug 1
21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Examples</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#introduction">Introduction</a><ul>
<li><a href="#1">#1</a></li>
@@ -90,11 +101,11 @@
</ul>
</div>
<hr />
-<h1 id="introduction">Introduction</h1>
-<h2 id="1">#1</h2>
+<h1 id="introduction">Introduction<a class="headerlink" href="#introduction"
title="Permanent link">¶</a></h1>
+<h2 id="1">#1<a class="headerlink" href="#1" title="Permanent
link">¶</a></h2>
<p>artifact-id: deltaspike-jse-owb-example
(the shown use-cases also work with <em>Weld</em> - only the bootstrapping of
the container is different, because this example is based on Java-SE and
therefore outside of an Java-EE(6+) application server.</p>
-<h1 id="external">External</h1>
+<h1 id="external">External<a class="headerlink" href="#external"
title="Permanent link">¶</a></h1>
<ul>
<li><a href="https://github.com/os890/ee6-ds-demo";>Fullstack EE6+ with
DeltaSpike @ os890 (tested with EE6 and EE7)</a></li>
<li><a href="http://s.apache.org/xA";>Fullstack CODI to DeltaSpike @
os890</a></li>
@@ -107,7 +118,7 @@
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/exceptions.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/exceptions.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/exceptions.html Sat Aug
1 21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Exception Handling</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#introduction">Introduction</a><ul>
<li><a href="#exception-handling-usage">Exception Handling - Usage</a><ul>
@@ -106,7 +117,7 @@
</ul>
</div>
<hr />
-<h1 id="introduction">Introduction</h1>
+<h1 id="introduction">Introduction<a class="headerlink" href="#introduction"
title="Permanent link">¶</a></h1>
<p>Exception handling in DeltaSpike is based around the CDI eventing model.
While
the implementation of exception handlers may not be the same as a CDI event,
and
the programming model is not exactly the same as specifying a CDI event /
@@ -120,8 +131,8 @@ infrastructure.</p>
<p>The exception handling process remains mostly transparent to the developer.
In most cases, you register an
exception handler simply by annotating a handler method. Alternatively, you
can handle an exception
programmatically, just as you would observe an event in CDI.</p>
-<h2 id="exception-handling-usage">Exception Handling - Usage</h2>
-<h3 id="eventing-into-the-exception-handling-framework">Eventing into the
exception handling framework</h3>
+<h2 id="exception-handling-usage">Exception Handling - Usage<a
class="headerlink" href="#exception-handling-usage" title="Permanent
link">¶</a></h2>
+<h3 id="eventing-into-the-exception-handling-framework">Eventing into the
exception handling framework<a class="headerlink"
href="#eventing-into-the-exception-handling-framework" title="Permanent
link">¶</a></h3>
<p>The entire exception handling process starts with an event. This helps keep
your application minimally coupled to
DeltaSpike, but also allows for further extension. Exception handling in
DeltaSpike is all about letting you take care of
exceptions the way that makes the most sense for your application. Events
provide this delicate balance. Firing the event
@@ -150,7 +161,7 @@ into an inventory database:</p>
your class for use later within a try/catch block.</p>
<p>The event is fired with a new instance of {{ExceptionToCatchEvent}}
constructed with the
exception to be handled.</p>
-<h2 id="exception-handlers">Exception handlers</h2>
+<h2 id="exception-handlers">Exception handlers<a class="headerlink"
href="#exception-handlers" title="Permanent link">¶</a></h2>
<p>As an application developer (i.e., an end user of DeltaSpike's exception
handling), you'll be focused on writing exception handlers. An
exception handler is a method on a CDI bean that is invoked to handle a
specific type of exception. Within that
method, you can implement any logic necessary to handle or respond to the
exception.</p>
@@ -167,12 +178,12 @@ immediately familiar to you if you are s
an exception and a stack trace, and even extend exception handling further
through events that are fired during the handling
workflow. We'll begin by covering the two annotations that are used to
declare an exception handler,
{{@ExceptionHandler}} and {{@Handles}}, and {{@BeforeHandles}} to create a
callback before the handler is called.</p>
-<h3 id="exception-handler-annotations">Exception handler annotations</h3>
+<h3 id="exception-handler-annotations">Exception handler annotations<a
class="headerlink" href="#exception-handler-annotations" title="Permanent
link">¶</a></h3>
<p>Exception handlers are contained within exception handler beans, which are
CDI beans annotated with
{{@ExceptionHandler}}. Exception handlers are methods which have a parameter
which is an
instance of {{ExceptionEvent<T extends Throwable>}} annotated with the
{{@Handles}} annotation.</p>
-<h4 id="exceptionhandler">{{@ExceptionHandler}}</h4>
+<h4 id="exceptionhandler">{{@ExceptionHandler}}<a class="headerlink"
href="#exceptionhandler" title="Permanent link">¶</a></h4>
<p>The {{@ExceptionHandler}} annotation is simply a marker annotation that
instructs the DeltaSpike
exception handling CDI extension to scan the bean for handler methods.</p>
<p>Let's designate a CDI bean as an exception handler by annotating it with
{{@ExceptionHandler}}.</p>
@@ -182,7 +193,7 @@ exception handling CDI extension to scan
<p>That's all there is to it. Now we can begin defining exception handling
methods on this bean.</p>
-<h4 id="handles-and-beforehandles">{{@Handles}} and {{@BeforeHandles}}</h4>
+<h4 id="handles-and-beforehandles">{{@Handles}} and {{@BeforeHandles}}<a
class="headerlink" href="#handles-and-beforehandles" title="Permanent
link">¶</a></h4>
<p>{{@Handles}} is a method parameter annotation that designates a method as
an exception
handler. Exception handler methods are registered on beans annotated with
{{@ExceptionHandler}}. DeltaSpike will discover all such methods at deployment
time.</p>
@@ -264,7 +275,7 @@ itself by invoking the {{unmute()}} meth
<p>Handlers must not throw checked exceptions, and should avoid throwing
unchecked exceptions. Should a handler
throw an unchecked exception it will propagate up the stack and all handling
done via DeltaSpike will cease. Any
exception that was being handled will be lost.</p>
-<h2 id="exception-chain-processing">Exception Chain Processing</h2>
+<h2 id="exception-chain-processing">Exception Chain Processing<a
class="headerlink" href="#exception-chain-processing" title="Permanent
link">¶</a></h2>
<p>When an exception is thrown, chances are it's nested (wrapped) inside other
exceptions. (If you've ever
examined a server log, you'll appreciate this fact). The collection of
exceptions in its entirety is termed an
exception chain.</p>
@@ -296,7 +307,7 @@ infrastructure. Otherwise, it simply ret
<p>If there's a handler for {{PersistenceException}}, it will likely prevent
the handlers for
{{EJBException}} from being invoked, which is a good thing since what useful
information can
really be obtained from {{EJBException}}?</p>
-<h2 id="handler-ordinal">Handler ordinal</h2>
+<h2 id="handler-ordinal">Handler ordinal<a class="headerlink"
href="#handler-ordinal" title="Permanent link">¶</a></h2>
<p>When DeltaSpike finds more than one handler for the same exception type, it
orders the handlers by ordinal.
Handlers with higher ordinal are executed before handlers with a lower
ordinal. If DeltaSpike detects two
handlers for the same type with the same ordinal, the order is
non-deterministic.</p>
@@ -326,13 +337,13 @@ handled):</p>
</pre></div>
-<h2 id="apis-for-exception-information-and-flow-control">APIs for exception
information and flow control</h2>
+<h2 id="apis-for-exception-information-and-flow-control">APIs for exception
information and flow control<a class="headerlink"
href="#apis-for-exception-information-and-flow-control" title="Permanent
link">¶</a></h2>
<p>There are two APIs provided by DeltaSpike that should be familiar to
application developers:</p>
<ul>
<li>{{ExceptionEvent}}</li>
<li>{{ExceptionStackEvent}}</li>
</ul>
-<h3 id="exceptionevent">ExceptionEvent</h3>
+<h3 id="exceptionevent">ExceptionEvent<a class="headerlink"
href="#exceptionevent" title="Permanent link">¶</a></h3>
<p>In addition to providing information about the exception being handled, the
{{ExceptionEvent}} object contains methods to control the exception handling
process, such
as rethrowing the exception, aborting the handler chain or unmuting the
current handler.
@@ -354,7 +365,7 @@ unless it's explicitly marked as unmuted
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/javadoc.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/javadoc.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/javadoc.html Sat Aug 1
21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>Javadoc</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#latest-version">Latest version</a></li>
<li><a href="#stable-releases">Stable Releases</a></li>
@@ -89,18 +100,18 @@
</ul>
</div>
<hr />
-<h1 id="latest-version">Latest version</h1>
+<h1 id="latest-version">Latest version<a class="headerlink"
href="#latest-version" title="Permanent link">¶</a></h1>
<ul>
<li><a href="/javadoc/1.2.1-SNAPSHOT/">1.2.1-SNAPSHOT</a></li>
</ul>
-<h1 id="stable-releases">Stable Releases</h1>
+<h1 id="stable-releases">Stable Releases<a class="headerlink"
href="#stable-releases" title="Permanent link">¶</a></h1>
<ul>
<li><a href="/javadoc/1.2.0/">1.2.0</a> </li>
<li><a href="/javadoc/1.1.0/">1.1.0</a> </li>
</ul>
-<h1 id="contribute">Contribute</h1>
+<h1 id="contribute">Contribute<a class="headerlink" href="#contribute"
title="Permanent link">¶</a></h1>
<p>If you would like to submit a javadoc patch through Jira, you can have a
look at the <a href="suggested-git-workflows.html">suggested approach</a>.</p>
-<h1 id="publish-procedure-for-committers-only">Publish procedure (for
committers only)</h1>
+<h1 id="publish-procedure-for-committers-only">Publish procedure (for
committers only)<a class="headerlink"
href="#publish-procedure-for-committers-only" title="Permanent
link">¶</a></h1>
<p>If you're a committer and want to publish the javadoc, you have do the
following steps:</p>
<p>Put the following information in your ~/.m2/settings.xml file</p>
<div class="codehilite"><pre><span class="nt"><server></span>
@@ -124,7 +135,7 @@ $ <span class="o">./</span><span class="
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
Modified: websites/staging/deltaspike/trunk/content/retired/jpa.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/retired/jpa.html (original)
+++ websites/staging/deltaspike/trunk/content/retired/jpa.html Sat Aug 1
21:44:56 2015
@@ -80,7 +80,18 @@
<div class="page-title">
<h1>JPA Module</h1>
</div>
- <div class="toc">
+ <style type="text/css">
+/* The following code is added by mdx_elementid.py
+ It was originally lifted from http://subversion.apache.org/style/site.css */
+/*
+ * Hide class="elementid-permalink", except when an enclosing heading
+ * has the :hover property.
+ */
+.headerlink, .elementid-permalink {
+ visibility: hidden;
+}
+h2:hover > .headerlink, h3:hover > .headerlink, h1:hover > .headerlink,
h6:hover > .headerlink, h4:hover > .headerlink, h5:hover > .headerlink,
dt:hover > .elementid-permalink { visibility: visible }</style>
+<div class="toc">
<ul>
<li><a href="#transactional">@Transactional</a></li>
<li><a href="#transactionscoped">@TransactionScoped</a></li>
@@ -89,7 +100,7 @@
</ul>
</div>
<hr />
-<h1 id="transactional">@Transactional</h1>
+<h1 id="transactional">@Transactional<a class="headerlink"
href="#transactional" title="Permanent link">¶</a></h1>
<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 <code>EntityManager</code> and it's needed to inject the
<code>EntityManager</code> in the bean which uses <code>@Transactional</code>.
As shown later on it's also possible to use multiple qualifiers for using
different <code>EntityManager</code>s.</p>
<p><strong>Hint:</strong>
@@ -357,7 +368,7 @@ The example afterwards shows how to chan
<p>The final transaction handling for all <code>EntityManager</code> s is also
done after the outermost transactional method if
<code>NestedTransactionBean</code> uses a different <code>EntityManager</code>.
So it's possible to catch an exception in
<code>FirstLevelTransactionBean</code> e.g. to try an optional path instead of
an immediate rollback.</p>
-<h1 id="transactionscoped">@TransactionScoped</h1>
+<h1 id="transactionscoped">@TransactionScoped<a class="headerlink"
href="#transactionscoped" title="Permanent link">¶</a></h1>
<p><code>@Transactional</code> also starts a context which is available as
long as the transaction started by <code>@Transactional</code>. Besides other
beans you can use this scope for the <code>EntityManager</code> itself. That
means the <code>EntityManager</code> will be closed after leaving the method
annotated with <code>@Transactional</code>.</p>
<p>Producer for the default EntityManager which should be used only for one
transaction:</p>
<div class="codehilite"><pre><span class="c1">//...</span>
@@ -385,7 +396,7 @@ So it's possible to catch an exception i
</pre></div>
-<h1 id="extended-persistence-contexts">Extended Persistence Contexts</h1>
+<h1 id="extended-persistence-contexts">Extended Persistence Contexts<a
class="headerlink" href="#extended-persistence-contexts" title="Permanent
link">¶</a></h1>
<p>Frameworks like MyFaces Orchestra provide a feature which allows keeping an
<code>EntityManager</code> across multiple requests. That means it isn't
required to call <code>EntityManager#merge</code> to add detached entities to
the context. However, several application architectures don't allow such an
approach (due to different reasons like scalability). In theory that sounds
nice and it works pretty well for small to medium sized projects esp. if an
application doesn't rely on session replication in clusters. That also means
that such an approach restricts your target environment from the very
beginning. One of the base problems is that an <code>EntityManager</code> isn't
serializable. Beans which are scoped in a normal-scoped CDI context have to be
serializable. So by default it isn't allowed by CDI to provide a
producer-method which exposes e.g. a conversation scoped
<code>EntityManager</code> as it is. We <strong>don't</strong> recommend to use
this approach and therefore it
isn't available out-of-the-box. However, if you really need this approach to
avoid calling <code>#merge</code> for your detached entities, it's pretty
simple to add this functionality.</p>
<p>Usage of a simple <code>ExtendedEntityManager</code></p>
<div class="codehilite"><pre><span class="nd">@Inject</span>
@@ -474,7 +485,7 @@ So it's possible to catch an exception i
<p>This approach just works if it <strong>doesn't come to
serialization</strong> of this wrapper e.g. in case of session-replication.
If those beans get serialized, you have to overcome this restriction by
storing the persistence-unit-name and recreate the <code>EntityManager</code>
via
<code>Persistence.createEntityManagerFactory(this.persistenceUnitName).createEntityManager();</code>
and sync it with the database before closing it on serialization.
Furthermore, you have to intercept some methods of the
<code>EntityManager</code> to merge detached entities automatically if those
entities get serialized as well. However, as mentioned before <strong>we don't
recommend</strong> such an approach.</p>
-<h1 id="jta-support">JTA Support</h1>
+<h1 id="jta-support">JTA Support<a class="headerlink" href="#jta-support"
title="Permanent link">¶</a></h1>
<p>Per default the transaction-type used by <code>@Transactional</code>is
'RESOURCE_LOCAL'. If you configure <code>transaction-type="JTA"</code>in the
persistence.xml, you have to enable an alternative
<code>TransactionStrategy</code> in the beans.xml which is called
<code>org.apache.deltaspike.jpa.impl.transaction.BeanManagedUserTransactionStrategy</code>.</p>
<div class="codehilite"><pre><span class="nt"><beans></span>
<span class="nt"><alternatives></span>
@@ -495,7 +506,7 @@ to /META-INF/apache-deltaspike.propertie
<hr>
<footer>
- <p>Copyright © 2011-2014 The Apache Software Foundation, Licensed
under the Apache License, Version 2.0.</p>
+ <p>Copyright © 2011-2015 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>
