This is an automated email from the ASF dual-hosted git repository.
ntimofeev pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/cayenne.git
The following commit(s) were added to refs/heads/master by this push:
new 2349e6e5a Mention callbacks configuration via annotations
2349e6e5a is described below
commit 2349e6e5a77500fef7c2d8289e883b640dc67a70
Author: Nikita Timofeev <[email protected]>
AuthorDate: Fri Aug 9 15:20:58 2024 +0400
Mention callbacks configuration via annotations
---
.../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 7178941ac..493ee6cfa 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 `PersistentObject.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 `PersistentObject.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:
