|
1 | 1 | [[events]] |
2 | 2 | = Events |
3 | 3 |
|
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: |
5 | 5 |
|
6 | 6 | * javadoc:org.springframework.data.rest.core.event.BeforeCreateEvent[] |
7 | 7 | * javadoc:org.springframework.data.rest.core.event.AfterCreateEvent[] |
8 | 8 | * javadoc:org.springframework.data.rest.core.event.BeforeSaveEvent[] |
9 | 9 | * javadoc:org.springframework.data.rest.core.event.AfterSaveEvent[] |
10 | 10 | * javadoc:org.springframework.data.rest.core.event.BeforeLinkSaveEvent[] |
11 | 11 | * 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[] |
12 | 14 | * javadoc:org.springframework.data.rest.core.event.BeforeDeleteEvent[] |
13 | 15 | * javadoc:org.springframework.data.rest.core.event.AfterDeleteEvent[] |
14 | 16 |
|
15 | 17 | [[events.lifecycle]] |
16 | 18 | == Event Lifecycle and Object State |
17 | 19 |
|
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: |
19 | 21 |
|
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(…)`. |
22 | 27 |
|
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: |
24 | 29 |
|
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"] |
84 | 31 | |=== |
85 | 32 | | Event | Triggered By | Object Passed to Handler |
86 | 33 |
|
87 | 34 | | `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 |
90 | 37 |
|
91 | 38 | | `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(…)` |
94 | 41 |
|
95 | 42 | | `BeforeSaveEvent` |
96 | 43 | | `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 |
98 | 45 |
|
99 | 46 | | `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(…)` |
102 | 49 |
|
103 | 50 | | `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. |
106 | 53 |
|
107 | 54 | | `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 |
110 | 65 |
|
111 | 66 | | `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 |
114 | 69 |
|
115 | 70 | | `AfterDeleteEvent` |
116 | | -| `DELETE` on item resource |
117 | | -| Domain object that was deleted |
| 71 | +| Same as `BeforeDeleteEvent` |
| 72 | +| Same instance, after `deleteById(…)` |
118 | 73 | |=== |
119 | 74 |
|
| 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 | + |
120 | 87 | [[events.application-listener]] |
121 | 88 | == Writing an `ApplicationListener` |
122 | 89 |
|
@@ -160,9 +127,6 @@ public class PersonEventHandler { |
160 | 127 | @HandleBeforeSave |
161 | 128 | public void handlePersonSave(Person p) { |
162 | 129 | // … 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. |
166 | 130 | } |
167 | 131 |
|
168 | 132 | @HandleBeforeSave |
|
0 commit comments