diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml new file mode 100644 index 0000000000..1435fc2171 --- /dev/null +++ b/.github/workflows/deploy-docs.yml @@ -0,0 +1,33 @@ +name: Deploy Docs +on: + push: + branches-ignore: [ gh-pages ] + tags: '**' + repository_dispatch: + types: request-build-reference # legacy + #schedule: + #- cron: '0 10 * * *' # Once per day at 10am UTC + workflow_dispatch: +permissions: + actions: write +jobs: + build: + runs-on: ubuntu-latest + # FIXME enable when pushed to spring-projects + # if: github.repository_owner == 'spring-projects' + steps: + - name: Checkout + uses: actions/checkout@v3 + with: + ref: docs-build + fetch-depth: 1 + - name: Dispatch (partial build) + if: github.ref_type == 'branch' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }} + - name: Dispatch (full build) + if: github.ref_type == 'tag' + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) diff --git a/.gitignore b/.gitignore index 1a71d533d0..7cdfa7a0f4 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,7 @@ target/ .sonar4clipse *.sonar4clipseExternals .DS_Store +node_modules +package-lock.json +package.json +node \ No newline at end of file diff --git a/pom.xml b/pom.xml index f3f62584cc..05de2b92d6 100644 --- a/pom.xml +++ b/pom.xml @@ -42,6 +42,16 @@ reuseReports + + v18.12.1 + 8.19.2 + 3.2.0-alpha.2 + 1.0.0-alpha.1 + 1.0.0-alpha.3 + 1.0.0-beta.3 + 1.4.0 + 1.0.0-alpha.9 + @@ -202,7 +212,6 @@ - diff --git a/spring-data-jpa-distribution/pom.xml b/spring-data-jpa-distribution/pom.xml index 991cd8cbf0..b6c5132943 100644 --- a/spring-data-jpa-distribution/pom.xml +++ b/spring-data-jpa-distribution/pom.xml @@ -21,6 +21,7 @@ ${basedir}/.. DATAJPA + @@ -29,11 +30,96 @@ org.apache.maven.plugins maven-assembly-plugin - - org.asciidoctor - asciidoctor-maven-plugin - + + + docs + + + + com.github.eirslett + frontend-maven-plugin + 1.12.1 + + + install-antora + + install-node-and-npm + + initialize + + ${node.version} + ${npm.version} + + + + npm install antora + + npm + + initialize + + install @antora/cli@${antora.version} @antora/site-generator-default@${antora.version} @antora/atlas-extension@${antora-atlas.version} @antora/collector-extension@${antora-collector.version} @asciidoctor/tabs@${asciidoctor-tabs.version} @springio/antora-extensions@${spring-antora-extensions.version} @springio/asciidoctor-extensions@${spring-asciidoctor-extensions.version} + + + + + + org.codehaus.mojo + exec-maven-plugin + 3.0.0 + + + antora + + exec + + compile + + + node/node + + node_modules/.bin/antora + src/main/antora/antora-playbook.yml + --to-dir=target/site + + ${project.parent.basedir} + + + + + + org.apache.maven.plugins + maven-clean-plugin + 3.1.0 + + + + node + false + + + node_modules + false + + + build + false + + + + + + + + src/main/resources + true + + + + + diff --git a/spring-data-jpa-distribution/src/main/resources/antora-resources/antora.yml b/spring-data-jpa-distribution/src/main/resources/antora-resources/antora.yml new file mode 100644 index 0000000000..53bf8ed334 --- /dev/null +++ b/spring-data-jpa-distribution/src/main/resources/antora-resources/antora.yml @@ -0,0 +1,11 @@ +version: ${project.version} + +asciidoc: + attributes: + version: ${project.version} + springversion: ${spring} + attribute-missing: 'warn' + spring-data-commons-docs-url: https://rwinch.github.io/spring-data-commons + spring-data-commons-javadoc-base: https://docs.spring.io/spring-data/data-commons/docs/current/api/ + springdocsurl: https://docs.spring.io/spring-framework/docs/${spring}/reference/html + springjavadocurl: https://docs.spring.io/spring-framework/docs/${spring}/javadoc-api \ No newline at end of file diff --git a/src/main/antora/antora-playbook.yml b/src/main/antora/antora-playbook.yml new file mode 100644 index 0000000000..643dd938eb --- /dev/null +++ b/src/main/antora/antora-playbook.yml @@ -0,0 +1,37 @@ +# PACKAGES antora@3.2.0-alpha.2 @antora/atlas-extension:1.0.0-alpha.1 @antora/collector-extension@1.0.0-alpha.3 @springio/antora-extensions@1.1.0-alpha.2 @asciidoctor/tabs@1.0.0-alpha.12 @opendevise/antora-release-line-extension@1.0.0-alpha.2 +# +# The purpose of this Antora playbook is to build the docs in the current branch. +antora: + extensions: + - '@antora/collector-extension' + - require: '@springio/antora-extensions/root-component-extension' + root_component_name: 'data-jpa' +site: + title: Spring Data JPA + url: https://docs.spring.io/spring-data-jpa/reference/ +content: + sources: + - url: ./../../.. + branches: HEAD + start_path: src/main/antora + worktrees: true +asciidoc: + attributes: + page-pagination: '' + hide-uri-scheme: '@' + tabs-sync-option: '@' + chomp: 'all' + extensions: + - '@asciidoctor/tabs' + - '@springio/asciidoctor-extensions' + sourcemap: true +urls: + latest_version_segment: '' +runtime: + log: + failure_level: warn + format: pretty +ui: + bundle: + url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.3/ui-bundle.zip + snapshot: true \ No newline at end of file diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml new file mode 100644 index 0000000000..f86bb29f07 --- /dev/null +++ b/src/main/antora/antora.yml @@ -0,0 +1,12 @@ +name: data-jpa +version: true +title: Spring Data JPA +nav: + - modules/ROOT/nav.adoc +ext: + collector: + - run: + command: mvnw resources:resources -pl spring-data-jpa-distribution -am -Pdocs + local: true + scan: + dir: spring-data-jpa-distribution/target/classes/antora-resources diff --git a/src/main/antora/modules/ROOT/assets/images/epub-cover.png b/src/main/antora/modules/ROOT/assets/images/epub-cover.png new file mode 100644 index 0000000000..bd31c43fae Binary files /dev/null and b/src/main/antora/modules/ROOT/assets/images/epub-cover.png differ diff --git a/src/main/antora/modules/ROOT/assets/images/epub-cover.svg b/src/main/antora/modules/ROOT/assets/images/epub-cover.svg new file mode 100644 index 0000000000..2feb05be1d --- /dev/null +++ b/src/main/antora/modules/ROOT/assets/images/epub-cover.svg @@ -0,0 +1,10 @@ + + + + + Spring Data JPA + Reference Guide + Oliver Gierke, Thomas Darimont, + Christoph Strobl, Mark Paluch, + Jay Bryant + diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc new file mode 100644 index 0000000000..204efcda6f --- /dev/null +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -0,0 +1,17 @@ +* xref:index.adoc[Overview] +* xref:jpa.adoc[] +** xref:jpa/introduction.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:jpa/transactions.adoc[] +** xref:jpa/locking.adoc[] +** xref:jpa/auditing.adoc[] +** xref:jpa/misc-context.adoc[] +** xref:jpa/misc-merging-persistence-units.adoc[] +** xref:jpa/jpd-misc-cdi-integration.adoc[] +* xref:envers.adoc[] +* xref:faq.adoc[] +* xref:glossary.adoc[] diff --git a/src/main/asciidoc/envers.adoc b/src/main/antora/modules/ROOT/pages/envers.adoc similarity index 98% rename from src/main/asciidoc/envers.adoc rename to src/main/antora/modules/ROOT/pages/envers.adoc index d1c46be1dd..0b6fc775f0 100644 --- a/src/main/asciidoc/envers.adoc +++ b/src/main/antora/modules/ROOT/pages/envers.adoc @@ -189,7 +189,7 @@ class EnversIntegrationTests { } } ---- -<1> This references the application context configuration presented earlier (in the <> section). +<1> This references the application context configuration presented earlier (in the xref:envers.adoc#envers.configuration[Configuration] section). ==== [[envers.resources]] diff --git a/src/main/asciidoc/faq.adoc b/src/main/antora/modules/ROOT/pages/faq.adoc similarity index 97% rename from src/main/asciidoc/faq.adoc rename to src/main/antora/modules/ROOT/pages/faq.adoc index 5a2f672738..7954f35158 100644 --- a/src/main/asciidoc/faq.adoc +++ b/src/main/antora/modules/ROOT/pages/faq.adoc @@ -1,5 +1,6 @@ [[faq]] [appendix] +[[frequently-asked-questions]] = Frequently Asked Questions [[faq.common]] diff --git a/src/main/asciidoc/glossary.adoc b/src/main/antora/modules/ROOT/pages/glossary.adoc similarity index 96% rename from src/main/asciidoc/glossary.adoc rename to src/main/antora/modules/ROOT/pages/glossary.adoc index b0810fe1cf..c74c09e214 100644 --- a/src/main/asciidoc/glossary.adoc +++ b/src/main/antora/modules/ROOT/pages/glossary.adoc @@ -1,6 +1,8 @@ [[glossary]] [appendix, glossary] +[[glossary]] = Glossary +:page-section-summary-toc: 1 AOP :: Aspect oriented programming diff --git a/src/main/antora/modules/ROOT/pages/index.adoc b/src/main/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000000..f7e6d65393 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,25 @@ +[[spring-data-jpa-reference-documentation]] += Spring Data JPA +Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist +:revnumber: {version} +:revdate: {localdate} +ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]] +:feature-scroll: true + +(C) 2008-2023 The original authors. + +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. + +[[preface]] +== Preface +:page-section-summary-toc: 1 + +Spring Data JPA provides repository support for the Jakarta Persistence API (JPA). It eases development of applications that need to access JPA data sources. + +[[project]] +== Project Metadata + +* 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 \ No newline at end of file diff --git a/src/main/antora/modules/ROOT/pages/jpa.adoc b/src/main/antora/modules/ROOT/pages/jpa.adoc new file mode 100644 index 0000000000..eae798bbc7 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa.adoc @@ -0,0 +1,6 @@ +[[jpa.repositories]] += JPA Repositories +: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. + diff --git a/src/main/antora/modules/ROOT/pages/jpa/auditing.adoc b/src/main/antora/modules/ROOT/pages/jpa/auditing.adoc new file mode 100644 index 0000000000..20aeaa4c7c --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/auditing.adoc @@ -0,0 +1,77 @@ +[[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]. + + +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. + + +[[jpa.auditing.configuration]] +== 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: + +.Auditing configuration orm.xml +==== +[source, xml] +---- + + + + + + + +---- +==== + +You can also enable the `AuditingEntityListener` on a per-entity basis by using the `@EntityListeners` annotation, as follows: + +==== +[source, java] +---- +@Entity +@EntityListeners(AuditingEntityListener.class) +public class MyEntity { + +} +---- +==== + +NOTE: 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: + +.Activating auditing using XML configuration +==== +[source, xml] +---- + +---- +==== + +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: + +.Activating auditing with Java configuration +==== +[source, java] +---- +@Configuration +@EnableJpaAuditing +class Config { + + @Bean + public AuditorAware 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`. + +// FIXME: does this need to exist? +// [[jpa.misc]] +// = Miscellaneous Considerations + diff --git a/src/main/antora/modules/ROOT/pages/jpa/entity-persistence.adoc b/src/main/antora/modules/ROOT/pages/jpa/entity-persistence.adoc new file mode 100644 index 0000000000..16ad24607f --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/entity-persistence.adoc @@ -0,0 +1,55 @@ +[[jpa.entity-persistence]] += Persisting Entities + +This section describes how to persist (save) entities with Spring Data JPA. + +[[jpa.entity-persistence.saving-entites]] +== 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. + +[[jpa.entity-persistence.saving-entites.strategies]] +=== Entity State-detection Strategies +Spring Data JPA offers the following strategies to detect whether an entity is new or not: + +1. 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 is `null`, then the entity is assumed to be new. + Otherwise, it is assumed to be not new. +2. Implementing `Persistable`: If an entity implements `Persistable`, Spring Data JPA delegates the new detection to the `isNew(…)` method of the entity. See the link:$$https://docs.spring.io/spring-data/data-commons/docs/current/api/index.html?org/springframework/data/domain/Persistable.html$$[JavaDoc] for details. +3. Implementing `EntityInformation`: You can customize the `EntityInformation` abstraction used in the `SimpleJpaRepository` implementation by creating a subclass of `JpaRepositoryFactory` and overriding the `getEntityInformation(…)` method accordingly. You then have to register the custom implementation of `JpaRepositoryFactory` as a Spring bean. Note that this should be rarely necessary. See the link:$$https://docs.spring.io/spring-data/data-jpa/docs/current/api/index.html?org/springframework/data/jpa/repository/support/JpaRepositoryFactory.html$$[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: + +.A base class for entities with manually assigned identifiers +==== +[source, java] +---- +@MappedSuperclass +public abstract class AbstractEntity implements Persistable { + + @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. +==== + diff --git a/src/main/antora/modules/ROOT/pages/jpa/introduction.adoc b/src/main/antora/modules/ROOT/pages/jpa/introduction.adoc new file mode 100644 index 0000000000..d1f66fd30a --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/introduction.adoc @@ -0,0 +1,126 @@ +[[jpa.introduction]] += Introduction + +This section describes the basics of 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.java-config]] +== Annotation-based Configuration +The Spring Data JPA repositories support can be activated through both JavaConfig as well as a custom XML namespace, as shown in the following example: + +.Spring Data JPA repositories using JavaConfig +==== +[source, java] +---- +@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; + } +} +---- +==== +NOTE: 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. + +[[jpa.namespace]] +== 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: + +.Setting up JPA repositories by using the namespace +==== +[source, xml] +---- + + + + + + +---- +==== + +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. + +[[jpa.namespace.custom-namespace-attributes]] +=== 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: + +.Custom JPA-specific attributes of the `repositories` element +[options = "autowidth"] +|=============== +|`entity-manager-factory-ref`|Explicitly wire the `EntityManagerFactory` to be used with the repositories being detected by the `repositories` element. Usually used if multiple `EntityManagerFactory` beans are used within the application. If not configured, Spring Data automatically looks up the `EntityManagerFactory` bean with the name `entityManagerFactory` in the `ApplicationContext`. +|`transaction-manager-ref`|Explicitly wire the `PlatformTransactionManager` to be used with the repositories being detected by the `repositories` element. Usually only necessary if multiple transaction managers or `EntityManagerFactory` beans have been configured. Default to a single defined `PlatformTransactionManager` inside the current `ApplicationContext`. +|=============== + +NOTE: Spring Data JPA requires a `PlatformTransactionManager` bean named `transactionManager` to be present if no explicit `transaction-manager-ref` is defined. + +[[jpa.bootstrap-mode]] +== 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 as `LAZY`, but triggering repository initialization in response to an `ContextRefreshedEvent` so that repositories are verified before the application has completely started. + +[[jpa.bootstrap-mode.recommendations]] +=== 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. + diff --git a/src/main/antora/modules/ROOT/pages/jpa/jpd-misc-cdi-integration.adoc b/src/main/antora/modules/ROOT/pages/jpa/jpd-misc-cdi-integration.adoc new file mode 100644 index 0000000000..98ba2bb2be --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/jpd-misc-cdi-integration.adoc @@ -0,0 +1,62 @@ +[[jpd.misc.cdi-integration]] += 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 {spring-data-commons-docs-url}/repositories/create-instances.html[Creating Repository 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: + +[source, java] +---- +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: + +[source, java] +---- +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: + +[source, java] +---- +class RepositoryClient { + + @Inject + PersonRepository repository; + + public void businessMethod() { + List people = repository.findAll(); + } +} +---- diff --git a/src/main/antora/modules/ROOT/pages/jpa/locking.adoc b/src/main/antora/modules/ROOT/pages/jpa/locking.adoc new file mode 100644 index 0000000000..43e178f939 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/locking.adoc @@ -0,0 +1,32 @@ +[[locking]] += Locking + +To specify the lock mode to be used, you can use the `@Lock` annotation on query methods, as shown in the following example: + +.Defining lock metadata on query methods +==== +[source, java] +---- +interface UserRepository extends Repository { + + // Plain query method + @Lock(LockModeType.READ) + List 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: + +.Defining lock metadata on CRUD methods +==== +[source, java] +---- +interface UserRepository extends Repository { + + // Redeclaration of a CRUD method + @Lock(LockModeType.READ) + List findAll(); +} +---- +==== diff --git a/src/main/antora/modules/ROOT/pages/jpa/misc-context.adoc b/src/main/antora/modules/ROOT/pages/jpa/misc-context.adoc new file mode 100644 index 0000000000..7cdb5feff4 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/misc-context.adoc @@ -0,0 +1,27 @@ +[[jpa.misc.jpa-context]] += Using `JpaContext` in Custom Implementations + +When working with multiple `EntityManager` instances and <>, 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: + +.Using `JpaContext` in a custom repository implementation +==== +[source, java] +---- +class 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. + diff --git a/src/main/antora/modules/ROOT/pages/jpa/misc-merging-persistence-units.adoc b/src/main/antora/modules/ROOT/pages/jpa/misc-merging-persistence-units.adoc new file mode 100644 index 0000000000..35ef016c2f --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/misc-merging-persistence-units.adoc @@ -0,0 +1,41 @@ +[[jpa.misc.merging-persistence-units]] += 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: + +.Using MergingPersistenceUnitmanager +==== +[source, xml] +---- + + + + + +---- +==== + +[[jpa.misc.entity-scanning]] +== 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: + +.Using ClasspathScanningPersistenceUnitPostProcessor +==== +[source, xml] +---- + + + + + + + + + + +---- +==== + +NOTE: 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 link:{springJavadocUrl}org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.html#setPackagesToScan(java.lang.String...)$$[JavaDoc] for details. + diff --git a/src/main/asciidoc/query-by-example.adoc b/src/main/antora/modules/ROOT/pages/jpa/query-by-example.adoc similarity index 91% rename from src/main/asciidoc/query-by-example.adoc rename to src/main/antora/modules/ROOT/pages/jpa/query-by-example.adoc index c67368c6e5..2a7c661db4 100644 --- a/src/main/asciidoc/query-by-example.adoc +++ b/src/main/antora/modules/ROOT/pages/jpa/query-by-example.adoc @@ -1,6 +1,8 @@ -[[query-by-example.running]] -== Running an Example += Query by Example + +Spring Data JPA leverages {spring-data-commons-docs-url}/query-by-example.html[Spring Data Commons support for Query by Example]. +[[query-by-example.running]] In Spring Data JPA, you can use Query by Example with Repositories, as shown in the following example: .Query by Example using a Repository diff --git a/src/main/antora/modules/ROOT/pages/jpa/query-methods.adoc b/src/main/antora/modules/ROOT/pages/jpa/query-methods.adoc new file mode 100644 index 0000000000..5385c6c063 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/query-methods.adoc @@ -0,0 +1,781 @@ +[[jpa.query-methods]] += Query Methods + +This section describes the various ways to create a query with Spring Data JPA. + +[[jpa.sample-app.finders.strategies]] +== 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 xref:jpa/query-methods.adoc#jpa.query.spel-expressions[Using SpEL Expressions]. + +[[jpa.query-methods.declared-queries]] +=== 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 xref:jpa/query-methods.adoc#jpa.query-methods.named-queries[Using JPA Named Queries] for more information) or rather annotate your query method with `@Query` (see xref:jpa/query-methods.adoc#jpa.query-methods.at-query[Using `@Query`] for details). + +[[jpa.query-methods.query-creation]] +== Query Creation + +Generally, the query creation mechanism for JPA works as described in {spring-data-commons-docs-url}/repositories/query-methods.html[Query Methods]. The following example shows what a JPA query method translates into: + +.Query creation from method names +==== +---- +public interface UserRepository extends Repository { + + List 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]. +==== + +The following table describes the keywords supported for JPA and what a method containing that keyword translates to: + +.Supported keywords inside method names +[options = "header, autowidth"] +|=============== +|Keyword|Sample|JPQL snippet +|`Distinct`|`findDistinctByLastnameAndFirstname`|`select distinct ... where x.lastname = ?1 and x.firstname = ?2` +|`And`|`findByLastnameAndFirstname`|`… where x.lastname = ?1 and x.firstname = ?2` +|`Or`|`findByLastnameOrFirstname`|`… where x.lastname = ?1 or x.firstname = ?2` +|`Is`, `Equals`|`findByFirstname`,`findByFirstnameIs`,`findByFirstnameEquals`|`… where x.firstname = ?1` +|`Between`|`findByStartDateBetween`|`… where x.startDate between ?1 and ?2` +|`LessThan`|`findByAgeLessThan`|`… where x.age < ?1` +|`LessThanEqual`|`findByAgeLessThanEqual`|`… where x.age \<= ?1` +|`GreaterThan`|`findByAgeGreaterThan`|`… where x.age > ?1` +|`GreaterThanEqual`|`findByAgeGreaterThanEqual`|`… where x.age >= ?1` +|`After`|`findByStartDateAfter`|`… where x.startDate > ?1` +|`Before`|`findByStartDateBefore`|`… where x.startDate < ?1` +|`IsNull`, `Null`|`findByAge(Is)Null`|`… where x.age is null` +|`IsNotNull`, `NotNull`|`findByAge(Is)NotNull`|`… where x.age not null` +|`Like`|`findByFirstnameLike`|`… where x.firstname like ?1` +|`NotLike`|`findByFirstnameNotLike`|`… where x.firstname not like ?1` +|`StartingWith`|`findByFirstnameStartingWith`|`… where x.firstname like ?1` (parameter bound with appended `%`) +|`EndingWith`|`findByFirstnameEndingWith`|`… where x.firstname like ?1` (parameter bound with prepended `%`) +|`Containing`|`findByFirstnameContaining`|`… where x.firstname like ?1` (parameter bound wrapped in `%`) +|`OrderBy`|`findByAgeOrderByLastnameDesc`|`… where x.age = ?1 order by x.lastname desc` +|`Not`|`findByLastnameNot`|`… where x.lastname <> ?1` +|`In`|`findByAgeIn(Collection ages)`|`… where x.age in ?1` +|`NotIn`|`findByAgeNotIn(Collection ages)`|`… where x.age not in ?1` +|`True`|`findByActiveTrue()`|`… where x.active = true` +|`False`|`findByActiveFalse()`|`… where x.active = false` +|`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]. + +[WARNING] +==== +`DISTINCT` can be tricky and not always producing the results you expect. +For example, `select distinct u from User u` will produce a complete different result than `select distinct u.lastname from User u`. +In the first case, since you are including `User.id`, nothing will duplicated, hence you'll get the whole table, and it would be of `User` objects. + +However, that latter query would narrow the focus to just `User.lastname` and find all unique last names for that table. +This would also yield a `List` result set instead of a `List result set. + + +`countDistinctByLastname(String lastname)` can also produce unexpected results. +Spring Data JPA will derive `select count(distinct u.id) from User u where u.lastname = ?1`. +Again, since `u.id` won't hit any duplicates, this query will count up all the users that had the binding last name. +Which would the same as `countByLastname(String lastname)`! + +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 `distinct` sometimes requires writing the query by hand and using `@Query` to best capture the information you seek, since you also may be needing a projection +to capture the result set. +==== + +[[jpa.query-methods.named-queries.annotation-based-configuration]] +=== 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. + +.Annotation-based named query configuration +==== +[source, java] +---- +@Entity +@NamedQuery(name = "User.findByEmailAddress", + query = "select u from User u where u.emailAddress = ?1") +public class User { + +} +---- +==== + +[[jpa.query-methods.named-queries]] +== Using JPA Named Queries + +NOTE: The examples use the `` element and `@NamedQuery` annotation. The queries for these configuration elements have to be defined in the JPA query language. Of course, you can use `` or `@NamedNativeQuery` too. These elements let you define the query in native SQL by losing the database platform independence. + +[[jpa.query-methods.named-queries.xml-named-query-definition]] +=== XML Named Query Definition +To use XML configuration, add the necessary `` 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. + +.XML named query configuration +==== +[source, xml] +---- + + select u from User u where u.lastname = ?1 + +---- +==== + +The query has a special name that is used to resolve it at runtime. + +[[jpa.query-methods.named-queries.declaring-interfaces]] +=== Declaring Interfaces +To allow these named queries, specify the `UserRepositoryWithRewriter` as follows: + +.Query method declaration in UserRepository +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + List 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. + +[[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 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: + +.Declare query at the query method using `@Query` +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + @Query("select u from User u where u.emailAddress = ?1") + User findByEmailAddress(String emailAddress); +} +---- +==== + +[[jpa.query-methods.query-rewriter]] +=== 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. + +.Declare a QueryRewriter using `@Query` +==== +[source, java] +---- +public interface MyRepository extends JpaRepository { + + @Query(value = "select original_user_alias.* from SD_USER original_user_alias", + nativeQuery = true, + queryRewriter = MyQueryRewriter.class) + List findByNativeQuery(String param); + + @Query(value = "select original_user_alias from User original_user_alias", + queryRewriter = MyQueryRewriter.class) + List 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: + +.Example `QueryRewriter` +==== +[source, java] +---- +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. + +.Repository that provides the `QueryRewriter` +==== +[source, java] +---- +public interface MyRepository extends JpaRepository, QueryRewriter { + + @Query(value = "select original_user_alias.* from SD_USER original_user_alias", + nativeQuery = true, + queryRewriter = MyRepository.class) + List findByNativeQuery(String param); + + @Query(value = "select original_user_alias from User original_user_alias", + queryRewriter = MyRepository.class) + List 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. + +NOTE: In a CDI-based environment, Spring Data JPA will search the `BeanManager` for instances of your implementation of +`QueryRewriter`. + + +[[jpa.query-methods.at-query.advanced-like]] +=== 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: + +.Advanced `like` expressions in @Query +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + @Query("select u from User u where u.firstname like %?1") + List 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. + +[[jpa.query-methods.at-query.native]] +=== Native Queries + +The `@Query` annotation allows for running native queries by setting the `nativeQuery` flag to true, as shown in the following example: + +.Declare a native query at the query method using @Query +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + @Query(value = "SELECT * FROM USERS WHERE EMAIL_ADDRESS = ?1", nativeQuery = true) + User findByEmailAddress(String emailAddress); +} +---- + +==== + +NOTE: 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: + +.Declare native count queries for pagination at the query method by using `@Query` +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + @Query(value = "SELECT * FROM USERS WHERE LASTNAME = ?1", + countQuery = "SELECT count(*) FROM USERS WHERE LASTNAME = ?1", + nativeQuery = true) + Page 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. + +[[jpa.query-methods.sorting]] +== 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. + +NOTE: Using any non-referenceable path expression leads to an `Exception`. + +However, using `Sort` together with xref:jpa/query-methods.adoc#jpa.query-methods.at-query[`@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`: + +.Using `Sort` and `JpaSort` +==== +[source, java] +---- +public interface UserRepository extends JpaRepository { + + @Query("select u from User u where u.lastname like ?1%") + List findByAndSort(String lastname, Sort sort); + + @Query("select u.id, LENGTH(u.firstname) as fn_len from User u where u.lastname like ?1%") + List 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. +==== + +[[jpa.query-methods.scroll]] +== Scrolling Large Query Results + +When working with large data sets, <> can help to process those results efficiently without loading all results into memory. + +You have multiple options to consume large query results: + +1. <>. +You have learned in the previous chapter about `Pageable` and `PageRequest`. +2. <>. +This is a lighter variant than paging because it does not require the total result count. +3. <>. +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 <> for your particular arrangement. + +You can use the Scroll API with query methods, xref:jpa/query-by-example.adoc[Query-by-Example], and <>. + +NOTE: Scrolling with String-based query methods is not yet supported. +Scrolling is also not supported using stored `@Procedure` query methods. + +[[jpa.named-parameters]] +== 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: + +.Using named parameters +==== +[source,java] +---- +public interface UserRepository extends JpaRepository { + + @Query("select u from User u where u.firstname = :firstname or u.lastname = :lastname") + User findByLastnameOrFirstname(@Param("lastname") String lastname, + @Param("firstname") String firstname); +} +---- +==== + +NOTE: The method parameters are switched according to their order in the defined query. + +NOTE: 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. + +[[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 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: + +.Using SpEL expressions in repository query methods - entityName +==== +[source, java] +---- +@Entity +public class User { + + @Id + @GeneratedValue + Long id; + + String lastname; +} + +public interface UserRepository extends JpaRepository { + + @Query("select u from #{#entityName} u where u.lastname = ?1") + List findByLastname(String lastname); +} +---- +==== + +To avoid stating the actual entity name in the query string of a `@Query` annotation, you can use the `+#{#entityName}+` variable. + +NOTE: 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: + +.Using SpEL expressions in repository query methods - entityName with inheritance +==== +[source, java] +---- +@MappedSuperclass +public abstract class AbstractMappedType { + … + String attribute +} + +@Entity +public class ConcreteType extends AbstractMappedType { … } + +@NoRepositoryBean +public interface MappedTypeRepository + extends Repository { + + @Query("select t from #{#entityName} t where t.attribute = ?1") + List findAllByAttribute(String attribute); +} + +public interface ConcreteRepository + extends MappedTypeRepository { … } +---- +==== + +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. + +.Using SpEL expressions in repository query methods - accessing arguments. +==== +[source, java] +---- +@Query("select u from User u where u.firstname = ?1 and u.firstname=?#{[0]} and u.emailAddress = ?#{principal.emailAddress}") +List 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. + +.Using SpEL expressions in repository query methods - wildcard shortcut. +==== +[source, java] +---- +@Query("select u from User u where u.lastname like %:#{[0]}% and u.lastname like %:lastname%") +List 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. + + +.Using SpEL expressions in repository query methods - sanitizing input values. +==== +[source, java] +---- +@Query("select u from User u where u.firstname like %?#{escape([0])}% escape ?#{escapeCharacter()}") +List 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. + +[[jpa.query.other-methods]] +== Other Methods + +Spring Data JPA offers many ways to build queries. +But sometimes, your query may simply be too complicated for the techniques offered. +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 <>. 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. +* Another option is putting your query inside the database and then using either Spring Data JPA's xref:jpa/stored-procedures.adoc[`@StoredProcedure` annotation] or if it's a database function using the xref:jpa/query-methods.adoc#jpa.query-methods.at-query[`@Query` annotation] and invoking it with a `CALL`. + +These tactics may be most effective when you need maximum control of your query, while still letting Spring Data JPA provide resource management. + +[[jpa.modifying-queries]] +== 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 {spring-data-commons-docs-url}/repositories/custom-implementations.html[Custom Implementations for Spring Data Repositories]. +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: + +.Declaring manipulating queries +==== +[source, java] +---- +@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 https://jakarta.ee/specifications/persistence/2.2/apidocs/javax/persistence/entitymanager[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. + +[[jpa.modifying-queries.derived-delete]] +=== 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: + +.Using a derived delete query +==== +[source, java] +---- +interface UserRepository extends Repository { + + 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 users)` on the result and keeping behavior in sync with the implementations of other `delete(…)` methods in `CrudRepository`. + +[[jpa.query-hints]] +== 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: + +.Using QueryHints with a repository method +==== +[source, java] +---- +public interface UserRepository extends Repository { + + @QueryHints(value = { @QueryHint(name = "name", value = "value")}, + forCounting = false) + Page 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. + +[[jpa.query-hints.comments]] +=== Adding Comments to Queries +Sometimes, you need to debug a query based upon database performance. +The query your database administrator shows you may look VERY different than what you wrote using `@Query`, or it may look +nothing like what you presume Spring Data JPA has generated regarding a custom finder or if you used query by example. + +To make this process easier, you can insert custom comments into almost any JPA operation, whether its a query or other operation +by applying the `@Meta` annotation. + +.Apply `@Meta` annotation to repository operations +==== +[source, java] +---- +public interface RoleRepository extends JpaRepository { + + @Meta(comment = "find roles by name") + List findByName(String name); + + @Override + @Meta(comment = "find roles using QBE") + List findAll(Example example); + + @Meta(comment = "count roles for a given name") + long countByName(String name); + + @Override + @Meta(comment = "exists based on QBE") + boolean exists(Example example); +} +---- +==== + +This sample repository has a mixture of custom finders as well as overriding the inherited operations from `JpaRepository`. +Either way, the `@Meta` annotation lets you add a `comment` that will be inserted into queries before they are sent to the database. + +It's also important to note that this feature isn't confined solely to queries. It extends to the `count` and `exists` operations. +And while not shown, it also extends to certain `delete` operations. + +IMPORTANT: While we have attempted to apply this feature everywhere possible, some operations of the underlying `EntityManager` don't support comments. For example, `entityManager.createQuery()` is clearly documented as supporting comments, but `entityManager.find()` operations do not. + +Neither JPQL logging nor SQL logging is a standard in JPA, so each provider requires custom configuration, as shown the sections below. + +[[activating-hibernate-comments]] +==== Activating Hibernate comments +To activate query comments in Hibernate, you must set `hibernate.use_sql_comments` to `true`. + +If you are using Java-based configuration settings, this can be done like this: + +.Java-based JPA configuration +==== +[source, java] +---- +@Bean +public Properties jpaProperties() { + + Properties properties = new Properties(); + properties.setProperty("hibernate.use_sql_comments", "true"); + return properties; +} +---- +==== + +If you have a `persistence.xml` file, you can apply it there: + +.`persistence.xml`-based configuration +==== +[source, xml] +---- + + + ...registered classes... + + + + + +---- +==== + +Finally, if you are using Spring Boot, then you can set it up inside your `application.properties` file: + +.Spring Boot property-based configuration +==== +---- +spring.jpa.properties.hibernate.use_sql_comments=true +---- +==== + +[[activating-eclipselink-comments]] +==== Activating EclipseLink comments +To activate query comments in EclipseLink, you must set `eclipselink.logging.level.sql` to `FINE`. + +If you are using Java-based configuration settings, this can be done like this: + +.Java-based JPA configuration +==== +[source, java] +---- +@Bean +public Properties jpaProperties() { + + Properties properties = new Properties(); + properties.setProperty("eclipselink.logging.level.sql", "FINE"); + return properties; +} +---- +==== + +If you have a `persistence.xml` file, you can apply it there: + +.`persistence.xml`-based configuration +==== +[source, xml] +---- + + + ...registered classes... + + + + + +---- +==== + +Finally, if you are using Spring Boot, then you can set it up inside your `application.properties` file: + +.Spring Boot property-based configuration +==== +---- +spring.jpa.properties.eclipselink.logging.level.sql=FINE +---- +==== + + +[[jpa.entity-graph]] +== 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: + +.Defining a named entity graph on an entity. +==== +[source, java] +---- +@Entity +@NamedEntityGraph(name = "GroupInfo.detail", + attributeNodes = @NamedAttributeNode("members")) +public class GroupInfo { + + // default fetch mode is lazy. + @ManyToMany + List members = new ArrayList(); + + … +} +---- +==== + +The following example shows how to reference a named entity graph on a repository query method: + +.Referencing a named entity graph definition on a repository query method. +==== +[source, java] +---- +public interface GroupRepository extends CrudRepository { + + @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: + +.Using AD-HOC entity graph definition on an repository query method. +==== +[source, java] +---- +public interface GroupRepository extends CrudRepository { + + @EntityGraph(attributePaths = { "members" }) + GroupInfo getByGroupName(String name); + +} +---- +==== + +[[projections]] +== Projections + +Spring Data JPA supports {spring-data-commons-docs-url}/repository-projects.html[Spring Data Commons Projections]. + +NOTE: It is important to note that {spring-data-commons-docs-url}/repository-projects.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`] \ No newline at end of file diff --git a/src/main/antora/modules/ROOT/pages/jpa/specifications.adoc b/src/main/antora/modules/ROOT/pages/jpa/specifications.adoc new file mode 100644 index 0000000000..e376e32afa --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/specifications.adoc @@ -0,0 +1,99 @@ +[[specifications]] += 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: + +[source, java] +---- +public interface CustomerRepository extends CrudRepository, JpaSpecificationExecutor { + … +} +---- + +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] +---- +List findAll(Specification spec); +---- + +The `Specification` interface is defined as follows: + +[source, java] +---- +public interface Specification { + Predicate toPredicate(Root 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: + +.Specifications for a Customer +==== +[source, java] +---- +public class CustomerSpecs { + + + public static Specification isLongTermCustomer() { + return (root, query, builder) -> { + LocalDate date = LocalDate.now().minusYears(2); + return builder.lessThan(root.get(Customer_.createdAt), date); + }; + } + + public static Specification 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 link:$$https://docs.jboss.org/hibernate/jpamodelgen/1.0/reference/en-US/html_single/#whatisit$$[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: + +.Using a simple Specification +==== +[source, java] +---- +List 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: + +.Combined Specifications +==== +[source, java] +---- +MonetaryAmount amount = new MonetaryAmount(200.0, Currencies.DOLLAR); +List 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. + +.Using a `Specification` to delete entries. +==== +[source, java] +---- +Specification 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. +==== + + diff --git a/src/main/antora/modules/ROOT/pages/jpa/stored-procedures.adoc b/src/main/antora/modules/ROOT/pages/jpa/stored-procedures.adoc new file mode 100644 index 0000000000..8985be4515 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/stored-procedures.adoc @@ -0,0 +1,97 @@ +[[jpa.stored-procedures]] += 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: + +.The definition of the `plus1inout` procedure in HSQL DB. +==== +[source, sql] +---- +/; +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. + +[[jpa.stored-procedure-entity-metadata]] +.StoredProcedure metadata definitions on an entity. +==== +[source, java] +---- +@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: + +[[jpa.stored-procedure-reference]] +.Referencing explicitly mapped procedure with name "plus1inout" in database. +==== +[source, java] +---- +@Procedure("plus1inout") +Integer explicitlyNamedPlus1inout(Integer arg); +---- +==== + +The following example is equivalent to the previous one but uses the `procedureName` alias: + +.Referencing implicitly mapped procedure with name "plus1inout" in database via `procedureName` alias. +==== +[source, java] +---- +@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. + +.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name. +==== +[source, java] +---- +@Procedure +Integer plus1inout(@Param("arg") Integer arg); +---- +==== + +The following example shows how to reference a stored procedure by referencing the `@NamedStoredProcedureQuery.name` attribute. + +.Referencing explicitly mapped named stored procedure "User.plus1IO" in `EntityManager`. +==== +[source, java] +---- +@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. + + diff --git a/src/main/antora/modules/ROOT/pages/jpa/transactions.adoc b/src/main/antora/modules/ROOT/pages/jpa/transactions.adoc new file mode 100644 index 0000000000..f4abfccdd3 --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/jpa/transactions.adoc @@ -0,0 +1,91 @@ +[[transactions]] += Transactionality + +By default, methods inherited from `CrudRepository` inherit the transactional configuration from link:$$https://docs.spring.io/spring-data/data-jpa/docs/current/api/org/springframework/data/jpa/repository/support/SimpleJpaRepository.html$$[`SimpleJpaRepository`]. +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: + +.Custom transaction configuration for CRUD +==== +[source, java] +---- +public interface UserRepository extends CrudRepository { + + @Override + @Transactional(timeout = 10) + public List 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: + +.Using a facade to define transactions for multiple repository calls +==== +[source, java] +---- +@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 `` 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]] +== Transactional query methods + +Declared query methods (including default methods) do not get any transaction configuration applied by default. +To run those methods transactionally, use `@Transactional` at the repository interface you define, as shown in the following example: + +.Using @Transactional at query methods +==== +[source, java] +---- +@Transactional(readOnly = true) +interface UserRepository extends JpaRepository { + + List 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`. +==== + +[NOTE] +==== +You can use transactions for read-only queries and mark them as such by setting the `readOnly` flag. Doing so does not, however, act as a check that you do not trigger a manipulating query (although some databases reject `INSERT` and `UPDATE` statements inside a read-only transaction). The `readOnly` flag is instead propagated as a hint to the underlying JDBC driver for performance optimizations. Furthermore, Spring performs some optimizations on the underlying JPA provider. For example, when used with Hibernate, the flush mode is set to `NEVER` when you configure a transaction as `readOnly`, which causes Hibernate to skip dirty checks (a noticeable improvement on large object trees). +==== + diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc deleted file mode 100644 index 3e3d7ec919..0000000000 --- a/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,43 +0,0 @@ -= Spring Data JPA - Reference Documentation -Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Paluch; Jay Bryant; Greg Turnquist -:revnumber: {version} -:revdate: {localdate} -ifdef::backend-epub3[:front-cover-image: image:epub-cover.png[Front Cover,1050,1600]] -:spring-data-commons-docs: ../../../../spring-data-commons/src/main/asciidoc -:spring-framework-docs: https://docs.spring.io/spring-framework/docs/{springVersion}/spring-framework-reference/ -:feature-scroll: true - -(C) 2008-2023 The original authors. - -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. - -include::preface.adoc[] - -include::{spring-data-commons-docs}/upgrade.adoc[leveloffset=+1] - -include::{spring-data-commons-docs}/dependencies.adoc[leveloffset=+1] - -include::{spring-data-commons-docs}/repositories.adoc[leveloffset=+1] - -[[reference]] -== Reference Documentation - -include::jpa.adoc[leveloffset=+2] - -include::envers.adoc[leveloffset=+2] - -[[appendix]] -== Appendix - -:numbered!: -include::{spring-data-commons-docs}/repository-namespace-reference.adoc[leveloffset=+1] - -include::{spring-data-commons-docs}/repository-populator-namespace-reference.adoc[leveloffset=+1] - -include::{spring-data-commons-docs}/repository-query-keywords-reference.adoc[leveloffset=+1] - -include::{spring-data-commons-docs}/repository-query-return-types-reference.adoc[leveloffset=+1] - -include::faq.adoc[leveloffset=+1] - -include::glossary.adoc[leveloffset=+1] diff --git a/src/main/asciidoc/jpa.adoc b/src/main/asciidoc/jpa.adoc deleted file mode 100644 index e8178c49df..0000000000 --- a/src/main/asciidoc/jpa.adoc +++ /dev/null @@ -1,1491 +0,0 @@ -[[jpa.repositories]] -= JPA Repositories - -This chapter points out the specialties for repository support for JPA. This builds on the core repository support explained in "`<>`". Make sure you have a sound understanding of the basic concepts explained there. - -[[jpa.introduction]] -== Introduction - -This section describes the basics of configuring Spring Data JPA through either: - -* "`<>`" (XML configuration) -* "`<>`" (Java configuration) - -[[jpa.java-config]] -=== Annotation-based Configuration -The Spring Data JPA repositories support can be activated through both JavaConfig as well as a custom XML namespace, as shown in the following example: - -.Spring Data JPA repositories using JavaConfig -==== -[source, java] ----- -@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; - } -} ----- -==== -NOTE: 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. - -[[jpa.namespace]] -=== 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: - -.Setting up JPA repositories by using the namespace -==== -[source, xml] ----- - - - - - - ----- -==== - -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 "`<>`". 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 -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: - -.Custom JPA-specific attributes of the `repositories` element -[options = "autowidth"] -|=============== -|`entity-manager-factory-ref`|Explicitly wire the `EntityManagerFactory` to be used with the repositories being detected by the `repositories` element. Usually used if multiple `EntityManagerFactory` beans are used within the application. If not configured, Spring Data automatically looks up the `EntityManagerFactory` bean with the name `entityManagerFactory` in the `ApplicationContext`. -|`transaction-manager-ref`|Explicitly wire the `PlatformTransactionManager` to be used with the repositories being detected by the `repositories` element. Usually only necessary if multiple transaction managers or `EntityManagerFactory` beans have been configured. Default to a single defined `PlatformTransactionManager` inside the current `ApplicationContext`. -|=============== - -NOTE: Spring Data JPA requires a `PlatformTransactionManager` bean named `transactionManager` to be present if no explicit `transaction-manager-ref` is defined. - -[[jpa.bootstrap-mode]] -=== 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 as `LAZY`, but triggering repository initialization in response to an `ContextRefreshedEvent` so that repositories are verified before the application has completely started. - -[[jpa.bootstrap-mode.recommendations]] -==== 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. - -[[jpa.entity-persistence]] -== Persisting Entities - -This section describes how to persist (save) entities with Spring Data JPA. - -[[jpa.entity-persistence.saving-entites]] -=== 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. - -[[jpa.entity-persistence.saving-entites.strategies]] -==== Entity State-detection Strategies -Spring Data JPA offers the following strategies to detect whether an entity is new or not: - -1. 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 is `null`, then the entity is assumed to be new. - Otherwise, it is assumed to be not new. -2. Implementing `Persistable`: If an entity implements `Persistable`, Spring Data JPA delegates the new detection to the `isNew(…)` method of the entity. See the link:$$https://docs.spring.io/spring-data/data-commons/docs/current/api/index.html?org/springframework/data/domain/Persistable.html$$[JavaDoc] for details. -3. Implementing `EntityInformation`: You can customize the `EntityInformation` abstraction used in the `SimpleJpaRepository` implementation by creating a subclass of `JpaRepositoryFactory` and overriding the `getEntityInformation(…)` method accordingly. You then have to register the custom implementation of `JpaRepositoryFactory` as a Spring bean. Note that this should be rarely necessary. See the link:$$https://docs.spring.io/spring-data/data-jpa/docs/current/api/index.html?org/springframework/data/jpa/repository/support/JpaRepositoryFactory.html$$[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: - -.A base class for entities with manually assigned identifiers -==== -[source, java] ----- -@MappedSuperclass -public abstract class AbstractEntity implements Persistable { - - @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. -==== - -[[jpa.query-methods]] -== Query Methods - -This section describes the various ways to create a query with Spring Data JPA. - -[[jpa.sample-app.finders.strategies]] -=== 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 <>. - -[[jpa.query-methods.declared-queries]] -==== 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 <> for more information) or rather annotate your query method with `@Query` (see <> for details). - -[[jpa.query-methods.query-creation]] -=== Query Creation - -Generally, the query creation mechanism for JPA works as described in "`<>`". The following example shows what a JPA query method translates into: - -.Query creation from method names -==== ----- -public interface UserRepository extends Repository { - - List 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 "`<>`". -==== - -The following table describes the keywords supported for JPA and what a method containing that keyword translates to: - -.Supported keywords inside method names -[options = "header, autowidth"] -|=============== -|Keyword|Sample|JPQL snippet -|`Distinct`|`findDistinctByLastnameAndFirstname`|`select distinct ... where x.lastname = ?1 and x.firstname = ?2` -|`And`|`findByLastnameAndFirstname`|`… where x.lastname = ?1 and x.firstname = ?2` -|`Or`|`findByLastnameOrFirstname`|`… where x.lastname = ?1 or x.firstname = ?2` -|`Is`, `Equals`|`findByFirstname`,`findByFirstnameIs`,`findByFirstnameEquals`|`… where x.firstname = ?1` -|`Between`|`findByStartDateBetween`|`… where x.startDate between ?1 and ?2` -|`LessThan`|`findByAgeLessThan`|`… where x.age < ?1` -|`LessThanEqual`|`findByAgeLessThanEqual`|`… where x.age \<= ?1` -|`GreaterThan`|`findByAgeGreaterThan`|`… where x.age > ?1` -|`GreaterThanEqual`|`findByAgeGreaterThanEqual`|`… where x.age >= ?1` -|`After`|`findByStartDateAfter`|`… where x.startDate > ?1` -|`Before`|`findByStartDateBefore`|`… where x.startDate < ?1` -|`IsNull`, `Null`|`findByAge(Is)Null`|`… where x.age is null` -|`IsNotNull`, `NotNull`|`findByAge(Is)NotNull`|`… where x.age not null` -|`Like`|`findByFirstnameLike`|`… where x.firstname like ?1` -|`NotLike`|`findByFirstnameNotLike`|`… where x.firstname not like ?1` -|`StartingWith`|`findByFirstnameStartingWith`|`… where x.firstname like ?1` (parameter bound with appended `%`) -|`EndingWith`|`findByFirstnameEndingWith`|`… where x.firstname like ?1` (parameter bound with prepended `%`) -|`Containing`|`findByFirstnameContaining`|`… where x.firstname like ?1` (parameter bound wrapped in `%`) -|`OrderBy`|`findByAgeOrderByLastnameDesc`|`… where x.age = ?1 order by x.lastname desc` -|`Not`|`findByLastnameNot`|`… where x.lastname <> ?1` -|`In`|`findByAgeIn(Collection ages)`|`… where x.age in ?1` -|`NotIn`|`findByAgeNotIn(Collection ages)`|`… where x.age not in ?1` -|`True`|`findByActiveTrue()`|`… where x.active = true` -|`False`|`findByActiveFalse()`|`… where x.active = false` -|`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 "`<>`". - -[WARNING] -==== -`DISTINCT` can be tricky and not always producing the results you expect. -For example, `select distinct u from User u` will produce a complete different result than `select distinct u.lastname from User u`. -In the first case, since you are including `User.id`, nothing will duplicated, hence you'll get the whole table, and it would be of `User` objects. - -However, that latter query would narrow the focus to just `User.lastname` and find all unique last names for that table. -This would also yield a `List` result set instead of a `List result set. - - -`countDistinctByLastname(String lastname)` can also produce unexpected results. -Spring Data JPA will derive `select count(distinct u.id) from User u where u.lastname = ?1`. -Again, since `u.id` won't hit any duplicates, this query will count up all the users that had the binding last name. -Which would the same as `countByLastname(String lastname)`! - -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 `distinct` sometimes requires writing the query by hand and using `@Query` to best capture the information you seek, since you also may be needing a projection -to capture the result set. -==== - -[[jpa.query-methods.named-queries.annotation-based-configuration]] -==== 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. - -.Annotation-based named query configuration -==== -[source, java] ----- -@Entity -@NamedQuery(name = "User.findByEmailAddress", - query = "select u from User u where u.emailAddress = ?1") -public class User { - -} ----- -==== - -[[jpa.query-methods.named-queries]] -=== Using JPA Named Queries - -NOTE: The examples use the `` element and `@NamedQuery` annotation. The queries for these configuration elements have to be defined in the JPA query language. Of course, you can use `` or `@NamedNativeQuery` too. These elements let you define the query in native SQL by losing the database platform independence. - -[[jpa.query-methods.named-queries.xml-named-query-definition]] -==== XML Named Query Definition -To use XML configuration, add the necessary `` 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. - -.XML named query configuration -==== -[source, xml] ----- - - select u from User u where u.lastname = ?1 - ----- -==== - -The query has a special name that is used to resolve it at runtime. - -[[jpa.query-methods.named-queries.declaring-interfaces]] -==== Declaring Interfaces -To allow these named queries, specify the `UserRepositoryWithRewriter` as follows: - -.Query method declaration in UserRepository -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - List 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. - -[[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 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: - -.Declare query at the query method using `@Query` -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - @Query("select u from User u where u.emailAddress = ?1") - User findByEmailAddress(String emailAddress); -} ----- -==== - -[[jpa.query-methods.query-rewriter]] -==== 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. - -.Declare a QueryRewriter using `@Query` -==== -[source, java] ----- -public interface MyRepository extends JpaRepository { - - @Query(value = "select original_user_alias.* from SD_USER original_user_alias", - nativeQuery = true, - queryRewriter = MyQueryRewriter.class) - List findByNativeQuery(String param); - - @Query(value = "select original_user_alias from User original_user_alias", - queryRewriter = MyQueryRewriter.class) - List 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: - -.Example `QueryRewriter` -==== -[source, java] ----- -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. - -.Repository that provides the `QueryRewriter` -==== -[source, java] ----- -public interface MyRepository extends JpaRepository, QueryRewriter { - - @Query(value = "select original_user_alias.* from SD_USER original_user_alias", - nativeQuery = true, - queryRewriter = MyRepository.class) - List findByNativeQuery(String param); - - @Query(value = "select original_user_alias from User original_user_alias", - queryRewriter = MyRepository.class) - List 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. - -NOTE: In a CDI-based environment, Spring Data JPA will search the `BeanManager` for instances of your implementation of -`QueryRewriter`. - - -[[jpa.query-methods.at-query.advanced-like]] -==== 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: - -.Advanced `like` expressions in @Query -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - @Query("select u from User u where u.firstname like %?1") - List 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. - -[[jpa.query-methods.at-query.native]] -==== Native Queries - -The `@Query` annotation allows for running native queries by setting the `nativeQuery` flag to true, as shown in the following example: - -.Declare a native query at the query method using @Query -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - @Query(value = "SELECT * FROM USERS WHERE EMAIL_ADDRESS = ?1", nativeQuery = true) - User findByEmailAddress(String emailAddress); -} ----- - -==== - -NOTE: 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: - -.Declare native count queries for pagination at the query method by using `@Query` -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - @Query(value = "SELECT * FROM USERS WHERE LASTNAME = ?1", - countQuery = "SELECT count(*) FROM USERS WHERE LASTNAME = ?1", - nativeQuery = true) - Page 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. - -[[jpa.query-methods.sorting]] -=== 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. - -NOTE: Using any non-referenceable path expression leads to an `Exception`. - -However, using `Sort` together with <> 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`: - -.Using `Sort` and `JpaSort` -==== -[source, java] ----- -public interface UserRepository extends JpaRepository { - - @Query("select u from User u where u.lastname like ?1%") - List findByAndSort(String lastname, Sort sort); - - @Query("select u.id, LENGTH(u.firstname) as fn_len from User u where u.lastname like ?1%") - List 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. -==== - -[[jpa.query-methods.scroll]] -=== Scrolling Large Query Results - -When working with large data sets, <> can help to process those results efficiently without loading all results into memory. - -You have multiple options to consume large query results: - -1. <>. -You have learned in the previous chapter about `Pageable` and `PageRequest`. -2. <>. -This is a lighter variant than paging because it does not require the total result count. -3. <>. -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 <> for your particular arrangement. - -You can use the Scroll API with query methods, <>, and <>. - -NOTE: Scrolling with String-based query methods is not yet supported. -Scrolling is also not supported using stored `@Procedure` query methods. - -[[jpa.named-parameters]] -=== 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: - -.Using named parameters -==== -[source,java] ----- -public interface UserRepository extends JpaRepository { - - @Query("select u from User u where u.firstname = :firstname or u.lastname = :lastname") - User findByLastnameOrFirstname(@Param("lastname") String lastname, - @Param("firstname") String firstname); -} ----- -==== - -NOTE: The method parameters are switched according to their order in the defined query. - -NOTE: 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. - -[[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 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: - -.Using SpEL expressions in repository query methods - entityName -==== -[source, java] ----- -@Entity -public class User { - - @Id - @GeneratedValue - Long id; - - String lastname; -} - -public interface UserRepository extends JpaRepository { - - @Query("select u from #{#entityName} u where u.lastname = ?1") - List findByLastname(String lastname); -} ----- -==== - -To avoid stating the actual entity name in the query string of a `@Query` annotation, you can use the `+#{#entityName}+` variable. - -NOTE: 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: - -.Using SpEL expressions in repository query methods - entityName with inheritance -==== -[source, java] ----- -@MappedSuperclass -public abstract class AbstractMappedType { - … - String attribute -} - -@Entity -public class ConcreteType extends AbstractMappedType { … } - -@NoRepositoryBean -public interface MappedTypeRepository - extends Repository { - - @Query("select t from #{#entityName} t where t.attribute = ?1") - List findAllByAttribute(String attribute); -} - -public interface ConcreteRepository - extends MappedTypeRepository { … } ----- -==== - -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. - -.Using SpEL expressions in repository query methods - accessing arguments. -==== -[source, java] ----- -@Query("select u from User u where u.firstname = ?1 and u.firstname=?#{[0]} and u.emailAddress = ?#{principal.emailAddress}") -List 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. - -.Using SpEL expressions in repository query methods - wildcard shortcut. -==== -[source, java] ----- -@Query("select u from User u where u.lastname like %:#{[0]}% and u.lastname like %:lastname%") -List 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. - - -.Using SpEL expressions in repository query methods - sanitizing input values. -==== -[source, java] ----- -@Query("select u from User u where u.firstname like %?#{escape([0])}% escape ?#{escapeCharacter()}") -List 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. - -[[jpa.query.other-methods]] -=== Other Methods - -Spring Data JPA offers many ways to build queries. -But sometimes, your query may simply be too complicated for the techniques offered. -In that situation, consider: - -* If you haven't already, simply write the query yourself using <>. -* If that doesn't fit your needs, consider implementing a <>. 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. -* Another option is putting your query inside the database and then using either Spring Data JPA's <> or if it's a database function using the <> and invoking it with a `CALL`. - -These tactics may be most effective when you need maximum control of your query, while still letting Spring Data JPA provide resource management. - -[[jpa.modifying-queries]] -=== 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 "`<>`". -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: - -.Declaring manipulating queries -==== -[source, java] ----- -@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 https://jakarta.ee/specifications/persistence/2.2/apidocs/javax/persistence/entitymanager[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. - -[[jpa.modifying-queries.derived-delete]] -==== 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: - -.Using a derived delete query -==== -[source, java] ----- -interface UserRepository extends Repository { - - 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 users)` on the result and keeping behavior in sync with the implementations of other `delete(…)` methods in `CrudRepository`. - -[[jpa.query-hints]] -=== 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: - -.Using QueryHints with a repository method -==== -[source, java] ----- -public interface UserRepository extends Repository { - - @QueryHints(value = { @QueryHint(name = "name", value = "value")}, - forCounting = false) - Page 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. - -[[jpa.query-hints.comments]] -==== Adding Comments to Queries -Sometimes, you need to debug a query based upon database performance. -The query your database administrator shows you may look VERY different than what you wrote using `@Query`, or it may look -nothing like what you presume Spring Data JPA has generated regarding a custom finder or if you used query by example. - -To make this process easier, you can insert custom comments into almost any JPA operation, whether its a query or other operation -by applying the `@Meta` annotation. - -.Apply `@Meta` annotation to repository operations -==== -[source, java] ----- -public interface RoleRepository extends JpaRepository { - - @Meta(comment = "find roles by name") - List findByName(String name); - - @Override - @Meta(comment = "find roles using QBE") - List findAll(Example example); - - @Meta(comment = "count roles for a given name") - long countByName(String name); - - @Override - @Meta(comment = "exists based on QBE") - boolean exists(Example example); -} ----- -==== - -This sample repository has a mixture of custom finders as well as overriding the inherited operations from `JpaRepository`. -Either way, the `@Meta` annotation lets you add a `comment` that will be inserted into queries before they are sent to the database. - -It's also important to note that this feature isn't confined solely to queries. It extends to the `count` and `exists` operations. -And while not shown, it also extends to certain `delete` operations. - -IMPORTANT: While we have attempted to apply this feature everywhere possible, some operations of the underlying `EntityManager` don't support comments. For example, `entityManager.createQuery()` is clearly documented as supporting comments, but `entityManager.find()` operations do not. - -Neither JPQL logging nor SQL logging is a standard in JPA, so each provider requires custom configuration, as shown the sections below. - -===== Activating Hibernate comments -To activate query comments in Hibernate, you must set `hibernate.use_sql_comments` to `true`. - -If you are using Java-based configuration settings, this can be done like this: - -.Java-based JPA configuration -==== -[source, java] ----- -@Bean -public Properties jpaProperties() { - - Properties properties = new Properties(); - properties.setProperty("hibernate.use_sql_comments", "true"); - return properties; -} ----- -==== - -If you have a `persistence.xml` file, you can apply it there: - -.`persistence.xml`-based configuration -==== -[source, xml] ----- - - - ...registered classes... - - - - - ----- -==== - -Finally, if you are using Spring Boot, then you can set it up inside your `application.properties` file: - -.Spring Boot property-based configuration -==== ----- -spring.jpa.properties.hibernate.use_sql_comments=true ----- -==== - -===== Activating EclipseLink comments -To activate query comments in EclipseLink, you must set `eclipselink.logging.level.sql` to `FINE`. - -If you are using Java-based configuration settings, this can be done like this: - -.Java-based JPA configuration -==== -[source, java] ----- -@Bean -public Properties jpaProperties() { - - Properties properties = new Properties(); - properties.setProperty("eclipselink.logging.level.sql", "FINE"); - return properties; -} ----- -==== - -If you have a `persistence.xml` file, you can apply it there: - -.`persistence.xml`-based configuration -==== -[source, xml] ----- - - - ...registered classes... - - - - - ----- -==== - -Finally, if you are using Spring Boot, then you can set it up inside your `application.properties` file: - -.Spring Boot property-based configuration -==== ----- -spring.jpa.properties.eclipselink.logging.level.sql=FINE ----- -==== - - -[[jpa.entity-graph]] -=== 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: - -.Defining a named entity graph on an entity. -==== -[source, java] ----- -@Entity -@NamedEntityGraph(name = "GroupInfo.detail", - attributeNodes = @NamedAttributeNode("members")) -public class GroupInfo { - - // default fetch mode is lazy. - @ManyToMany - List members = new ArrayList(); - - … -} ----- -==== - -The following example shows how to reference a named entity graph on a repository query method: - -.Referencing a named entity graph definition on a repository query method. -==== -[source, java] ----- -public interface GroupRepository extends CrudRepository { - - @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: - -.Using AD-HOC entity graph definition on an repository query method. -==== -[source, java] ----- -public interface GroupRepository extends CrudRepository { - - @EntityGraph(attributePaths = { "members" }) - GroupInfo getByGroupName(String name); - -} ----- -==== - -:repository-projections-trailing-dto-fragment: ../../../../spring-data-jpa/src/main/asciidoc/repository-projections-dto-limitations.adoc - -include::{spring-data-commons-docs}/repository-projections.adoc[leveloffset=+2] - -[[jpa.stored-procedures]] -== 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: - -.The definition of the `plus1inout` procedure in HSQL DB. -==== -[source, sql] ----- -/; -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. - -[[jpa.stored-procedure-entity-metadata]] -.StoredProcedure metadata definitions on an entity. -==== -[source, java] ----- -@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: - -[[jpa.stored-procedure-reference]] -.Referencing explicitly mapped procedure with name "plus1inout" in database. -==== -[source, java] ----- -@Procedure("plus1inout") -Integer explicitlyNamedPlus1inout(Integer arg); ----- -==== - -The following example is equivalent to the previous one but uses the `procedureName` alias: - -.Referencing implicitly mapped procedure with name "plus1inout" in database via `procedureName` alias. -==== -[source, java] ----- -@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. - -.Referencing implicitly mapped named stored procedure "User.plus1" in `EntityManager` by using the method name. -==== -[source, java] ----- -@Procedure -Integer plus1inout(@Param("arg") Integer arg); ----- -==== - -The following example shows how to reference a stored procedure by referencing the `@NamedStoredProcedureQuery.name` attribute. - -.Referencing explicitly mapped named stored procedure "User.plus1IO" in `EntityManager`. -==== -[source, java] ----- -@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. - - -[[specifications]] -== 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: - -[source, java] ----- -public interface CustomerRepository extends CrudRepository, JpaSpecificationExecutor { - … -} ----- - -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] ----- -List findAll(Specification spec); ----- - -The `Specification` interface is defined as follows: - -[source, java] ----- -public interface Specification { - Predicate toPredicate(Root 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: - -.Specifications for a Customer -==== -[source, java] ----- -public class CustomerSpecs { - - - public static Specification isLongTermCustomer() { - return (root, query, builder) -> { - LocalDate date = LocalDate.now().minusYears(2); - return builder.lessThan(root.get(Customer_.createdAt), date); - }; - } - - public static Specification 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 link:$$https://docs.jboss.org/hibernate/jpamodelgen/1.0/reference/en-US/html_single/#whatisit$$[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: - -.Using a simple Specification -==== -[source, java] ----- -List 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: - -.Combined Specifications -==== -[source, java] ----- -MonetaryAmount amount = new MonetaryAmount(200.0, Currencies.DOLLAR); -List 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. - -.Using a `Specification` to delete entries. -==== -[source, java] ----- -Specification 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. -==== - -include::{spring-data-commons-docs}/query-by-example.adoc[leveloffset=+1] -include::query-by-example.adoc[leveloffset=+1] - -[[transactions]] -== Transactionality - -By default, methods inherited from `CrudRepository` inherit the transactional configuration from link:$$https://docs.spring.io/spring-data/data-jpa/docs/current/api/org/springframework/data/jpa/repository/support/SimpleJpaRepository.html$$[`SimpleJpaRepository`]. -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: - -.Custom transaction configuration for CRUD -==== -[source, java] ----- -public interface UserRepository extends CrudRepository { - - @Override - @Transactional(timeout = 10) - public List 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: - -.Using a facade to define transactions for multiple repository calls -==== -[source, java] ----- -@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 `` 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]] -=== Transactional query methods - -Declared query methods (including default methods) do not get any transaction configuration applied by default. -To run those methods transactionally, use `@Transactional` at the repository interface you define, as shown in the following example: - -.Using @Transactional at query methods -==== -[source, java] ----- -@Transactional(readOnly = true) -interface UserRepository extends JpaRepository { - - List 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`. -==== - -[NOTE] -==== -You can use transactions for read-only queries and mark them as such by setting the `readOnly` flag. Doing so does not, however, act as a check that you do not trigger a manipulating query (although some databases reject `INSERT` and `UPDATE` statements inside a read-only transaction). The `readOnly` flag is instead propagated as a hint to the underlying JDBC driver for performance optimizations. Furthermore, Spring performs some optimizations on the underlying JPA provider. For example, when used with Hibernate, the flush mode is set to `NEVER` when you configure a transaction as `readOnly`, which causes Hibernate to skip dirty checks (a noticeable improvement on large object trees). -==== - -[[locking]] -== Locking -To specify the lock mode to be used, you can use the `@Lock` annotation on query methods, as shown in the following example: - -.Defining lock metadata on query methods -==== -[source, java] ----- -interface UserRepository extends Repository { - - // Plain query method - @Lock(LockModeType.READ) - List 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: - -.Defining lock metadata on CRUD methods -==== -[source, java] ----- -interface UserRepository extends Repository { - - // Redeclaration of a CRUD method - @Lock(LockModeType.READ) - List findAll(); -} ----- -==== - -:leveloffset: +1 - -include::{spring-data-commons-docs}/auditing.adoc[] - -:leveloffset: -1 - -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. - -[[jpa.auditing]] -== JPA Auditing - -[[jpa.auditing.configuration]] -=== 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: - -.Auditing configuration orm.xml -==== -[source, xml] ----- - - - - - - - ----- -==== - -You can also enable the `AuditingEntityListener` on a per-entity basis by using the `@EntityListeners` annotation, as follows: - -==== -[source, java] ----- -@Entity -@EntityListeners(AuditingEntityListener.class) -public class MyEntity { - -} ----- -==== - -NOTE: 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: - -.Activating auditing using XML configuration -==== -[source, xml] ----- - ----- -==== - -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: - -.Activating auditing with Java configuration -==== -[source, java] ----- -@Configuration -@EnableJpaAuditing -class Config { - - @Bean - public AuditorAware 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`. - -[[jpa.misc]] -= Miscellaneous Considerations - -[[jpa.misc.jpa-context]] -== Using `JpaContext` in Custom Implementations - -When working with multiple `EntityManager` instances and <>, 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: - -.Using `JpaContext` in a custom repository implementation -==== -[source, java] ----- -class 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. - -[[jpa.misc.merging-persistence-units]] -== 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: - -.Using MergingPersistenceUnitmanager -==== -[source, xml] ----- - - - - - ----- -==== - -[[jpa.misc.entity-scanning]] -=== 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: - -.Using ClasspathScanningPersistenceUnitPostProcessor -==== -[source, xml] ----- - - - - - - - - - - ----- -==== - -NOTE: 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 link:{springJavadocUrl}org/springframework/orm/jpa/LocalContainerEntityManagerFactoryBean.html#setPackagesToScan(java.lang.String...)$$[JavaDoc] for details. - -[[jpd.misc.cdi-integration]] -== 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 <>. 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: - -[source, java] ----- -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: - -[source, java] ----- -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: - -[source, java] ----- -class RepositoryClient { - - @Inject - PersonRepository repository; - - public void businessMethod() { - List people = repository.findAll(); - } -} ----- diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc deleted file mode 100644 index 8b30257482..0000000000 --- a/src/main/asciidoc/preface.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[[preface]] -== 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. - -[[project]] -=== Project Metadata - -* 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 diff --git a/src/main/asciidoc/repository-projections-dto-limitations.adoc b/src/main/asciidoc/repository-projections-dto-limitations.adoc deleted file mode 100644 index bc2a33df14..0000000000 --- a/src/main/asciidoc/repository-projections-dto-limitations.adoc +++ /dev/null @@ -1 +0,0 @@ -NOTE: 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`]