deltaspike-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From t...@apache.org
Subject svn commit: r1597819 - /deltaspike/site/trunk/content/data.mdtext
Date Tue, 27 May 2014 16:37:52 GMT
Author: thug
Date: Tue May 27 16:37:51 2014
New Revision: 1597819

URL: http://svn.apache.org/r1597819
Log:
Updated docu for mapper and EntityManagerDelegate

Modified:
    deltaspike/site/trunk/content/data.mdtext

Modified: deltaspike/site/trunk/content/data.mdtext
URL: http://svn.apache.org/viewvc/deltaspike/site/trunk/content/data.mdtext?rev=1597819&r1=1597818&r2=1597819&view=diff
==============================================================================
--- deltaspike/site/trunk/content/data.mdtext (original)
+++ deltaspike/site/trunk/content/data.mdtext Tue May 27 16:37:51 2014
@@ -31,7 +31,7 @@ specific entities.
 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.
 
 The code sample below will give you a quick overview on the common usage scenarios of the
data module:
@@ -65,22 +65,22 @@ features are outlines in the following c
 
 ## Prerequisites
 
-The simplest way using the DeltaSpike data module is to run your application in a Java EE
container
+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.
 
 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.
+of the [javassist][1] library in your classpath.
 
 **CAUTION:**
 
-> Using DeltaSpike data in an EAR deployment is currently restricted to annotation-based
entities.
+> Using DeltaSpike Data in an EAR deployment is currently restricted to annotation-based
entities.
 
 
 ## Maven Dependency Configuration
 
-If you are using Maven as your build tool, you can add the following dependencies to your
+pom.xml+
+If you are using Maven as your build tool, you can add the following dependencies to your
`pom.xml`
 file to include the DeltaSpike data module:
 
     <dependency>
@@ -107,7 +107,7 @@ inadvertantly depending on an implementa
 
 ## Setup your application
 
-DeltaSpike data requires an `EntityManager` exposed via a CDI producer - which is common
practice
+DeltaSpike Data requires an `EntityManager` exposed via a CDI producer - which is common
practice
 in Java EE 6 applications.
 
     :::java
@@ -153,7 +153,7 @@ You're now ready to use repositories in 
 
 ## Repositories
 
-With the DeltaSpike data module, it is possible to make a repository out of basically any
+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:
@@ -174,7 +174,7 @@ The `@Repository` annotation tells the e
 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.
+In order to simplify this, DeltaSpike Data provides several base types.
 
 ### The `EntityRepository` interface
 
@@ -244,8 +244,7 @@ when custom query logic needs also to be
     
         public Person findBySSN(String ssn)
         {
-            return getEntityManager()
-                    .createQuery("select p from Person p where p.ssn = ?1", Person.class)
+            return typedQuery("select p from Person p where p.ssn = ?1")
                     .setParameter(1, ssn)
                     .getResultList();
         }
@@ -282,6 +281,19 @@ where multiple data sources are used. Th
 Again, note that annotations on interfaces do not inherit, so it's not possible to create
something like a base
 `CrmRepository` interface with the `@EntityManagerConfig` and then extending / implementing
this interface.
 
+## Other `EntityManager` methods
+
+While the `EntityRepository` methods should cover most interactions normally done with an
`EntityManager`,
+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 `EntityManagerDelegate` interface for repositories,
which offers
+most other methods available in a JPA 2.0 `EntityManager`:
+
+    :::java
+    @Repository
+    public interface PersonRepository extends EntityRepository<Person, Long>, EntityManagerDelegate<Person>
+    {
+        ...
+    }
 
 # Query Method Expressions
 
@@ -318,7 +330,7 @@ Let's start by looking at a (simplified 
 
 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):
 
 
@@ -421,7 +433,7 @@ In case the `findBy` prefix does not com
 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.
+DeltaSpike Data module supports also annotating methods for more control on the generated
query.
 
 ## Using Query Annotations
 
@@ -663,7 +675,7 @@ This option will not throw an exception.
 
 If you call any method expression, `@Query`-annotated method or a method from the `EntityRepository`,
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 `TransactionStrategy` provided by the [JPA Module][1] for this.
See the JPA module
+The Data module uses the `TransactionStrategy` provided by the [JPA Module][2] for this.
See the JPA module
 documentation for more details.
 
 **CAUTION:**
@@ -841,6 +853,13 @@ can be subclassed, which only requires t
     :::java
     public class PersonMapper extends SimpleQueryInOutMapperBase<Person, PersonDto>
     {
+    
+        @Override
+        protected Object getPrimaryKey(PersonDto dto)
+        {
+            return dto.getId();
+        }
+    
         @Override
         protected PersonDto toDto(Person entity)
         {
@@ -848,14 +867,21 @@ can be subclassed, which only requires t
         }
 
         @Override
-        protected Person toEntity(PersonDto dto) {
+        protected Person toEntity(Person entity, PersonDto dto) {
             ...
+            return entity;
         }
     }
 
+The first method, `getPrimaryKey`, 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
`toEntity` method,
+so the entity to be mapped is **attached to the persistence context**. 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).
+
 # JPA Criteria API Support
 
-Beside automatic query generation, the DeltaSpike data module also provides a DSL-like API
to create JPA 2 Criteria queries.
+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.
 
 **TIP:**
@@ -932,7 +958,7 @@ This creates a JPA TypedQuery object for
 
 ## Joins
 
-For simple cases, restricting on the repository entity only works out fine, but once the
data model
+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:
 
@@ -1173,4 +1199,5 @@ there must be a bean available of the ma
 > target entity.
 
 
-  [1]: http://deltaspike.apache.org/jpa "JPA module"
\ No newline at end of file
+  [1]: http://www.javassist.org
+  [2]: http://deltaspike.apache.org/jpa "JPA module"
\ No newline at end of file



Mime
View raw message