diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc index 91dc7ac38..1b5248ee7 100644 --- a/src/main/asciidoc/index.adoc +++ b/src/main/asciidoc/index.adoc @@ -10,8 +10,6 @@ ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1 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. -toc::[] - include::preface.adoc[] include::new-features.adoc[leveloffset=+1] @@ -21,12 +19,12 @@ include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1] include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1] [[reference]] -= Reference Documentation +== Reference Documentation include::jpa.adoc[leveloffset=+1] [[appendix]] -= Appendix +== Appendix :numbered!: include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/jpa.adoc b/src/main/asciidoc/jpa.adoc index 585b910a5..4c788db6f 100644 --- a/src/main/asciidoc/jpa.adoc +++ b/src/main/asciidoc/jpa.adoc @@ -122,8 +122,8 @@ In case you bootstrap JPA asynchronously, `DEFERRED` is a reasonable default as 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're pretty sure that repositories will properly bootstrap, or in cases where you're testing other parts of the application, executing verification for all repositories might just unnecessarily increase the startup time. -The same applies to local development in which you only access parts of the application which might just need a single repository initialized. +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. [[jpa.entity-persistence]] == Persisting Entities @@ -287,7 +287,7 @@ public class User { ==== ==== Declaring Interfaces -To allow execution of these named queries, specify the `UserRepository` as follows: +To allow these named queries, specify the `UserRepository` as follows: .Query method declaration in UserRepository ==== @@ -307,7 +307,7 @@ Spring Data tries to resolve a call to these methods to a named query, starting [[jpa.query-methods.at-query]] === Using `@Query` -Using named queries to declare queries for entities is a valid approach and works fine for a small number of queries. As the queries themselves are tied to the Java method that executes them, you 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. +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`. @@ -327,7 +327,7 @@ public interface UserRepository extends JpaRepository { ==== Using Advanced `LIKE` Expressions -The query execution 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: +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: .Advanced `like` expressions in @Query ==== @@ -341,7 +341,7 @@ public interface UserRepository extends JpaRepository { ---- ==== -In the preceding example, the `LIKE` delimiter character (`%`) is recognized, and the query is transformed into a valid JPQL query (removing the `%`). Upon query execution, the parameter passed to the method call gets augmented with the previously recognized `LIKE` pattern. +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 @@ -439,7 +439,7 @@ NOTE: As of version 4, Spring fully supports Java 8’s parameter name discovery [[jpa.query.spel-expressions]] === 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 query execution, 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. +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: @@ -589,13 +589,13 @@ interface UserRepository extends Repository { ---- ==== -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 get executed. +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(…)` executes a query and then deletes the returned instances one by one, so that the persistence provider can actually invoke `@PreRemove` callbacks on those entities. +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 executing the query and then calling `CrudRepository.delete(Iterable users)` on the result and keeping behavior in sync with the implementations of other `delete(…)` methods in `CrudRepository`. +In fact, a derived delete query is a shortcut for running the query and then calling `CrudRepository.delete(Iterable users)` on the result and keeping behavior in sync with the implementations of other `delete(…)` methods in `CrudRepository`. [[jpa.query-hints]] === Applying Query Hints @@ -785,7 +785,7 @@ public interface CustomerRepository extends CrudRepository, JpaS } ---- -The additional interface has methods that let you execute specifications in a variety of ways. For example, the `findAll` method returns all entities that match the specification, as shown in the following example: +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: [source, java] ---- diff --git a/src/main/asciidoc/new-features.adoc b/src/main/asciidoc/new-features.adoc index 30fab666f..952975692 100644 --- a/src/main/asciidoc/new-features.adoc +++ b/src/main/asciidoc/new-features.adoc @@ -8,7 +8,7 @@ Spring Data JPA 1.11 added the following features: * Improved compatibility with Hibernate 5.2. * Support any-match mode for <>. -* Paged query execution optimizations. +* Paged query optimizations. * Support for the `exists` projection in repository query derivation. [[new-features.1-10-0]] diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc index 008aa779d..74a10121f 100644 --- a/src/main/asciidoc/preface.adoc +++ b/src/main/asciidoc/preface.adoc @@ -1,10 +1,10 @@ [[preface]] -= Preface +== Preface Spring Data JPA provides repository support for the Java Persistence API (JPA). It eases development of applications that need to access JPA data sources. [[project]] -== Project Metadata +=== Project Metadata * Version control: https://github.com/spring-projects/spring-data-jpa * Bugtracker: https://jira.spring.io/browse/DATAJPA diff --git a/src/main/asciidoc/query-by-example.adoc b/src/main/asciidoc/query-by-example.adoc index 95aaae516..c67368c6e 100644 --- a/src/main/asciidoc/query-by-example.adoc +++ b/src/main/asciidoc/query-by-example.adoc @@ -1,5 +1,5 @@ -[[query-by-example.execution]] -== Executing an example +[[query-by-example.running]] +== Running an Example In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example: