© 2008-2022 The original authors.
Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically. |
1. Preface
Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources.
1.1. Project Metadata
-
Version control: https://github.com/spring-projects/spring-data-jpa
-
Bugtracker: https://github.com/spring-projects/spring-data-jpa/issues
-
Release repository: https://repo.spring.io/libs-release
-
Milestone repository: https://repo.spring.io/libs-milestone
-
Snapshot repository: https://repo.spring.io/libs-snapshot
2. New & Noteworthy
2.1. What’s New in Spring Data JPA 2.5
There is a new getById
method in the JpaRepository
which will replace getOne
, which is now deprecated.
Since this method returns a reference this changes the behaviour of an existing getById
method which before was implemented by query derivation.
This in turn might lead to an unexpected LazyLoadingException
when accessing attributes of that reference outside a transaction.
To avoid this please rename your existing getById
method to getXyzById
with Xyz
being an arbitrary string.
2.2. What’s New in Spring Data JPA 1.11
Spring Data JPA 1.11 added the following features:
-
Improved compatibility with Hibernate 5.2.
-
Support any-match mode for [query-by-example].
-
Paged query optimizations.
-
Support for the
exists
projection in repository query derivation.
2.3. What’s New in Spring Data JPA 1.10
Spring Data JPA 1.10 added the following features:
-
Support for [projections] in repository query methods.
-
Support for [query-by-example].
-
The following annotations have been enabled to build on composed annotations:
@EntityGraph
,@Lock
,@Modifying
,@Query
,@QueryHints
, and@Procedure
. -
Support for the
Contains
keyword on collection expressions. -
AttributeConverter
implementations forZoneId
of JSR-310 and ThreeTenBP. -
Upgrade to Querydsl 4, Hibernate 5, OpenJPA 2.4, and EclipseLink 2.6.1.
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/dependencies.adoc[leveloffset=+1]
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repositories.adoc[leveloffset=+1]
3. Reference Documentation
3.1. JPA Repositories
This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in “[repositories]”. Make sure you have a sound understanding of the basic concepts explained there.
3.1.1. Introduction
This section describes the basics of configuring Spring Data JPA through either:
-
“Spring Namespace” (XML configuration)
-
“Annotation-based Configuration” (Java configuration)
Spring Namespace
The JPA module of Spring Data contains a custom namespace that allows defining repository beans. It also contains certain features and element attributes that are special to JPA. Generally, the JPA repositories can be set up by using the repositories
element, as shown in the following example:
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jpa="http://www.springframework.org/schema/data/jpa"
xsi:schemaLocation="http://www.springframework.org/schema/beans
https://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/data/jpa
https://www.springframework.org/schema/data/jpa/spring-jpa.xsd">
<jpa:repositories base-package="com.acme.repositories" />
</beans>
Using the repositories
element looks up Spring Data repositories as described in “[repositories.create-instances]”. Beyond that, it activates persistence exception translation for all beans annotated with @Repository
, to let exceptions being thrown by the JPA persistence providers be converted into Spring’s DataAccessException
hierarchy.
Custom Namespace Attributes
Beyond the default attributes of the repositories
element, the JPA namespace offers additional attributes to let you gain more detailed control over the setup of the repositories:
|
Explicitly wire the |
|
Explicitly wire the |
Spring Data JPA requires a PlatformTransactionManager bean named transactionManager to be present if no explicit transaction-manager-ref is defined.
|
Annotation-based Configuration
The Spring Data JPA repositories support can be activated not only through an XML namespace but also by using an annotation through JavaConfig, as shown in the following example:
@Configuration
@EnableJpaRepositories
@EnableTransactionManagement
class ApplicationConfig {
@Bean
public DataSource dataSource() {
EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
return builder.setType(EmbeddedDatabaseType.HSQL).build();
}
@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
vendorAdapter.setGenerateDdl(true);
LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
factory.setJpaVendorAdapter(vendorAdapter);
factory.setPackagesToScan("com.acme.domain");
factory.setDataSource(dataSource());
return factory;
}
@Bean
public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
JpaTransactionManager txManager = new JpaTransactionManager();
txManager.setEntityManagerFactory(entityManagerFactory);
return txManager;
}
}
You must create LocalContainerEntityManagerFactoryBean and not EntityManagerFactory directly, since the former also participates in exception translation mechanisms in addition to creating EntityManagerFactory .
|
The preceding configuration class sets up an embedded HSQL database by using the EmbeddedDatabaseBuilder
API of spring-jdbc
. Spring Data then sets up an EntityManagerFactory
and uses Hibernate as the sample persistence provider. The last infrastructure component declared here is the JpaTransactionManager
. Finally, the example activates Spring Data JPA repositories by using the @EnableJpaRepositories
annotation, which essentially carries the same attributes as the XML namespace. If no base package is configured, it uses the one in which the configuration class resides.
Bootstrap Mode
By default, Spring Data JPA repositories are default Spring beans.
They are singleton scoped and eagerly initialized.
During startup, they already interact with the JPA EntityManager
for verification and metadata analysis purposes.
Spring Framework supports the initialization of the JPA EntityManagerFactory
in a background thread because that process usually takes up a significant amount of startup time in a Spring application.
To make use of that background initialization effectively, we need to make sure that JPA repositories are initialized as late as possible.
As of Spring Data JPA 2.1 you can now configure a BootstrapMode
(either via the @EnableJpaRepositories
annotation or the XML namespace) that takes the following values:
-
DEFAULT
(default) — Repositories are instantiated eagerly unless explicitly annotated with@Lazy
. The lazification only has effect if no client bean needs an instance of the repository as that will require the initialization of the repository bean. -
LAZY
— Implicitly declares all repository beans lazy and also causes lazy initialization proxies to be created to be injected into client beans. That means, that repositories will not get instantiated if the client bean is simply storing the instance in a field and not making use of the repository during initialization. Repository instances will be initialized and verified upon first interaction with the repository. -
DEFERRED
— Fundamentally the same mode of operation asLAZY
, but triggering repository initialization in response to anContextRefreshedEvent
so that repositories are verified before the application has completely started.
Recommendations
If you’re not using asynchronous JPA bootstrap stick with the default bootstrap mode.
In case you bootstrap JPA asynchronously, DEFERRED
is a reasonable default as it will make sure the Spring Data JPA bootstrap only waits for the EntityManagerFactory
setup if that itself takes longer than initializing all other application components.
Still, it makes sure that repositories are properly initialized and validated before the application signals it’s up.
LAZY
is a decent choice for testing scenarios and local development.
Once you are pretty sure that repositories can properly bootstrap, or in cases where you are testing other parts of the application, running verification for all repositories might unnecessarily increase the startup time.
The same applies to local development in which you only access parts of the application that might need to have a single repository initialized.
3.1.2. Persisting Entities
This section describes how to persist (save) entities with Spring Data JPA.
Saving Entities
Saving an entity can be performed with the CrudRepository.save(…)
method. It persists or merges the given entity by using the underlying JPA EntityManager
. If the entity has not yet been persisted, Spring Data JPA saves the entity with a call to the entityManager.persist(…)
method. Otherwise, it calls the entityManager.merge(…)
method.
Entity State-detection Strategies
Spring Data JPA offers the following strategies to detect whether an entity is new or not:
-
Version-Property and Id-Property inspection (default): By default Spring Data JPA inspects first if there is a Version-property of non-primitive type. If there is, the entity is considered new if the value of that property is
null
. Without such a Version-property Spring Data JPA inspects the identifier property of the given entity. If the identifier property isnull
, then the entity is assumed to be new. Otherwise, it is assumed to be not new. -
Implementing
Persistable
: If an entity implementsPersistable
, Spring Data JPA delegates the new detection to theisNew(…)
method of the entity. See the JavaDoc for details. -
Implementing
EntityInformation
: You can customize theEntityInformation
abstraction used in theSimpleJpaRepository
implementation by creating a subclass ofJpaRepositoryFactory
and overriding thegetEntityInformation(…)
method accordingly. You then have to register the custom implementation ofJpaRepositoryFactory
as a Spring bean. Note that this should be rarely necessary. See the JavaDoc for details.
Option 1 is not an option for entities that use manually assigned identifiers and no version attribute as with those the identifier will always be non-null
.
A common pattern in that scenario is to use a common base class with a transient flag defaulting to indicate a new instance and using JPA lifecycle callbacks to flip that flag on persistence operations:
@MappedSuperclass
public abstract class AbstractEntity<ID> implements Persistable<ID> {
@Transient
private boolean isNew = true; (1)
@Override
public boolean isNew() {
return isNew; (2)
}
@PrePersist (3)
@PostLoad
void markNotNew() {
this.isNew = false;
}
// More code…
}
1 | Declare a flag to hold the new state. Transient so that it’s not persisted to the database. |
2 | Return the flag in the implementation of Persistable.isNew() so that Spring Data repositories know whether to call EntityManager.persist() or ….merge() . |
3 | Declare a method using JPA entity callbacks so that the flag is switched to indicate an existing entity after a repository call to save(…) or an instance creation by the persistence provider. |
3.1.3. Query Methods
This section describes the various ways to create a query with Spring Data JPA.
Query Lookup Strategies
The JPA module supports defining a query manually as a String or having it being derived from the method name.
Derived queries with the predicates IsStartingWith
, StartingWith
, StartsWith
, IsEndingWith
, EndingWith
, EndsWith
,
IsNotContaining
, NotContaining
, NotContains
, IsContaining
, Containing
, Contains
the respective arguments for these queries will get sanitized.
This means if the arguments actually contain characters recognized by LIKE
as wildcards these will get escaped so they match only as literals.
The escape character used can be configured by setting the escapeCharacter
of the @EnableJpaRepositories
annotation.
Compare with Using SpEL Expressions.
Declared Queries
Although getting a query derived from the method name is quite convenient, one might face the situation in which either the method name parser does not support the keyword one wants to use or the method name would get unnecessarily ugly. So you can either use JPA named queries through a naming convention (see Using JPA Named Queries for more information) or rather annotate your query method with @Query
(see Using @Query
for details).
Query Creation
Generally, the query creation mechanism for JPA works as described in “[repositories.query-methods]”. The following example shows what a JPA query method translates into:
public interface UserRepository extends Repository<User, Long> { List<User> findByEmailAddressAndLastname(String emailAddress, String lastname); }
We create a query using the JPA criteria API from this, but, essentially, this translates into the following query: select u from User u where u.emailAddress = ?1 and u.lastname = ?2
. Spring Data JPA does a property check and traverses nested properties, as described in “[repositories.query-methods.query-property-expressions]”.
The following table describes the keywords supported for JPA and what a method containing that keyword translates to:
Keyword | Sample | JPQL snippet |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
In and NotIn also take any subclass of Collection as a parameter as well as arrays or varargs. For other syntactical versions of the same logical operator, check “[repository-query-keywords]”.
|
However, that latter query would narrow the focus to just
What is the point of this query anyway? To find the number of people with a given last name? To find the number of distinct people with that binding last name?
To find the number of distinct last names? (That last one is an entirely different query!)
Using |
Using JPA Named Queries
The examples use the <named-query /> element and @NamedQuery annotation. The queries for these configuration elements have to be defined in the JPA query language. Of course, you can use <named-native-query /> or @NamedNativeQuery too. These elements let you define the query in native SQL by losing the database platform independence.
|
XML Named Query Definition
To use XML configuration, add the necessary <named-query />
element to the orm.xml
JPA configuration file located in the META-INF
folder of your classpath. Automatic invocation of named queries is enabled by using some defined naming convention. For more details, see below.
<named-query name="User.findByLastname">
<query>select u from User u where u.lastname = ?1</query>
</named-query>
The query has a special name that is used to resolve it at runtime.
Annotation-based Configuration
Annotation-based configuration has the advantage of not needing another configuration file to be edited, lowering maintenance effort. You pay for that benefit by the need to recompile your domain class for every new query declaration.
@Entity
@NamedQuery(name = "User.findByEmailAddress",
query = "select u from User u where u.emailAddress = ?1")
public class User {
}
Declaring Interfaces
To allow these named queries, specify the UserRepositoryWithRewriter
as follows:
public interface UserRepository extends JpaRepository<User, Long> {
List<User> findByLastname(String lastname);
User findByEmailAddress(String emailAddress);
}
Spring Data tries 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 preceding example would use the named queries defined earlier instead of trying to create a query from the method name.
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 runs them, you can actually bind them directly by using the Spring Data JPA @Query
annotation rather than annotating them to the domain class. This frees the domain class from persistence specific information and co-locates the query to the repository interface.
Queries annotated to the query method take precedence over queries defined using @NamedQuery
or named queries declared in orm.xml
.
The following example shows a query created with the @Query
annotation:
@Query
public interface UserRepository extends JpaRepository<User, Long> {
@Query("select u from User u where u.emailAddress = ?1")
User findByEmailAddress(String emailAddress);
}
Applying a QueryRewriter
Sometimes, no matter how many features you try to apply, it seems impossible to get Spring Data JPA to apply every thing
you’d like to a query before it is sent to the EntityManager
.
You have the ability to get your hands on the query, right before it’s sent to the EntityManager
and "rewrite" it. That is,
you can make any alterations at the last moment.
@Query
public interface MyRepository extends JpaRepository<User, Long> {
@Query(value = "select original_user_alias.* from SD_USER original_user_alias",
nativeQuery = true,
queryRewriter = MyQueryRewriter.class)
List<User> findByNativeQuery(String param);
@Query(value = "select original_user_alias from User original_user_alias",
queryRewriter = MyQueryRewriter.class)
List<User> findByNonNativeQuery(String param);
}
This example shows both a native (pure SQL) rewriter as well as a JPQL query, both leveraging the same QueryRewriter
.
In this scenario, Spring Data JPA will look for a bean registered in the application context of the corresponding type.
You can write a query rewriter like this:
QueryRewriter
public class MyQueryRewriter implements QueryRewriter {
@Override
public String rewrite(String query, Sort sort) {
return query.replaceAll("original_user_alias", "rewritten_user_alias");
}
}
You have to ensure your QueryRewriter
is registered in the application context, whether it’s by applying one of Spring Framework’s
@Component
-based annotations, or having it as part of a @Bean
method inside an @Configuration
class.
Another option is to have the repository itself implement the interface.
QueryRewriter
public interface MyRepository extends JpaRepository<User, Long>, QueryRewriter {
@Query(value = "select original_user_alias.* from SD_USER original_user_alias",
nativeQuery = true,
queryRewriter = MyRepository.class)
List<User> findByNativeQuery(String param);
@Query(value = "select original_user_alias from User original_user_alias",
queryRewriter = MyRepository.class)
List<User> findByNonNativeQuery(String param);
@Override
default String rewrite(String query, Sort sort) {
return query.replaceAll("original_user_alias", "rewritten_user_alias");
}
}
Depending on what you’re doing with your QueryRewriter
, it may be advisable to have more than one, each registered with the
application context.
In a CDI-based environment, Spring Data JPA will search the BeanManager for instances of your implementation of
QueryRewriter .
|
Using Advanced LIKE
Expressions
The query running mechanism for manually defined queries created with @Query
allows the definition of advanced LIKE
expressions inside the query definition, as shown in the following example:
like
expressions in @Querypublic interface UserRepository extends JpaRepository<User, Long> {
@Query("select u from User u where u.firstname like %?1")
List<User> findByFirstnameEndsWith(String firstname);
}
In the preceding example, the LIKE
delimiter character (%
) is recognized, and the query is transformed into a valid JPQL query (removing the %
). Upon running the query, the parameter passed to the method call gets augmented with the previously recognized LIKE
pattern.
Native Queries
The @Query
annotation allows for running native queries by setting the nativeQuery
flag to true, as shown in the following example:
public interface UserRepository extends JpaRepository<User, Long> {
@Query(value = "SELECT * FROM USERS WHERE EMAIL_ADDRESS = ?1", nativeQuery = true)
User findByEmailAddress(String emailAddress);
}
Spring Data JPA does not currently support dynamic sorting for native queries, because it would have to manipulate the actual query declared, which it cannot do reliably for native SQL. You can, however, use native queries for pagination by specifying the count query yourself, as shown in the following example: |
@Query
public interface UserRepository extends JpaRepository<User, Long> {
@Query(value = "SELECT * FROM USERS WHERE LASTNAME = ?1",
countQuery = "SELECT count(*) FROM USERS WHERE LASTNAME = ?1",
nativeQuery = true)
Page<User> findByLastname(String lastname, Pageable pageable);
}
A similar approach also works with named native queries, by adding the .count
suffix to a copy of your query. You probably need to register a result set mapping for your count query, though.
Using Sort
Sorting can be done by either providing a PageRequest
or by using Sort
directly. The properties actually used within the Order
instances of Sort
need to match your domain model, which means they need to resolve to either a property or an alias used within the query. The JPQL defines this as a state field path expression.
Using any non-referenceable path expression leads to an Exception .
|
However, using Sort
together with @Query
lets you sneak in non-path-checked Order
instances containing functions within the ORDER BY
clause. This is possible because the Order
is appended to the given query string. By default, Spring Data JPA rejects any Order
instance containing function calls, but you can use JpaSort.unsafe
to add potentially unsafe ordering.
The following example uses Sort
and JpaSort
, including an unsafe option on JpaSort
:
Sort
and JpaSort
public interface UserRepository extends JpaRepository<User, Long> {
@Query("select u from User u where u.lastname like ?1%")
List<User> findByAndSort(String lastname, Sort sort);
@Query("select u.id, LENGTH(u.firstname) as fn_len from User u where u.lastname like ?1%")
List<Object[]> findByAsArrayAndSort(String lastname, Sort sort);
}
repo.findByAndSort("lannister", Sort.by("firstname")); (1)
repo.findByAndSort("stark", Sort.by("LENGTH(firstname)")); (2)
repo.findByAndSort("targaryen", JpaSort.unsafe("LENGTH(firstname)")); (3)
repo.findByAsArrayAndSort("bolton", Sort.by("fn_len")); (4)
1 | Valid Sort expression pointing to property in domain model. |
2 | Invalid Sort containing function call. Throws Exception. |
3 | Valid Sort containing explicitly unsafe Order . |
4 | Valid Sort expression pointing to aliased function. |
Using Named Parameters
By default, Spring Data JPA uses position-based parameter binding, as described in all the preceding examples. This makes query methods a little error-prone when 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, as shown in the following example:
public interface UserRepository extends JpaRepository<User, Long> {
@Query("select u from User u where u.firstname = :firstname or u.lastname = :lastname")
User findByLastnameOrFirstname(@Param("lastname") String lastname,
@Param("firstname") String firstname);
}
The method parameters are switched according to their order in the defined query. |
As of version 4, Spring fully supports Java 8’s parameter name discovery based on the -parameters compiler flag. By using this flag in your build as an alternative to debug information, you can omit the @Param annotation for named parameters.
|
Using SpEL Expressions
As of Spring Data JPA release 1.4, we support the usage of restricted SpEL template expressions in manually defined queries that are defined with @Query
. Upon the query being run, these expressions are evaluated against a predefined set of variables. Spring Data JPA supports a variable called entityName
. Its usage is select x from #{#entityName} x
. It inserts the entityName
of the domain type associated with the given repository. The entityName
is resolved as follows: If the domain type has set the name property on the @Entity
annotation, it is used. Otherwise, the simple class-name of the domain type is used.
The following example demonstrates one use case for the #{#entityName}
expression in a query string where you want to define a repository interface with a query method and a manually defined query:
@Entity
public class User {
@Id
@GeneratedValue
Long id;
String lastname;
}
public interface UserRepository extends JpaRepository<User,Long> {
@Query("select u from #{#entityName} u where u.lastname = ?1")
List<User> findByLastname(String lastname);
}
To avoid stating the actual entity name in the query string of a @Query
annotation, you can use the #{#entityName}
variable.
The entityName can be customized by using the @Entity annotation. Customizations in orm.xml are not supported for the SpEL expressions.
|
Of course, you could have just used User
in the query declaration directly, but that would require you to change the query as well. The reference to #entityName
picks up potential future remappings of the User
class to a different entity name (for example, by using @Entity(name = "MyUser")
.
Another use case for the #{#entityName}
expression in a query string is if you want to define a generic repository interface with specialized repository interfaces for a concrete domain type. To not repeat the definition of custom query methods on the concrete interfaces, you can use the entity name expression in the query string of the @Query
annotation in the generic repository interface, as shown in the following example:
@MappedSuperclass
public abstract class AbstractMappedType {
…
String attribute
}
@Entity
public class ConcreteType extends AbstractMappedType { … }
@NoRepositoryBean
public interface MappedTypeRepository<T extends AbstractMappedType>
extends Repository<T, Long> {
@Query("select t from #{#entityName} t where t.attribute = ?1")
List<T> findAllByAttribute(String attribute);
}
public interface ConcreteRepository
extends MappedTypeRepository<ConcreteType> { … }
In the preceding example, the MappedTypeRepository
interface is the common parent interface for a few domain types extending AbstractMappedType
. It also defines the generic findAllByAttribute(…)
method, which can be used on instances of the specialized repository interfaces. If you now invoke findByAllAttribute(…)
on ConcreteRepository
, the query becomes select t from ConcreteType t where t.attribute = ?1
.
SpEL expressions to manipulate arguments may also be used to manipulate method arguments. In these SpEL expressions the entity name is not available, but the arguments are. They can be accessed by name or index as demonstrated in the following example.
@Query("select u from User u where u.firstname = ?1 and u.firstname=?#{[0]} and u.emailAddress = ?#{principal.emailAddress}")
List<User> findByFirstnameAndCurrentUserWithCustomQuery(String firstname);
For like
-conditions one often wants to append %
to the beginning or the end of a String valued parameter.
This can be done by appending or prefixing a bind parameter marker or a SpEL expression with %
.
Again the following example demonstrates this.
@Query("select u from User u where u.lastname like %:#{[0]}% and u.lastname like %:lastname%")
List<User> findByLastnameWithSpelExpression(@Param("lastname") String lastname);
When using like
-conditions with values that are coming from a not secure source the values should be sanitized so they can’t contain any wildcards and thereby allow attackers to select more data than they should be able to.
For this purpose the escape(String)
method is made available in the SpEL context.
It prefixes all instances of _
and %
in the first argument with the single character from the second argument.
In combination with the escape
clause of the like
expression available in JPQL and standard SQL this allows easy cleaning of bind parameters.
@Query("select u from User u where u.firstname like %?#{escape([0])}% escape ?#{escapeCharacter()}")
List<User> findContainingEscaped(String namePart);
Given this method declaration in a repository interface findContainingEscaped("Peter_")
will find Peter_Parker
but not Peter Parker
.
The escape character used can be configured by setting the escapeCharacter
of the @EnableJpaRepositories
annotation.
Note that the method escape(String)
available in the SpEL context will only escape the SQL and JPQL standard wildcards _
and %
.
If the underlying database or the JPA implementation supports additional wildcards these will not get escaped.
Modifying Queries
All the previous sections describe how to declare queries to access a given entity or collection of entities.
You can add custom modifying behavior by using the custom method facilities described in “[repositories.custom-implementations]”.
As this approach is feasible for comprehensive custom functionality, you can modify queries that only need parameter binding by annotating the query method with @Modifying
, as shown in the following example:
@Modifying
@Query("update User u set u.firstname = ?1 where u.lastname = ?2")
int setFixedFirstnameFor(String firstname, String lastname);
Doing so triggers the query annotated to the method as an updating query instead of a selecting one. As the EntityManager
might contain outdated entities after the execution of the modifying query, we do not automatically clear it (see the JavaDoc of EntityManager.clear()
for details), since this effectively drops all non-flushed changes still pending in the EntityManager
.
If you wish the EntityManager
to be cleared automatically, you can set the @Modifying
annotation’s clearAutomatically
attribute to true
.
The @Modifying
annotation is only relevant in combination with the @Query
annotation.
Derived query methods or custom methods do not require this annotation.
Derived Delete Queries
Spring Data JPA also supports derived delete queries that let you avoid having to declare the JPQL query explicitly, as shown in the following example:
interface UserRepository extends Repository<User, Long> {
void deleteByRoleId(long roleId);
@Modifying
@Query("delete from User u where u.role.id = ?1")
void deleteInBulkByRoleId(long roleId);
}
Although the deleteByRoleId(…)
method looks like it basically produces the same result as the deleteInBulkByRoleId(…)
, there is an important difference between the two method declarations in terms of the way they are run.
As the name suggests, the latter method issues a single JPQL query (the one defined in the annotation) against the database.
This means even currently loaded instances of User
do not see lifecycle callbacks invoked.
To make sure lifecycle queries are actually invoked, an invocation of deleteByRoleId(…)
runs a query and then deletes the returned instances one by one, so that the persistence provider can actually invoke @PreRemove
callbacks on those entities.
In fact, a derived delete query is a shortcut for running the query and then calling CrudRepository.delete(Iterable<User> users)
on the result and keeping behavior in sync with the implementations of other delete(…)
methods in CrudRepository
.
Applying Query Hints
To apply JPA query hints to the queries declared in your repository interface, you can use the @QueryHints
annotation. It takes an array of JPA @QueryHint
annotations plus a boolean flag to potentially disable the hints applied to the additional count query triggered when applying pagination, as shown in the following example:
public interface UserRepository extends Repository<User, Long> {
@QueryHints(value = { @QueryHint(name = "name", value = "value")},
forCounting = false)
Page<User> findByLastname(String lastname, Pageable pageable);
}
The preceding declaration would apply the configured @QueryHint
for that actually query but omit applying it to the count query triggered to calculate the total number of pages.
Configuring Fetch- and LoadGraphs
The JPA 2.1 specification introduced support for specifying Fetch- and LoadGraphs that we also support with the @EntityGraph
annotation, which lets you reference a @NamedEntityGraph
definition. You can use that annotation on an entity to configure the fetch plan of the resulting query. The type (Fetch
or Load
) of the fetching can be configured by using the type
attribute on the @EntityGraph
annotation. See the JPA 2.1 Spec 3.7.4 for further reference.
The following example shows how to define a named entity graph on an entity:
@Entity
@NamedEntityGraph(name = "GroupInfo.detail",
attributeNodes = @NamedAttributeNode("members"))
public class GroupInfo {
// default fetch mode is lazy.
@ManyToMany
List<GroupMember> members = new ArrayList<GroupMember>();
…
}
The following example shows how to reference a named entity graph on a repository query method:
public interface GroupRepository extends CrudRepository<GroupInfo, String> {
@EntityGraph(value = "GroupInfo.detail", type = EntityGraphType.LOAD)
GroupInfo getByGroupName(String name);
}
It is also possible to define ad hoc entity graphs by using @EntityGraph
. The provided attributePaths
are translated into the according EntityGraph
without needing to explicitly add @NamedEntityGraph
to your domain types, as shown in the following example:
public interface GroupRepository extends CrudRepository<GroupInfo, String> {
@EntityGraph(attributePaths = { "members" })
GroupInfo getByGroupName(String name);
}
Unresolved directive in jpa.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repository-projections.adoc[leveloffset=+2]
3.1.4. Stored Procedures
The JPA 2.1 specification introduced support for calling stored procedures by using the JPA criteria query API.
We Introduced the @Procedure
annotation for declaring stored procedure metadata on a repository method.
The examples to follow use the following stored procedure:
plus1inout
procedure in HSQL DB./;
DROP procedure IF EXISTS plus1inout
/;
CREATE procedure plus1inout (IN arg int, OUT res int)
BEGIN ATOMIC
set res = arg + 1;
END
/;
Metadata for stored procedures can be configured by using the NamedStoredProcedureQuery
annotation on an entity type.
@Entity
@NamedStoredProcedureQuery(name = "User.plus1", procedureName = "plus1inout", parameters = {
@StoredProcedureParameter(mode = ParameterMode.IN, name = "arg", type = Integer.class),
@StoredProcedureParameter(mode = ParameterMode.OUT, name = "res", type = Integer.class) })
public class User {}
Note that @NamedStoredProcedureQuery
has two different names for the stored procedure.
name
is the name JPA uses. procedureName
is the name the stored procedure has in the database.
You can reference stored procedures from a repository method in multiple ways.
The stored procedure to be called can either be defined directly by using the value
or procedureName
attribute of the @Procedure
annotation.
This refers directly to the stored procedure in the database and ignores any configuration via @NamedStoredProcedureQuery
.
Alternatively you may specify the @NamedStoredProcedureQuery.name
attribute as the @Procedure.name
attribute.
If neither value
, procedureName
nor name
is configured, the name of the repository method is used as the name
attribute.
The following example shows how to reference an explicitly mapped procedure:
@Procedure("plus1inout")
Integer explicitlyNamedPlus1inout(Integer arg);
The following example is equivalent to the previous one but uses the procedureName
alias:
procedureName
alias.@Procedure(procedureName = "plus1inout")
Integer callPlus1InOut(Integer arg);
The following is again equivalent to the previous two but using the method name instead of an explicite annotation attribute.
EntityManager
by using the method name.@Procedure
Integer plus1inout(@Param("arg") Integer arg);
The following example shows how to reference a stored procedure by referencing the @NamedStoredProcedureQuery.name
attribute.
EntityManager
.@Procedure(name = "User.plus1IO")
Integer entityAnnotatedCustomNamedProcedurePlus1IO(@Param("arg") Integer arg);
If the stored procedure getting called has a single out parameter that parameter may be returned as the return value of the method.
If there are multiple out parameters specified in a @NamedStoredProcedureQuery
annotation those can be returned as a Map
with the key being the parameter name given in the @NamedStoredProcedureQuery
annotation.
3.1.5. Specifications
JPA 2 introduces a criteria API that you can use to build queries programmatically. By writing a criteria
, you define the where clause of a query for a domain class. Taking another step back, these criteria can be regarded as a 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 with the JPA criteria API. To support specifications, you can extend your repository interface with the JpaSpecificationExecutor
interface, as follows:
public interface CustomerRepository extends CrudRepository<Customer, Long>, JpaSpecificationExecutor<Customer> {
…
}
The additional interface has methods that let you run specifications in a variety of ways. For example, the findAll
method returns all entities that match the specification, as shown in the following example:
List<T> findAll(Specification<T> spec);
The Specification
interface is defined as follows:
public interface Specification<T> {
Predicate toPredicate(Root<T> root, CriteriaQuery<?> query,
CriteriaBuilder builder);
}
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, as shown in the following example:
public class CustomerSpecs {
public static Specification<Customer> isLongTermCustomer() {
return (root, query, builder) -> {
LocalDate date = LocalDate.now().minusYears(2);
return builder.lessThan(root.get(Customer_.createdAt), date);
};
}
public static Specification<Customer> hasSalesOfMoreThan(MonetaryAmount value) {
return (root, query, builder) -> {
// build query here
};
}
}
The Customer_
type is a metamodel type generated using the JPA Metamodel generator (see the Hibernate implementation’s documentation for an example).
So the expression, Customer_.createdAt
, assumes the Customer
has a createdAt
attribute of type Date
.
Besides that, we have expressed some criteria on a business requirement abstraction level and created executable Specifications
.
So a client might use a Specification
as follows:
List<Customer> customers = customerRepository.findAll(isLongTermCustomer());
Why not create a query for this kind of data access? Using a single Specification
does not gain a lot of benefit over a plain query declaration. The power of specifications really shines when you combine them to create new Specification
objects. You can achieve this through the default methods of Specification
we provide to build expressions similar to the following:
MonetaryAmount amount = new MonetaryAmount(200.0, Currencies.DOLLAR);
List<Customer> customers = customerRepository.findAll(
isLongTermCustomer().or(hasSalesOfMoreThan(amount)));
Specification
offers some “glue-code” default methods to chain and combine Specification
instances. These methods let you extend your data access layer by creating new Specification
implementations and combining them with already existing implementations.
And with JPA 2.1, the CriteriaBuilder
API introduced CriteriaDelete
. This is provided through JpaSpecificationExecutor’s `delete(Specification)
API.
Specification
to delete entries.Specification<User> ageLessThan18 = (root, query, cb) -> cb.lessThan(root.get("age").as(Integer.class), 18)
userRepository.delete(ageLessThan18);
The Specification
builds up a criteria where the age
field (cast as an integer) is less than 18
.
Passed on to the userRepository
, it will use JPA’s CriteriaDelete
feature to generate the right DELETE
operation.
It then returns the number of entities deleted.
Unresolved directive in jpa.adoc - include::../../../../spring-data-commons/src/main/asciidoc/query-by-example.adoc[leveloffset=+1] :leveloffset: +1
3.1.6. Running an Example
In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example:
public interface PersonRepository extends JpaRepository<Person, String> { … }
public class PersonService {
@Autowired PersonRepository personRepository;
public List<Person> findPeople(Person probe) {
return personRepository.findAll(Example.of(probe));
}
}
Currently, only SingularAttribute properties can be used for property matching.
|
The property specifier accepts property names (such as firstname
and lastname
). You can navigate by chaining properties together with dots (address.city
). You can also tune it with matching options and case sensitivity.
The following table shows the various StringMatcher
options that you can use and the result of using them on a field named firstname
:
Matching | Logical result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3.1.7. Transactionality
By default, CRUD methods on repository instances inherited from SimpleJpaRepository
are transactional.
For read operations, the transaction configuration readOnly
flag is set to true
.
All others are configured with a plain @Transactional
so that default transaction configuration applies.
Repository methods that are backed by transactional repository fragments inherit the transactional attributes from the actual fragment method.
If you need to tweak transaction configuration for one of the methods declared in a repository, redeclare the method in your repository interface, as follows:
public interface UserRepository extends CrudRepository<User, Long> {
@Override
@Transactional(timeout = 10)
public List<User> findAll();
// Further query method declarations
}
Doing so causes the findAll()
method to run with a timeout of 10 seconds and without the readOnly
flag.
Another way to alter transactional behaviour is to use a facade or service implementation that (typically) covers more than one repository. Its purpose is to define transactional boundaries for non-CRUD operations. The following example shows how to use such a facade for more than one repository:
@Service
public class UserManagementImpl implements UserManagement {
private final UserRepository userRepository;
private final RoleRepository roleRepository;
public UserManagementImpl(UserRepository userRepository,
RoleRepository roleRepository) {
this.userRepository = userRepository;
this.roleRepository = roleRepository;
}
@Transactional
public void addRoleToAllUsers(String roleName) {
Role role = roleRepository.findByName(roleName);
for (User user : userRepository.findAll()) {
user.addRole(role);
userRepository.save(user);
}
}
}
This example causes call to addRoleToAllUsers(…)
to run inside a transaction (participating in an existing one or creating a new one if none are already running). The transaction configuration at the repositories is then neglected, as the outer transaction configuration determines the actual one used. Note that you must activate <tx:annotation-driven />
or use @EnableTransactionManagement
explicitly to get annotation-based configuration of facades to work.
This example assumes you use component scanning.
Note that the call to save
is not strictly necessary from a JPA point of view, but should still be there in order to stay consistent to the repository abstraction offered by Spring Data.
Transactional query methods
To let your query methods be transactional, use @Transactional
at the repository interface you define, as shown in the following example:
@Transactional(readOnly = true)
interface UserRepository extends JpaRepository<User, Long> {
List<User> findByLastname(String lastname);
@Modifying
@Transactional
@Query("delete from User u where u.active = false")
void deleteInactiveUsers();
}
Typically, you want the readOnly
flag to be set to true
, as most of the query methods only read data. In contrast to that, deleteInactiveUsers()
makes use of the @Modifying
annotation and overrides the transaction configuration. Thus, the method runs with the readOnly
flag set to false
.
You can use transactions for read-only queries and mark them as such by setting the |
3.1.8. Locking
To specify the lock mode to be used, you can use the @Lock
annotation on query methods, as shown in the following example:
interface UserRepository extends Repository<User, Long> {
// Plain query method
@Lock(LockModeType.READ)
List<User> findByLastname(String lastname);
}
This method declaration causes the query being triggered to be equipped with a LockModeType
of READ
. You can also define locking for CRUD methods by redeclaring them in your repository interface and adding the @Lock
annotation, as shown in the following example:
interface UserRepository extends Repository<User, Long> {
// Redeclaration of a CRUD method
@Lock(LockModeType.READ)
List<User> findAll();
}
Unresolved directive in jpa.adoc - include::../../../../spring-data-commons/src/main/asciidoc/auditing.adoc[]
There is also a convenience base class, AbstractAuditable
, which you can extend to avoid the need to manually implement the interface methods. Doing so increases the coupling of your domain classes to Spring Data, which might be something you want to avoid. Usually, the annotation-based way of defining auditing metadata is preferred as it is less invasive and more flexible.
3.1.9. JPA Auditing
General Auditing Configuration
Spring Data JPA ships with an entity listener that can be used to trigger the capturing of auditing information. First, you must register the AuditingEntityListener
to be used for all entities in your persistence contexts inside your orm.xml
file, as shown in the following example:
<persistence-unit-metadata>
<persistence-unit-defaults>
<entity-listeners>
<entity-listener class="….data.jpa.domain.support.AuditingEntityListener" />
</entity-listeners>
</persistence-unit-defaults>
</persistence-unit-metadata>
You can also enable the AuditingEntityListener
on a per-entity basis by using the @EntityListeners
annotation, as follows:
@Entity
@EntityListeners(AuditingEntityListener.class)
public class MyEntity {
}
The auditing feature requires spring-aspects.jar to be on the classpath.
|
With orm.xml
suitably modified and spring-aspects.jar
on the classpath, activating auditing functionality is a matter of adding the Spring Data JPA auditing
namespace element to your configuration, as follows:
<jpa:auditing auditor-aware-ref="yourAuditorAwareBean" />
As of Spring Data JPA 1.5, you can enable auditing by annotating a configuration class with the @EnableJpaAuditing
annotation. You must still modify the orm.xml
file and have spring-aspects.jar
on the classpath. The following example shows how to use the @EnableJpaAuditing
annotation:
@Configuration
@EnableJpaAuditing
class Config {
@Bean
public AuditorAware<AuditableUser> auditorProvider() {
return new AuditorAwareImpl();
}
}
If you expose a bean of type AuditorAware
to the ApplicationContext
, the auditing infrastructure automatically picks it up and uses it to determine the current user to be set on domain types. If you have multiple implementations registered in the ApplicationContext
, you can select the one to be used by explicitly setting the auditorAwareRef
attribute of @EnableJpaAuditing
.
3.2. Miscellaneous Considerations
3.2.1. Using JpaContext
in Custom Implementations
When working with multiple EntityManager
instances and custom repository implementations, you need to wire the correct EntityManager
into the repository implementation class. You can do so by explicitly naming the EntityManager
in the @PersistenceContext
annotation or, if the EntityManager
is @Autowired
, by using @Qualifier
.
As of Spring Data JPA 1.9, Spring Data JPA includes a class called JpaContext
that lets you obtain the EntityManager
by managed domain class, assuming it is managed by only one of the EntityManager
instances in the application. The following example shows how to use JpaContext
in a custom repository:
JpaContext
in a custom repository implementationclass UserRepositoryImpl implements UserRepositoryCustom {
private final EntityManager em;
@Autowired
public UserRepositoryImpl(JpaContext context) {
this.em = context.getEntityManagerByManagedType(User.class);
}
…
}
The advantage of this approach is that, if the domain type gets assigned to a different persistence unit, the repository does not have to be touched to alter the reference to the persistence unit.
3.2.2. Merging persistence units
Spring supports having multiple persistence units. Sometimes, however, you might want to modularize your application but still make sure that all these modules run inside a single persistence unit. To enable that behavior, Spring Data JPA offers a PersistenceUnitManager
implementation that automatically merges persistence units based on their name, as shown in the following example:
<bean class="….LocalContainerEntityManagerFactoryBean">
<property name="persistenceUnitManager">
<bean class="….MergingPersistenceUnitManager" />
</property>
</bean>
Classpath Scanning for @Entity Classes and JPA Mapping Files
A plain JPA setup requires all annotation-mapped entity classes to be listed in orm.xml
. The same applies to XML mapping files. Spring Data JPA provides a ClasspathScanningPersistenceUnitPostProcessor
that gets a base package configured and optionally takes a mapping filename pattern. It then scans the given package for classes annotated with @Entity
or @MappedSuperclass
, loads the configuration files that match the filename pattern, and hands them to the JPA configuration. The post-processor must be configured as follows:
<bean class="….LocalContainerEntityManagerFactoryBean">
<property name="persistenceUnitPostProcessors">
<list>
<bean class="org.springframework.data.jpa.support.ClasspathScanningPersistenceUnitPostProcessor">
<constructor-arg value="com.acme.domain" />
<property name="mappingFileNamePattern" value="**/*Mapping.xml" />
</bean>
</list>
</property>
</bean>
As of Spring 3.1, a package to scan can be configured on the LocalContainerEntityManagerFactoryBean directly to enable classpath scanning for entity classes. See the JavaDoc for details.
|
3.2.3. CDI Integration
Instances of the repository interfaces are usually created by a container, for which Spring is the most natural choice when working with Spring Data. Spring offers sophisticated support for creating bean instances, as documented in [repositories.create-instances]. As of version 1.1.0, Spring Data JPA ships with a custom CDI extension that allows using the repository abstraction in CDI environments. The extension is part of the JAR. To activate it, include the Spring Data JPA JAR on your classpath.
You can now set up the infrastructure by implementing a CDI Producer for the EntityManagerFactory
and EntityManager
, as shown in the following example:
class EntityManagerFactoryProducer {
@Produces
@ApplicationScoped
public EntityManagerFactory createEntityManagerFactory() {
return Persistence.createEntityManagerFactory("my-persistence-unit");
}
public void close(@Disposes EntityManagerFactory entityManagerFactory) {
entityManagerFactory.close();
}
@Produces
@RequestScoped
public EntityManager createEntityManager(EntityManagerFactory entityManagerFactory) {
return entityManagerFactory.createEntityManager();
}
public void close(@Disposes EntityManager entityManager) {
entityManager.close();
}
}
The necessary setup can vary depending on the JavaEE environment. You may need to do nothing more than redeclare a EntityManager
as a CDI bean, as follows:
class CdiConfig {
@Produces
@RequestScoped
@PersistenceContext
public EntityManager entityManager;
}
In the preceding example, the container has to be capable of creating JPA EntityManagers
itself. All the configuration does is re-export the JPA EntityManager
as a CDI bean.
The Spring Data JPA CDI extension picks up all available EntityManager
instances as CDI beans and creates a proxy for a Spring Data repository whenever a bean of a repository type is requested by the container. Thus, obtaining an instance of a Spring Data repository is a matter of declaring an @Injected
property, as shown in the following example:
class RepositoryClient {
@Inject
PersonRepository repository;
public void businessMethod() {
List<Person> people = repository.findAll();
}
}
3.3. Spring Data Envers
3.3.1. What is Spring Data Envers?
Spring Data Envers makes typical Envers queries available in repositories for Spring Data JPA. It differs from other Spring Data modules in that it is always used in combination with another Spring Data Module: Spring Data JPA.
3.3.2. What is Envers?
Envers is a Hibernate module that adds auditing capabilities to JPA entities. This documentation assumes you are familiar with Envers, just as Spring Data Envers relies on Envers being properly configured.
3.3.3. Configuration
As a starting point for using Spring Data Envers, you need a project with Spring Data JPA on the classpath and an additional spring-data-envers
dependency:
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-envers</artifactId>
<version>3.0.0-M4</version>
</dependency>
</dependencies>
This also brings hibernate-envers
into the project as a transient dependency.
To enable Spring Data Envers and Spring Data JPA, we need to configure two beans and a special repositoryFactoryBeanClass
:
@Configuration
@EnableEnversRepositories
@EnableTransactionManagement
public class EnversDemoConfiguration {
@Bean
public DataSource dataSource() {
EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
return builder.setType(EmbeddedDatabaseType.HSQL).build();
}
@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
vendorAdapter.setGenerateDdl(true);
LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
factory.setJpaVendorAdapter(vendorAdapter);
factory.setPackagesToScan("example.springdata.jpa.envers");
factory.setDataSource(dataSource());
return factory;
}
@Bean
public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
JpaTransactionManager txManager = new JpaTransactionManager();
txManager.setEntityManagerFactory(entityManagerFactory);
return txManager;
}
}
To actually use Spring Data Envers, make one or more repositories into a {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[RevisionRepository
] by adding it as an extended interface:
interface PersonRepository
extends CrudRepository<Person, Long>,
RevisionRepository<Person, Long, Long> (1)
{}
1 | The first type parameter (Person ) denotes the entity type, the second (Long ) denotes the type of the id property, and the last one (Long ) is the type of the revision number.
For Envers in default configuration, the revision number parameter should be Integer or Long . |
The entity for that repository must be an entity with Envers auditing enabled (that is, it must have an @Audited
annotation):
@Entity
@Audited
class Person {
@Id @GeneratedValue
Long id;
String name;
@Version Long version;
}
3.3.4. Usage
You can now use the methods from RevisionRepository
to query the revisions of the entity, as the following test case shows:
@ExtendWith(SpringExtension.class)
@Import(EnversDemoConfiguration.class) (1)
class EnversIntegrationTests {
final PersonRepository repository;
final TransactionTemplate tx;
EnversIntegrationTests(@Autowired PersonRepository repository, @Autowired PlatformTransactionManager tm) {
this.repository = repository;
this.tx = new TransactionTemplate(tm);
}
@Test
void testRepository() {
Person updated = preparePersonHistory();
Revisions<Long, Person> revisions = repository.findRevisions(updated.id);
Iterator<Revision<Long, Person>> revisionIterator = revisions.iterator();
checkNextRevision(revisionIterator, "John", RevisionType.INSERT);
checkNextRevision(revisionIterator, "Jonny", RevisionType.UPDATE);
checkNextRevision(revisionIterator, null, RevisionType.DELETE);
assertThat(revisionIterator.hasNext()).isFalse();
}
/**
* Checks that the next element in the iterator is a Revision entry referencing a Person
* with the given name after whatever change brought that Revision into existence.
* <p>
* As a side effect the Iterator gets advanced by one element.
*
* @param revisionIterator the iterator to be tested.
* @param name the expected name of the Person referenced by the Revision.
* @param revisionType the type of the revision denoting if it represents an insert, update or delete.
*/
private void checkNextRevision(Iterator<Revision<Long, Person>> revisionIterator, String name,
RevisionType revisionType) {
assertThat(revisionIterator.hasNext()).isTrue();
Revision<Long, Person> revision = revisionIterator.next();
assertThat(revision.getEntity().name).isEqualTo(name);
assertThat(revision.getMetadata().getRevisionType()).isEqualTo(revisionType);
}
/**
* Creates a Person with a couple of changes so it has a non-trivial revision history.
* @return the created Person.
*/
private Person preparePersonHistory() {
Person john = new Person();
john.setName("John");
// create
Person saved = tx.execute(__ -> repository.save(john));
assertThat(saved).isNotNull();
saved.setName("Jonny");
// update
Person updated = tx.execute(__ -> repository.save(saved));
assertThat(updated).isNotNull();
// delete
tx.executeWithoutResult(__ -> repository.delete(updated));
return updated;
}
}
1 | This references the application context configuration presented earlier (in the Configuration section). |
3.3.5. Further Resources
You can download the Spring Data Envers example in the Spring Data Examples repository and play around with to get a feel for how the library works.
You should also check out the {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[Javadoc for RevisionRepository
] and related classes.
You can ask questions at Stackoverflow by using the spring-data-envers
tag.
4. Appendix
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repository-namespace-reference.adoc[leveloffset=+1]
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repository-populator-namespace-reference.adoc[leveloffset=+1]
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repository-query-keywords-reference.adoc[leveloffset=+1]
Unresolved directive in index.adoc - include::../../../../spring-data-commons/src/main/asciidoc/repository-query-return-types-reference.adoc[leveloffset=+1]
Appendix A: Frequently Asked Questions
Common
-
I’d like to get more detailed logging information on what methods are called inside
JpaRepository
for example. How can I gain them?You can make use of
CustomizableTraceInterceptor
provided by Spring, as shown in the following example:<bean id="customizableTraceInterceptor" class=" org.springframework.aop.interceptor.CustomizableTraceInterceptor"> <property name="enterMessage" value="Entering $[methodName]($[arguments])"/> <property name="exitMessage" value="Leaving $[methodName](): $[returnValue]"/> </bean> <aop:config> <aop:advisor advice-ref="customizableTraceInterceptor" pointcut="execution(public * org.springframework.data.jpa.repository.JpaRepository+.*(..))"/> </aop:config>
Infrastructure
-
Currently I have implemented a repository layer based on
HibernateDaoSupport
. I create aSessionFactory
by using Spring’sAnnotationSessionFactoryBean
. How do I get Spring Data repositories working in this environment?You have to replace
AnnotationSessionFactoryBean
with theHibernateJpaSessionFactoryBean
, as follows:Example 50. Looking up aSessionFactory
from aHibernateEntityManagerFactory
<bean id="sessionFactory" class="org.springframework.orm.jpa.vendor.HibernateJpaSessionFactoryBean"> <property name="entityManagerFactory" ref="entityManagerFactory"/> </bean>
Appendix B: Glossary
- AOP
-
Aspect oriented programming
- Commons DBCP
-
Commons DataBase Connection Pools - a library from the Apache foundation that offers pooling implementations of the DataSource interface.
- CRUD
-
Create, Read, Update, Delete - Basic persistence operations.
- DAO
-
Data Access Object - Pattern to separate persisting logic from the object to be persisted
- Dependency Injection
-
Pattern to hand a component’s dependency to the component from outside, freeing the component to lookup the dependent itself. For more information, see https://en.wikipedia.org/wiki/Dependency_Injection.
- EclipseLink
-
Object relational mapper implementing JPA - https://www.eclipse.org/eclipselink/
- Hibernate
-
Object relational mapper implementing JPA - https://hibernate.org/
- JPA
-
Jakarta Persistence API
- Spring
-
Java application framework - https://projects.spring.io/spring-framework