This is an automated email from the ASF dual-hosted git repository.
ntimofeev pushed a commit to branch STABLE-4.2
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/STABLE-4.2 by this push:
new 70d8e9795 Mention callbacks configuration via annotations
70d8e9795 is described below
commit 70d8e9795d08f2866dde64d34baa0c5dc441c82d
Author: Nikita Timofeev <stari...@gmail.com>
AuthorDate: Fri Aug 9 15:20:58 2024 +0400
Mention callbacks configuration via annotations
(cherry picked from commit 2349e6e5a77500fef7c2d8289e883b640dc67a70)
---
.../asciidoc/_cayenne-guide/part2/lifecycle.adoc | 28 ++++++++++++++++++----
1 file changed, 23 insertions(+), 5 deletions(-)
diff --git
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
index f6fdecce0..d961650e7 100644
---
a/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
+++
b/docs/asciidoc/cayenne-guide/src/docs/asciidoc/_cayenne-guide/part2/lifecycle.adoc
@@ -60,7 +60,29 @@ a|
==== Callbacks on Persistent Objects
-Callback methods on Persistent classes are mapped in CayenneModeler for each
ObjEntity. Empty callback methods are automatically created as a part of class
generation (either with Maven, Ant or the Modeler) and are later filled with
appropriate logic by the programmer. E.g. assuming we mapped a 'post-add'
callback called 'onNewOrder' in ObjEntity 'Order', the following code will be
generated:
+Apache Cayenne provides two main methods to set up callbacks for Persistent
objects: using annotated methods or configuring them via Cayenne Modeler.
+As a rule callback methods do not have any knowledge of the outside
application, and can only access the state of the object itself and possibly
the state of other persistent objects via object's own ObjectContext.
+
+NOTE: Validation and callbacks: There is a clear overlap in functionality
between object callbacks and `DataObject.validateForX()` methods. In the future
validation may be completely superseded by callbacks. It is a good idea to use
"validateForX" strictly for validation (or not use it at all). Updating the
state before commit should be done via callbacks.
+
+===== Annotated Callbacks Methods
+
+You can define callback methods directly in your Persistent object class using
annotations. These methods are invoked automatically by Cayenne during the
lifecycle of the object.
+
+[source,java]
+----
+public class Order extends _Order {
+
+ @PostAdd
+ public void onNewOrder() {
+ // Custom logic before inserting
+ }
+}
+----
+
+===== Cayenne Modeler Callbacks Configuration
+
+Alternatively, you can configure callbacks using the Cayenne Modeler for each
ObjEntity. Empty callback methods are automatically created as a part of class
generation (either with Maven, Ant or the Modeler) and are later filled with
appropriate logic by the programmer. E.g. assuming we mapped a 'post-add'
callback called 'onNewOrder' in ObjEntity 'Order', the following code will be
generated:
[source, Java]
----
@@ -79,10 +101,6 @@ public class Order extends _Order {
As `onNewOrder()` is already declared in the mapping, it does not need to be
registered explicitly. Implementing the method in subclass to do something
meaningful is all that is required at this point.
-As a rule callback methods do not have any knowledge of the outside
application, and can only access the state of the object itself and possibly
the state of other persistent objects via object's own ObjectContext.
-
-NOTE: Validation and callbacks: There is a clear overlap in functionality
between object callbacks and `DataObject.validateForX()` methods. In the future
validation may be completely superseded by callbacks. It is a good idea to use
"validateForX" strictly for validation (or not use it at all). Updating the
state before commit should be done via callbacks.
-
==== Callbacks on Non-Persistent Listeners
A listener is simply some application class that has one or more annotated
callback methods. A callback method signature should be `void
someMethod(SomePersistentType object)`. It can be public, private, protected or
use default access:
