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

DATACMNS-1467 - Apply suggested documentation changes.

Browse Source 
Original Pull Request: #332
This commit is contained in:
Christoph Strobl
2019-06-06 08:49:24 +02:00
parent 687222d1fa
commit 84049e9f8e
1 changed files with 10 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
src/main/asciidoc/entity-callbacks.adoc
View File

@@ -1,27 +1,27 @@
[entity-callbacks]
= Entity Callbacks
The Spring Data infrastructure provides hooks for modifying an entity before and/or after certain methods are invoked.
Those so called ``EntityCallback``s 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`, with which you might be already familiar.
Some Spring Data modules publish store specific events, like a `BeforeSaveEvent` that allow modifying the given entity which in some cases, eg. immutable types, can cause trouble.
Another aspects is that, event publishing relies on `ApplicationEventMulticaster` that can be configured with an asynchronous `TaskExecutor` leading to unpredictable outcome as event processing can be forked onto a `Thread`.
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 guaranteeing an in-order execution at well-defined checkpoints within the processing chain, returning a potentially modified entity or an reactive wrapper type.
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 only considers synchronous entity callbacks and a reactive implementation considers only reactive entity callbacks.
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``s.
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 a set of predefined `EntityCallback` interfaces covering the entity lifecycle.
Each Spring Data module typically ships with a set of predefined `EntityCallback` interfaces covering the entity lifecycle.
.Anatomy of an `EntityCallback`
====
@@ -98,7 +98,7 @@ class DefaultingEntityCallback implements BeforeSaveCallback<Person>, Ordered <2
[entity-callbacks.register]
== Registering Entity Callbacks
``EntityCallback`` beans are picked up by the store specific implementations in case they are registered in the `ApplicationContext`.
`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: