Skip to content

Commit 3038b17

Browse files
committed
Polish.
See #1161 Original Pull Request: #2594
1 parent 1239776 commit 3038b17

2 files changed

Lines changed: 70 additions & 174 deletions

File tree

‎src/main/antora/modules/ROOT/pages/events.adoc‎

Lines changed: 46 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,122 +1,89 @@
11
[[events]]
22
= Events
33

4-
The REST exporter emits eight different events throughout the process of working with an entity:
4+
The REST exporter emits ten different events throughout the process of working with an entity:
55

66
* javadoc:org.springframework.data.rest.core.event.BeforeCreateEvent[]
77
* javadoc:org.springframework.data.rest.core.event.AfterCreateEvent[]
88
* javadoc:org.springframework.data.rest.core.event.BeforeSaveEvent[]
99
* javadoc:org.springframework.data.rest.core.event.AfterSaveEvent[]
1010
* javadoc:org.springframework.data.rest.core.event.BeforeLinkSaveEvent[]
1111
* javadoc:org.springframework.data.rest.core.event.AfterLinkSaveEvent[]
12+
* javadoc:org.springframework.data.rest.core.event.BeforeLinkDeleteEvent[]
13+
* javadoc:org.springframework.data.rest.core.event.AfterLinkDeleteEvent[]
1214
* javadoc:org.springframework.data.rest.core.event.BeforeDeleteEvent[]
1315
* javadoc:org.springframework.data.rest.core.event.AfterDeleteEvent[]
1416

1517
[[events.lifecycle]]
1618
== Event Lifecycle and Object State
1719

18-
Understanding _when_ each event fires and _what object_ is passed to the event handler is critical for writing correct event handlers and validators.
20+
"Before*" events are published right before the repository call, "After*" events right after it. For example, `PATCH /people/1` runs as follows:
1921

20-
[[events.lifecycle.create]]
21-
=== Create Events (`POST`)
22+
1. `Person` 1 is loaded from the repository.
23+
2. The patch is applied to it.
24+
3. `BeforeSaveEvent` is published with the patched `Person`.
25+
4. `save(…)` is called.
26+
5. `AfterSaveEvent` is published with the object returned by `save(…)`.
2227

23-
When a `POST` request is received to create a new entity:
28+
The following table shows which requests trigger each event and which object the event carries:
2429

25-
1. The request body is deserialized into a new domain object instance.
26-
2. `BeforeCreateEvent` is published with the **new, unsaved domain object**.
27-
3. The repository `save(…)` method is called.
28-
4. `AfterCreateEvent` is published with the **saved domain object** (as returned by the repository, which may include generated IDs, audit fields, etc.).
29-
30-
[[events.lifecycle.save]]
31-
=== Save Events (`PUT` and `PATCH`)
32-
33-
Save events are fired for both `PUT` and `PATCH` requests on item resources. The key distinction is **what object state** is passed to the event, which differs between `PUT` and `PATCH`.
34-
35-
[[events.lifecycle.save.put]]
36-
==== `PUT` Requests
37-
38-
When a `PUT` request is received to replace an existing entity:
39-
40-
1. The existing entity is loaded from the repository.
41-
2. The request body is applied to the existing entity using PUT replacement semantics: writable, mapped properties are overwritten, including with null values, and omitted properties take their deserialization defaults. Identifier, version, and ignored or read-only properties are preserved.
42-
3. `BeforeSaveEvent` is published with the **fully merged domain object** (the existing entity with all fields replaced by the request body).
43-
4. The repository `save(…)` method is called.
44-
5. `AfterSaveEvent` is published with the **saved domain object** (as returned by the repository).
45-
46-
[[events.lifecycle.save.patch]]
47-
==== `PATCH` Requests
48-
49-
When a `PATCH` request is received to partially update an existing entity:
50-
51-
1. The existing entity is loaded from the repository.
52-
2. The patch (either JSON Patch per https://tools.ietf.org/html/rfc6902[RFC 6902] or JSON Merge Patch per https://tools.ietf.org/html/rfc7386[RFC 7386]) is applied directly to the existing entity object in memory.
53-
3. `BeforeSaveEvent` is published with the **merged domain object** — that is, the existing entity with only the patched fields updated.
54-
4. The repository `save(…)` method is called.
55-
5. `AfterSaveEvent` is published with the **saved domain object** (as returned by the repository).
56-
57-
IMPORTANT: For `PATCH` requests, the `BeforeSaveEvent` receives the already-merged domain object (the existing entity with the patch applied), **not** the raw partial input from the request body. This means validators and event handlers can safely inspect the full state of the entity, including fields that were not part of the patch.
58-
59-
[[events.lifecycle.link-save]]
60-
=== Link Save Events (Association Resources)
61-
62-
When a `PUT` or `POST` request is received on an association resource (e.g., `PUT /orders/1/customer`):
63-
64-
1. `BeforeLinkSaveEvent` is published with the **parent entity** and the **linked entity** being associated.
65-
2. The parent entity is saved via the repository.
66-
3. `AfterLinkSaveEvent` is published with the **saved parent entity** and the **linked entity**.
67-
68-
[[events.lifecycle.delete]]
69-
=== Delete Events (`DELETE`)
70-
71-
When a `DELETE` request is received to remove an entity:
72-
73-
1. The entity is loaded from the repository.
74-
2. `BeforeDeleteEvent` is published with the **domain object to be deleted**.
75-
3. The repository `delete(…)` method is called.
76-
4. `AfterDeleteEvent` is published with the **deleted domain object**.
77-
78-
[[events.lifecycle.summary]]
79-
=== Summary Table
80-
81-
The following table summarizes the events, the HTTP operations that trigger them, and the object state passed to the event handler:
82-
83-
[cols="3,2,4", options="header"]
30+
[cols="3,3,4", options="header"]
8431
|===
8532
| Event | Triggered By | Object Passed to Handler
8633

8734
| `BeforeCreateEvent`
88-
| `POST` on collection resource or `PUT` on a non-existent item resource (if creation via `PUT` is supported)
89-
| New, unsaved domain object (deserialized from request body)
35+
| `POST` on a collection resource, `PUT` on a non-existent item resource
36+
| New domain object, deserialized from the request body
9037

9138
| `AfterCreateEvent`
92-
| `POST` on collection resource or `PUT` on a non-existent item resource (if creation via `PUT` is supported)
93-
| Saved domain object (as returned by repository `save(…)`)
39+
| Same as `BeforeCreateEvent`
40+
| Object returned by `save(…)`
9441

9542
| `BeforeSaveEvent`
9643
| `PUT` or `PATCH` on an existing item resource
97-
| Merged domain object (existing entity with request changes applied); for `PATCH`, only the patched fields are updated on the existing entity
44+
| Existing entity with the request applied
9845

9946
| `AfterSaveEvent`
100-
| `PUT` or `PATCH` on an existing item resource
101-
| Saved domain object (as returned by repository `save(…)`)
47+
| Same as `BeforeSaveEvent`
48+
| Object returned by `save(…)`
10249

10350
| `BeforeLinkSaveEvent`
104-
| `PUT` or `POST` on association resource
105-
| Parent entity (before save); linked entity is available via the event
51+
| `PUT`, `POST`, or `PATCH` on an association resource
52+
| Parent entity with the association already updated. The linked value is the new property value: the referenced entity, or the complete collection or map.
10653

10754
| `AfterLinkSaveEvent`
108-
| `PUT` or `POST` on association resource
109-
| Saved parent entity; linked entity is available via the event
55+
| Same as `BeforeLinkSaveEvent`
56+
| Parent entity returned by `save(…)`, with the same linked value
57+
58+
| `BeforeLinkDeleteEvent`
59+
| `DELETE` on a single-valued association resource (`/people/1/address`) or on an item of a multi-valued one (`/people/1/addresses/42`)
60+
| Parent entity with the reference already removed. The linked value is the removed entity for single-valued associations, and the remaining collection or map for multi-valued ones.
61+
62+
| `AfterLinkDeleteEvent`
63+
| Same as `BeforeLinkDeleteEvent`
64+
| Parent entity returned by `save(…)`, with the same linked value
11065

11166
| `BeforeDeleteEvent`
112-
| `DELETE` on item resource
113-
| Domain object to be deleted (loaded from repository)
67+
| `DELETE` on an item resource
68+
| Entity loaded from the repository
11469

11570
| `AfterDeleteEvent`
116-
| `DELETE` on item resource
117-
| Domain object that was deleted
71+
| Same as `BeforeDeleteEvent`
72+
| Same instance, after `deleteById(…)`
11873
|===
11974

75+
The object passed to `BeforeSaveEvent` depends on the HTTP method:
76+
77+
* `PUT` replaces the state of the existing entity with the request body. Omitted properties are reset, except the identifier, version, read-only and Jackson-ignored properties, and associations to exported repositories, which keep their persisted values. See xref:repository-resources.adoc#repository-resources.item-resource.supported-methods.put[`PUT`].
78+
* `PATCH` changes only the patched properties. Handlers receive the full entity, not the partial request body. For example, `PATCH /people/1` with `{ "firstName": "Dave" }` publishes a `Person` with the new `firstName` and the persisted `lastName`.
79+
80+
Requests on non-existent item resources behave as follows:
81+
82+
* `PUT` creates the entity and publishes create events. If `PUT` for creation is disabled, the request is rejected with `405 Method Not Allowed` and no events are published.
83+
* `PATCH` and `DELETE` return `404 Not Found` and publish no events.
84+
85+
On association resources, `PUT` replaces the association, `POST` adds to a collection, and `PATCH` adds to a collection or map. Single-valued associations can only be set with `PUT`.
86+
12087
[[events.application-listener]]
12188
== Writing an `ApplicationListener`
12289

@@ -160,9 +127,6 @@ public class PersonEventHandler {
160127
@HandleBeforeSave
161128
public void handlePersonSave(Person p) {
162129
// … you can now deal with Person in a type-safe way
163-
// For PATCH requests, `p` is the merged object: the existing Person
164-
// with only the patched fields updated. All other fields retain
165-
// their current persisted values.
166130
}
167131
168132
@HandleBeforeSave
Lines changed: 24 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,10 @@
11
[[validation]]
22
= Validation
33

4-
To register a `Validator` instance in Spring Data REST, implement `RepositoryRestConfigurer` and override `configureValidatingRepositoryEventListener` to assign the validator to an event.
5-
6-
Use `ValidatingRepositoryEventListener.addValidator(…)` with the event name and the validator instance. For example, register a validator for `Person` instances under `beforeCreate` to validate new entities before they are saved. Naming a validator bean with an event prefix does not automatically register it.
7-
8-
[[validation.events]]
9-
== Validation Events and Object State
10-
11-
Validators are invoked as part of the Spring Data REST event lifecycle. Understanding _when_ each validator fires and _what object_ it receives is essential for writing correct validation logic.
12-
13-
The following table shows the event name used to register a validator with `ValidatingRepositoryEventListener.addValidator(…)`, the HTTP operation that triggers it, and the state of the object passed to the validator:
14-
15-
[cols="2,2,4", options="header"]
16-
|===
17-
| Event Name | Triggered By | Object Passed to Validator
18-
19-
| `beforeCreate`
20-
| `POST` on collection resource
21-
| New, unsaved domain object (deserialized from request body)
22-
23-
| `afterCreate`
24-
| `POST` on collection resource
25-
| Saved domain object (as returned by repository `save(…)`)
26-
27-
| `beforeSave`
28-
| `PUT` or `PATCH` on item resource
29-
| Merged domain object (existing entity with request changes applied); see note below about `PATCH`
30-
31-
| `afterSave`
32-
| `PUT` or `PATCH` on item resource
33-
| Saved domain object (as returned by repository `save(…)`)
34-
35-
| `beforeLinkSave`
36-
| `PUT` or `POST` on association resource
37-
| Parent entity (before save)
38-
39-
| `afterLinkSave`
40-
| `PUT` or `POST` on association resource
41-
| Saved parent entity
42-
43-
| `beforeDelete`
44-
| `DELETE` on item resource
45-
| Domain object to be deleted (loaded from repository)
46-
47-
| `afterDelete`
48-
| `DELETE` on item resource
49-
| Domain object that was deleted
50-
|===
51-
52-
[[validation.events.patch]]
53-
=== Validation and `PATCH` Requests
54-
55-
For `PATCH` requests, the `beforeSave` validator receives the **already-merged domain object** — that is, the existing entity loaded from the repository with the patch already applied to it in memory. The validator does **not** receive the raw partial input from the request body.
56-
57-
This means:
58-
59-
* You can safely validate the full state of the entity, including fields that were not part of the patch.
60-
* You do not need to handle the case of missing or `null` fields that simply were not included in the partial update.
61-
62-
For example, if a `Person` entity has `firstName` and `lastName` fields, and a `PATCH` request only updates `firstName`, the `beforeSave` validator will receive a `Person` object with both `firstName` (updated) and `lastName` (unchanged from the persisted value).
63-
64-
====
65-
[source,java]
66-
----
67-
public class BeforeSavePersonValidator implements Validator {
68-
69-
@Override
70-
public boolean supports(Class<?> clazz) {
71-
return Person.class.equals(clazz);
72-
}
73-
74-
@Override
75-
public void validate(Object target, Errors errors) {
76-
Person person = (Person) target;
77-
78-
// Safe to validate the full entity state for both PUT and PATCH requests.
79-
// For PATCH, this object already has the patch applied on top of the
80-
// existing persisted entity — it is not a partial/incomplete object.
81-
if (!StringUtils.hasText(person.getFirstName())) {
82-
errors.rejectValue("firstName", "firstName.empty");
83-
}
84-
if (!StringUtils.hasText(person.getLastName())) {
85-
errors.rejectValue("lastName", "lastName.empty");
86-
}
87-
}
88-
}
89-
----
90-
====
91-
924
[[validation.assigning-validators]]
93-
[[validation.assigning-validators.manual]]
94-
== Assigning Validators Manually
5+
== Assigning Validators
956

96-
Register an instance of your validator with the listener that invokes validators for the corresponding event. In your configuration that implements `RepositoryRestConfigurer`, override the `configureValidatingRepositoryEventListener` method and call `addValidator` on the `ValidatingRepositoryEventListener`, passing the event on which you want this validator to be triggered and an instance of the validator. The following example shows how to do so:
7+
To register a `Validator` instance, implement `RepositoryRestConfigurer`, override `configureValidatingRepositoryEventListener`, and call `addValidator` on the `ValidatingRepositoryEventListener`, passing the event on which you want this validator to be triggered and an instance of the validator. The following example shows how to do so:
978

989
====
9910
[source,java]
@@ -105,4 +16,25 @@ public void configureValidatingRepositoryEventListener(ValidatingRepositoryEvent
10516
----
10617
====
10718

108-
For more details on the event lifecycle and the object state at each stage, see xref:events.adoc[Events].
19+
[[validation.events]]
20+
== Validation Events
21+
22+
A validator runs when its event is published and validates the object the event carries. For link events, that is the parent entity. See xref:events.adoc#events.lifecycle[Event Lifecycle and Object State] for when each event fires and which object it carries.
23+
24+
The following table maps event names to events:
25+
26+
[cols="1,1", options="header"]
27+
|===
28+
| Event Name | Event
29+
30+
| `beforeCreate` | `BeforeCreateEvent`
31+
| `afterCreate` | `AfterCreateEvent`
32+
| `beforeSave` | `BeforeSaveEvent`
33+
| `afterSave` | `AfterSaveEvent`
34+
| `beforeLinkSave` | `BeforeLinkSaveEvent`
35+
| `afterLinkSave` | `AfterLinkSaveEvent`
36+
| `beforeDelete` | `BeforeDeleteEvent`
37+
| `afterDelete` | `AfterDeleteEvent`
38+
|===
39+
40+
`BeforeLinkDeleteEvent` and `AfterLinkDeleteEvent` do not trigger validation.

0 commit comments

Comments
 (0)