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
