From 84049e9f8ec397a121e3a710855350a530fdba0d Mon Sep 17 00:00:00 2001 From: Christoph Strobl Date: Thu, 6 Jun 2019 08:49:24 +0200 Subject: [PATCH] DATACMNS-1467 - Apply suggested documentation changes. Original Pull Request: #332 --- src/main/asciidoc/entity-callbacks.adoc | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/main/asciidoc/entity-callbacks.adoc b/src/main/asciidoc/entity-callbacks.adoc index b2c41fb4b..29c732f26 100644 --- a/src/main/asciidoc/entity-callbacks.adoc +++ b/src/main/asciidoc/entity-callbacks.adoc @@ -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, 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: