Author: buildbot
Date: Tue May 27 16:37:58 2014
New Revision: 910124
Log:
Staging update by buildbot for deltaspike
Modified:
websites/staging/deltaspike/trunk/content/ (props changed)
websites/staging/deltaspike/trunk/content/data.html
Propchange: websites/staging/deltaspike/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue May 27 16:37:58 2014
@@ -1 +1 @@
-1597589
+1597819
Modified: websites/staging/deltaspike/trunk/content/data.html
==============================================================================
--- websites/staging/deltaspike/trunk/content/data.html (original)
+++ websites/staging/deltaspike/trunk/content/data.html Tue May 27 16:37:58 2014
@@ -94,6 +94,7 @@
</ul>
</li>
<li><a href="#using-multiple-entitymanager">Using Multiple
EntityManager</a></li>
+<li><a href="#other-entitymanager-methods">Other EntityManager methods</a></li>
</ul>
</li>
<li><a href="#query-method-expressions">Query Method Expressions</a><ul>
@@ -153,7 +154,7 @@ specific entities.</p>
<p>The DeltaSpike Data module is intended to help you simplifying your
repository layer.
While you will have complex queries in a repository requiring your full
attention,
there will also be many simple ones often requiring boilerplate code and
clutter.
-This is where the DeltaSpike data module will help you keeping your repository
lean so you
+This is where the DeltaSpike Data module will help you keeping your repository
lean so you
can focus on the though things.</p>
<p>The code sample below will give you a quick overview on the common usage
scenarios of the data module:</p>
<div class="codehilite"><pre><span class="nd">@Repository</span>
@@ -183,18 +184,18 @@ A client can declare a dependency to the
features are outlines in the following chapters.</p>
<h1 id="installation">Installation</h1>
<h2 id="prerequisites">Prerequisites</h2>
-<p>The simplest way using the DeltaSpike data module is to run your
application in a Java EE container
+<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
to your application manually.</p>
<p>Also note that in order to use abstract classes as repositories, this
currently requires the presence
-of the http://www.javassist.org[javassist] library in your classpath.</p>
+of the <a href="http://www.javassist.org";>javassist</a> library in your
classpath.</p>
<p><strong>CAUTION:</strong></p>
<blockquote>
-<p>Using DeltaSpike data in an EAR deployment is currently restricted to
annotation-based entities.</p>
+<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>
-<p>If you are using Maven as your build tool, you can add the following
dependencies to your +pom.xml+
+<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>
<span class="nt"><groupId></span>org.apache.deltaspike.modules<span
class="nt"></groupId></span>
@@ -220,7 +221,7 @@ substitution so you can centrally manage
<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>
-<p>DeltaSpike data requires an <code>EntityManager</code> exposed via a CDI
producer - which is common practice
+<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>
<span class="o">{</span>
@@ -262,7 +263,7 @@ 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>
-<p>With the DeltaSpike data module, it is possible to make a repository out of
basically any
+<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
simple annotation:</p>
@@ -282,7 +283,7 @@ simple annotation:</p>
Any method defined on the repository will be processed by the framework. The
annotation does not
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>
+In order to simplify this, DeltaSpike Data provides several base types.</p>
<h3 id="the-entityrepository-interface">The <code>EntityRepository</code>
interface</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,
@@ -345,8 +346,7 @@ when custom query logic needs also to be
<span class="kd">public</span> <span class="n">Person</span> <span
class="nf">findBySSN</span><span class="o">(</span><span
class="n">String</span> <span class="n">ssn</span><span class="o">)</span>
<span class="o">{</span>
- <span class="k">return</span> <span
class="nf">getEntityManager</span><span class="o">()</span>
- <span class="o">.</span><span
class="na">createQuery</span><span class="o">(</span><span
class="s">"select p from Person p where p.ssn = ?1"</span><span
class="o">,</span> <span class="n">Person</span><span class="o">.</span><span
class="na">class</span><span class="o">)</span>
+ <span class="k">return</span> <span class="nf">typedQuery</span><span
class="o">(</span><span class="s">"select p from Person p where p.ssn =
?1"</span><span class="o">)</span>
<span class="o">.</span><span
class="na">setParameter</span><span class="o">(</span><span
class="mi">1</span><span class="o">,</span> <span class="n">ssn</span><span
class="o">)</span>
<span class="o">.</span><span
class="na">getResultList</span><span class="o">();</span>
<span class="o">}</span>
@@ -381,6 +381,19 @@ 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>
+<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
+most other methods available in a JPA 2.0 <code>EntityManager</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> <span
class="n">EntityManagerDelegate</span><span class="o"><</span><span
class="n">Person</span><span class="o">></span>
+<span class="o">{</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+
+
<h1 id="query-method-expressions">Query Method Expressions</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
@@ -412,7 +425,7 @@ method name is actually the implementati
<p>Looking at the method name, this can easily be read as query all Persons
which have a name like
the given name parameter, their age is between a min and a max age and having
a specific gender.
-The DeltaSpike module can translate method names following a given format and
directly generate
+The DeltaSpike Data module can translate method names following a given format
and directly generate
the query implementation out of it (in EBNF-like form):</p>
<div class="codehilite"><pre><span class="p">(</span><span
class="n">Entity</span><span class="o">|</span><span class="n">List</span><span
class="o"><</span><span class="n">Entity</span><span
class="o">></span><span class="p">)</span> <span
class="n">findBy</span><span class="p">(</span><span
class="n">Property</span><span class="p">[</span><span
class="n">Comparator</span><span class="p">]){</span><span
class="n">Operator</span> <span class="n">Property</span> <span
class="p">[</span><span class="n">Comparator</span><span class="p">]}</span>
</pre></div>
@@ -507,7 +520,7 @@ you can change the first result as well
<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>
+DeltaSpike Data module supports also annotating methods for more control on
the generated query.</p>
<h2 id="using-query-annotations">Using Query Annotations</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>
@@ -891,6 +904,13 @@ parameter to <code>Person</code> entity
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>
<span class="o">{</span>
+
+ <span class="nd">@Override</span>
+ <span class="kd">protected</span> <span class="n">Object</span> <span
class="nf">getPrimaryKey</span><span class="o">(</span><span
class="n">PersonDto</span> <span class="n">dto</span><span class="o">)</span>
+ <span class="o">{</span>
+ <span class="k">return</span> <span class="n">dto</span><span
class="o">.</span><span class="na">getId</span><span class="o">();</span>
+ <span class="o">}</span>
+
<span class="nd">@Override</span>
<span class="kd">protected</span> <span class="n">PersonDto</span> <span
class="nf">toDto</span><span class="o">(</span><span class="n">Person</span>
<span class="n">entity</span><span class="o">)</span>
<span class="o">{</span>
@@ -898,15 +918,21 @@ can be subclassed, which only requires t
<span class="o">}</span>
<span class="nd">@Override</span>
- <span class="kd">protected</span> <span class="n">Person</span> <span
class="nf">toEntity</span><span class="o">(</span><span
class="n">PersonDto</span> <span class="n">dto</span><span class="o">)</span>
<span class="o">{</span>
+ <span class="kd">protected</span> <span class="n">Person</span> <span
class="nf">toEntity</span><span class="o">(</span><span class="n">Person</span>
<span class="n">entity</span><span class="o">,</span> <span
class="n">PersonDto</span> <span class="n">dto</span><span class="o">)</span>
<span class="o">{</span>
<span class="o">...</span>
+ <span class="k">return</span> <span class="n">entity</span><span
class="o">;</span>
<span class="o">}</span>
<span class="o">}</span>
</pre></div>
+<p>The first method, <code>getPrimaryKey</code>, identifies the primary key of
an incoming DTO (this might need mapping too).
+If there is a primary key in the DTO, Data tries to retrieve the Entity and
feed it to the <code>toEntity</code> method,
+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>
-<p>Beside automatic query generation, the DeltaSpike data module also provides
a DSL-like API to create JPA 2 Criteria queries.
+<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>
<blockquote>
@@ -976,7 +1002,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>
-<p>For simple cases, restricting on the repository entity only works out fine,
but once the data model
+<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>
<div class="codehilite"><pre><span class="nd">@Repository</span>
