You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/03/03 09:07:03 UTC
[isis] 04/05: ISIS-2444: more on domain event docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 5dead7731da9b185a7dd2f6202642a973988fd32
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 3 07:22:48 2021 +0000
ISIS-2444: more on domain event docs
---
.../applib-classes/pages/events/domainevent.adoc | 4 +-
.../events/domainevent/CollectionDomainEvent.adoc | 50 ---------------
.../events/domainevent/PropertyDomainEvent.adoc | 46 --------------
.../applib/events/domain/ActionDomainEvent.java | 19 +++---
.../events/domain/CollectionDomainEvent.java | 13 ++--
.../applib/events/domain/PropertyDomainEvent.java | 73 +++++++++++++++++-----
6 files changed, 80 insertions(+), 125 deletions(-)
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
index a26d546..8dcc604 100644
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/events/domainevent.adoc
@@ -6,10 +6,8 @@
This section catalogues the various domain event classes defined by Apache Isis.
-These events are broadcast on the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService].
-The domain events are broadcast as a result of being specified in the , or xref:refguide:applib:index/annotation/Collection.adoc#domainEvent[@Collection#domainEvent()] attributes.
+These events are broadcast through the xref:refguide:applib:index/services/eventbus/EventBusService.adoc[EventBusService] whenever the framework interacts with the domain object members
-They are listed in the table below.
.Domain Event Classes
[cols="1a,2a,2a,2a", options="header"]
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc
deleted file mode 100644
index e35af06..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/CollectionDomainEvent.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[CollectionDomainEvent]]
-= `CollectionDomainEvent`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-
-== API
-
-The API of the class is:
-
-// TODO: v2: use include::[]
-
-[source,java]
-----
-public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S> {
-
- public static class Default // <.>
- extends CollectionDomainEvent<Object, Object> { }
- public static class Noop // <.>
- extends CollectionDomainEvent<Object, Object> { }
- public static class Doop // <.>
- extends CollectionDomainEvent<Object, Object> { }
-
- public T getValue(); // <.>
- public Of getOf(); // <.>
-}
-----
-<1> The `Default` nested static class is the default for the xref:refguide:applib:index/annotation/Collection.adoc#domainEvent[@Collection#domainEvent()] annotation attribute.
-Whether this raises an event or not depends upon the
-`isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault` configuration property.
-<2> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).
-<3> Similarly, the `Doop` class is provided as a convenience to indicate that an event _should_ be raised (irrespective of the configuration property setting).
-<4> the object being added or removed
-<5> whether this is to add or to remove
-
-where the `Of` enum indicates in turn how the collection is being interacted with:
-
-[source,java]
-----
-public static enum Of {
- ACCESS, // <1>
- ADD_TO, // <2>
- REMOVE_FROM // <3>
-}
-----
-<1> collection is being rendered; set during for hide and disable phases
-<2> collection is being added to; set for validate, executing and executed phases
-<3> or, collection is being removed from; set for validate, executing and executed phases
diff --git a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/PropertyDomainEvent.adoc b/antora/components/refguide/modules/applib-classes/pages/events/domainevent/PropertyDomainEvent.adoc
deleted file mode 100644
index 6f37046..0000000
--- a/antora/components/refguide/modules/applib-classes/pages/events/domainevent/PropertyDomainEvent.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[PropertyDomainEvent]]
-= `PropertyDomainEvent`
-
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-:page-partial:
-
-
-Subclass of xref:applib-classes:events.adoc#AbstractDomainEvent[AbstractDomainEvent] for properties.
-
-The class has a couple of responsibilities (in addition to those it inherits):
-
-* capture the target object being interacted with
-
-* capture the old and new values of the property
-
-
-The class itself is instantiated automatically by the framework whenever interacting with a rendered object's property.
-
-== API
-
-The API of the class is:
-
-// TODO: v2: use include::[]
-
-[source,java]
-----
-public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
-
- public static class Default // <.>
- extends PropertyDomainEvent<Object, Object> { }
- public static class Noop // <.>
- extends PropertyDomainEvent<Object, Object> { }
- public static class Doop // <.>
- extends PropertyDomainEvent<Object, Object> { }
-
- public T getOldValue(); // <.>
- public T getNewValue(); // <.>
-}
-----
-<1> The `Default` nested static class is the default for the xref:refguide:applib:index/annotation/Property.adoc#domainEvent[@Property#domainEvent()] annotation attribute.
-Whether this raises an event or not depends upon the
-`isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault` configuration property.
-<2> The `Noop` class is provided as a convenience to indicate that an event should _not_ be posted (irrespective of the configuration property setting).
-<3> Similarly, the `Doop` class is provided as a convenience to indicate that an event _should_ be raised (irrespective of the configuration property setting).
-<4> The pre-modification value of the property; populated at validate and subsequent phases.
-<5> The proposed (post-modification) value of the property; populated at validate and subsequent phases
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
index 983b711..fb21014 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
@@ -29,17 +29,20 @@ import lombok.Getter;
import lombok.Setter;
/**
- * Subclass of {@link AbstractDomainEvent} for actions.
+ * Fired whenever the framework interacts with a domain object's action.
*
* <p>
- * The class has a number of responsibilities (in addition to those it inherits):
+ * This is the specialization of {@link AbstractDomainEvent}, for actions,
+ * which should then be further subclassed by domain application.
+ * </p>
+ *
+ * <p>
+ * The class has a number of responsibilities (in addition to those it
+ * inherits):
* </p>
*
* <ul>
* <li>
- * capture the target object being interacted with
- * </li>
- * <li>
* capture the arguments for each of the action's parameters
* </li>
* <li>
@@ -49,8 +52,8 @@ import lombok.Setter;
* </ul>
*
* <p>
- * The class itself is instantiated automatically by the framework whenever
- * interacting with a rendered object's action.
+ * The class itself is instantiated automatically by the framework using a
+ * no-arg constructor; fields are set reflectively.
* </p>
*
* @since 1.x {@index}
@@ -63,7 +66,7 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
*
* <p>
* Whether this raises an event or not depends upon the
- * <tt>isis.core.meta-model.annotation.action.domain-event.post-for-default</tt>
+ * <tt>isis.applib.annotation.action.domain-event.post-for-default</tt>
* configuration property.
* </p>
*/
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
index a126c76..91ee8b8 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
@@ -24,11 +24,16 @@ import org.apache.isis.applib.util.ToString;
import lombok.Getter;
/**
- * Subclass of {@link AbstractDomainEvent} for collections.
+ * Fired whenever the framework interacts with a domain object's collection.
*
* <p>
- * The class itself is instantiated automatically by the framework whenever
- * interacting with a rendered object's collection.
+ * This is the specialization of {@link AbstractDomainEvent}, for collections,
+ * * which should then be further subclassed by domain application. .
+ * </p>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework using a
+ * no-arg constructor; fields are set reflectively.
* </p>
*
* @since 1.x {@index}
@@ -42,7 +47,7 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
*
* <p>
* Whether this raises an event or not depends upon the
- * <tt>isis.core.meta-model.annotation.collection.domain-event.post-for-default</tt>
+ * <tt>isis.applib.annotation.collection.domain-event.post-for-default</tt>
* configuration property.
* </p>
*/
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
index 2801a66..5886dfa 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
@@ -25,27 +25,57 @@ import lombok.Getter;
import lombok.Setter;
/**
+ * Fired whenever the framework interacts with a domain object's property.
+ *
+ * <p>
+ * This is the specialization of {@link AbstractDomainEvent}, for properties,
+ * * which should then be further subclassed by domain application.
+ * </p>
+ *
+ * <p>
+ * The class has a number of responsibilities (in addition to those it
+ * inherits):
+ * </p>
+ *
+ * <ul>
+ * <li>
+ * capture the old and new values of the property
+ * </li>
+ * </ul>
+ *
+ * <p>
+ * The class itself is instantiated automatically by the framework using a
+ * no-arg constructor; fields are set reflectively.
+ * </p>
+ *
* @since 1.x {@index}
*/
public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
/**
* This class is the default for the
- * {@link org.apache.isis.applib.annotation.Property#domainEvent()} annotation attribute. Whether this
- * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.property.domain-event.post-for-default</tt>
+ * {@link org.apache.isis.applib.annotation.Property#domainEvent()}
+ * annotation attribute.
+ *
+ * <p>
+ * Whether this raises an event or not depends upon the
+ * <tt>isis.applib.annotation.property.domain-event.post-for-default</tt>
* configuration property.
+ * </p>
*/
public static class Default extends PropertyDomainEvent<Object, Object> {}
/**
- * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event.
+ * Convenience class to use indicating that an event should <i>not</i> be
+ * posted (irrespective of the configuration property setting for the
+ * {@link Default} event.
*/
public static class Noop extends PropertyDomainEvent<Object, Object> {}
/**
- * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
- * property setting for the {@link Default} event..
+ * Convenience class meaning that an event <i>should</i> be posted
+ * (irrespective of the configuration property setting for the
+ * {@link Default} event..
*/
public static class Doop extends PropertyDomainEvent<Object, Object> {}
@@ -57,21 +87,37 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
}
/**
- * The current (pre-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
- * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
+ * The current (pre-modification) value of the property.
+ *
+ * <p>
+ * Populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent
+ * phases (but null for
+ * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden}
+ * and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable}
+ * phases).
+ * </p>
*/
@Getter @Setter
private T oldValue;
/**
- * The proposed (post-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
- * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
+ * The proposed (post-modification) value of the property.
+ *
+ * <p>
+ * Populated at
+ * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE}
+ * and subsequent phases (but null for
+ * {@link Phase#HIDE hidden}
+ * and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable}
+ * phases).
+ * </p>
*
* <p>
* The proposed new value can also be modified by event handlers
- * during the {@link Phase#EXECUTING} phase. The new value must be
- * the same type as the expected value; the framework performs
- * no sanity checks.
+ * during the
+ * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#EXECUTING executing}
+ * phase. The new value must be the same type as the expected value;
+ * the framework performs no sanity checks.
* </p>
*/
@Getter @Setter
@@ -79,7 +125,6 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
-
private static final ToString<PropertyDomainEvent<?,?>> toString =
ObjectContracts.<PropertyDomainEvent<?,?>>
toString("source", PropertyDomainEvent::getSource)