Spring/spring-data-jpa
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Restructure content to include partials from Commons.

Browse Source 
See #3080
This commit is contained in:
Mark Paluch
2023-08-22 14:52:18 +02:00
parent 016be28e79
commit b47a340c0d
30 changed files with 304 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
spring-data-jpa-distribution/pom.xml
View File

@@ -37,6 +37,19 @@
<artifactId>maven-assembly-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>resources</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>io.spring.maven.antora</groupId>
<artifactId>antora-maven-plugin</artifactId>
@@ -44,17 +57,4 @@
</plugins>
</build>
<profiles>
<profile>
<id>antora</id>
<build>
<plugins>
</plugins>
</build>
</profile>
</profiles>
</project>

5
src/main/antora/antora-playbook.yml
View File

@@ -15,6 +15,11 @@ content:
branches: HEAD
start_path: src/main/antora
worktrees: true
- url: https://github.com/spring-projects/spring-data-commons
# Refname matching:
# https://docs.antora.org/antora/latest/playbook/content-refname-matching/
branches: [main, 3.2.x]
start_path: src/main/antora
asciidoc:
attributes:
page-pagination: ''

27
src/main/antora/modules/ROOT/nav.adoc
View File

@@ -1,17 +1,34 @@
* xref:index.adoc[Overview]
** xref:commons/upgrade.adoc[]
* xref:repositories/introduction.adoc[]
** xref:repositories/core-concepts.adoc[]
** xref:repositories/definition.adoc[]
** xref:repositories/create-instances.adoc[]
** xref:repositories/query-methods-details.adoc[]
** xref:repositories/projections.adoc[]
** xref:repositories/custom-implementations.adoc[]
** xref:repositories/core-domain-events.adoc[]
** xref:repositories/core-extensions.adoc[]
** xref:repositories/null-handling.adoc[]
** xref:repositories/query-keywords-reference.adoc[]
** xref:repositories/query-return-types-reference.adoc[]
* xref:jpa.adoc[]
** xref:jpa/introduction.adoc[]
** xref:jpa/configuration.adoc[]
** xref:jpa/entity-persistence.adoc[]
** xref:jpa/query-methods.adoc[]
** xref:jpa/stored-procedures.adoc[]
** xref:jpa/specifications.adoc[]
** xref:jpa/query-by-example.adoc[]
** xref:query-by-example.adoc[]
** xref:jpa/transactions.adoc[]
** xref:jpa/locking.adoc[]
** xref:jpa/auditing.adoc[]
** xref:auditing.adoc[]
** xref:jpa/misc-context.adoc[]
** xref:jpa/misc-merging-persistence-units.adoc[]
** xref:jpa/jpd-misc-cdi-integration.adoc[]
** xref:jpa/faq.adoc[]
** xref:jpa/glossary.adoc[]
* xref:envers.adoc[]
* xref:faq.adoc[]
* xref:glossary.adoc[]
** xref:envers/introduction.adoc[]
** xref:envers/configuration.adoc[]
** xref:envers/usage.adoc[]
* https://github.com/spring-projects/spring-data-commons/wiki[Wiki]

6
src/main/antora/modules/ROOT/pages/jpa/auditing.adoc → src/main/antora/modules/ROOT/pages/auditing.adoc
View File

@@ -1,8 +1,4 @@
[[jpa.auditing]]
= JPA Auditing
Spring Data JPA provides auditing based upon the foundation provided by {spring-data-commons-docs-url}/auditing.html[Spring Data Common's Auditing support].
include::{commons}@data-commons::page$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.

1
src/main/antora/modules/ROOT/pages/commons/upgrade.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$upgrade.adoc[]

205
src/main/antora/modules/ROOT/pages/envers.adoc
View File

@@ -1,204 +1,5 @@
[[envers]]
= Spring Data Envers
= Envers
:page-section-summary-toc: 1
[[envers.what.is.spring.data]]
== 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.
[[envers.what]]
== What is Envers?
Envers is a https://hibernate.org/orm/envers/[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.
[[envers.configuration]]
== 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:
====
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-envers</artifactId>
<version>{version}</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`:
====
[source,java]
----
@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:
====
[source,java]
----
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):
====
[source,java]
----
@Entity
@Audited
class Person {
@Id @GeneratedValue
Long id;
String name;
@Version Long version;
}
----
====
[[envers.usage]]
== Usage
You can now use the methods from `RevisionRepository` to query the revisions of the entity, as the following test case shows:
====
[source,java]
----
@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 xref:envers.adoc#envers.configuration[Configuration] section).
====
[[envers.resources]]
== Further Resources
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.
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 https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].
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).
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.

95
src/main/antora/modules/ROOT/pages/envers/configuration.adoc Normal file
View File

@@ -0,0 +1,95 @@
[[envers.configuration]]
= 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:
====
[source,xml,subs="+attributes"]
----
<dependencies>
<!-- other dependency elements omitted -->
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-envers</artifactId>
<version>{version}</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`:
====
[source,java]
----
@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:
====
[source,java]
----
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):
====
[source,java]
----
@Entity
@Audited
class Person {
@Id @GeneratedValue
Long id;
String name;
@Version Long version;
}
----
====

