deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r910124 - in /websites/staging/deltaspike/trunk/content: ./ data.html
Date Tue, 27 May 2014 16:37:58 GMT
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">&lt;dependency&gt;</span>
     <span class="nt">&lt;groupId&gt;</span>org.apache.deltaspike.modules<span
class="nt">&lt;/groupId&gt;</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">&quot;select p from Person p where p.ssn
= ?1&quot;</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">&quot;select p from Person p where p.ssn
= ?1&quot;</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">&lt;</span><span
class="n">Person</span><span class="o">,</span> <span class="n">Long</span><span
class="o">&gt;,</span> <span class="n">EntityManagerDelegate</span><span
class="o">&lt;</span><span class="n">Person</span><span class="o">&gt;</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">&lt;</span><span
class="n">Entity</span><span class="o">&gt;</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">&lt;</span><span class="n">Person</span><span class="o">,</span>
<span class="n">PersonDto</span><span class="o">&gt;</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>



Mime
View raw message