Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 8219c96

Browse files
mp911demp911de
committedAug 23, 2023
Restructure content to include partials from Commons.
See #3080
1 parent 016be28 commit 8219c96

29 files changed

+286
-245
lines changed
 

‎src/main/antora/antora-playbook.yml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,11 @@ content:
1515
branches: HEAD
1616
start_path: src/main/antora
1717
worktrees: true
18+
- url: https://github.com/spring-projects/spring-data-commons
19+
# Refname matching:
20+
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
21+
branches: [main, 3.2.x]
22+
start_path: src/main/antora
1823
asciidoc:
1924
attributes:
2025
page-pagination: ''

‎src/main/antora/modules/ROOT/nav.adoc

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,33 @@
11
* xref:index.adoc[Overview]
2+
** xref:commons/upgrade.adoc[]
3+
* xref:repositories/introduction.adoc[]
4+
** xref:repositories/core-concepts.adoc[]
5+
** xref:repositories/definition.adoc[]
6+
** xref:repositories/create-instances.adoc[]
7+
** xref:repositories/query-methods-details.adoc[]
8+
** xref:repositories/custom-implementations.adoc[]
9+
** xref:repositories/core-domain-events.adoc[]
10+
** xref:repositories/core-extensions.adoc[]
11+
** xref:repositories/null-handling.adoc[]
12+
** xref:repositories/query-keywords-reference.adoc[]
13+
** xref:repositories/query-return-types-reference.adoc[]
214
* xref:jpa.adoc[]
3-
** xref:jpa/introduction.adoc[]
15+
** xref:jpa/configuration.adoc[]
416
** xref:jpa/entity-persistence.adoc[]
517
** xref:jpa/query-methods.adoc[]
618
** xref:jpa/stored-procedures.adoc[]
719
** xref:jpa/specifications.adoc[]
8-
** xref:jpa/query-by-example.adoc[]
20+
** xref:query-by-example.adoc[]
921
** xref:jpa/transactions.adoc[]
1022
** xref:jpa/locking.adoc[]
11-
** xref:jpa/auditing.adoc[]
23+
** xref:auditing.adoc[]
1224
** xref:jpa/misc-context.adoc[]
1325
** xref:jpa/misc-merging-persistence-units.adoc[]
1426
** xref:jpa/jpd-misc-cdi-integration.adoc[]
27+
** xref:jpa/faq.adoc[]
28+
** xref:jpa/glossary.adoc[]
1529
* xref:envers.adoc[]
16-
* xref:faq.adoc[]
17-
* xref:glossary.adoc[]
30+
** xref:envers/introduction.adoc[]
31+
** xref:envers/configuration.adoc[]
32+
** xref:envers/usage.adoc[]
33+
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

‎src/main/antora/modules/ROOT/pages/jpa/auditing.adoc renamed to ‎src/main/antora/modules/ROOT/pages/auditing.adoc

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
1-
[[jpa.auditing]]
2-
= JPA Auditing
3-
4-
Spring Data JPA provides auditing based upon the foundation provided by {spring-data-commons-docs-url}/auditing.html[Spring Data Common's Auditing support].
5-
1+
include::{commons}@data-commons::page$auditing.adoc[]
62

73
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.
84

‎src/main/antora/modules/ROOT/pages/commons/upgrade.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$upgrade.adoc[]

‎src/main/antora/modules/ROOT/pages/envers.adoc

Lines changed: 3 additions & 202 deletions
Original file line numberDiff line numberDiff line change
@@ -1,204 +1,5 @@
11
[[envers]]
2-
= Spring Data Envers
2+
= Envers
3+
:page-section-summary-toc: 1
34

4-
[[envers.what.is.spring.data]]
5-
== What is Spring Data Envers?
6-
7-
Spring Data Envers makes typical Envers queries available in repositories for Spring Data JPA.
8-
It differs from other Spring Data modules in that it is always used in combination with another Spring Data Module: Spring Data JPA.
9-
10-
[[envers.what]]
11-
== What is Envers?
12-
13-
Envers is a https://hibernate.org/orm/envers/[Hibernate module] that adds auditing capabilities to JPA entities.
14-
This documentation assumes you are familiar with Envers, just as Spring Data Envers relies on Envers being properly configured.
15-
16-
[[envers.configuration]]
17-
== Configuration
18-
19-
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:
20-
21-
====
22-
[source,xml,subs="+attributes"]
23-
----
24-
<dependencies>
25-
26-
<!-- other dependency elements omitted -->
27-
28-
<dependency>
29-
<groupId>org.springframework.data</groupId>
30-
<artifactId>spring-data-envers</artifactId>
31-
<version>{version}</version>
32-
</dependency>
33-
34-
</dependencies>
35-
----
36-
====
37-
38-
This also brings `hibernate-envers` into the project as a transient dependency.
39-
40-
To enable Spring Data Envers and Spring Data JPA, we need to configure two beans and a special `repositoryFactoryBeanClass`:
41-
42-
====
43-
[source,java]
44-
----
45-
@Configuration
46-
@EnableEnversRepositories
47-
@EnableTransactionManagement
48-
public class EnversDemoConfiguration {
49-
50-
@Bean
51-
public DataSource dataSource() {
52-
53-
EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
54-
return builder.setType(EmbeddedDatabaseType.HSQL).build();
55-
}
56-
57-
@Bean
58-
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
59-
60-
HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
61-
vendorAdapter.setGenerateDdl(true);
62-
63-
LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
64-
factory.setJpaVendorAdapter(vendorAdapter);
65-
factory.setPackagesToScan("example.springdata.jpa.envers");
66-
factory.setDataSource(dataSource());
67-
return factory;
68-
}
69-
70-
@Bean
71-
public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
72-
73-
JpaTransactionManager txManager = new JpaTransactionManager();
74-
txManager.setEntityManagerFactory(entityManagerFactory);
75-
return txManager;
76-
}
77-
}
78-
----
79-
====
80-
81-
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:
82-
83-
====
84-
[source,java]
85-
----
86-
interface PersonRepository
87-
extends CrudRepository<Person, Long>,
88-
RevisionRepository<Person, Long, Long> // <1>
89-
{}
90-
----
91-
<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.
92-
For Envers in default configuration, the revision number parameter should be `Integer` or `Long`.
93-
====
94-
95-
The entity for that repository must be an entity with Envers auditing enabled (that is, it must have an `@Audited` annotation):
96-
97-
====
98-
[source,java]
99-
----
100-
@Entity
101-
@Audited
102-
class Person {
103-
104-
@Id @GeneratedValue
105-
Long id;
106-
String name;
107-
@Version Long version;
108-
}
109-
----
110-
====
111-
112-
[[envers.usage]]
113-
== Usage
114-
115-
You can now use the methods from `RevisionRepository` to query the revisions of the entity, as the following test case shows:
116-
117-
====
118-
[source,java]
119-
----
120-
@ExtendWith(SpringExtension.class)
121-
@Import(EnversDemoConfiguration.class) // <1>
122-
class EnversIntegrationTests {
123-
124-
final PersonRepository repository;
125-
final TransactionTemplate tx;
126-
127-
EnversIntegrationTests(@Autowired PersonRepository repository, @Autowired PlatformTransactionManager tm) {
128-
this.repository = repository;
129-
this.tx = new TransactionTemplate(tm);
130-
}
131-
132-
@Test
133-
void testRepository() {
134-
135-
Person updated = preparePersonHistory();
136-
137-
Revisions<Long, Person> revisions = repository.findRevisions(updated.id);
138-
139-
Iterator<Revision<Long, Person>> revisionIterator = revisions.iterator();
140-
141-
checkNextRevision(revisionIterator, "John", RevisionType.INSERT);
142-
checkNextRevision(revisionIterator, "Jonny", RevisionType.UPDATE);
143-
checkNextRevision(revisionIterator, null, RevisionType.DELETE);
144-
assertThat(revisionIterator.hasNext()).isFalse();
145-
146-
}
147-
148-
/**
149-
* Checks that the next element in the iterator is a Revision entry referencing a Person
150-
* with the given name after whatever change brought that Revision into existence.
151-
* <p>
152-
* As a side effect the Iterator gets advanced by one element.
153-
*
154-
* @param revisionIterator the iterator to be tested.
155-
* @param name the expected name of the Person referenced by the Revision.
156-
* @param revisionType the type of the revision denoting if it represents an insert, update or delete.
157-
*/
158-
private void checkNextRevision(Iterator<Revision<Long, Person>> revisionIterator, String name,
159-
RevisionType revisionType) {
160-
161-
assertThat(revisionIterator.hasNext()).isTrue();
162-
Revision<Long, Person> revision = revisionIterator.next();
163-
assertThat(revision.getEntity().name).isEqualTo(name);
164-
assertThat(revision.getMetadata().getRevisionType()).isEqualTo(revisionType);
165-
}
166-
167-
/**
168-
* Creates a Person with a couple of changes so it has a non-trivial revision history.
169-
* @return the created Person.
170-
*/
171-
private Person preparePersonHistory() {
172-
173-
Person john = new Person();
174-
john.setName("John");
175-
176-
// create
177-
Person saved = tx.execute(__ -> repository.save(john));
178-
assertThat(saved).isNotNull();
179-
180-
saved.setName("Jonny");
181-
182-
// update
183-
Person updated = tx.execute(__ -> repository.save(saved));
184-
assertThat(updated).isNotNull();
185-
186-
// delete
187-
tx.executeWithoutResult(__ -> repository.delete(updated));
188-
return updated;
189-
}
190-
}
191-
----
192-
<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section).
193-
====
194-
195-
[[envers.resources]]
196-
== Further Resources
197-
198-
You can download the https://github.com/spring-projects/spring-data-examples[Spring Data Envers example in the Spring Data Examples repository] and play around with to get a feel for how the library works.
199-
200-
You should also check out the {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[Javadoc for `RevisionRepository`] and related classes.
201-
202-
You can ask questions at https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].
203-
204-
The https://github.com/spring-projects/spring-data-jpa[source code and issue tracker for Spring Data Envers is hosted at GitHub] (as a module of Spring Data JPA).
5+
This chapter points out the specialties for repository support for Envers. This builds on the core repository support explained earlier. Make sure you have a sound understanding of the basic concepts explained there.

‎src/main/antora/modules/ROOT/pages/envers/configuration.adoc

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
[[envers.configuration]]
2+
= Configuration
3+
4+
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:
5+
6+
====
7+
[source,xml,subs="+attributes"]
8+
----
9+
<dependencies>
10+
11+
<!-- other dependency elements omitted -->
12+
13+
<dependency>
14+
<groupId>org.springframework.data</groupId>
15+
<artifactId>spring-data-envers</artifactId>
16+
<version>{version}</version>
17+
</dependency>
18+
19+
</dependencies>
20+
----
21+
====
22+
23+
This also brings `hibernate-envers` into the project as a transient dependency.
24+
25+
To enable Spring Data Envers and Spring Data JPA, we need to configure two beans and a special `repositoryFactoryBeanClass`:
26+
27+
====
28+
[source,java]
29+
----
30+
@Configuration
31+
@EnableEnversRepositories
32+
@EnableTransactionManagement
33+
public class EnversDemoConfiguration {
34+
35+
@Bean
36+
public DataSource dataSource() {
37+
38+
EmbeddedDatabaseBuilder builder = new EmbeddedDatabaseBuilder();
39+
return builder.setType(EmbeddedDatabaseType.HSQL).build();
40+
}
41+
42+
@Bean
43+
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
44+
45+
HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
46+
vendorAdapter.setGenerateDdl(true);
47+
48+
LocalContainerEntityManagerFactoryBean factory = new LocalContainerEntityManagerFactoryBean();
49+
factory.setJpaVendorAdapter(vendorAdapter);
50+
factory.setPackagesToScan("example.springdata.jpa.envers");
51+
factory.setDataSource(dataSource());
52+
return factory;
53+
}
54+
55+
@Bean
56+
public PlatformTransactionManager transactionManager(EntityManagerFactory entityManagerFactory) {
57+
58+
JpaTransactionManager txManager = new JpaTransactionManager();
59+
txManager.setEntityManagerFactory(entityManagerFactory);
60+
return txManager;
61+
}
62+
}
63+
----
64+
====
65+
66+
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:
67+
68+
====
69+
[source,java]
70+
----
71+
interface PersonRepository
72+
extends CrudRepository<Person, Long>,
73+
RevisionRepository<Person, Long, Long> // <1>
74+
{}
75+
----
76+
<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.
77+
For Envers in default configuration, the revision number parameter should be `Integer` or `Long`.
78+
====
79+
80+
The entity for that repository must be an entity with Envers auditing enabled (that is, it must have an `@Audited` annotation):
81+
82+
====
83+
[source,java]
84+
----
85+
@Entity
86+
@Audited
87+
class Person {
88+
89+
@Id @GeneratedValue
90+
Long id;
91+
String name;
92+
@Version Long version;
93+
}
94+
----
95+
====

‎src/main/antora/modules/ROOT/pages/envers/introduction.adoc

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[[envers.introduction]]
2+
= Introduction
3+
4+
[[envers.what.is.spring.data]]
5+
== What is Spring Data Envers?
6+
7+
Spring Data Envers makes typical Envers queries available in repositories for Spring Data JPA.
8+
It differs from other Spring Data modules in that it is always used in combination with another Spring Data Module: Spring Data JPA.
9+
10+
[[envers.what]]
11+
== What is Envers?
12+
13+
Envers is a https://hibernate.org/orm/envers/[Hibernate module] that adds auditing capabilities to JPA entities.
14+
This documentation assumes you are familiar with Envers, just as Spring Data Envers relies on Envers being properly configured.

‎src/main/antora/modules/ROOT/pages/envers/usage.adoc

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
[[envers.usage]]
2+
= Usage
3+
4+
You can now use the methods from `RevisionRepository` to query the revisions of the entity, as the following test case shows:
5+
6+
====
7+
[source,java]
8+
----
9+
@ExtendWith(SpringExtension.class)
10+
@Import(EnversDemoConfiguration.class) // <1>
11+
class EnversIntegrationTests {
12+
13+
final PersonRepository repository;
14+
final TransactionTemplate tx;
15+
16+
EnversIntegrationTests(@Autowired PersonRepository repository, @Autowired PlatformTransactionManager tm) {
17+
this.repository = repository;
18+
this.tx = new TransactionTemplate(tm);
19+
}
20+
21+
@Test
22+
void testRepository() {
23+
24+
Person updated = preparePersonHistory();
25+
26+
Revisions<Long, Person> revisions = repository.findRevisions(updated.id);
27+
28+
Iterator<Revision<Long, Person>> revisionIterator = revisions.iterator();
29+
30+
checkNextRevision(revisionIterator, "John", RevisionType.INSERT);
31+
checkNextRevision(revisionIterator, "Jonny", RevisionType.UPDATE);
32+
checkNextRevision(revisionIterator, null, RevisionType.DELETE);
33+
assertThat(revisionIterator.hasNext()).isFalse();
34+
35+
}
36+
37+
/**
38+
* Checks that the next element in the iterator is a Revision entry referencing a Person
39+
* with the given name after whatever change brought that Revision into existence.
40+
* <p>
41+
* As a side effect the Iterator gets advanced by one element.
42+
*
43+
* @param revisionIterator the iterator to be tested.
44+
* @param name the expected name of the Person referenced by the Revision.
45+
* @param revisionType the type of the revision denoting if it represents an insert, update or delete.
46+
*/
47+
private void checkNextRevision(Iterator<Revision<Long, Person>> revisionIterator, String name,
48+
RevisionType revisionType) {
49+
50+
assertThat(revisionIterator.hasNext()).isTrue();
51+
Revision<Long, Person> revision = revisionIterator.next();
52+
assertThat(revision.getEntity().name).isEqualTo(name);
53+
assertThat(revision.getMetadata().getRevisionType()).isEqualTo(revisionType);
54+
}
55+
56+
/**
57+
* Creates a Person with a couple of changes so it has a non-trivial revision history.
58+
* @return the created Person.
59+
*/
60+
private Person preparePersonHistory() {
61+
62+
Person john = new Person();
63+
john.setName("John");
64+
65+
// create
66+
Person saved = tx.execute(__ -> repository.save(john));
67+
assertThat(saved).isNotNull();
68+
69+
saved.setName("Jonny");
70+
71+
// update
72+
Person updated = tx.execute(__ -> repository.save(saved));
73+
assertThat(updated).isNotNull();
74+
75+
// delete
76+
tx.executeWithoutResult(__ -> repository.delete(updated));
77+
return updated;
78+
}
79+
}
80+
----
81+
<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section).
82+
====
83+
84+
[[envers.resources]]
85+
== Further Resources
86+
87+
You can download the https://github.com/spring-projects/spring-data-examples[Spring Data Envers example in the Spring Data Examples repository] and play around with to get a feel for how the library works.
88+
89+
You should also check out the {spring-data-commons-javadoc-base}/org/springframework/data/repository/history/RevisionRepository.html[Javadoc for `RevisionRepository`] and related classes.
90+
91+
You can ask questions at https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].
92+
93+
The https://github.com/spring-projects/spring-data-jpa[source code and issue tracker for Spring Data Envers is hosted at GitHub] (as a module of Spring Data JPA).

‎src/main/antora/modules/ROOT/pages/index.adoc

Lines changed: 10 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,21 @@
11
[[spring-data-jpa-reference-documentation]]
22
= Spring Data JPA
3-
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist
43
:revnumber: {version}
54
:revdate: {localdate}
65
:feature-scroll: true
76

8-
(C) 2008-2023 The original authors.
7+
_Spring Data JPA provides repository support for the Jakarta Persistence API (JPA).
8+
It eases development of applications with a consistent programming model that need to access JPA data sources._
99

10-
NOTE: 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.
10+
[horizontal]
11+
xref:jpa.adoc[JPA] :: JPA and JPA Repositories
12+
xref:envers.adoc[Envers] :: Support for Envers Revision Repositories
13+
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New,
14+
Upgrade Notes, Supported Versions, additional cross-version information.
1115

12-
[[preface]]
13-
== Preface
14-
:page-section-summary-toc: 1
16+
Oliver Gierke, Thomas Darimont, Christoph Strobl, Mark Paluch, Jay Bryant, Greg Turnquist
1517

16-
Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources.
18+
(C) 2008-2023 VMware, Inc.
1719

18-
[[project]]
19-
== Project Metadata
20+
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.
2021

21-
* Version control: https://github.com/spring-projects/spring-data-jpa
22-
* Bugtracker: https://github.com/spring-projects/spring-data-jpa/issues
23-
* Milestone repository: https://repo.spring.io/milestone
24-
* Snapshot repository: https://repo.spring.io/snapshot

‎src/main/antora/modules/ROOT/pages/jpa.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[[jpa.repositories]]
2-
= JPA Repositories
2+
= JPA
33
:page-section-summary-toc: 1
44

55
This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in {spring-data-commons-docs-url}/repositories.html[Working with Spring Data Repositories]. Make sure you have a sound understanding of the basic concepts explained there.

‎src/main/antora/modules/ROOT/pages/jpa/introduction.adoc renamed to ‎src/main/antora/modules/ROOT/pages/jpa/configuration.adoc

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
[[jpa.introduction]]
2-
= Introduction
1+
[[jpa.configuration]]
2+
= Configuration
33

4-
This section describes the basics of configuring Spring Data JPA through either:
4+
This section describes configuring Spring Data JPA through either:
55

6-
* "`xref:jpa/introduction.adoc#jpa.namespace[Spring Namespace]`" (XML configuration)
7-
* "`xref:jpa/introduction.adoc#jpa.java-config[Annotation-based Configuration]`" (Java configuration)
6+
* "`<<jpa.namespace,Spring Namespace>>`" (XML configuration)
7+
* "`<<jpa.java-config,Annotation-based Configuration>>`" (Java configuration)
88

99
[[jpa.java-config]]
1010
== Annotation-based Configuration

‎src/main/antora/modules/ROOT/pages/jpa/misc-context.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[jpa.misc.jpa-context]]
22
= Using `JpaContext` in Custom Implementations
33

4-
When working with multiple `EntityManager` instances and <<repositories.custom-implementations,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`.
4+
When working with multiple `EntityManager` instances and xref:repositories/custom-implementations.adoc#repositories.custom-implementations[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`.
55

66
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:
77

‎src/main/antora/modules/ROOT/pages/jpa/query-methods.adoc

Lines changed: 7 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ public interface UserRepository extends Repository<User, Long> {
3131
List<User> findByEmailAddressAndLastname(String emailAddress, String lastname);
3232
}
3333
----
34-
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 {spring-data-commons-docs-url}/repositories/query-methods-details.html#repositories.query-methods.query-property-expressions[Property Expressions].
34+
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 xref:repositories/query-methods-details.adoc#repositories.query-methods.query-property-expressions[Property Expressions].
3535
====
3636

3737
The following table describes the keywords supported for JPA and what a method containing that keyword translates to:
@@ -67,7 +67,7 @@ The following table describes the keywords supported for JPA and what a method c
6767
|`IgnoreCase`|`findByFirstnameIgnoreCase`|`… where UPPER(x.firstname) = UPPER(?1)`
6868
|===============
6969

70-
NOTE: `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 {spring-data-commons-docs-url}/repository-query-keywords-reference.html[Repository query keywords].
70+
NOTE: `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 xref:repositories/query-keywords-reference.adoc[Repository query keywords].
7171

7272
[WARNING]
7373
====
@@ -350,16 +350,16 @@ When working with large data sets, <<repositories.scrolling,scrolling>> can help
350350

351351
You have multiple options to consume large query results:
352352

353-
1. <<repositories.paging-and-sorting,Paging>>.
353+
1. xref:repositories/query-methods-details.adoc#repositories.paging-and-sorting[Paging].
354354
You have learned in the previous chapter about `Pageable` and `PageRequest`.
355355
2. <<repositories.scrolling.offset,Offset-based scrolling>>.
356356
This is a lighter variant than paging because it does not require the total result count.
357357
3. <<repositories.scrolling.keyset,Keyset-baset scrolling>>.
358358
This method avoids https://use-the-index-luke.com/no-offset[the shortcomings of offset-based result retrieval by leveraging database indexes].
359359

360-
Read more on <<repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
360+
Read more on xref:repositories/query-methods-details.adoc#repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
361361

362-
You can use the Scroll API with query methods, xref:jpa/query-by-example.adoc[Query-by-Example], and <<core.extensions.querydsl,Querydsl>>.
362+
You can use the Scroll API with query methods, xref:query-by-example.adoc[Query-by-Example], and xref:repositories/core-extensions.adoc#core.extensions.querydsl[Querydsl].
363363

364364
NOTE: Scrolling with String-based query methods is not yet supported.
365365
Scrolling is also not supported using stored `@Procedure` query methods.
@@ -507,7 +507,7 @@ But sometimes, your query may simply be too complicated for the techniques offer
507507
In that situation, consider:
508508

509509
* If you haven't already, simply write the query yourself using xref:jpa/query-methods.adoc#jpa.query-methods.at-query[`@Query`].
510-
* If that doesn't fit your needs, consider implementing a <<repositories.custom-implementations,custom implementation>>. This lets you register a method in your repository while leaving the implementation completely up to you. This gives you the ability to:
510+
* If that doesn't fit your needs, consider implementing a xref:repositories/custom-implementations.adoc#repositories.custom-implementations[custom implementation]. This lets you register a method in your repository while leaving the implementation completely up to you. This gives you the ability to:
511511
** Talk directly to the `EntityManager` (writing pure HQL/JPQL/EQL/native SQL or using the *Criteria API*)
512512
** Leverage Spring Framework's `JdbcTemplate` (native SQL)
513513
** Use another 3rd-party database toolkit.
@@ -773,9 +773,4 @@ public interface GroupRepository extends CrudRepository<GroupInfo, String> {
773773
----
774774
====
775775

776-
[[projections]]
777-
== Projections
778-
779-
Spring Data JPA supports {spring-data-commons-docs-url}/repository-projections.html[Spring Data Commons Projections].
780-
781-
NOTE: It is important to note that {spring-data-commons-docs-url}/repository-projections.html#projections.dtos[Class-based projections] with JPQL is limited to *constructor expressions* in your JPQL expression, e.g. `SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u`. (Note the usage of a FQDN for the DTO type!) This JPQL expression can be used in `@Query` annotations as well where you define any named queries. And it's important to point out that class-based projections do not work with native queries AT ALL. As a workaround you may use named queries with `ResultSetMapping` or the Hibernate specific https://docs.jboss.org/hibernate/orm/6.0/javadocs/org/hibernate/transform/ResultTransformer.html[`ResultTransformer`]
776+
include::{commons}@data-commons::page$repositories/scrolling.adoc[leveloffset=+1]

‎src/main/antora/modules/ROOT/pages/jpa/query-by-example.adoc renamed to ‎src/main/antora/modules/ROOT/pages/query-by-example.adoc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
= Query by Example
22

3-
Spring Data JPA leverages {spring-data-commons-docs-url}/query-by-example.html[Spring Data Commons support for Query by Example].
3+
include::{commons}@data-commons::page$query-by-example.adoc[leveloffset=+1]
44

55
[[query-by-example.running]]
66
In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example:

‎src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/core-concepts.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/core-extensions.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/create-instances.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/definition.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/definition.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/introduction.adoc

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[[common.basics]]
2+
= Introduction
3+
:page-section-summary-toc: 1
4+
5+
This chapter explains the basic foundations of Spring Data repositories. Before continuing to the JPA specifics, make sure you have a sound understanding of the basic concepts explained here.

‎src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/null-handling.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/projections.adoc

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[[jpa.projections]]
2+
== Projections
3+
4+
include::{commons}@data-commons::page$repositories/projections.adoc[leveloffset=+1]
5+
6+
NOTE: It is important to note that <<projections.dtos,Class-based projections>> with JPQL is limited to *constructor expressions* in your JPQL expression, e.g. `SELECT new com.example.NamesOnly(u.firstname, u.lastname) from User u`. (Note the usage of a FQDN for the DTO type!) This JPQL expression can be used in `@Query` annotations as well where you define any named queries. And it's important to point out that class-based projections do not work with native queries AT ALL. As a workaround you may use named queries with `ResultSetMapping` or the Hibernate specific https://docs.jboss.org/hibernate/orm/6.0/javadocs/org/hibernate/transform/ResultTransformer.html[`ResultTransformer`]

‎src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]

‎src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]

‎src/main/antora/resources/antora-resources/antora.yml

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,14 @@ asciidoc:
77
springversionshort: ${spring.short}
88
springversion: ${spring}
99
attribute-missing: 'warn'
10+
commons: ${springdata.commons.docs}
11+
include-xml-namespaces: false
1012
spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
1113
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
1214
springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
1315
springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
16+
spring-framework-docs: '{springdocsurl}'
17+
spring-framework-javadoc: '{springjavadocurl}'
18+
springhateoasversion: ${spring-hateoas}
19+
releasetrainversion: ${releasetrain}
20+
store: Jpa

0 commit comments

Comments
 (0)
Please sign in to comment.