14
src/main/antora/modules/ROOT/pages/envers/introduction.adoc Normal file
View File

@@ -0,0 +1,14 @@
[[envers.introduction]]
= Introduction
[[envers.what.is.spring.data]]
== 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.
[[envers.what]]
== What is Envers?
Envers is a https://hibernate.org/orm/envers/[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.

93
src/main/antora/modules/ROOT/pages/envers/usage.adoc Normal file
View File

@@ -0,0 +1,93 @@
[[envers.usage]]
= Usage
You can now use the methods from `RevisionRepository` to query the revisions of the entity, as the following test case shows:
====
[source,java]
----
@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 xref:envers.adoc#envers.configuration[Configuration] section).
====
[[envers.resources]]
== Further Resources
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.
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 https://stackoverflow.com/questions/tagged/spring-data-envers[Stackoverflow by using the `spring-data-envers` tag].
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).

23
src/main/antora/modules/ROOT/pages/index.adoc
View File

@@ -1,24 +1,21 @@
[[spring-data-jpa-reference-documentation]]
= Spring Data JPA
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist
:revnumber: {version}
:revdate: {localdate}
:feature-scroll: true
(C) 2008-2023 The original authors.
_Spring Data JPA provides repository support for the Jakarta Persistence API (JPA).
It eases development of applications with a consistent programming model that need to access JPA data sources._
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.
[horizontal]
xref:jpa.adoc[JPA] :: JPA and JPA Repositories
xref:envers.adoc[Envers] :: Support for Envers Revision Repositories
https://github.com/spring-projects/spring-data-commons/wiki[Wiki] :: What's New,
Upgrade Notes, Supported Versions, additional cross-version information.
[[preface]]
== Preface
:page-section-summary-toc: 1
Oliver Gierke, Thomas Darimont, Christoph Strobl, Mark Paluch, Jay Bryant, Greg Turnquist
Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources.
(C) 2008-2023 VMware, Inc.
[[project]]
== Project Metadata
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.
* Version control: https://github.com/spring-projects/spring-data-jpa
* Bugtracker: https://github.com/spring-projects/spring-data-jpa/issues
* Milestone repository: https://repo.spring.io/milestone
* Snapshot repository: https://repo.spring.io/snapshot

4
src/main/antora/modules/ROOT/pages/jpa.adoc
View File

@@ -1,6 +1,6 @@
[[jpa.repositories]]
= JPA Repositories
= JPA
:page-section-summary-toc: 1
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.
This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in xref:repositories/introduction.adoc[Working with Spring Data Repositories]. Make sure you have a sound understanding of the basic concepts explained there.

12
src/main/antora/modules/ROOT/pages/jpa/introduction.adoc → src/main/antora/modules/ROOT/pages/jpa/configuration.adoc
View File

