Greg L. Turnquist
@@ -1,123 +0,0 @@
|
||||
[[auditing]]
|
||||
= Auditing
|
||||
|
||||
[[auditing.basics]]
|
||||
== Basics
|
||||
Spring Data provides sophisticated support to transparently keep track of who created or changed an entity and when the change happened.To benefit from that functionality, you have to equip your entity classes with auditing metadata that can be defined either using annotations or by implementing an interface.
|
||||
Additionally, auditing has to be enabled either through Annotation configuration or XML configuration to register the required infrastructure components.
|
||||
Please refer to the store-specific section for configuration samples.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Applications that only track creation and modification dates are not required do make their entities implement <<auditing.auditor-aware, `AuditorAware`>>.
|
||||
====
|
||||
|
||||
[[auditing.annotations]]
|
||||
=== Annotation-based Auditing Metadata
|
||||
We provide `@CreatedBy` and `@LastModifiedBy` to capture the user who created or modified the entity as well as `@CreatedDate` and `@LastModifiedDate` to capture when the change happened.
|
||||
|
||||
.An audited entity
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Customer {
|
||||
|
||||
@CreatedBy
|
||||
private User user;
|
||||
|
||||
@CreatedDate
|
||||
private Instant createdDate;
|
||||
|
||||
// … further properties omitted
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
As you can see, the annotations can be applied selectively, depending on which information you want to capture.
|
||||
The annotations, indicating to capture when changes are made, can be used on properties of type JDK8 date and time types, `long`, `Long`, and legacy Java `Date` and `Calendar`.
|
||||
|
||||
Auditing metadata does not necessarily need to live in the root level entity but can be added to an embedded one (depending on the actual store in use), as shown in the snippet below.
|
||||
|
||||
.Audit metadata in embedded entity
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class Customer {
|
||||
|
||||
private AuditMetadata auditingMetadata;
|
||||
|
||||
// … further properties omitted
|
||||
}
|
||||
|
||||
class AuditMetadata {
|
||||
|
||||
@CreatedBy
|
||||
private User user;
|
||||
|
||||
@CreatedDate
|
||||
private Instant createdDate;
|
||||
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
[[auditing.interfaces]]
|
||||
=== Interface-based Auditing Metadata
|
||||
In case you do not want to use annotations to define auditing metadata, you can let your domain class implement the `Auditable` interface. It exposes setter methods for all of the auditing properties.
|
||||
|
||||
[[auditing.auditor-aware]]
|
||||
=== `AuditorAware`
|
||||
|
||||
In case you use either `@CreatedBy` or `@LastModifiedBy`, the auditing infrastructure somehow needs to become aware of the current principal. To do so, we provide an `AuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be.
|
||||
|
||||
The following example shows an implementation of the interface that uses Spring Security's `Authentication` object:
|
||||
|
||||
.Implementation of `AuditorAware` based on Spring Security
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
class SpringSecurityAuditorAware implements AuditorAware<User> {
|
||||
|
||||
@Override
|
||||
public Optional<User> getCurrentAuditor() {
|
||||
|
||||
return Optional.ofNullable(SecurityContextHolder.getContext())
|
||||
.map(SecurityContext::getAuthentication)
|
||||
.filter(Authentication::isAuthenticated)
|
||||
.map(Authentication::getPrincipal)
|
||||
.map(User.class::cast);
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere.
|
||||
|
||||
[[auditing.reactive-auditor-aware]]
|
||||
=== `ReactiveAuditorAware`
|
||||
|
||||
When using reactive infrastructure you might want to make use of contextual information to provide `@CreatedBy` or `@LastModifiedBy` information.
|
||||
We provide an `ReactiveAuditorAware<T>` SPI interface that you have to implement to tell the infrastructure who the current user or system interacting with the application is. The generic type `T` defines what type the properties annotated with `@CreatedBy` or `@LastModifiedBy` have to be.
|
||||
|
||||
The following example shows an implementation of the interface that uses reactive Spring Security's `Authentication` object:
|
||||
|
||||
.Implementation of `ReactiveAuditorAware` based on Spring Security
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
class SpringSecurityAuditorAware implements ReactiveAuditorAware<User> {
|
||||
|
||||
@Override
|
||||
public Mono<User> getCurrentAuditor() {
|
||||
|
||||
return ReactiveSecurityContextHolder.getContext()
|
||||
.map(SecurityContext::getAuthentication)
|
||||
.filter(Authentication::isAuthenticated)
|
||||
.map(Authentication::getPrincipal)
|
||||
.map(User.class::cast);
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The implementation accesses the `Authentication` object provided by Spring Security and looks up the custom `UserDetails` instance that you have created in your `UserDetailsService` implementation. We assume here that you are exposing the domain user through the `UserDetails` implementation but that, based on the `Authentication` found, you could also look it up from anywhere.
|
||||
@@ -1,41 +0,0 @@
|
||||
The following example of a Spring `Converter` implementation converts from a `String` to a custom `Email` value object:
|
||||
|
||||
[source,java,subs="verbatim,attributes"]
|
||||
----
|
||||
@ReadingConverter
|
||||
public class EmailReadConverter implements Converter<String, Email> {
|
||||
|
||||
public Email convert(String source) {
|
||||
return Email.valueOf(source);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
If you write a `Converter` whose source and target type are native types, we cannot determine whether we should consider it as a reading or a writing converter.
|
||||
Registering the converter instance as both might lead to unwanted results.
|
||||
For example, a `Converter<String, Long>` is ambiguous, although it probably does not make sense to try to convert all `String` instances into `Long` instances when writing.
|
||||
To let you force the infrastructure to register a converter for only one way, we provide `@ReadingConverter` and `@WritingConverter` annotations to be used in the converter implementation.
|
||||
|
||||
Converters are subject to explicit registration as instances are not picked up from a classpath or container scan to avoid unwanted registration with a conversion service and the side effects resulting from such a registration. Converters are registered with `CustomConversions` as the central facility that allows registration and querying for registered converters based on source- and target type.
|
||||
|
||||
`CustomConversions` ships with a pre-defined set of converter registrations:
|
||||
|
||||
* JSR-310 Converters for conversion between `java.time`, `java.util.Date` and `String` types.
|
||||
|
||||
NOTE: Default converters for local temporal types (e.g. `LocalDateTime` to `java.util.Date`) rely on system-default timezone settings to convert between those types. You can override the default converter, by registering your own converter.
|
||||
|
||||
[[customconversions.converter-disambiguation]]
|
||||
== Converter Disambiguation
|
||||
|
||||
Generally, we inspect the `Converter` implementations for the source and target types they convert from and to.
|
||||
Depending on whether one of those is a type the underlying data access API can handle natively, we register the converter instance as a reading or a writing converter.
|
||||
The following examples show a writing- and a read converter (note the difference is in the order of the qualifiers on `Converter`):
|
||||
|
||||
[source,java]
|
||||
----
|
||||
// Write converter as only the target type is one that can be handled natively
|
||||
class MyConverter implements Converter<Person, String> { … }
|
||||
|
||||
// Read converter as only the source type is one that can be handled natively
|
||||
class MyConverter implements Converter<String, Person> { … }
|
||||
----
|
||||
@@ -1,61 +0,0 @@
|
||||
[[dependencies]]
|
||||
= Dependencies
|
||||
|
||||
Due to the different inception dates of individual Spring Data modules, most of them carry different major and minor version numbers. The easiest way to find compatible ones is to rely on the Spring Data Release Train BOM that we ship with the compatible versions defined. In a Maven project, you would declare this dependency in the `<dependencyManagement />` section of your POM as follows:
|
||||
|
||||
.Using the Spring Data release train BOM
|
||||
====
|
||||
[source, xml, subs="+attributes"]
|
||||
----
|
||||
<dependencyManagement>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.data</groupId>
|
||||
<artifactId>spring-data-bom</artifactId>
|
||||
<version>{releasetrainVersion}</version>
|
||||
<scope>import</scope>
|
||||
<type>pom</type>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
</dependencyManagement>
|
||||
----
|
||||
====
|
||||
|
||||
[[dependencies.train-names]]
|
||||
[[dependencies.train-version]]
|
||||
The current release train version is `{releasetrainVersion}`. The train version uses https://calver.org/[calver] with the pattern `YYYY.MINOR.MICRO`.
|
||||
The version name follows `${calver}` for GA releases and service releases and the following pattern for all other versions: `${calver}-${modifier}`, where `modifier` can be one of the following:
|
||||
|
||||
* `SNAPSHOT`: Current snapshots
|
||||
* `M1`, `M2`, and so on: Milestones
|
||||
* `RC1`, `RC2`, and so on: Release candidates
|
||||
|
||||
You can find a working example of using the BOMs in our https://github.com/spring-projects/spring-data-examples/tree/main/bom[Spring Data examples repository]. With that in place, you can declare the Spring Data modules you would like to use without a version in the `<dependencies />` block, as follows:
|
||||
|
||||
.Declaring a dependency to a Spring Data module
|
||||
====
|
||||
[source, xml]
|
||||
----
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>org.springframework.data</groupId>
|
||||
<artifactId>spring-data-jpa</artifactId>
|
||||
</dependency>
|
||||
<dependencies>
|
||||
----
|
||||
====
|
||||
|
||||
[[dependencies.spring-boot]]
|
||||
== Dependency Management with Spring Boot
|
||||
|
||||
Spring Boot selects a recent version of the Spring Data modules for you. If you still want to upgrade to a newer version,
|
||||
set the `spring-data-bom.version` property to the <<dependencies.train-version,train version and iteration>>
|
||||
you would like to use.
|
||||
|
||||
See Spring Boot's https://docs.spring.io/spring-boot/docs/current/reference/html/dependency-versions.html#appendix.dependency-versions.properties[documentation]
|
||||
(search for "Spring Data Bom") for more details.
|
||||
|
||||
[[dependencies.spring-framework]]
|
||||
== Spring Framework
|
||||
|
||||
The current version of Spring Data modules require Spring Framework {springVersion} or better. The modules might also work with an older bugfix version of that minor version. However, using the most recent version within that generation is highly recommended.
|
||||
@@ -1,163 +0,0 @@
|
||||
[[entity-callbacks]]
|
||||
= Entity Callbacks
|
||||
|
||||
The Spring Data infrastructure provides hooks for modifying an entity before and after certain methods are invoked.
|
||||
Those so called `EntityCallback` instances provide a convenient way to check and potentially modify an entity in a callback fashioned style. +
|
||||
An `EntityCallback` looks pretty much like a specialized `ApplicationListener`.
|
||||
Some Spring Data modules publish store specific events (such as `BeforeSaveEvent`) that allow modifying the given entity. In some cases, such as when working with immutable types, these events can cause trouble.
|
||||
Also, event publishing relies on `ApplicationEventMulticaster`. If configuring that with an asynchronous `TaskExecutor` it can lead to unpredictable outcomes, as event processing can be forked onto a Thread.
|
||||
|
||||
Entity callbacks provide integration points with both synchronous and reactive APIs to guarantee in-order execution at well-defined checkpoints within the processing chain, returning a potentially modified entity or an reactive wrapper type.
|
||||
|
||||
Entity callbacks are typically separated by API type. This separation means that a synchronous API considers only synchronous entity callbacks and a reactive implementation considers only reactive entity callbacks.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The Entity Callback API has been introduced with Spring Data Commons 2.2. It is the recommended way of applying entity modifications.
|
||||
Existing store specific `ApplicationEvents` are still published *before* the invoking potentially registered `EntityCallback` instances.
|
||||
====
|
||||
|
||||
[[entity-callbacks.implement]]
|
||||
== Implementing Entity Callbacks
|
||||
|
||||
An `EntityCallback` is directly associated with its domain type through its generic type argument.
|
||||
Each Spring Data module typically ships with a set of predefined `EntityCallback` interfaces covering the entity lifecycle.
|
||||
|
||||
.Anatomy of an `EntityCallback`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@FunctionalInterface
|
||||
public interface BeforeSaveCallback<T> extends EntityCallback<T> {
|
||||
|
||||
/**
|
||||
* Entity callback method invoked before a domain object is saved.
|
||||
* Can return either the same or a modified instance.
|
||||
*
|
||||
* @return the domain object to be persisted.
|
||||
*/
|
||||
T onBeforeSave(T entity <2>, String collection <3>); <1>
|
||||
}
|
||||
----
|
||||
<1> `BeforeSaveCallback` specific method to be called before an entity is saved. Returns a potentially modifed instance.
|
||||
<2> The entity right before persisting.
|
||||
<3> A number of store specific arguments like the _collection_ the entity is persisted to.
|
||||
====
|
||||
|
||||
.Anatomy of a reactive `EntityCallback`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@FunctionalInterface
|
||||
public interface ReactiveBeforeSaveCallback<T> extends EntityCallback<T> {
|
||||
|
||||
/**
|
||||
* Entity callback method invoked on subscription, before a domain object is saved.
|
||||
* The returned Publisher can emit either the same or a modified instance.
|
||||
*
|
||||
* @return Publisher emitting the domain object to be persisted.
|
||||
*/
|
||||
Publisher<T> onBeforeSave(T entity <2>, String collection <3>); <1>
|
||||
}
|
||||
----
|
||||
<1> `BeforeSaveCallback` specific method to be called on subscription, before an entity is saved. Emits a potentially modifed instance.
|
||||
<2> The entity right before persisting.
|
||||
<3> A number of store specific arguments like the _collection_ the entity is persisted to.
|
||||
====
|
||||
|
||||
NOTE: Optional entity callback parameters are defined by the implementing Spring Data module and inferred from call site of `EntityCallback.callback()`.
|
||||
|
||||
Implement the interface suiting your application needs like shown in the example below:
|
||||
|
||||
.Example `BeforeSaveCallback`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
class DefaultingEntityCallback implements BeforeSaveCallback<Person>, Ordered { <2>
|
||||
|
||||
@Override
|
||||
public Object onBeforeSave(Person entity, String collection) { <1>
|
||||
|
||||
if(collection == "user") {
|
||||
return // ...
|
||||
}
|
||||
|
||||
return // ...
|
||||
}
|
||||
|
||||
@Override
|
||||
public int getOrder() {
|
||||
return 100; <2>
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> Callback implementation according to your requirements.
|
||||
<2> Potentially order the entity callback if multiple ones for the same domain type exist. Ordering follows lowest precedence.
|
||||
====
|
||||
|
||||
[[entity-callbacks.register]]
|
||||
== Registering Entity Callbacks
|
||||
|
||||
`EntityCallback` beans are picked up by the store specific implementations in case they are registered in the `ApplicationContext`.
|
||||
Most template APIs already implement `ApplicationContextAware` and therefore have access to the `ApplicationContext`
|
||||
|
||||
The following example explains a collection of valid entity callback registrations:
|
||||
|
||||
.Example `EntityCallback` Bean registration
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@Order(1) <1>
|
||||
@Component
|
||||
class First implements BeforeSaveCallback<Person> {
|
||||
|
||||
@Override
|
||||
public Person onBeforeSave(Person person) {
|
||||
return // ...
|
||||
}
|
||||
}
|
||||
|
||||
@Component
|
||||
class DefaultingEntityCallback implements BeforeSaveCallback<Person>,
|
||||
Ordered { <2>
|
||||
|
||||
@Override
|
||||
public Object onBeforeSave(Person entity, String collection) {
|
||||
// ...
|
||||
}
|
||||
|
||||
@Override
|
||||
public int getOrder() {
|
||||
return 100; <2>
|
||||
}
|
||||
}
|
||||
|
||||
@Configuration
|
||||
public class EntityCallbackConfiguration {
|
||||
|
||||
@Bean
|
||||
BeforeSaveCallback<Person> unorderedLambdaReceiverCallback() { <3>
|
||||
return (BeforeSaveCallback<Person>) it -> // ...
|
||||
}
|
||||
}
|
||||
|
||||
@Component
|
||||
class UserCallbacks implements BeforeConvertCallback<User>,
|
||||
BeforeSaveCallback<User> { <4>
|
||||
|
||||
@Override
|
||||
public Person onBeforeConvert(User user) {
|
||||
return // ...
|
||||
}
|
||||
|
||||
@Override
|
||||
public Person onBeforeSave(User user) {
|
||||
return // ...
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> `BeforeSaveCallback` receiving its order from the `@Order` annotation.
|
||||
<2> `BeforeSaveCallback` receiving its order via the `Ordered` interface implementation.
|
||||
<3> `BeforeSaveCallback` using a lambda expression. Unordered by default and invoked last. Note that callbacks implemented by a lambda expression do not expose typing information hence invoking these with a non-assignable entity affects the callback throughput. Use a `class` or `enum` to enable type filtering for the callback bean.
|
||||
<4> Combine multiple entity callback interfaces in a single implementation class.
|
||||
====
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 58 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 8.8 KiB |
@@ -1,41 +0,0 @@
|
||||
= Spring Data Commons - Reference Documentation
|
||||
Oliver Gierke; Thomas Darimont; Christoph Strobl; Mark Pollack; Thomas Risberg; Mark Paluch; Jay Bryant
|
||||
:revnumber: {version}
|
||||
:revdate: {localdate}
|
||||
:feature-scroll: true
|
||||
|
||||
(C) 2008-2022 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[]
|
||||
|
||||
[[reference-documentation]]
|
||||
= Reference Documentation
|
||||
|
||||
:leveloffset: +1
|
||||
|
||||
include::dependencies.adoc[]
|
||||
|
||||
include::object-mapping.adoc[]
|
||||
|
||||
include::repositories.adoc[]
|
||||
|
||||
include::repository-projections.adoc[]
|
||||
|
||||
include::query-by-example.adoc[]
|
||||
|
||||
include::auditing.adoc[]
|
||||
|
||||
:leveloffset: -1
|
||||
|
||||
[[appendix]]
|
||||
= Appendices
|
||||
|
||||
:numbered!:
|
||||
:leveloffset: +1
|
||||
include::repository-namespace-reference.adoc[]
|
||||
include::repository-populator-namespace-reference.adoc[]
|
||||
include::repository-query-keywords-reference.adoc[]
|
||||
include::repository-query-return-types-reference.adoc[]
|
||||
:leveloffset: -1
|
||||
@@ -1,30 +0,0 @@
|
||||
[[is-new-state-detection]]
|
||||
= Entity State Detection Strategies
|
||||
|
||||
The following table describes the strategies that Spring Data offers for detecting whether an entity is new:
|
||||
|
||||
.Options for detection whether an entity is new in Spring Data
|
||||
[options = "autowidth",cols="1,1"]
|
||||
|===
|
||||
|`@Id`-Property inspection (the default)
|
||||
|By default, Spring Data inspects the identifier property of the given entity.
|
||||
If the identifier property is `null` or `0` in case of primitive types, then the entity is assumed to be new.
|
||||
Otherwise, it is assumed to not be new.
|
||||
|
||||
|`@Version`-Property inspection
|
||||
|If a property annotated with `@Version` is present and `null`, or in case of a version property of primitive type `0` the entity is considered new.
|
||||
If the version property is present but has a different value, the entity is considered to not be new.
|
||||
If no version property is present Spring Data falls back to inspection of the identifier property.
|
||||
|
||||
|Implementing `Persistable`
|
||||
|If an entity implements `Persistable`, Spring Data 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.
|
||||
|
||||
_Note: Properties of `Persistable` will get detected and persisted if you use `AccessType.PROPERTY`.
|
||||
To avoid that, use `@Transient`._
|
||||
|
||||
|Providing a custom `EntityInformation` implementation
|
||||
|You can customize the `EntityInformation` abstraction used in the repository base implementation by creating a subclass of the module specific repository factory and overriding the `getEntityInformation(…)` method.
|
||||
You then have to register the custom implementation of module specific repository factory as a Spring bean.
|
||||
Note that this should rarely be necessary.
|
||||
|===
|
||||
@@ -1,92 +0,0 @@
|
||||
[[kotlin.coroutines]]
|
||||
= Coroutines
|
||||
|
||||
Kotlin https://kotlinlang.org/docs/reference/coroutines-overview.html[Coroutines] are lightweight threads allowing to write non-blocking code imperatively.
|
||||
On language side, `suspend` functions provides an abstraction for asynchronous operations while on library side https://github.com/Kotlin/kotlinx.coroutines[kotlinx.coroutines] provides functions like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/async.html[`async { }`] and types like https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`].
|
||||
|
||||
Spring Data modules provide support for Coroutines on the following scope:
|
||||
|
||||
* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-deferred/index.html[Deferred] and https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[Flow] return values support in Kotlin extensions
|
||||
|
||||
[[kotlin.coroutines.dependencies]]
|
||||
== Dependencies
|
||||
|
||||
Coroutines support is enabled when `kotlinx-coroutines-core`, `kotlinx-coroutines-reactive` and `kotlinx-coroutines-reactor` dependencies are in the classpath:
|
||||
|
||||
.Dependencies to add in Maven pom.xml
|
||||
====
|
||||
[source,xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.jetbrains.kotlinx</groupId>
|
||||
<artifactId>kotlinx-coroutines-core</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.jetbrains.kotlinx</groupId>
|
||||
<artifactId>kotlinx-coroutines-reactive</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.jetbrains.kotlinx</groupId>
|
||||
<artifactId>kotlinx-coroutines-reactor</artifactId>
|
||||
</dependency>
|
||||
----
|
||||
====
|
||||
|
||||
NOTE: Supported versions `1.3.0` and above.
|
||||
|
||||
[[kotlin.coroutines.reactive]]
|
||||
== How Reactive translates to Coroutines?
|
||||
|
||||
For return values, the translation from Reactive to Coroutines APIs is the following:
|
||||
|
||||
* `fun handler(): Mono<Void>` becomes `suspend fun handler()`
|
||||
* `fun handler(): Mono<T>` becomes `suspend fun handler(): T` or `suspend fun handler(): T?` depending on if the `Mono` can be empty or not (with the advantage of being more statically typed)
|
||||
* `fun handler(): Flux<T>` becomes `fun handler(): Flow<T>`
|
||||
|
||||
https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html[`Flow`] is `Flux` equivalent in Coroutines world, suitable for hot or cold stream, finite or infinite streams, with the following main differences:
|
||||
|
||||
* `Flow` is push-based while `Flux` is push-pull hybrid
|
||||
* Backpressure is implemented via suspending functions
|
||||
* `Flow` has only a https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/collect.html[single suspending `collect` method] and operators are implemented as https://kotlinlang.org/docs/reference/extensions.html[extensions]
|
||||
* https://github.com/Kotlin/kotlinx.coroutines/tree/master/kotlinx-coroutines-core/common/src/flow/operators[Operators are easy to implement] thanks to Coroutines
|
||||
* Extensions allow adding custom operators to `Flow`
|
||||
* Collect operations are suspending functions
|
||||
* https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/map.html[`map` operator] supports asynchronous operation (no need for `flatMap`) since it takes a suspending function parameter
|
||||
|
||||
Read this blog post about https://spring.io/blog/2019/04/12/going-reactive-with-spring-coroutines-and-kotlin-flow[Going Reactive with Spring, Coroutines and Kotlin Flow] for more details, including how to run code concurrently with Coroutines.
|
||||
|
||||
[[kotlin.coroutines.repositories]]
|
||||
== Repositories
|
||||
|
||||
Here is an example of a Coroutines repository:
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
interface CoroutineRepository : CoroutineCrudRepository<User, String> {
|
||||
|
||||
suspend fun findOne(id: String): User
|
||||
|
||||
fun findByFirstname(firstname: String): Flow<User>
|
||||
|
||||
suspend fun findAllByFirstname(id: String): List<User>
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Coroutines repositories are built on reactive repositories to expose the non-blocking nature of data access through Kotlin's Coroutines.
|
||||
Methods on a Coroutines repository can be backed either by a query method or a custom implementation.
|
||||
Invoking a custom implementation method propagates the Coroutines invocation to the actual implementation method if the custom method is `suspend`-able without requiring the implementation method to return a reactive type such as `Mono` or `Flux`.
|
||||
|
||||
Note that depending on the method declaration the coroutine context may or may not be available.
|
||||
To retain access to the context, either declare your method using `suspend` or return a type that enables context propagation such as `Flow`.
|
||||
|
||||
* `suspend fun findOne(id: String): User`: Retrieve the data once and synchronously by suspending.
|
||||
* `fun findByFirstname(firstname: String): Flow<User>`: Retrieve a stream of data.
|
||||
The `Flow` is created eagerly while data is fetched upon `Flow` interaction (`Flow.collect(…)`).
|
||||
* `fun getUser(): User`: Retrieve data once *blocking the thread* and without context propagation.
|
||||
This should be avoided.
|
||||
|
||||
NOTE: Coroutines repositories are only discovered when the repository extends the `CoroutineCrudRepository` interface.
|
||||
@@ -1,13 +0,0 @@
|
||||
[[kotlin.extensions]]
|
||||
= Extensions
|
||||
|
||||
Kotlin https://kotlinlang.org/docs/reference/extensions.html[extensions] provide the ability to extend existing classes with additional functionality. Spring Data Kotlin APIs use these extensions to add new Kotlin-specific conveniences to existing Spring APIs.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
Keep in mind that Kotlin extensions need to be imported to be used.
|
||||
Similar to static imports, an IDE should automatically suggest the import in most cases.
|
||||
====
|
||||
|
||||
For example, https://kotlinlang.org/docs/reference/inline-functions.html#reified-type-parameters[Kotlin reified type parameters] provide a workaround for JVM https://docs.oracle.com/javase/tutorial/java/generics/erasure.html[generics type erasure], and Spring Data provides some extensions to take advantage of this feature.
|
||||
This allows for a better Kotlin API.
|
||||
@@ -1,43 +0,0 @@
|
||||
[[kotlin]]
|
||||
= Kotlin Support
|
||||
|
||||
https://kotlinlang.org[Kotlin] is a statically typed language that targets the JVM (and other platforms) which allows writing concise and elegant code while providing excellent https://kotlinlang.org/docs/reference/java-interop.html[interoperability] with existing libraries written in Java.
|
||||
|
||||
Spring Data provides first-class support for Kotlin and lets developers write Kotlin applications almost as if Spring Data was a Kotlin native framework.
|
||||
|
||||
The easiest way to build a Spring application with Kotlin is to leverage Spring Boot and its https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-kotlin.html[dedicated Kotlin support].
|
||||
This comprehensive https://spring.io/guides/tutorials/spring-boot-kotlin/[tutorial] will teach you how to build Spring Boot applications with Kotlin using https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
|
||||
|
||||
[[kotlin.requirements]]
|
||||
== Requirements
|
||||
|
||||
Spring Data supports Kotlin 1.3 and requires `kotlin-stdlib` (or one of its variants, such as `kotlin-stdlib-jdk8`) and `kotlin-reflect` to be present on the classpath.
|
||||
Those are provided by default if you bootstrap a Kotlin project via https://start.spring.io/#!language=kotlin&type=gradle-project[start.spring.io].
|
||||
|
||||
[[kotlin.null-safety]]
|
||||
== Null Safety
|
||||
|
||||
One of Kotlin's key features is https://kotlinlang.org/docs/null-safety.html[null safety], which cleanly deals with `null` values at compile time.
|
||||
This makes applications safer through nullability declarations and the expression of "`value or no value`" semantics without paying the cost of wrappers, such as `Optional`.
|
||||
(Kotlin allows using functional constructs with nullable values. See this https://www.baeldung.com/kotlin/null-safety[comprehensive guide to Kotlin null safety].)
|
||||
|
||||
Although Java does not let you express null safety in its type system, Spring Data API is annotated with https://jcp.org/en/jsr/detail?id=305[JSR-305] tooling friendly annotations declared in the `org.springframework.lang` package.
|
||||
By default, types from Java APIs used in Kotlin are recognized as https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[platform types], for which null checks are relaxed.
|
||||
https://kotlinlang.org/docs/reference/java-interop.html#jsr-305-support[Kotlin support for JSR-305 annotations] and Spring nullability annotations provide null safety for the whole Spring Data API to Kotlin developers, with the advantage of dealing with `null` related issues at compile time.
|
||||
|
||||
See <<repositories.nullability>> how null safety applies to Spring Data Repositories.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
You can configure JSR-305 checks by adding the `-Xjsr305` compiler flag with the following options: `-Xjsr305={strict|warn|ignore}`.
|
||||
|
||||
For Kotlin versions 1.1+, the default behavior is the same as `-Xjsr305=warn`.
|
||||
The `strict` value is required take Spring Data API null-safety into account. Kotlin types inferred from Spring API but should be used with the knowledge that Spring API nullability declaration could evolve, even between minor releases and that more checks may be added in the future.
|
||||
====
|
||||
|
||||
NOTE: Generic type arguments, varargs, and array elements nullability are not supported yet, but should be in an upcoming release.
|
||||
|
||||
[[kotlin.mapping]]
|
||||
== Object Mapping
|
||||
|
||||
See <<mapping.kotlin>> for details on how Kotlin objects are materialized.
|
||||
@@ -1,462 +0,0 @@
|
||||
[[mapping.fundamentals]]
|
||||
= Object Mapping Fundamentals
|
||||
|
||||
This section covers the fundamentals of Spring Data object mapping, object creation, field and property access, mutability and immutability.
|
||||
Note, that this section only applies to Spring Data modules that do not use the object mapping of the underlying data store (like JPA).
|
||||
Also be sure to consult the store-specific sections for store-specific object mapping, like indexes, customizing column or field names or the like.
|
||||
|
||||
Core responsibility of the Spring Data object mapping is to create instances of domain objects and map the store-native data structures onto those.
|
||||
This means we need two fundamental steps:
|
||||
|
||||
1. Instance creation by using one of the constructors exposed.
|
||||
2. Instance population to materialize all exposed properties.
|
||||
|
||||
[[mapping.object-creation]]
|
||||
== Object creation
|
||||
|
||||
Spring Data automatically tries to detect a persistent entity's constructor to be used to materialize objects of that type.
|
||||
The resolution algorithm works as follows:
|
||||
|
||||
1. If there is a single static factory method annotated with `@PersistenceCreator` then it is used.
|
||||
2. If there is a single constructor, it is used.
|
||||
3. If there are multiple constructors and exactly one is annotated with `@PersistenceCreator`, it is used.
|
||||
4. If the type is a Java `Record` the canonical constructor is used.
|
||||
5. If there's a no-argument constructor, it is used.
|
||||
Other constructors will be ignored.
|
||||
|
||||
The value resolution assumes constructor/factory method argument names to match the property names of the entity, i.e. the resolution will be performed as if the property was to be populated, including all customizations in mapping (different datastore column or field name etc.).
|
||||
This also requires either parameter names information available in the class file or an `@ConstructorProperties` annotation being present on the constructor.
|
||||
|
||||
The value resolution can be customized by using Spring Framework's `@Value` value annotation using a store-specific SpEL expression.
|
||||
Please consult the section on store specific mappings for further details.
|
||||
|
||||
[[mapping.object-creation.details]]
|
||||
.Object creation internals
|
||||
****
|
||||
|
||||
To avoid the overhead of reflection, Spring Data object creation uses a factory class generated at runtime by default, which will call the domain classes constructor directly.
|
||||
I.e. for this example type:
|
||||
|
||||
[source,java]
|
||||
----
|
||||
class Person {
|
||||
Person(String firstname, String lastname) { … }
|
||||
}
|
||||
----
|
||||
|
||||
we will create a factory class semantically equivalent to this one at runtime:
|
||||
|
||||
[source, java]
|
||||
----
|
||||
class PersonObjectInstantiator implements ObjectInstantiator {
|
||||
|
||||
Object newInstance(Object... args) {
|
||||
return new Person((String) args[0], (String) args[1]);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
This gives us a roundabout 10% performance boost over reflection.
|
||||
For the domain class to be eligible for such optimization, it needs to adhere to a set of constraints:
|
||||
|
||||
- it must not be a private class
|
||||
- it must not be a non-static inner class
|
||||
- it must not be a CGLib proxy class
|
||||
- the constructor to be used by Spring Data must not be private
|
||||
|
||||
If any of these criteria match, Spring Data will fall back to entity instantiation via reflection.
|
||||
****
|
||||
|
||||
[[mapping.property-population]]
|
||||
== Property population
|
||||
|
||||
Once an instance of the entity has been created, Spring Data populates all remaining persistent properties of that class.
|
||||
Unless already populated by the entity's constructor (i.e. consumed through its constructor argument list), the identifier property will be populated first to allow the resolution of cyclic object references.
|
||||
After that, all non-transient properties that have not already been populated by the constructor are set on the entity instance.
|
||||
For that we use the following algorithm:
|
||||
|
||||
1. If the property is immutable but exposes a `with…` method (see below), we use the `with…` method to create a new entity instance with the new property value.
|
||||
2. If property access (i.e. access through getters and setters) is defined, we're invoking the setter method.
|
||||
3. If the property is mutable we set the field directly.
|
||||
4. If the property is immutable we're using the constructor to be used by persistence operations (see <<mapping.object-creation>>) to create a copy of the instance.
|
||||
5. By default, we set the field value directly.
|
||||
|
||||
[[mapping.property-population.details]]
|
||||
.Property population internals
|
||||
****
|
||||
Similarly to our <<mapping.object-creation.details,optimizations in object construction>> we also use Spring Data runtime generated accessor classes to interact with the entity instance.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
class Person {
|
||||
|
||||
private final Long id;
|
||||
private String firstname;
|
||||
private @AccessType(Type.PROPERTY) String lastname;
|
||||
|
||||
Person() {
|
||||
this.id = null;
|
||||
}
|
||||
|
||||
Person(Long id, String firstname, String lastname) {
|
||||
// Field assignments
|
||||
}
|
||||
|
||||
Person withId(Long id) {
|
||||
return new Person(id, this.firstname, this.lastame);
|
||||
}
|
||||
|
||||
void setLastname(String lastname) {
|
||||
this.lastname = lastname;
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
.A generated Property Accessor
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
class PersonPropertyAccessor implements PersistentPropertyAccessor {
|
||||
|
||||
private static final MethodHandle firstname; <2>
|
||||
|
||||
private Person person; <1>
|
||||
|
||||
public void setProperty(PersistentProperty property, Object value) {
|
||||
|
||||
String name = property.getName();
|
||||
|
||||
if ("firstname".equals(name)) {
|
||||
firstname.invoke(person, (String) value); <2>
|
||||
} else if ("id".equals(name)) {
|
||||
this.person = person.withId((Long) value); <3>
|
||||
} else if ("lastname".equals(name)) {
|
||||
this.person.setLastname((String) value); <4>
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
<1> PropertyAccessor's hold a mutable instance of the underlying object. This is, to enable mutations of otherwise immutable properties.
|
||||
<2> By default, Spring Data uses field-access to read and write property values. As per visibility rules of `private` fields, `MethodHandles` are used to interact with fields.
|
||||
<3> The class exposes a `withId(…)` method that's used to set the identifier, e.g. when an instance is inserted into the datastore and an identifier has been generated. Calling `withId(…)` creates a new `Person` object. All subsequent mutations will take place in the new instance leaving the previous untouched.
|
||||
<4> Using property-access allows direct method invocations without using `MethodHandles`.
|
||||
====
|
||||
|
||||
This gives us a roundabout 25% performance boost over reflection.
|
||||
For the domain class to be eligible for such optimization, it needs to adhere to a set of constraints:
|
||||
|
||||
- Types must not reside in the default or under the `java` package.
|
||||
- Types and their constructors must be `public`
|
||||
- Types that are inner classes must be `static`.
|
||||
- The used Java Runtime must allow for declaring classes in the originating `ClassLoader`. Java 9 and newer impose certain limitations.
|
||||
|
||||
By default, Spring Data attempts to use generated property accessors and falls back to reflection-based ones if a limitation is detected.
|
||||
****
|
||||
|
||||
Let's have a look at the following entity:
|
||||
|
||||
.A sample entity
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
class Person {
|
||||
|
||||
private final @Id Long id; <1>
|
||||
private final String firstname, lastname; <2>
|
||||
private final LocalDate birthday;
|
||||
private final int age; <3>
|
||||
|
||||
private String comment; <4>
|
||||
private @AccessType(Type.PROPERTY) String remarks; <5>
|
||||
|
||||
static Person of(String firstname, String lastname, LocalDate birthday) { <6>
|
||||
|
||||
return new Person(null, firstname, lastname, birthday,
|
||||
Period.between(birthday, LocalDate.now()).getYears());
|
||||
}
|
||||
|
||||
Person(Long id, String firstname, String lastname, LocalDate birthday, int age) { <6>
|
||||
|
||||
this.id = id;
|
||||
this.firstname = firstname;
|
||||
this.lastname = lastname;
|
||||
this.birthday = birthday;
|
||||
this.age = age;
|
||||
}
|
||||
|
||||
Person withId(Long id) { <1>
|
||||
return new Person(id, this.firstname, this.lastname, this.birthday, this.age);
|
||||
}
|
||||
|
||||
void setRemarks(String remarks) { <5>
|
||||
this.remarks = remarks;
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
<1> The identifier property is final but set to `null` in the constructor.
|
||||
The class exposes a `withId(…)` method that's used to set the identifier, e.g. when an instance is inserted into the datastore and an identifier has been generated.
|
||||
The original `Person` instance stays unchanged as a new one is created.
|
||||
The same pattern is usually applied for other properties that are store managed but might have to be changed for persistence operations.
|
||||
The wither method is optional as the persistence constructor (see 6) is effectively a copy constructor and setting the property will be translated into creating a fresh instance with the new identifier value applied.
|
||||
<2> The `firstname` and `lastname` properties are ordinary immutable properties potentially exposed through getters.
|
||||
<3> The `age` property is an immutable but derived one from the `birthday` property.
|
||||
With the design shown, the database value will trump the defaulting as Spring Data uses the only declared constructor.
|
||||
Even if the intent is that the calculation should be preferred, it's important that this constructor also takes `age` as parameter (to potentially ignore it) as otherwise the property population step will attempt to set the age field and fail due to it being immutable and no `with…` method being present.
|
||||
<4> The `comment` property is mutable and is populated by setting its field directly.
|
||||
<5> The `remarks` property is mutable and is populated by invoking the setter method.
|
||||
<6> The class exposes a factory method and a constructor for object creation.
|
||||
The core idea here is to use factory methods instead of additional constructors to avoid the need for constructor disambiguation through `@PersistenceCreator`.
|
||||
Instead, defaulting of properties is handled within the factory method.
|
||||
If you want Spring Data to use the factory method for object instantiation, annotate it with `@PersistenceCreator`.
|
||||
|
||||
[[mapping.general-recommendations]]
|
||||
== General recommendations
|
||||
|
||||
* _Try to stick to immutable objects_ -- Immutable objects are straightforward to create as materializing an object is then a matter of calling its constructor only.
|
||||
Also, this avoids your domain objects to be littered with setter methods that allow client code to manipulate the objects state.
|
||||
If you need those, prefer to make them package protected so that they can only be invoked by a limited amount of co-located types.
|
||||
Constructor-only materialization is up to 30% faster than properties population.
|
||||
* _Provide an all-args constructor_ -- Even if you cannot or don't want to model your entities as immutable values, there's still value in providing a constructor that takes all properties of the entity as arguments, including the mutable ones, as this allows the object mapping to skip the property population for optimal performance.
|
||||
* _Use factory methods instead of overloaded constructors to avoid ``@PersistenceCreator``_ -- With an all-argument constructor needed for optimal performance, we usually want to expose more application use case specific constructors that omit things like auto-generated identifiers etc.
|
||||
It's an established pattern to rather use static factory methods to expose these variants of the all-args constructor.
|
||||
* _Make sure you adhere to the constraints that allow the generated instantiator and property accessor classes to be used_ --
|
||||
* _For identifiers to be generated, still use a final field in combination with an all-arguments persistence constructor (preferred) or a `with…` method_ --
|
||||
* _Use Lombok to avoid boilerplate code_ -- As persistence operations usually require a constructor taking all arguments, their declaration becomes a tedious repetition of boilerplate parameter to field assignments that can best be avoided by using Lombok's `@AllArgsConstructor`.
|
||||
|
||||
[[mapping.general-recommendations.override.properties]]
|
||||
=== Overriding Properties
|
||||
|
||||
Java's allows a flexible design of domain classes where a subclass could define a property that is already declared with the same name in its superclass.
|
||||
Consider the following example:
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
public class SuperType {
|
||||
|
||||
private CharSequence field;
|
||||
|
||||
public SuperType(CharSequence field) {
|
||||
this.field = field;
|
||||
}
|
||||
|
||||
public CharSequence getField() {
|
||||
return this.field;
|
||||
}
|
||||
|
||||
public void setField(CharSequence field) {
|
||||
this.field = field;
|
||||
}
|
||||
}
|
||||
|
||||
public class SubType extends SuperType {
|
||||
|
||||
private String field;
|
||||
|
||||
public SubType(String field) {
|
||||
super(field);
|
||||
this.field = field;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getField() {
|
||||
return this.field;
|
||||
}
|
||||
|
||||
public void setField(String field) {
|
||||
this.field = field;
|
||||
|
||||
// optional
|
||||
super.setField(field);
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Both classes define a `field` using assignable types. `SubType` however shadows `SuperType.field`.
|
||||
Depending on the class design, using the constructor could be the only default approach to set `SuperType.field`.
|
||||
Alternatively, calling `super.setField(…)` in the setter could set the `field` in `SuperType`.
|
||||
All these mechanisms create conflicts to some degree because the properties share the same name yet might represent two distinct values.
|
||||
Spring Data skips super-type properties if types are not assignable.
|
||||
That is, the type of the overridden property must be assignable to its super-type property type to be registered as override, otherwise the super-type property is considered transient.
|
||||
We generally recommend using distinct property names.
|
||||
|
||||
Spring Data modules generally support overridden properties holding different values.
|
||||
From a programming model perspective there are a few things to consider:
|
||||
|
||||
1. Which property should be persisted (default to all declared properties)?
|
||||
You can exclude properties by annotating these with `@Transient`.
|
||||
2. How to represent properties in your data store?
|
||||
Using the same field/column name for different values typically leads to corrupt data so you should annotate least one of the properties using an explicit field/column name.
|
||||
3. Using `@AccessType(PROPERTY)` cannot be used as the super-property cannot be generally set without making any further assumptions of the setter implementation.
|
||||
|
||||
[[mapping.kotlin]]
|
||||
== Kotlin support
|
||||
|
||||
Spring Data adapts specifics of Kotlin to allow object creation and mutation.
|
||||
|
||||
[[mapping.kotlin.creation]]
|
||||
=== Kotlin object creation
|
||||
|
||||
Kotlin classes are supported to be instantiated, all classes are immutable by default and require explicit property declarations to define mutable properties.
|
||||
|
||||
Spring Data automatically tries to detect a persistent entity's constructor to be used to materialize objects of that type.
|
||||
The resolution algorithm works as follows:
|
||||
|
||||
1. If there is a constructor that is annotated with `@PersistenceCreator`, it is used.
|
||||
2. If the type is a <<mapping.kotlin,Kotlin data cass>> the primary constructor is used.
|
||||
3. If there is a single static factory method annotated with `@PersistenceCreator` then it is used.
|
||||
4. If there is a single constructor, it is used.
|
||||
5. If there are multiple constructors and exactly one is annotated with `@PersistenceCreator`, it is used.
|
||||
6. If the type is a Java `Record` the canonical constructor is used.
|
||||
7. If there's a no-argument constructor, it is used.
|
||||
Other constructors will be ignored.
|
||||
|
||||
Consider the following `data` class `Person`:
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
data class Person(val id: String, val name: String)
|
||||
----
|
||||
====
|
||||
|
||||
The class above compiles to a typical class with an explicit constructor.We can customize this class by adding another constructor and annotate it with `@PersistenceCreator` to indicate a constructor preference:
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
data class Person(var id: String, val name: String) {
|
||||
|
||||
@PersistenceCreator
|
||||
constructor(id: String) : this(id, "unknown")
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Kotlin supports parameter optionality by allowing default values to be used if a parameter is not provided.
|
||||
When Spring Data detects a constructor with parameter defaulting, then it leaves these parameters absent if the data store does not provide a value (or simply returns `null`) so Kotlin can apply parameter defaulting.Consider the following class that applies parameter defaulting for `name`
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
data class Person(var id: String, val name: String = "unknown")
|
||||
----
|
||||
====
|
||||
|
||||
Every time the `name` parameter is either not part of the result or its value is `null`, then the `name` defaults to `unknown`.
|
||||
|
||||
=== Property population of Kotlin data classes
|
||||
|
||||
In Kotlin, all classes are immutable by default and require explicit property declarations to define mutable properties.
|
||||
Consider the following `data` class `Person`:
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
data class Person(val id: String, val name: String)
|
||||
----
|
||||
====
|
||||
|
||||
This class is effectively immutable.
|
||||
It allows creating new instances as Kotlin generates a `copy(…)` method that creates new object instances copying all property values from the existing object and applying property values provided as arguments to the method.
|
||||
|
||||
[[mapping.kotlin.override.properties]]
|
||||
=== Kotlin Overriding Properties
|
||||
|
||||
Kotlin allows declaring https://kotlinlang.org/docs/inheritance.html#overriding-properties[property overrides] to alter properties in subclasses.
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
open class SuperType(open var field: Int)
|
||||
|
||||
class SubType(override var field: Int = 1) :
|
||||
SuperType(field) {
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Such an arrangement renders two properties with the name `field`.
|
||||
Kotlin generates property accessors (getters and setters) for each property in each class.
|
||||
Effectively, the code looks like as follows:
|
||||
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
public class SuperType {
|
||||
|
||||
private int field;
|
||||
|
||||
public SuperType(int field) {
|
||||
this.field = field;
|
||||
}
|
||||
|
||||
public int getField() {
|
||||
return this.field;
|
||||
}
|
||||
|
||||
public void setField(int field) {
|
||||
this.field = field;
|
||||
}
|
||||
}
|
||||
|
||||
public final class SubType extends SuperType {
|
||||
|
||||
private int field;
|
||||
|
||||
public SubType(int field) {
|
||||
super(field);
|
||||
this.field = field;
|
||||
}
|
||||
|
||||
public int getField() {
|
||||
return this.field;
|
||||
}
|
||||
|
||||
public void setField(int field) {
|
||||
this.field = field;
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Getters and setters on `SubType` set only `SubType.field` and not `SuperType.field`.
|
||||
In such an arrangement, using the constructor is the only default approach to set `SuperType.field`.
|
||||
Adding a method to `SubType` to set `SuperType.field` via `this.SuperType.field = …` is possible but falls outside of supported conventions.
|
||||
Property overrides create conflicts to some degree because the properties share the same name yet might represent two distinct values.
|
||||
We generally recommend using distinct property names.
|
||||
|
||||
Spring Data modules generally support overridden properties holding different values.
|
||||
From a programming model perspective there are a few things to consider:
|
||||
|
||||
1. Which property should be persisted (default to all declared properties)?
|
||||
You can exclude properties by annotating these with `@Transient`.
|
||||
2. How to represent properties in your data store?
|
||||
Using the same field/column name for different values typically leads to corrupt data so you should annotate least one of the properties using an explicit field/column name.
|
||||
3. Using `@AccessType(PROPERTY)` cannot be used as the super-property cannot be set.
|
||||
|
||||
[[mapping.kotlin.value.classes]]
|
||||
=== Kotlin Value Classes
|
||||
|
||||
Kotlin Value Classes are designed for a more expressive domain model to make underlying concepts explicit.
|
||||
Spring Data can read and write types that define properties using Value Classes.
|
||||
|
||||
Consider the following domain model:
|
||||
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
@JvmInline
|
||||
value class EmailAddress(val theAddress: String) <1>
|
||||
|
||||
data class Contact(val id: String, val name:String, val emailAddress: EmailAddress) <2>
|
||||
----
|
||||
|
||||
<1> A simple value class with a non-nullable value type.
|
||||
<2> Data class defining a property using the `EmailAddress` value class.
|
||||
====
|
||||
|
||||
NOTE: Non-nullable properties using non-primitive value types are flattened in the compiled class to the value type.
|
||||
Nullable primitive value types or nullable value-in-value types are represented with their wrapper type and that affects how value types are represented in the database.
|
||||
@@ -1,12 +0,0 @@
|
||||
[[preface]]
|
||||
= Preface
|
||||
The Spring Data Commons project applies core Spring concepts to the development of solutions using many relational and non-relational data stores.
|
||||
|
||||
[[project]]
|
||||
== Project Metadata
|
||||
|
||||
* Version control: https://github.com/spring-projects/spring-data-commons
|
||||
* Bugtracker: https://github.com/spring-projects/spring-data-commons/issues
|
||||
* Release repository: https://repo1.maven.org/maven2/
|
||||
* Milestone repository: https://repo.spring.io/milestone/
|
||||
* Snapshot repository: https://repo.spring.io/snapshot/
|
||||
@@ -1,218 +0,0 @@
|
||||
[[query-by-example]]
|
||||
= Query by Example
|
||||
|
||||
[[query-by-example.introduction]]
|
||||
== Introduction
|
||||
|
||||
This chapter provides an introduction to Query by Example and explains how to use it.
|
||||
|
||||
Query by Example (QBE) is a user-friendly querying technique with a simple interface.
|
||||
It allows dynamic query creation and does not require you to write queries that contain field names.
|
||||
In fact, Query by Example does not require you to write queries by using store-specific query languages at all.
|
||||
|
||||
[[query-by-example.usage]]
|
||||
== Usage
|
||||
|
||||
The Query by Example API consists of four parts:
|
||||
|
||||
* Probe: The actual example of a domain object with populated fields.
|
||||
* `ExampleMatcher`: The `ExampleMatcher` carries details on how to match particular fields.
|
||||
It can be reused across multiple Examples.
|
||||
* `Example`: An `Example` consists of the probe and the `ExampleMatcher`.
|
||||
It is used to create the query.
|
||||
* `FetchableFluentQuery`: A `FetchableFluentQuery` offers a fluent API, that allows further customization of a query derived from an `Example`.
|
||||
Using the fluent API lets you to specify ordering projection and result processing for your query.
|
||||
|
||||
Query by Example is well suited for several use cases:
|
||||
|
||||
* Querying your data store with a set of static or dynamic constraints.
|
||||
* Frequent refactoring of the domain objects without worrying about breaking existing queries.
|
||||
* Working independently from the underlying data store API.
|
||||
|
||||
Query by Example also has several limitations:
|
||||
|
||||
* No support for nested or grouped property constraints, such as `firstname = ?0 or (firstname = ?1 and lastname = ?2)`.
|
||||
* Only supports starts/contains/ends/regex matching for strings and exact matching for other property types.
|
||||
|
||||
Before getting started with Query by Example, you need to have a domain object.
|
||||
To get started, create an interface for your repository, as shown in the following example:
|
||||
|
||||
.Sample Person object
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
public class Person {
|
||||
|
||||
@Id
|
||||
private String id;
|
||||
private String firstname;
|
||||
private String lastname;
|
||||
private Address address;
|
||||
|
||||
// … getters and setters omitted
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The preceding example shows a simple domain object.
|
||||
You can use it to create an `Example`.
|
||||
By default, fields having `null` values are ignored, and strings are matched by using the store specific defaults.
|
||||
|
||||
NOTE: Inclusion of properties into a Query by Example criteria is based on nullability.
|
||||
Properties using primitive types (`int`, `double`, …) are always included unless the <<query-by-example.matchers, `ExampleMatcher` ignores the property path>>.
|
||||
|
||||
Examples can be built by either using the `of` factory method or by using <<query-by-example.matchers,`ExampleMatcher`>>. `Example` is immutable.
|
||||
The following listing shows a simple Example:
|
||||
|
||||
.Simple Example
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Person person = new Person(); <1>
|
||||
person.setFirstname("Dave"); <2>
|
||||
|
||||
Example<Person> example = Example.of(person); <3>
|
||||
----
|
||||
|
||||
<1> Create a new instance of the domain object.
|
||||
<2> Set the properties to query.
|
||||
<3> Create the `Example`.
|
||||
====
|
||||
|
||||
You can run the example queries by using repositories.
|
||||
To do so, let your repository interface extend `QueryByExampleExecutor<T>`.
|
||||
The following listing shows an excerpt from the `QueryByExampleExecutor` interface:
|
||||
|
||||
.The `QueryByExampleExecutor`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
public interface QueryByExampleExecutor<T> {
|
||||
|
||||
<S extends T> S findOne(Example<S> example);
|
||||
|
||||
<S extends T> Iterable<S> findAll(Example<S> example);
|
||||
|
||||
// … more functionality omitted.
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
[[query-by-example.matchers]]
|
||||
== Example Matchers
|
||||
|
||||
Examples are not limited to default settings.
|
||||
You can specify your own defaults for string matching, null handling, and property-specific settings by using the `ExampleMatcher`, as shown in the following example:
|
||||
|
||||
.Example matcher with customized matching
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Person person = new Person(); <1>
|
||||
person.setFirstname("Dave"); <2>
|
||||
|
||||
ExampleMatcher matcher = ExampleMatcher.matching() <3>
|
||||
.withIgnorePaths("lastname") <4>
|
||||
.withIncludeNullValues() <5>
|
||||
.withStringMatcher(StringMatcher.ENDING); <6>
|
||||
|
||||
Example<Person> example = Example.of(person, matcher); <7>
|
||||
|
||||
----
|
||||
|
||||
<1> Create a new instance of the domain object.
|
||||
<2> Set properties.
|
||||
<3> Create an `ExampleMatcher` to expect all values to match.
|
||||
It is usable at this stage even without further configuration.
|
||||
<4> Construct a new `ExampleMatcher` to ignore the `lastname` property path.
|
||||
<5> Construct a new `ExampleMatcher` to ignore the `lastname` property path and to include null values.
|
||||
<6> Construct a new `ExampleMatcher` to ignore the `lastname` property path, to include null values, and to perform suffix string matching.
|
||||
<7> Create a new `Example` based on the domain object and the configured `ExampleMatcher`.
|
||||
====
|
||||
|
||||
By default, the `ExampleMatcher` expects all values set on the probe to match.
|
||||
If you want to get results matching any of the predicates defined implicitly, use `ExampleMatcher.matchingAny()`.
|
||||
|
||||
You can specify behavior for individual properties (such as "firstname" and "lastname" or, for nested properties, "address.city").
|
||||
You can tune it with matching options and case sensitivity, as shown in the following example:
|
||||
|
||||
.Configuring matcher options
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
ExampleMatcher matcher = ExampleMatcher.matching()
|
||||
.withMatcher("firstname", endsWith())
|
||||
.withMatcher("lastname", startsWith().ignoreCase());
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Another way to configure matcher options is to use lambdas (introduced in Java 8).
|
||||
This approach creates a callback that asks the implementor to modify the matcher.
|
||||
You need not return the matcher, because configuration options are held within the matcher instance.
|
||||
The following example shows a matcher that uses lambdas:
|
||||
|
||||
.Configuring matcher options with lambdas
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
ExampleMatcher matcher = ExampleMatcher.matching()
|
||||
.withMatcher("firstname", match -> match.endsWith())
|
||||
.withMatcher("firstname", match -> match.startsWith());
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Queries created by `Example` use a merged view of the configuration.
|
||||
Default matching settings can be set at the `ExampleMatcher` level, while individual settings can be applied to particular property paths.
|
||||
Settings that are set on `ExampleMatcher` are inherited by property path settings unless they are defined explicitly.
|
||||
Settings on a property patch have higher precedence than default settings.
|
||||
The following table describes the scope of the various `ExampleMatcher` settings:
|
||||
|
||||
[cols="1,2",options="header"]
|
||||
.Scope of `ExampleMatcher` settings
|
||||
|===
|
||||
| Setting
|
||||
| Scope
|
||||
|
||||
| Null-handling
|
||||
| `ExampleMatcher`
|
||||
|
||||
| String matching
|
||||
| `ExampleMatcher` and property path
|
||||
|
||||
| Ignoring properties
|
||||
| Property path
|
||||
|
||||
| Case sensitivity
|
||||
| `ExampleMatcher` and property path
|
||||
|
||||
| Value transformation
|
||||
| Property path
|
||||
|
||||
|===
|
||||
|
||||
[[query-by-example.fluent]]
|
||||
== Fluent API
|
||||
|
||||
`QueryByExampleExecutor` offers one more method, which we did not mention so far: `<S extends T, R> R findBy(Example<S> example, Function<FluentQuery.FetchableFluentQuery<S>, R> queryFunction)`.
|
||||
As with other methods, it executes a query derived from an `Example`.
|
||||
However, with the second argument, you can control aspects of that execution that you cannot dynamically control otherwise.
|
||||
You do so by invoking the various methods of the `FetchableFluentQuery` in the second argument.
|
||||
`sortBy` lets you specify an ordering for your result.
|
||||
`as` lets you specify the type to which you want the result to be transformed.
|
||||
`project` limits the queried attributes.
|
||||
`first`, `firstValue`, `one`, `oneValue`, `all`, `page`, `stream`, `count`, and `exists` define what kind of result you get and how the query behaves when more than the expected number of results are available.
|
||||
|
||||
|
||||
.Use the fluent API to get the last of potentially many results, ordered by lastname.
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Optional<Person> match = repository.findBy(example,
|
||||
q -> q
|
||||
.sortBy(Sort.by("lastname").descending())
|
||||
.first()
|
||||
);
|
||||
----
|
||||
====
|
||||
@@ -1,97 +0,0 @@
|
||||
[[repositories.nullability]]
|
||||
=== Null Handling of Repository Methods
|
||||
|
||||
As of Spring Data 2.0, repository CRUD methods that return an individual aggregate instance use Java 8's `Optional` to indicate the potential absence of a value.
|
||||
Besides that, Spring Data supports returning the following wrapper types on query methods:
|
||||
|
||||
* `com.google.common.base.Optional`
|
||||
* `scala.Option`
|
||||
* `io.vavr.control.Option`
|
||||
|
||||
Alternatively, query methods can choose not to use a wrapper type at all.
|
||||
The absence of a query result is then indicated by returning `null`.
|
||||
Repository methods returning collections, collection alternatives, wrappers, and streams are guaranteed never to return `null` but rather the corresponding empty representation.
|
||||
See "`<<repository-query-return-types>>`" for details.
|
||||
|
||||
[[repositories.nullability.annotations]]
|
||||
==== Nullability Annotations
|
||||
|
||||
You can express nullability constraints for repository methods by using {spring-framework-docs}/core.html#null-safety[Spring Framework's nullability annotations].
|
||||
They provide a tooling-friendly approach and opt-in `null` checks during runtime, as follows:
|
||||
|
||||
* {spring-framework-javadoc}/org/springframework/lang/NonNullApi.html[`@NonNullApi`]: Used on the package level to declare that the default behavior for parameters and return values is, respectively, neither to accept nor to produce `null` values.
|
||||
* {spring-framework-javadoc}/org/springframework/lang/NonNull.html[`@NonNull`]: Used on a parameter or return value that must not be `null` (not needed on a parameter and return value where `@NonNullApi` applies).
|
||||
* {spring-framework-javadoc}/org/springframework/lang/Nullable.html[`@Nullable`]: Used on a parameter or return value that can be `null`.
|
||||
|
||||
Spring annotations are meta-annotated with https://jcp.org/en/jsr/detail?id=305[JSR 305] annotations (a dormant but widely used JSR).
|
||||
JSR 305 meta-annotations let tooling vendors (such as https://www.jetbrains.com/help/idea/nullable-and-notnull-annotations.html[IDEA], https://help.eclipse.org/latest/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm[Eclipse], and link:https://kotlinlang.org/docs/reference/java-interop.html#null-safety-and-platform-types[Kotlin]) provide null-safety support in a generic way, without having to hard-code support for Spring annotations.
|
||||
To enable runtime checking of nullability constraints for query methods, you need to activate non-nullability on the package level by using Spring’s `@NonNullApi` in `package-info.java`, as shown in the following example:
|
||||
|
||||
.Declaring Non-nullability in `package-info.java`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
@org.springframework.lang.NonNullApi
|
||||
package com.acme;
|
||||
----
|
||||
====
|
||||
|
||||
Once non-null defaulting is in place, repository query method invocations get validated at runtime for nullability constraints.
|
||||
If a query result violates the defined constraint, an exception is thrown.
|
||||
This happens when the method would return `null` but is declared as non-nullable (the default with the annotation defined on the package in which the repository resides).
|
||||
If you want to opt-in to nullable results again, selectively use `@Nullable` on individual methods.
|
||||
Using the result wrapper types mentioned at the start of this section continues to work as expected: an empty result is translated into the value that represents absence.
|
||||
|
||||
The following example shows a number of the techniques just described:
|
||||
|
||||
.Using different nullability constraints
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
package com.acme; <1>
|
||||
|
||||
import org.springframework.lang.Nullable;
|
||||
|
||||
interface UserRepository extends Repository<User, Long> {
|
||||
|
||||
User getByEmailAddress(EmailAddress emailAddress); <2>
|
||||
|
||||
@Nullable
|
||||
User findByEmailAddress(@Nullable EmailAddress emailAdress); <3>
|
||||
|
||||
Optional<User> findOptionalByEmailAddress(EmailAddress emailAddress); <4>
|
||||
}
|
||||
----
|
||||
<1> The repository resides in a package (or sub-package) for which we have defined non-null behavior.
|
||||
<2> Throws an `EmptyResultDataAccessException` when the query does not produce a result.
|
||||
Throws an `IllegalArgumentException` when the `emailAddress` handed to the method is `null`.
|
||||
<3> Returns `null` when the query does not produce a result.
|
||||
Also accepts `null` as the value for `emailAddress`.
|
||||
<4> Returns `Optional.empty()` when the query does not produce a result.
|
||||
Throws an `IllegalArgumentException` when the `emailAddress` handed to the method is `null`.
|
||||
====
|
||||
|
||||
[[repositories.nullability.kotlin]]
|
||||
==== Nullability in Kotlin-based Repositories
|
||||
|
||||
Kotlin has the definition of https://kotlinlang.org/docs/reference/null-safety.html[nullability constraints] baked into the language.
|
||||
Kotlin code compiles to bytecode, which does not express nullability constraints through method signatures but rather through compiled-in metadata.
|
||||
Make sure to include the `kotlin-reflect` JAR in your project to enable introspection of Kotlin's nullability constraints.
|
||||
Spring Data repositories use the language mechanism to define those constraints to apply the same runtime checks, as follows:
|
||||
|
||||
.Using nullability constraints on Kotlin repositories
|
||||
====
|
||||
[source,kotlin]
|
||||
----
|
||||
interface UserRepository : Repository<User, String> {
|
||||
|
||||
fun findByUsername(username: String): User <1>
|
||||
|
||||
fun findByFirstname(firstname: String?): User? <2>
|
||||
}
|
||||
----
|
||||
<1> The method defines both the parameter and the result as non-nullable (the Kotlin default).
|
||||
The Kotlin compiler rejects method invocations that pass `null` to the method.
|
||||
If the query yields an empty result, an `EmptyResultDataAccessException` is thrown.
|
||||
<2> This method accepts `null` for the `firstname` parameter and returns `null` if the query does not produce a result.
|
||||
====
|
||||
@@ -1,232 +0,0 @@
|
||||
[[repositories.special-parameters]]
|
||||
=== Paging, Iterating Large Results, Sorting & Limiting
|
||||
|
||||
To handle parameters in your query, define method parameters as already seen in the preceding examples.
|
||||
Besides that, the infrastructure recognizes certain specific types like `Pageable`, `Sort` and `Limit`, to apply pagination, sorting and limiting to your queries dynamically.
|
||||
The following example demonstrates these features:
|
||||
|
||||
ifdef::feature-scroll[]
|
||||
.Using `Pageable`, `Slice`, `ScrollPosition`, `Sort` and `Limit` in query methods
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Page<User> findByLastname(String lastname, Pageable pageable);
|
||||
|
||||
Slice<User> findByLastname(String lastname, Pageable pageable);
|
||||
|
||||
Window<User> findTop10ByLastname(String lastname, ScrollPosition position, Sort sort);
|
||||
|
||||
List<User> findByLastname(String lastname, Sort sort);
|
||||
|
||||
List<User> findByLastname(String lastname, Sort sort, Limit limit);
|
||||
|
||||
List<User> findByLastname(String lastname, Pageable pageable);
|
||||
----
|
||||
====
|
||||
endif::[]
|
||||
|
||||
ifndef::feature-scroll[]
|
||||
.Using `Pageable`, `Slice`, `Sort` and `Limit` in query methods
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Page<User> findByLastname(String lastname, Pageable pageable);
|
||||
|
||||
Slice<User> findByLastname(String lastname, Pageable pageable);
|
||||
|
||||
List<User> findByLastname(String lastname, Sort sort);
|
||||
|
||||
List<User> findByLastname(String lastname, Sort sort, Limit limit);
|
||||
|
||||
List<User> findByLastname(String lastname, Pageable pageable);
|
||||
----
|
||||
====
|
||||
endif::[]
|
||||
|
||||
IMPORTANT: APIs taking `Sort`, `Pageable` and `Limit` expect non-`null` values to be handed into methods.
|
||||
If you do not want to apply any sorting or pagination, use `Sort.unsorted()`, `Pageable.unpaged()` and `Limit.unlimited()`.
|
||||
|
||||
The first method lets you pass an `org.springframework.data.domain.Pageable` instance to the query method to dynamically add paging to your statically defined query.
|
||||
A `Page` knows about the total number of elements and pages available.
|
||||
It does so by the infrastructure triggering a count query to calculate the overall number.
|
||||
As this might be expensive (depending on the store used), you can instead return a `Slice`.
|
||||
A `Slice` knows only about whether a next `Slice` is available, which might be sufficient when walking through a larger result set.
|
||||
|
||||
Sorting options are handled through the `Pageable` instance, too.
|
||||
If you need only sorting, add an `org.springframework.data.domain.Sort` parameter to your method.
|
||||
As you can see, returning a `List` is also possible.
|
||||
In this case, the additional metadata required to build the actual `Page` instance is not created (which, in turn, means that the additional count query that would have been necessary is not issued).
|
||||
Rather, it restricts the query to look up only the given range of entities.
|
||||
|
||||
NOTE: To find out how many pages you get for an entire query, you have to trigger an additional count query.
|
||||
By default, this query is derived from the query you actually trigger.
|
||||
|
||||
[IMPORTANT]
|
||||
====
|
||||
Special parameters may only be used once within a query method. +
|
||||
Some special parameters described above are mutually exclusive.
|
||||
Please consider the following list of invalid parameter combinations.
|
||||
|
||||
|===
|
||||
| Parameters | Example | Reason
|
||||
|
||||
| `Pageable` and `Sort`
|
||||
| `findBy...(Pageable page, Sort sort)`
|
||||
| `Pageable` already defines `Sort`
|
||||
|
||||
| `Pageable` and `Limit`
|
||||
| `findBy...(Pageable page, Limit limit)`
|
||||
| `Pageable` already defines a limit.
|
||||
|
||||
|===
|
||||
|
||||
The `Top` keyword used to limit results can be used to along with `Pageable` whereas `Top` defines the total maximum of results, whereas the Pageable parameter may reduce this number.
|
||||
====
|
||||
|
||||
[[repositories.scrolling.guidance]]
|
||||
==== Which Method is Appropriate?
|
||||
|
||||
The value provided by the Spring Data abstractions is perhaps best shown by the possible query method return types outlined in the following table below.
|
||||
The table shows which types you can return from a query method
|
||||
|
||||
.Consuming Large Query Results
|
||||
[cols="1,2,2,3"]
|
||||
|===
|
||||
| Method|Amount of Data Fetched|Query Structure|Constraints
|
||||
|
||||
| <<repositories.collections-and-iterables,`List<T>`>>
|
||||
| All results.
|
||||
| Single query.
|
||||
| Query results can exhaust all memory. Fetching all data can be time-intensive.
|
||||
|
||||
| <<repositories.collections-and-iterables.streamable,`Streamable<T>`>>
|
||||
| All results.
|
||||
| Single query.
|
||||
| Query results can exhaust all memory. Fetching all data can be time-intensive.
|
||||
|
||||
| <<repositories.query-streaming,`Stream<T>`>>
|
||||
| Chunked (one-by-one or in batches) depending on `Stream` consumption.
|
||||
| Single query using typically cursors.
|
||||
| Streams must be closed after usage to avoid resource leaks.
|
||||
|
||||
| `Flux<T>`
|
||||
| Chunked (one-by-one or in batches) depending on `Flux` consumption.
|
||||
| Single query using typically cursors.
|
||||
| Store module must provide reactive infrastructure.
|
||||
|
||||
| `Slice<T>`
|
||||
| `Pageable.getPageSize() + 1` at `Pageable.getOffset()`
|
||||
| One to many queries fetching data starting at `Pageable.getOffset()` applying limiting.
|
||||
a| A `Slice` can only navigate to the next `Slice`.
|
||||
|
||||
* `Slice` provides details whether there is more data to fetch.
|
||||
* Offset-based queries becomes inefficient when the offset is too large because the database still has to materialize the full result.
|
||||
|
||||
ifdef::feature-scroll[]
|
||||
| Offset-based `Window<T>`
|
||||
| `limit + 1` at `OffsetScrollPosition.getOffset()`
|
||||
| One to many queries fetching data starting at `OffsetScrollPosition.getOffset()` applying limiting.
|
||||
a| A `Window` can only navigate to the next `Window`.
|
||||
endif::[]
|
||||
|
||||
* `Window` provides details whether there is more data to fetch.
|
||||
* Offset-based queries becomes inefficient when the offset is too large because the database still has to materialize the full result.
|
||||
|
||||
| `Page<T>`
|
||||
| `Pageable.getPageSize()` at `Pageable.getOffset()`
|
||||
| One to many queries starting at `Pageable.getOffset()` applying limiting. Additionally, `COUNT(…)` query to determine the total number of elements can be required.
|
||||
a| Often times, `COUNT(…)` queries are required that are costly.
|
||||
|
||||
* Offset-based queries becomes inefficient when the offset is too large because the database still has to materialize the full result.
|
||||
|
||||
ifdef::feature-scroll[]
|
||||
| Keyset-based `Window<T>`
|
||||
| `limit + 1` using a rewritten `WHERE` condition
|
||||
| One to many queries fetching data starting at `KeysetScrollPosition.getKeys()` applying limiting.
|
||||
a| A `Window` can only navigate to the next `Window`.
|
||||
|
||||
* `Window` provides details whether there is more data to fetch.
|
||||
* Keyset-based queries require a proper index structure for efficient querying.
|
||||
* Most data stores do not work well when Keyset-based query results contain `null` values.
|
||||
* Results must expose all sorting keys in their results requiring projections to select potentially more properties than required for the actual projection.
|
||||
endif::[]
|
||||
|
||||
|===
|
||||
|
||||
[[repositories.paging-and-sorting]]
|
||||
==== Paging and Sorting
|
||||
|
||||
You can define simple sorting expressions by using property names.
|
||||
You can concatenate expressions to collect multiple criteria into one expression.
|
||||
|
||||
.Defining sort expressions
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
Sort sort = Sort.by("firstname").ascending()
|
||||
.and(Sort.by("lastname").descending());
|
||||
----
|
||||
====
|
||||
|
||||
For a more type-safe way to define sort expressions, start with the type for which to define the sort expression and use method references to define the properties on which to sort.
|
||||
|
||||
.Defining sort expressions by using the type-safe API
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
TypedSort<Person> person = Sort.sort(Person.class);
|
||||
|
||||
Sort sort = person.by(Person::getFirstname).ascending()
|
||||
.and(person.by(Person::getLastname).descending());
|
||||
----
|
||||
====
|
||||
|
||||
NOTE: `TypedSort.by(…)` makes use of runtime proxies by (typically) using CGlib, which may interfere with native image compilation when using tools such as Graal VM Native.
|
||||
|
||||
If your store implementation supports Querydsl, you can also use the generated metamodel types to define sort expressions:
|
||||
|
||||
.Defining sort expressions by using the Querydsl API
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
QSort sort = QSort.by(QPerson.firstname.asc())
|
||||
.and(QSort.by(QPerson.lastname.desc()));
|
||||
----
|
||||
====
|
||||
|
||||
ifdef::feature-scroll[]
|
||||
include::repositories-scrolling.adoc[]
|
||||
endif::[]
|
||||
|
||||
[[repositories.limit-query-result]]
|
||||
=== Limiting Query Results
|
||||
|
||||
You can limit the results of query methods by using the `first` or `top` keywords, which you can use interchangeably.
|
||||
You can append an optional numeric value to `top` or `first` to specify the maximum result size to be returned.
|
||||
If the number is left out, a result size of 1 is assumed.
|
||||
The following example shows how to limit the query size:
|
||||
|
||||
.Limiting the result size of a query with `Top` and `First`
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
User findFirstByOrderByLastnameAsc();
|
||||
|
||||
User findTopByOrderByAgeDesc();
|
||||
|
||||
Page<User> queryFirst10ByLastname(String lastname, Pageable pageable);
|
||||
|
||||
Slice<User> findTop3ByLastname(String lastname, Pageable pageable);
|
||||
|
||||
List<User> findFirst10ByLastname(String lastname, Sort sort);
|
||||
|
||||
List<User> findTop10ByLastname(String lastname, Pageable pageable);
|
||||
----
|
||||
====
|
||||
|
||||
The limiting expressions also support the `Distinct` keyword for datastores that support distinct queries.
|
||||
Also, for the queries that limit the result set to one instance, wrapping the result into with the `Optional` keyword is supported.
|
||||
|
||||
If pagination or slicing is applied to a limiting query pagination (and the calculation of the number of available pages), it is applied within the limited result.
|
||||
|
||||
NOTE: Limiting the results in combination with dynamic sorting by using a `Sort` parameter lets you express query methods for the 'K' smallest as well as for the 'K' biggest elements.
|
||||
@@ -1,106 +0,0 @@
|
||||
[[repositories.scrolling]]
|
||||
==== Scrolling
|
||||
|
||||
Scrolling is a more fine-grained approach to iterate through larger results set chunks.
|
||||
Scrolling consists of a stable sort, a scroll type (Offset- or Keyset-based scrolling) and result limiting.
|
||||
You can define simple sorting expressions by using property names and define static result limiting using the <<repositories.limit-query-result,`Top` or `First` keyword>> through query derivation.
|
||||
You can concatenate expressions to collect multiple criteria into one expression.
|
||||
|
||||
Scroll queries return a `Window<T>` that allows obtaining the scroll position to resume to obtain the next `Window<T>` until your application has consumed the entire query result.
|
||||
Similar to consuming a Java `Iterator<List<…>>` by obtaining the next batch of results, query result scrolling lets you access the a `ScrollPosition` through `Window.positionAt(...)`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
Window<User> users = repository.findFirst10ByLastnameOrderByFirstname("Doe", OffsetScrollPosition.initial());
|
||||
do {
|
||||
|
||||
for (User u : users) {
|
||||
// consume the user
|
||||
}
|
||||
|
||||
// obtain the next Scroll
|
||||
users = repository.findFirst10ByLastnameOrderByFirstname("Doe", users.positionAt(users.size() - 1));
|
||||
} while (!users.isEmpty() && users.hasNext());
|
||||
----
|
||||
|
||||
`WindowIterator` provides a utility to simplify scrolling across ``Window``s by removing the need to check for the presence of a next `Window` and applying the `ScrollPosition`.
|
||||
|
||||
[source,java]
|
||||
----
|
||||
WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
|
||||
.startingAt(OffsetScrollPosition.initial());
|
||||
|
||||
while (users.hasNext()) {
|
||||
User u = users.next();
|
||||
// consume the user
|
||||
}
|
||||
----
|
||||
|
||||
[[repositories.scrolling.offset]]
|
||||
===== Scrolling using Offset
|
||||
|
||||
Offset scrolling uses similar to pagination, an Offset counter to skip a number of results and let the data source only return results beginning at the given Offset.
|
||||
This simple mechanism avoids large results being sent to the client application.
|
||||
However, most databases require materializing the full query result before your server can return the results.
|
||||
|
||||
.Using `OffsetScrollPosition` with Repository Query Methods
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
interface UserRepository extends Repository<User, Long> {
|
||||
|
||||
Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, OffsetScrollPosition position);
|
||||
}
|
||||
|
||||
WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
|
||||
.startingAt(OffsetScrollPosition.initial()); <1>
|
||||
----
|
||||
|
||||
<1> Start from the initial offset at position `0`.
|
||||
====
|
||||
|
||||
[[repositories.scrolling.keyset]]
|
||||
===== Scrolling using Keyset-Filtering
|
||||
|
||||
Offset-based requires most databases require materializing the entire result before your server can return the results.
|
||||
So while the client only sees the portion of the requested results, your server needs to build the full result, which causes additional load.
|
||||
|
||||
Keyset-Filtering approaches result subset retrieval by leveraging built-in capabilities of your database aiming to reduce the computation and I/O requirements for individual queries.
|
||||
This approach maintains a set of keys to resume scrolling by passing keys into the query, effectively amending your filter criteria.
|
||||
|
||||
The core idea of Keyset-Filtering is to start retrieving results using a stable sorting order.
|
||||
Once you want to scroll to the next chunk, you obtain a `ScrollPosition` that is used to reconstruct the position within the sorted result.
|
||||
The `ScrollPosition` captures the keyset of the last entity within the current `Window`.
|
||||
To run the query, reconstruction rewrites the criteria clause to include all sort fields and the primary key so that the database can leverage potential indexes to run the query.
|
||||
The database needs only constructing a much smaller result from the given keyset position without the need to fully materialize a large result and then skipping results until reaching a particular offset.
|
||||
|
||||
[WARNING]
|
||||
====
|
||||
Keyset-Filtering requires the keyset properties (those used for sorting) to be non-nullable.
|
||||
This limitation applies due to the store specific `null` value handling of comparison operators as well as the need to run queries against an indexed source.
|
||||
Keyset-Filtering on nullable properties will lead to unexpected results.
|
||||
====
|
||||
|
||||
.Using `KeysetScrollPosition` with Repository Query Methods
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
interface UserRepository extends Repository<User, Long> {
|
||||
|
||||
Window<User> findFirst10ByLastnameOrderByFirstname(String lastname, KeysetScrollPosition position);
|
||||
}
|
||||
|
||||
WindowIterator<User> users = WindowIterator.of(position -> repository.findFirst10ByLastnameOrderByFirstname("Doe", position))
|
||||
.startingAt(KeysetScrollPosition.initial()); <1>
|
||||
----
|
||||
<1> Start at the very beginning and do not apply additional filtering.
|
||||
====
|
||||
|
||||
Keyset-Filtering works best when your database contains an index that matches the sort fields, hence a static sort works well.
|
||||
Scroll queries applying Keyset-Filtering require to the properties used in the sort order to be returned by the query, and these must be mapped in the returned entity.
|
||||
|
||||
You can use interface and DTO projections, however make sure to include all properties that you've sorted by to avoid keyset extraction failures.
|
||||
|
||||
When specifying your `Sort` order, it is sufficient to include sort properties relevant to your query;
|
||||
You do not need to ensure unique query results if you do not want to.
|
||||
The keyset query mechanism amends your sort order by including the primary key (or any remainder of composite primary keys) to ensure each query result is unique.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,18 +0,0 @@
|
||||
[[repositories.namespace-reference]]
|
||||
[appendix]
|
||||
= Namespace reference
|
||||
|
||||
[[populator.namespace-dao-config]]
|
||||
== The `<repositories />` Element
|
||||
The `<repositories />` element triggers the setup of the Spring Data repository infrastructure. The most important attribute is `base-package`, which defines the package to scan for Spring Data repository interfaces. See "`<<repositories.create-instances.xml>>`". The following table describes the attributes of the `<repositories />` element:
|
||||
|
||||
.Attributes
|
||||
[options="header", cols="1,3"]
|
||||
|===============
|
||||
|Name|Description
|
||||
|`base-package`|Defines the package to be scanned for repository interfaces that extend `*Repository` (the actual interface is determined by the specific Spring Data module) in auto-detection mode. All packages below the configured package are scanned, too. Wildcards are allowed.
|
||||
|`repository-impl-postfix`|Defines the postfix to autodetect custom repository implementations. Classes whose names end with the configured postfix are considered as candidates. Defaults to `Impl`.
|
||||
|`query-lookup-strategy`|Determines the strategy to be used to create finder queries. See "`<<repositories.query-methods.query-lookup-strategies>>`" for details. Defaults to `create-if-not-found`.
|
||||
|`named-queries-location`|Defines the location to search for a Properties file containing externally defined queries.
|
||||
|`consider-nested-repositories`|Whether nested repository interface definitions should be considered. Defaults to `false`.
|
||||
|===============
|
||||
@@ -1,15 +0,0 @@
|
||||
[[populator.namespace-reference]]
|
||||
[appendix]
|
||||
= Populators namespace reference
|
||||
|
||||
[[namespace-dao-config]]
|
||||
== The <populator /> element
|
||||
The `<populator />` element allows to populate a data store via the Spring Data repository infrastructure.footnote:[see <<repositories.create-instances.xml>>]
|
||||
|
||||
.Attributes
|
||||
[options="header", cols="1,3"]
|
||||
|===============
|
||||
|Name|Description
|
||||
|`locations`|Where to find the files to read the objects from the repository shall be populated with.
|
||||
|===============
|
||||
|
||||
@@ -1,290 +0,0 @@
|
||||
ifndef::projection-collection[]
|
||||
:projection-collection: Collection
|
||||
endif::[]
|
||||
|
||||
[[projections]]
|
||||
= Projections
|
||||
|
||||
Spring Data query methods usually return one or multiple instances of the aggregate root managed by the repository.
|
||||
However, it might sometimes be desirable to create projections based on certain attributes of those types.
|
||||
Spring Data allows modeling dedicated return types, to more selectively retrieve partial views of the managed aggregates.
|
||||
|
||||
Imagine a repository and aggregate root type such as the following example:
|
||||
|
||||
.A sample aggregate and repository
|
||||
====
|
||||
[source, java, subs="+attributes"]
|
||||
----
|
||||
class Person {
|
||||
|
||||
@Id UUID id;
|
||||
String firstname, lastname;
|
||||
Address address;
|
||||
|
||||
static class Address {
|
||||
String zipCode, city, street;
|
||||
}
|
||||
}
|
||||
|
||||
interface PersonRepository extends Repository<Person, UUID> {
|
||||
|
||||
{projection-collection}<Person> findByLastname(String lastname);
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Now imagine that we want to retrieve the person's name attributes only.
|
||||
What means does Spring Data offer to achieve this? The rest of this chapter answers that question.
|
||||
|
||||
[[projections.interfaces]]
|
||||
== Interface-based Projections
|
||||
|
||||
The easiest way to limit the result of the queries to only the name attributes is by declaring an interface that exposes accessor methods for the properties to be read, as shown in the following example:
|
||||
|
||||
.A projection interface to retrieve a subset of attributes
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
String getFirstname();
|
||||
String getLastname();
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The important bit here is that the properties defined here exactly match properties in the aggregate root.
|
||||
Doing so lets a query method be added as follows:
|
||||
|
||||
.A repository using an interface based projection with a query method
|
||||
====
|
||||
[source, java, subs="+attributes"]
|
||||
----
|
||||
interface PersonRepository extends Repository<Person, UUID> {
|
||||
|
||||
{projection-collection}<NamesOnly> findByLastname(String lastname);
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The query execution engine creates proxy instances of that interface at runtime for each element returned and forwards calls to the exposed methods to the target object.
|
||||
|
||||
NOTE: Declaring a method in your `Repository` that overrides a base method (e.g. declared in `CrudRepository`, a store-specific repository interface, or the `Simple…Repository`) results in a call to the base method regardless of the declared return type. Make sure to use a compatible return type as base methods cannot be used for projections. Some store modules support `@Query` annotations to turn an overridden base method into a query method that then can be used to return projections.
|
||||
|
||||
[[projections.interfaces.nested]]
|
||||
Projections can be used recursively. If you want to include some of the `Address` information as well, create a projection interface for that and return that interface from the declaration of `getAddress()`, as shown in the following example:
|
||||
|
||||
.A projection interface to retrieve a subset of attributes
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface PersonSummary {
|
||||
|
||||
String getFirstname();
|
||||
String getLastname();
|
||||
AddressSummary getAddress();
|
||||
|
||||
interface AddressSummary {
|
||||
String getCity();
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
On method invocation, the `address` property of the target instance is obtained and wrapped into a projecting proxy in turn.
|
||||
|
||||
[[projections.interfaces.closed]]
|
||||
=== Closed Projections
|
||||
|
||||
A projection interface whose accessor methods all match properties of the target aggregate is considered to be a closed projection. The following example (which we used earlier in this chapter, too) is a closed projection:
|
||||
|
||||
.A closed projection
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
String getFirstname();
|
||||
String getLastname();
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If you use a closed projection, Spring Data can optimize the query execution, because we know about all the attributes that are needed to back the projection proxy.
|
||||
For more details on that, see the module-specific part of the reference documentation.
|
||||
|
||||
[[projections.interfaces.open]]
|
||||
=== Open Projections
|
||||
|
||||
Accessor methods in projection interfaces can also be used to compute new values by using the `@Value` annotation, as shown in the following example:
|
||||
|
||||
[[projections.interfaces.open.simple]]
|
||||
.An Open Projection
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
@Value("#{target.firstname + ' ' + target.lastname}")
|
||||
String getFullName();
|
||||
…
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
The aggregate root backing the projection is available in the `target` variable.
|
||||
A projection interface using `@Value` is an open projection.
|
||||
Spring Data cannot apply query execution optimizations in this case, because the SpEL expression could use any attribute of the aggregate root.
|
||||
|
||||
The expressions used in `@Value` should not be too complex -- you want to avoid programming in `String` variables.
|
||||
For very simple expressions, one option might be to resort to default methods (introduced in Java 8), as shown in the following example:
|
||||
|
||||
[[projections.interfaces.open.default]]
|
||||
.A projection interface using a default method for custom logic
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
String getFirstname();
|
||||
String getLastname();
|
||||
|
||||
default String getFullName() {
|
||||
return getFirstname().concat(" ").concat(getLastname());
|
||||
}
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
This approach requires you to be able to implement logic purely based on the other accessor methods exposed on the projection interface.
|
||||
A second, more flexible, option is to implement the custom logic in a Spring bean and then invoke that from the SpEL expression, as shown in the following example:
|
||||
|
||||
[[projections.interfaces.open.bean-reference]]
|
||||
.Sample Person object
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
@Component
|
||||
class MyBean {
|
||||
|
||||
String getFullName(Person person) {
|
||||
…
|
||||
}
|
||||
}
|
||||
|
||||
interface NamesOnly {
|
||||
|
||||
@Value("#{@myBean.getFullName(target)}")
|
||||
String getFullName();
|
||||
…
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Notice how the SpEL expression refers to `myBean` and invokes the `getFullName(…)` method and forwards the projection target as a method parameter.
|
||||
Methods backed by SpEL expression evaluation can also use method parameters, which can then be referred to from the expression.
|
||||
The method parameters are available through an `Object` array named `args`. The following example shows how to get a method parameter from the `args` array:
|
||||
|
||||
.Sample Person object
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
@Value("#{args[0] + ' ' + target.firstname + '!'}")
|
||||
String getSalutation(String prefix);
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Again, for more complex expressions, you should use a Spring bean and let the expression invoke a method, as described <<projections.interfaces.open.bean-reference,earlier>>.
|
||||
|
||||
[[projections.interfaces.nullable-wrappers]]
|
||||
=== Nullable Wrappers
|
||||
|
||||
Getters in projection interfaces can make use of nullable wrappers for improved null-safety. Currently supported wrapper types are:
|
||||
|
||||
* `java.util.Optional`
|
||||
* `com.google.common.base.Optional`
|
||||
* `scala.Option`
|
||||
* `io.vavr.control.Option`
|
||||
|
||||
.A projection interface using nullable wrappers
|
||||
====
|
||||
[source, java]
|
||||
----
|
||||
interface NamesOnly {
|
||||
|
||||
Optional<String> getFirstname();
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
If the underlying projection value is not `null`, then values are returned using the present-representation of the wrapper type.
|
||||
In case the backing value is `null`, then the getter method returns the empty representation of the used wrapper type.
|
||||
|
||||
[[projections.dtos]]
|
||||
== Class-based Projections (DTOs)
|
||||
|
||||
Another way of defining projections is by using value type DTOs (Data Transfer Objects) that hold properties for the fields that are supposed to be retrieved.
|
||||
These DTO types can be used in exactly the same way projection interfaces are used, except that no proxying happens and no nested projections can be applied.
|
||||
|
||||
If the store optimizes the query execution by limiting the fields to be loaded, the fields to be loaded are determined from the parameter names of the constructor that is exposed.
|
||||
|
||||
The following example shows a projecting DTO:
|
||||
|
||||
.A projecting DTO
|
||||
====
|
||||
[source,java]
|
||||
----
|
||||
record NamesOnly(String firstname, String lastname) {
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
Java Records are ideal to define DTO types since they adhere to value semantics:
|
||||
All fields are `private final` and ``equals(…)``/``hashCode()``/``toString()`` methods are created automatically.
|
||||
Alternatively, you can use any class that defines the properties you want to project.
|
||||
|
||||
ifdef::repository-projections-trailing-dto-fragment[]
|
||||
include::{repository-projections-trailing-dto-fragment}[]
|
||||
endif::[]
|
||||
|
||||
[[projection.dynamic]]
|
||||
== Dynamic Projections
|
||||
|
||||
So far, we have used the projection type as the return type or element type of a collection.
|
||||
However, you might want to select the type to be used at invocation time (which makes it dynamic).
|
||||
To apply dynamic projections, use a query method such as the one shown in the following example:
|
||||
|
||||
.A repository using a dynamic projection parameter
|
||||
====
|
||||
[source,java,subs="+attributes"]
|
||||
----
|
||||
interface PersonRepository extends Repository<Person, UUID> {
|
||||
|
||||
<T> {projection-collection}<T> findByLastname(String lastname, Class<T> type);
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
This way, the method can be used to obtain the aggregates as is or with a projection applied, as shown in the following example:
|
||||
|
||||
.Using a repository with dynamic projections
|
||||
====
|
||||
[source,java,subs="+attributes"]
|
||||
----
|
||||
void someMethod(PersonRepository people) {
|
||||
|
||||
{projection-collection}<Person> aggregates =
|
||||
people.findByLastname("Matthews", Person.class);
|
||||
|
||||
{projection-collection}<NamesOnly> aggregates =
|
||||
people.findByLastname("Matthews", NamesOnly.class);
|
||||
}
|
||||
----
|
||||
====
|
||||
|
||||
NOTE: Query parameters of type `Class` are inspected whether they qualify as dynamic projection parameter.
|
||||
If the actual return type of the query equals the generic parameter type of the `Class` parameter, then the matching `Class` parameter is not available for usage within the query or SpEL expressions.
|
||||
If you want to use a `Class` parameter as query argument then make sure to use a different generic parameter, for example `Class<?>`.
|
||||
@@ -1,72 +0,0 @@
|
||||
[[repository-query-keywords]]
|
||||
[appendix]
|
||||
= Repository query keywords
|
||||
|
||||
[[appendix.query.method.subject]]
|
||||
== Supported query method subject keywords
|
||||
|
||||
The following table lists the subject keywords generally supported by the Spring Data repository query derivation mechanism to express the predicate.
|
||||
Consult the store-specific documentation for the exact list of supported keywords, because some keywords listed here might not be supported in a particular store.
|
||||
|
||||
.Query subject keywords
|
||||
[options="header",cols="1,3"]
|
||||
|===============
|
||||
|Keyword | Description
|
||||
|`find…By`, `read…By`, `get…By`, `query…By`, `search…By`, `stream…By`| General query method returning typically the repository type, a `Collection` or `Streamable` subtype or a result wrapper such as `Page`, `GeoResults` or any other store-specific result wrapper. Can be used as `findBy…`, `findMyDomainTypeBy…` or in combination with additional keywords.
|
||||
|`exists…By`| Exists projection, returning typically a `boolean` result.
|
||||
|`count…By`| Count projection returning a numeric result.
|
||||
|`delete…By`, `remove…By`| Delete query method returning either no result (`void`) or the delete count.
|
||||
|`…First<number>…`, `…Top<number>…`| Limit the query results to the first `<number>` of results. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
|
||||
|`…Distinct…`| Use a distinct query to return only unique results. Consult the store-specific documentation whether that feature is supported. This keyword can occur in any place of the subject between `find` (and the other keywords) and `by`.
|
||||
|===============
|
||||
|
||||
[[appendix.query.method.predicate]]
|
||||
== Supported query method predicate keywords and modifiers
|
||||
|
||||
The following table lists the predicate keywords generally supported by the Spring Data repository query derivation mechanism.
|
||||
However, consult the store-specific documentation for the exact list of supported keywords, because some keywords listed here might not be supported in a particular store.
|
||||
|
||||
.Query predicate keywords
|
||||
[options="header",cols="1,3"]
|
||||
|===============
|
||||
|Logical keyword|Keyword expressions
|
||||
|`AND`|`And`
|
||||
|`OR`|`Or`
|
||||
|`AFTER`|`After`, `IsAfter`
|
||||
|`BEFORE`|`Before`, `IsBefore`
|
||||
|`CONTAINING`|`Containing`, `IsContaining`, `Contains`
|
||||
|`BETWEEN`|`Between`, `IsBetween`
|
||||
|`ENDING_WITH`|`EndingWith`, `IsEndingWith`, `EndsWith`
|
||||
|`EXISTS`|`Exists`
|
||||
|`FALSE`|`False`, `IsFalse`
|
||||
|`GREATER_THAN`|`GreaterThan`, `IsGreaterThan`
|
||||
|`GREATER_THAN_EQUALS`|`GreaterThanEqual`, `IsGreaterThanEqual`
|
||||
|`IN`|`In`, `IsIn`
|
||||
|`IS`|`Is`, `Equals`, (or no keyword)
|
||||
|`IS_EMPTY`|`IsEmpty`, `Empty`
|
||||
|`IS_NOT_EMPTY`|`IsNotEmpty`, `NotEmpty`
|
||||
|`IS_NOT_NULL`|`NotNull`, `IsNotNull`
|
||||
|`IS_NULL`|`Null`, `IsNull`
|
||||
|`LESS_THAN`|`LessThan`, `IsLessThan`
|
||||
|`LESS_THAN_EQUAL`|`LessThanEqual`, `IsLessThanEqual`
|
||||
|`LIKE`|`Like`, `IsLike`
|
||||
|`NEAR`|`Near`, `IsNear`
|
||||
|`NOT`|`Not`, `IsNot`
|
||||
|`NOT_IN`|`NotIn`, `IsNotIn`
|
||||
|`NOT_LIKE`|`NotLike`, `IsNotLike`
|
||||
|`REGEX`|`Regex`, `MatchesRegex`, `Matches`
|
||||
|`STARTING_WITH`|`StartingWith`, `IsStartingWith`, `StartsWith`
|
||||
|`TRUE`|`True`, `IsTrue`
|
||||
|`WITHIN`|`Within`, `IsWithin`
|
||||
|===============
|
||||
|
||||
In addition to filter predicates, the following list of modifiers is supported:
|
||||
|
||||
.Query predicate modifier keywords
|
||||
[options="header",cols="1,3"]
|
||||
|===============
|
||||
|Keyword | Description
|
||||
|`IgnoreCase`, `IgnoringCase`| Used with a predicate keyword for case-insensitive comparison.
|
||||
|`AllIgnoreCase`, `AllIgnoringCase`| Ignore case for all suitable properties. Used somewhere in the query method predicate.
|
||||
|`OrderBy…`| Specify a static sorting order followed by the property path and direction (e. g. `OrderByFirstnameAscLastnameDesc`).
|
||||
|===============
|
||||
@@ -1,43 +0,0 @@
|
||||
[appendix]
|
||||
[[repository-query-return-types]]
|
||||
= Repository query return types
|
||||
|
||||
[[appendix.query.return.types]]
|
||||
== Supported Query Return Types
|
||||
|
||||
The following table lists the return types generally supported by Spring Data repositories.
|
||||
However, consult the store-specific documentation for the exact list of supported return types, because some types listed here might not be supported in a particular store.
|
||||
|
||||
NOTE: Geospatial types (such as `GeoResult`, `GeoResults`, and `GeoPage`) are available only for data stores that support geospatial queries.
|
||||
Some store modules may define their own result wrapper types.
|
||||
|
||||
.Query return types
|
||||
[options="header",cols="1,3"]
|
||||
|===============
|
||||
|Return type|Description
|
||||
|`void`|Denotes no return value.
|
||||
|Primitives|Java primitives.
|
||||
|Wrapper types|Java wrapper types.
|
||||
|`T`|A unique entity. Expects the query method to return one result at most. If no result is found, `null` is returned. More than one result triggers an `IncorrectResultSizeDataAccessException`.
|
||||
|`Iterator<T>`|An `Iterator`.
|
||||
|`Collection<T>`|A `Collection`.
|
||||
|`List<T>`|A `List`.
|
||||
|`Optional<T>`|A Java 8 or Guava `Optional`. Expects the query method to return one result at most. If no result is found, `Optional.empty()` or `Optional.absent()` is returned. More than one result triggers an `IncorrectResultSizeDataAccessException`.
|
||||
|`Option<T>`|Either a Scala or Vavr `Option` type. Semantically the same behavior as Java 8's `Optional`, described earlier.
|
||||
|`Stream<T>`|A Java 8 `Stream`.
|
||||
|`Streamable<T>`|A convenience extension of `Iterable` that directly exposes methods to stream, map and filter results, concatenate them etc.
|
||||
|Types that implement `Streamable` and take a `Streamable` constructor or factory method argument|Types that expose a constructor or `….of(…)`/`….valueOf(…)` factory method taking a `Streamable` as argument. See <<repositories.collections-and-iterables.streamable-wrapper>> for details.
|
||||
|Vavr `Seq`, `List`, `Map`, `Set`|Vavr collection types. See <<repositories.collections-and-iterables.vavr>> for details.
|
||||
|`Future<T>`|A `Future`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled.
|
||||
|`CompletableFuture<T>`|A Java 8 `CompletableFuture`. Expects a method to be annotated with `@Async` and requires Spring's asynchronous method execution capability to be enabled.
|
||||
|`Slice<T>`|A sized chunk of data with an indication of whether there is more data available. Requires a `Pageable` method parameter.
|
||||
|`Page<T>`|A `Slice` with additional information, such as the total number of results. Requires a `Pageable` method parameter.
|
||||
|`GeoResult<T>`|A result entry with additional information, such as the distance to a reference location.
|
||||
|`GeoResults<T>`|A list of `GeoResult<T>` with additional information, such as the average distance to a reference location.
|
||||
|`GeoPage<T>`|A `Page` with `GeoResult<T>`, such as the average distance to a reference location.
|
||||
|`Mono<T>`|A Project Reactor `Mono` emitting zero or one element using reactive repositories. Expects the query method to return one result at most. If no result is found, `Mono.empty()` is returned. More than one result triggers an `IncorrectResultSizeDataAccessException`.
|
||||
|`Flux<T>`|A Project Reactor `Flux` emitting zero, one, or many elements using reactive repositories. Queries returning `Flux` can emit also an infinite number of elements.
|
||||
|`Single<T>`|A RxJava `Single` emitting a single element using reactive repositories. Expects the query method to return one result at most. If no result is found, `Mono.empty()` is returned. More than one result triggers an `IncorrectResultSizeDataAccessException`.
|
||||
|`Maybe<T>`|A RxJava `Maybe` emitting zero or one element using reactive repositories. Expects the query method to return one result at most. If no result is found, `Mono.empty()` is returned. More than one result triggers an `IncorrectResultSizeDataAccessException`.
|
||||
|`Flowable<T>`|A RxJava `Flowable` emitting zero, one, or many elements using reactive repositories. Queries returning `Flowable` can emit also an infinite number of elements.
|
||||
|===============
|
||||
@@ -1,8 +0,0 @@
|
||||
[[new-features]]
|
||||
[[upgrading]]
|
||||
= Upgrading Spring Data
|
||||
|
||||
Instructions for how to upgrade from earlier versions of Spring Data are provided on the project https://github.com/spring-projects/spring-data-commons/wiki[wiki].
|
||||
Follow the links in the https://github.com/spring-projects/spring-data-commons/wiki#release-notes[release notes section] to find the version that you want to upgrade to.
|
||||
|
||||
Upgrading instructions are always the first item in the release notes. If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped.
|
||||
Reference in New Issue
Block a user