You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/06/23 06:26:21 UTC

[causeway] branch master updated: CAUSEWAY-3395: updates user guide, custom events

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git


The following commit(s) were added to refs/heads/master by this push:
     new 42c5f34f0e CAUSEWAY-3395: updates user guide, custom events
42c5f34f0e is described below

commit 42c5f34f0e92e70846590cdbfc27ab26d5fffbf1
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Jun 23 07:26:05 2023 +0100

    CAUSEWAY-3395: updates user guide, custom events
---
 .../ROOT/partials/events/custom-events.adoc        | 81 +++++++++++++++++++++-
 1 file changed, 80 insertions(+), 1 deletion(-)

diff --git a/antora/components/userguide/modules/ROOT/partials/events/custom-events.adoc b/antora/components/userguide/modules/ROOT/partials/events/custom-events.adoc
index ab9fd52ec7..1fd22a5df8 100644
--- a/antora/components/userguide/modules/ROOT/partials/events/custom-events.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/events/custom-events.adoc
@@ -5,4 +5,83 @@
 :page-partial:
 
 
-CAUTION: TODO - write something about custom events here...
+The built-in events provided by the framework (domain, UI, lifecycle) are each emitted at well-defined points when the domain object is interacted with through the framework.
+Sometimes though there is a need to emit events programmatically.
+This can be done using the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService].
+
+== Define the Event Class
+
+First define the event class.
+
+* It's common to define a base class in fact, for example:
++
+[source,java]
+.StateTransitionEvent.java
+----
+public abstract class StateTransitionEvent<
+        DO,
+        S extends State<S>
+        > extends java.util.EventObject {
+
+    private final DO domainObject;
+
+    public StateTransitionEvent(
+            final DO domainObject) {
+        super(domainObject);
+        this.domainObject = domainObject;
+    }
+
+    @Override
+    public DO getSource() {
+        return (DO) super.getSource();
+    }
+}
+----
++
+As the example shows, you might wish to inherit from `java.util.EventObject`, but there's no strict requirement to do so.
+
+* if we have a base class, then we need a concrete subclass:
++
+[source,java,indent=0]
+.InvoiceApprovalTransitionEvent.java
+----
+public static class InvoiceApprovalTransitionEvent
+        extends StateTransitionEvent<
+        IncomingInvoice,
+        IncomingInvoiceApprovalState> {
+    public InvoiceApprovalTransitionEvent( final IncomingInvoice domainObject) {
+        super(domainObject, stateTransitionIfAny, transitionType);
+    }
+}
+----
+
+
+== Post the event
+
+With the event class fully defined, we simply instantiate and post:
+
+[source,java]
+----
+val event = new InvoiceApprovalTransitionEvent(
+                invoice, IncomingInvoiceApprovalState.APPROVED);
+
+eventBusService.post(event);
+----
+
+== Subscribe to the event
+
+The subscribers of custom events are defined much the same way as subscribers of the framework's built-in events.
+For example:
+
+[source,java]
+.IncomingInvoiceSubscriber.java
+----
+@Service
+public class IncomingInvoiceSubscriber {
+
+    @EventListener(InvoiceApprovalTransitionEvent.class)
+    public void on(InvoiceApprovalTransitionEvent ev) {
+        // ...
+    }
+}
+----