@@ -1,10 +1,10 @@
[[jpa.introduction]]
= Introduction
[[jpa.configuration]]
= Configuration
This section describes the basics of configuring Spring Data JPA through either:
This section describes configuring Spring Data JPA through either:
* "`xref:jpa/introduction.adoc#jpa.namespace[Spring Namespace]`" (XML configuration)
* "`xref:jpa/introduction.adoc#jpa.java-config[Annotation-based Configuration]`" (Java configuration)
* "`<<jpa.namespace,Spring Namespace>>`" (XML configuration)
* "`<<jpa.java-config,Annotation-based Configuration>>`" (Java configuration)
[[jpa.java-config]]
== Annotation-based Configuration
@@ -79,7 +79,7 @@ The JPA module of Spring Data contains a custom namespace that allows defining r
TIP: Which is better, JavaConfig or XML? XML is how Spring was configured long ago. In today's era of fast-growing Java, record types, annotations, and more, new projects typically use as much pure Java as possible. While there is no immediate plan to remove XML support, some of the newest features MAY not be available through XML.
Using the `repositories` element looks up Spring Data repositories as described in {spring-data-commons-docs-url}/repositories/create-instances.html[Creating Repository 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.
Using the `repositories` element looks up Spring Data repositories as described in xref:repositories/create-instances.adoc[Creating Repository 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.
[[jpa.namespace.custom-namespace-attributes]]
=== Custom Namespace Attributes

0
src/main/antora/modules/ROOT/pages/faq.adoc → src/main/antora/modules/ROOT/pages/jpa/faq.adoc
View File

0
src/main/antora/modules/ROOT/pages/glossary.adoc → src/main/antora/modules/ROOT/pages/jpa/glossary.adoc
View File

2
src/main/antora/modules/ROOT/pages/jpa/misc-context.adoc
View File

@@ -1,7 +1,7 @@
[[jpa.misc.jpa-context]]
= Using `JpaContext` in Custom Implementations
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`.
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`.
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:

19
src/main/antora/modules/ROOT/pages/jpa/query-methods.adoc
View File

@@ -31,7 +31,7 @@ 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 {spring-data-commons-docs-url}/repositories/query-methods-details.html#repositories.query-methods.query-property-expressions[Property Expressions].
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].
====
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
|`IgnoreCase`|`findByFirstnameIgnoreCase`|`… where UPPER(x.firstname) = UPPER(?1)`
|===============
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].
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].
[WARNING]
====
@@ -350,16 +350,16 @@ When working with large data sets, <<repositories.scrolling,scrolling>> can help
You have multiple options to consume large query results:
1. <<repositories.paging-and-sorting,Paging>>.
1. xref:repositories/query-methods-details.adoc#repositories.paging-and-sorting[Paging].
You have learned in the previous chapter about `Pageable` and `PageRequest`.
2. <<repositories.scrolling.offset,Offset-based scrolling>>.
This is a lighter variant than paging because it does not require the total result count.
3. <<repositories.scrolling.keyset,Keyset-baset scrolling>>.
This method avoids https://use-the-index-luke.com/no-offset[the shortcomings of offset-based result retrieval by leveraging database indexes].
Read more on <<repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
Read more on xref:repositories/query-methods-details.adoc#repositories.scrolling.guidance,which method to use best>> for your particular arrangement.
You can use the Scroll API with query methods, xref:jpa/query-by-example.adoc[Query-by-Example], and <<core.extensions.querydsl,Querydsl>>.
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].
NOTE: Scrolling with String-based query methods is not yet supported.
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
In that situation, consider:
* If you haven't already, simply write the query yourself using xref:jpa/query-methods.adoc#jpa.query-methods.at-query[`@Query`].
* 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:
* 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:
** Talk directly to the `EntityManager` (writing pure HQL/JPQL/EQL/native SQL or using the *Criteria API*)
** Leverage Spring Framework's `JdbcTemplate` (native SQL)
** Use another 3rd-party database toolkit.
@@ -773,9 +773,4 @@ public interface GroupRepository extends CrudRepository<GroupInfo, String> {
----
====
[[projections]]
== Projections
Spring Data JPA supports {spring-data-commons-docs-url}/repository-projections.html[Spring Data Commons Projections].
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`]
include::{commons}@data-commons::page$repositories/scrolling.adoc[leveloffset=+1]

2
src/main/antora/modules/ROOT/pages/jpa/query-by-example.adoc → src/main/antora/modules/ROOT/pages/query-by-example.adoc
View File

@@ -1,6 +1,6 @@
= Query by Example
Spring Data JPA leverages {spring-data-commons-docs-url}/query-by-example.html[Spring Data Commons support for Query by Example].
include::{commons}@data-commons::page$query-by-example.adoc[leveloffset=+1]
[[query-by-example.running]]
In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example:

1
src/main/antora/modules/ROOT/pages/repositories/core-concepts.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-concepts.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/core-domain-events.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-domain-events.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/core-extensions.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/core-extensions.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/create-instances.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/create-instances.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/custom-implementations.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/custom-implementations.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/definition.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/definition.adoc[]

7
src/main/antora/modules/ROOT/pages/repositories/introduction.adoc Normal file
View File

@@ -0,0 +1,7 @@
[[common.basics]]
= Introduction
:page-section-summary-toc: 1
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.
The goal of the Spring Data repository abstraction is to significantly reduce the amount of boilerplate code required to implement data access layers for various persistence stores.

1
src/main/antora/modules/ROOT/pages/repositories/null-handling.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/null-handling.adoc[]

6
src/main/antora/modules/ROOT/pages/repositories/projections.adoc Normal file
View File

@@ -0,0 +1,6 @@
[[jpa.projections]]
= Projections
include::{commons}@data-commons::page$repositories/projections.adoc[leveloffset=+1]
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`]

1
src/main/antora/modules/ROOT/pages/repositories/query-keywords-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-keywords-reference.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-methods-details.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-methods-details.adoc[]

1
src/main/antora/modules/ROOT/pages/repositories/query-return-types-reference.adoc Normal file
View File

@@ -0,0 +1 @@
include::{commons}@data-commons::page$repositories/query-return-types-reference.adoc[]

7
src/main/antora/resources/antora-resources/antora.yml
View File

@@ -7,7 +7,14 @@ asciidoc:
springversionshort: ${spring.short}
springversion: ${spring}
attribute-missing: 'warn'
commons: ${springdata.commons.docs}
include-xml-namespaces: false
spring-data-commons-docs-url: https://docs.spring.io/spring-data-commons/reference
spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/commons/docs/${springdata.commons}/api/
springdocsurl: https://docs.spring.io/spring-framework/reference/{springversionshort}
springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api
spring-framework-docs: '{springdocsurl}'
spring-framework-javadoc: '{springjavadocurl}'
springhateoasversion: ${spring-hateoas}
releasetrainversion: ${releasetrain}
store: Jpa