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

Improve and clarify documentation of callbacks.

Browse Source 
This also removes deprecated Events and Callbacks.

Closes #1236
This commit is contained in:
Jens Schauder
2022-05-11 13:43:53 +02:00
parent f6e7792094
commit 4353dc8e06
16 changed files with 128 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
src/main/asciidoc/jdbc.adoc
View File

@@ -848,7 +848,7 @@ class PersonLoadListener extends AbstractRelationalEventListener<Person> {
----
====
The following table describes the available events:
The following table describes the available events. For more details about the exact relation between process steps see the link:#jdbc.entity-callbacks[description of available callbacks] which map 1:1 to events.
.Available events
|===
@@ -865,7 +865,7 @@ The following table describes the available events:
This is the correct event if you want to set an id programmatically.
| {javadoc-base}/org/springframework/data/relational/core/mapping/event/BeforeSaveEvent.html[`BeforeSaveEvent`]
| Before an aggregate root gets saved (that is, inserted or updated but after the decision about whether if it gets inserted or updated was made).
| Before an aggregate root gets saved (that is, inserted or updated but after the decision about whether if it gets inserted or updated was made). Do not use this for creating Ids for new aggregates. Use `BeforeConvertEvent` or even better `BeforeConvertCallback` instead.
| {javadoc-base}org/springframework/data/relational/core/mapping/event/AfterSaveEvent.html[`AfterSaveEvent`]
| After an aggregate root gets saved (that is, inserted or updated).
@@ -883,35 +883,43 @@ WARNING: Lifecycle events depend on an `ApplicationEventMulticaster`, which in c
[[jdbc.entity-callbacks]]
=== Store-specific EntityCallbacks
Spring Data JDBC uses the `EntityCallback` API for its auditing support and reacts on the following callbacks:
Spring Data JDBC uses the `EntityCallback` API for its auditing support and reacts on the callbacks listed in the following table.
.Available Callbacks
.Process Steps and Callbacks of the Different Processes performed by Spring Data JDBC.
|===
| `EntityCallback` | When It Is Published
| Process | `EntityCallback` / Process Step | Comment
| {javadoc-base}org/springframework/data/relational/core/mapping/event/BeforeDeleteCallback.html[`BeforeDeleteCallback`]
| Before an aggregate root gets deleted.
.3+| Delete | {javadoc-base}org/springframework/data/relational/core/mapping/event/BeforeDeleteCallback.html[`BeforeDeleteCallback`]
| Before the actual deletion.
2+| The aggregate root and all the entities of that aggregate get removed from the database.
| {javadoc-base}org/springframework/data/relational/core/mapping/event/AfterDeleteCallback.html[`AfterDeleteCallback`]
| After an aggregate root gets deleted.
| After an aggregate gets deleted.
.6+| Save 2+| Determine if an insert or an update of the aggregate is to be performed dependen on if it is new or not.
| {javadoc-base}/org/springframework/data/relational/core/mapping/event/BeforeConvertCallback.html[`BeforeConvertCallback`]
| Before an aggregate root gets converted into a plan for executing SQL statements, but after the decision was made if the aggregate is new or not, i.e. if an update or an insert is in order.
This is the correct callback if you want to set an id programmatically.
| This is the correct callback if you want to set an id programmatically. In the previous step new aggregates got detected as such and a Id generated in this step would be used in the following step.
2+| Convert the aggregate to a aggregate change, it is a sequence of SQL statements to be executed against the database. In this step the decision is made if an Id is provided by the aggregate or if the Id is still empty and is expected to be generated by the database.
| {javadoc-base}/org/springframework/data/relational/core/mapping/event/BeforeSaveCallback.html[`BeforeSaveCallback`]
| Before an aggregate root gets saved (that is, inserted or updated but after the decision about whether if it gets inserted or updated was made).
| Changes made to the aggregate root may get considered, but the decision if an id value will be sent to the database is already made in the previous step.
2+| The SQL statements determined above get executed against the database.
| {javadoc-base}org/springframework/data/relational/core/mapping/event/AfterSaveCallback.html[`AfterSaveCallback`]
| After an aggregate root gets saved (that is, inserted or updated).
| {javadoc-base}org/springframework/data/relational/core/mapping/event/AfterLoadCallback.html[`AfterLoadCallback`]
| After an aggregate root gets created from a database `ResultSet` and all its property get set. _This is deprecated, use `AfterConvertCallback` instead_
.2+| Load 2+| Load the aggregate using 1 or more SQL queries. Construct the aggregate from the resultset.
| {javadoc-base}org/springframework/data/relational/core/mapping/event/AfterConvertCallback.html[`AfterConvertCallback`]
| After an aggregate root gets created from a database `ResultSet` and all its property get set.
|
|===
We encourage the use of callbacks over events since they support the use of immutable classes and therefore are more powerful and versatile than events.
include::{spring-data-commons-docs}/entity-callbacks.adoc[leveloffset=+1]
include::jdbc-custom-conversions.adoc[]