diff --git a/src/docbkx/reference/jpa.xml b/src/docbkx/reference/jpa.xml index f045c971b..c72e30edf 100644 --- a/src/docbkx/reference/jpa.xml +++ b/src/docbkx/reference/jpa.xml @@ -113,8 +113,8 @@ named queries through a naming convention (see for more information) or rather annotate your query method with - @Query (see - for details). + @Query (see for details). @@ -288,8 +288,8 @@ element and @NamedQuery annotation. The queries for these configuration elements have to be defined in JPA query language. Of course you can use <named-native-query /> or - @NamedNativeQuery too. These elements allow you to - define the query in native SQL by losing the database platform + @NamedNativeQuery too. These elements allow you to define + the query in native SQL by losing the database platform independence. @@ -318,10 +318,10 @@ Annotation configuration - Annotation configuration has the advantage of not needing another - configuration file to be edited, probably lowering maintenance costs. You pay - for that benefit by the need to recompile your domain class for every - new query declaration. + Annotation configuration has the advantage of not needing + another configuration file to be edited, probably lowering maintenance + costs. You pay for that benefit by the need to recompile your domain + class for every new query declaration. Annotation based named query configuration @@ -338,8 +338,8 @@ public class User { Declaring interfaces - To allow execution of these named queries all you need to do is to - specify the UserRepository as + To allow execution of these named queries all you need to do is + to specify the UserRepository as follows: @@ -353,11 +353,11 @@ public class User { } - Spring Data will try to resolve a call to these - methods to a named query, starting with the simple name of the - configured domain class, followed by the method name separated by a - dot. So the example here would use the named queries defined above - instead of trying to create a query from the method name. + Spring Data will try to resolve a call to these methods to a + named query, starting with the simple name of the configured domain + class, followed by the method name separated by a dot. So the example + here would use the named queries defined above instead of trying to + create a query from the method name. @@ -365,16 +365,16 @@ public class User { Using @Query Using named queries to declare queries for entities is a valid - approach and works fine for a small number of queries. As the - queries themselves are tied to the Java method that executes them you - actually can bind them directly using the Spring Data - JPA @Query annotation rather than annotating them to the - domain class. This will free the domain class from persistence specific - information and co-locate the query to the repository interface. + approach and works fine for a small number of queries. As the queries + themselves are tied to the Java method that executes them you actually + can bind them directly using the Spring Data JPA @Query + annotation rather than annotating them to the domain class. This will + free the domain class from persistence specific information and + co-locate the query to the repository interface. - Queries annotated to the query method will take precedence over queries defined - using @NamedQuery or named queries declared in - orm.xml. + Queries annotated to the query method will take precedence over + queries defined using @NamedQuery or named queries declared + in orm.xml. Declare query at the query method using @Query @@ -392,8 +392,8 @@ public class User { By default Spring Data JPA will use position based parameter binding as described in all the samples above. This makes query methods - a little error prone to refactoring regarding the parameter position. - To solve this issue you can use @Param annotation to give a + a little error prone to refactoring regarding the parameter position. To + solve this issue you can use @Param annotation to give a method parameter a concrete name and bind the name in the query: @@ -414,8 +414,8 @@ public class User {
Modifying queries - All the sections above describe how to declare queries to access - a given entity or collection of entities. Of course you can add custom + All the sections above describe how to declare queries to access a + given entity or collection of entities. Of course you can add custom modifying behaviour by using facilities described in . As this approach is feasible for comprehensive custom functionality, you can achieve the execution of @@ -450,31 +450,36 @@ int setFixedFirstnameFor(String firstname, String lastname); Specifications JPA 2 introduces a criteria API that can be used to build queries - programmatically. Writing a criteria you actually define the where-clause - of a query for a domain class. Taking another step - back these criteria can be regarded as predicate over the entity that is - described by the JPA criteria API constraints. + programmatically. Writing a criteria you actually define the + where-clause of a query for a domain class. Taking another step back these + criteria can be regarded as predicate over the entity that is described by + the JPA criteria API constraints. Spring Data JPA takes the concept of a specification from Eric Evans' book "Domain Driven Design", following the same semantics and providing an API to define such Specifications using the JPA criteria API. - To support specifications you can extend your repository interface with the - JpaSpecificationExecutor interface: + To support specifications you can extend your repository interface with + the JpaSpecificationExecutor + interface: public interface CustomerRepository extends CrudRepository<Customer, Long>, JpaSpecificationExecutor { … } - The additional interface carries methods that allow - you to execute Specifications in a variety - of ways. For example, the readAll method will return - all entities that match the specification: + The additional interface carries methods that allow you to execute + Specifications in a variety of ways. + + For example, the + + readAll + + method will return all entities that match the specification: List<T> readAll(Specification<T> spec); - The Specification interface is - as follows: + The Specification interface is as + follows: public interface Specification<T> { Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, @@ -485,8 +490,8 @@ int setFixedFirstnameFor(String firstname, String lastname); Specifications can easily be used to build an extensible set of predicates on top of an entity that then can be combined and used with JpaRepository - without the need to declare a query (method) for every needed - combination. Here's an example: + without the need to declare a query (method) for every needed combination. + Here's an example: Specifications for a Customer @@ -625,8 +630,8 @@ class UserManagementImpl implements UserManagement { will be neglected then as the outer transaction configuration determines the actual one used. Note that you will have to activate <tx:annotation-driven /> explicitly to get annotation - based configuration at facades working. The example above assumes you are - using component scanning. + based configuration at facades working. The example above assumes you + are using component scanning.
@@ -661,15 +666,17 @@ public interface UserRepository extends JpaRepository<User, Long> { It's definitely reasonable to use transactions for read only queries and we can mark them as such by setting the - readOnly flag. This will not, however, act as check that you do not - trigger a manipulating query (although some databases + readOnly flag. This will not, however, act as check that + you do not trigger a manipulating query (although some databases reject INSERT and UPDATE - statements inside a read only transaction). The readOnly flag instead is - propagated as hint to the underlying JDBC driver for performance - optimizations. Furthermore, Spring will perform some optimizations on the - underlying JPA provider. E.g. when used with Hibernate the flush mode - is set to NEVER when you configure a transaction as readOnly which - causes Hibernate to skip dirty checks (a noticeable improvement on large object trees). + statements inside a read only transaction). The readOnly + flag instead is propagated as hint to the underlying JDBC driver for + performance optimizations. Furthermore, Spring will perform some + optimizations on the underlying JPA provider. E.g. when used with + Hibernate the flush mode is set to NEVER when you + configure a transaction as readOnly which causes + Hibernate to skip dirty checks (a noticeable improvement on large + object trees).
@@ -677,11 +684,11 @@ public interface UserRepository extends JpaRepository<User, Long> {
Auditing - Most applications will require some form of auditability to track when - an entity was created or modified and by whom. - Spring Data JPA provides facilities to add this audit information to - an entity transparently by AOP means. To take part in this functionality your - domain classes must implement a more advanced interface: + Most applications will require some form of auditability to track + when an entity was created or modified and by whom. Spring Data JPA + provides facilities to add this audit information to an entity + transparently by AOP means. To take part in this functionality your domain + classes must implement a more advanced interface: <interfacename>Auditable</interfacename> interface @@ -778,10 +785,11 @@ public interface UserRepository extends JpaRepository<User, Long> { Merging persistence units Spring supports having multiple persistence units out of the box. - Sometimes, however, you might want to modularize your application but still make sure - that all these modules run inside a single persistence unit at runtime. - To do so Spring Data JPA offers a PersistenceUnitManager implementation - that automatically merges persistence units based on their name. + Sometimes, however, you might want to modularize your application but + still make sure that all these modules run inside a single persistence + unit at runtime. To do so Spring Data JPA offers a + PersistenceUnitManager implementation that automatically + merges persistence units based on their name. Using MergingPersistenceUnitmanager