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 2018/11/23 08:36:10 UTC
[isis] 04/04: ISIS-2043: updates docs for
@DomainObject#xxxDomainEvent
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/isis.git
commit 901b63e2236bd93ed3af8a4b5e188dddecd27dd5
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Nov 22 19:11:07 2018 +0100
ISIS-2043: updates docs for @DomainObject#xxxDomainEvent
---
.../guides/rgant/_rgant-Action_domainEvent.adoc | 79 ++++++++++++++--------
.../rgant/_rgant-Collection_domainEvent.adoc | 44 ++++++------
.../_rgant-DomainObjectLayout_bookmarking.adoc | 6 +-
.../_rgant-DomainObjectLayout_cssClassFa.adoc | 8 +--
.../_rgant-DomainObjectLayout_describedAs.adoc | 4 +-
.../_rgant-DomainObjectLayout_iconUiEvent.adoc | 6 +-
.../rgant/_rgant-DomainObjectLayout_named.adoc | 3 +-
.../rgant/_rgant-DomainObjectLayout_paged.adoc | 6 +-
.../rgant/_rgant-DomainObjectLayout_plural.adoc | 3 +-
.../_rgant-DomainObjectLayout_titleUiEvent.adoc | 34 ++++------
.../_rgant-DomainObject_actionDomainEvent.adoc | 45 ++++++++++++
.../_rgant-DomainObject_collectionDomainEvent.adoc | 62 +++++++++++++++++
...rgant-DomainObject_persistedLifecycleEvent.adoc | 18 ++---
...gant-DomainObject_persistingLifecycleEvent.adoc | 15 ++--
.../_rgant-DomainObject_propertyDomainEvent.adoc | 62 +++++++++++++++++
.../rgant/_rgant-DomainObject_publishing.adoc | 13 ++--
..._rgant-DomainObject_removingLifecycleEvent.adoc | 24 +++----
.../_rgant-DomainObject_updatedLifecycleEvent.adoc | 25 +++----
..._rgant-DomainObject_updatingLifecycleEvent.adoc | 30 ++++----
.../guides/rgant/_rgant-Property_domainEvent.adoc | 45 ++++++------
..._ugvw_hints-and-tips_highlight-current-row.adoc | 4 +-
21 files changed, 347 insertions(+), 189 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
index 504a118..ed63229 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's actions, the events that are fired are:
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
+In the cases of the domain object's actions, the events that are fired are:
* hide phase: to check that the action is visible (has not been hidden)
* disable phase: to check that the action is usable (has not been disabled)
@@ -15,7 +16,8 @@ Whenever a domain object (or list of domain objects) is to be rendered, the fram
Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
-By default the event raised is `ActionDomainEvent.Default`. For example:
+By default the event raised is `ActionDomainEvent.Default`.
+For example:
[source,java]
----
@@ -28,9 +30,9 @@ public class ToDoItem {
The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
-subclasses) to be defined instead. This attribute is also supported for
-xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[collections] and
-xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
+subclasses) to be defined instead.
+This attribute is also supported for
+xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[collections] and xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
For example:
@@ -54,10 +56,6 @@ This substantially reduces the boilerplate required in subclasses because no exp
-
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
@@ -68,7 +66,8 @@ Subscribers can be either coarse-grained (if they subscribe to the top-level eve
----
@DomainService(nature=NatureOfService.DOMAIN)
public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
+ @org.axonframework.eventhandling.annotation.EventHandler // if using axon
+ @com.google.common.eventbus.Subscribe // if using guava
public void on(ActionDomainEvent ev) {
...
}
@@ -81,17 +80,14 @@ or can be fine-grained (by subscribing to specific event subtypes):
----
@DomainService(nature=NatureOfService.DOMAIN)
public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
+ @org.axonframework.eventhandling.annotation.EventHandler // if using axon
+ @com.google.common.eventbus.Subscribe // if using guava
public void on(ToDoItem.CompletedEvent ev) {
...
}
}
----
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
The subscriber's method is called (up to) 5 times:
@@ -99,15 +95,16 @@ The subscriber's method is called (up to) 5 times:
* whether to veto visibility (hide)
* whether to veto usability (disable)
* whether to veto execution (validate)
-* steps to perform prior to the action being invoked.
-* steps to perform after the action has been invoked.
+* steps to perform prior to the action being invoked
+* steps to perform after the action has been invoked
-The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+The subscriber can distinguish these by calling `ev.getEventPhase()`.
+Thus the general form is:
[source,java]
----
-@Programmatic
-@com.google.common.eventbus.Subscribe
+@org.axonframework.eventhandling.annotation.EventHandler // if using axon
+@com.google.common.eventbus.Subscribe // if using guava
public void on(ActionDomainEvent ev) {
switch(ev.getEventPhase()) {
case HIDE:
@@ -135,28 +132,50 @@ It is also possible to abort the transaction during the executing or executed ph
== Default, Doop and Noop events
-If the `domainEvent` attribute is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`),
-then the framework will, by default, post an event.
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
+
+
+
+=== Class-level default
-And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
-then no event will be posted.
+Sometimes a subscriber is interested in all of the actions of a given class, though not any individual action.
+A common use case is to hide or disable all actions for some particular object for some particular user group.
+For this use, the default action domain event can be annotated using `@DomainObject`:
+[source,java]
+----
+@DomainObject(
+ actionDomainEvent=ToDoItem.ActionDomainEventDefault.class
+)
+public class ToDoItem {
+ public static class ActionDomainEventDefault
+ extends org.apache.isis.applib.services.eventbus.ActionDomainEvent<Object> { }
+ ...
+ public void updateDescription(final String description) {
+ this.description = description;
+ }
+}
+----
== Raising events programmatically
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] domain service.
+Normally events are only raised for interactions through the UI.
+However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] API directly, or by emulating the UI by wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
index 3ac38e7..043652c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Collection_domainEvent.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's collections, the events that are fired are:
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
+In the cases of the domain object's collections, the events that are fired are:
* hide phase: to check that the collection is visible (has not been hidden)
* disable phase: to check that the collection is usable (has not been disabled)
@@ -18,7 +19,8 @@ Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-ap
[WARNING]
====
-The xref:../ugvw/ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only. However, domain events are still relevant to determine if such collections should be hidden.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.
+However, domain events are still relevant to determine if such collections should be hidden.
The workaround is to create add/remove actions and use xref:../rgant/rgant.adoc#_rgant-MemberOrder[UI hints] to render them close to the collection.
====
@@ -34,8 +36,8 @@ public class ToDoItem {
}
----
-The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
-subclasses) to be defined instead. This attribute is also supported for
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
+This attribute is also supported for
xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions] and
xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
@@ -73,7 +75,8 @@ This substantially reduces the boilerplate in the subclasses because no explicit
== Subscribers
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.
+The examples below use the Guava API.
Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
@@ -94,17 +97,14 @@ or can be fine-grained (by subscribing to specific event subtypes):
----
@DomainService(nature=NatureOfService.DOMAIN)
public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
+ @org.axonframework.eventhandling.annotation.EventHandler // if using axon
+ @com.google.common.eventbus.Subscribe // if using guava
public void on(ToDoItem.DependenciesChangedEvent ev) {
...
}
}
----
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
The subscriber's method is called (up to) 5 times:
@@ -112,9 +112,10 @@ The subscriber's method is called (up to) 5 times:
* whether to veto usability (disable)
* whether to veto execution (validate) the element being added to/removed from the collection
* steps to perform prior to the collection being added to/removed from
-* steps to perform after the collection has been added to/removed from.
+* steps to perform after the collection has been added to/removed from
-The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+The subscriber can distinguish these by calling `ev.getEventPhase()`.
+Thus the general form is:
[source,java]
----
@@ -140,25 +141,22 @@ public void on(CollectionDomainEvent ev) {
}
----
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
+If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
== Default, Doop and Noop events
-If the `domainEvent` attribute is not explicitly specified (is left as its default value, `CollectionDomainEvent.Default`),
-then the framework will, by default, post an event.
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `CollectionDomainEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault`
-configuration collection can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault` configuration collection can be set to "false"; this will disable posting.
On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `CollectionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration collection setting.
+The framework provides `CollectionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration collection setting.
-And, conversely, the framework also provides `CollectionDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `CollectionDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
@@ -166,8 +164,8 @@ then no event will be posted.
== Raising events programmatically
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] domain service.
+Normally events are only raised for interactions through the UI.
+However, events can be raised programmatically either by calling the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] API directly, or by emulating the UI by wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] domain service.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
index 98cb467..281cbdc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_bookmarking.adoc
@@ -6,7 +6,8 @@
-The `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Action_bookmarking[domain objects].
+The `bookmarking()` attribute indicates that an entity is automatically bookmarked.
+This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Action_bookmarking[domain objects].
(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
@@ -30,7 +31,8 @@ public class ToDoItem ... {
indicates that the `ToDoItem` class is bookmarkable:
-It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
+It is also possible to nest bookmarkable entities.
+For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
index 4b25012..9045c53 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassFa.adoc
@@ -24,7 +24,9 @@ For example:
public class ToDoItem { ... }
----
-There can be multiple "fa-" classes, eg to mirror or rotate the icon. There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list. The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
+There can be multiple "fa-" classes, eg to mirror or rotate the icon.
+There is no need to include the mandatory `fa` "marker" CSS class; it will be automatically added to the list.
+The `fa-` prefix can also be omitted from the class names; it will be prepended to each if required.
The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
@@ -32,9 +34,7 @@ The related `cssClassFaPosition()` attribute is currently unused for domain obje
[TIP]
====
-The similar xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
-to apply CSS, but for wrapping the representation of an object or object
-member so that it can be styled in an application-specific way.
+The similar xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
index ac6b00a..25d7fbb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_describedAs.adoc
@@ -5,7 +5,9 @@
:_imagesdir: images/
-The `describedAs()` attribute is used to provide a short description of the domain object to the user. In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_descr [...]
+The `describedAs()` attribute is used to provide a short description of the domain object to the user.
+In the xref:../ugvw/ugvw.adoc#[Wicket viewer] it is displayed as a 'tool tip'.
+The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-CollectionLayout_describedAs[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_describedAs[properties], xref:../rgant/rgant.adoc#_rgant-ActionLayout_describedAs[actions], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_describedAs[parameters] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_describedAs[view models].
For example:
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 15a4eac..854d822 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -97,11 +97,9 @@ If the `iconUiEvent` attribute is not explicitly specified (is left as its defau
If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.iconUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `iconUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `iconUiEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `iconUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
index c5e702e..07524e6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_named.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-The `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-ViewMo [...]
+The `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code.
+The attribute can also be specified for xref:../rgant/rgant.adoc#_rgant-ActionLayout_named[actions], xref:../rgant/rgant.adoc#_rgant-CollectionLayout_named[collections], xref:../rgant/rgant.adoc#_rgant-PropertyLayout_named[properties], xref:../rgant/rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_named[view models] and xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_named[domain services].
[TIP]
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
index fb206ee..e9632ba 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_paged.adoc
@@ -6,12 +6,14 @@
-The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_paged[view models].
+The `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation.
+This attribute can also be applied to xref:../rgant/rgant.adoc#_rgant-CollectionLayout_paged[collections] and xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_paged[view models].
[WARNING]
====
-The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] currently does not support paging. The xref:../ugvw/ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+The xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] currently does not support paging.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
index 60c38fc..c1f979c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_plural.adoc
@@ -10,7 +10,8 @@ When Apache Isis displays a standalone collection of several objects, it will la
By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_plural[view models].
+The `plural()` attribute allows the plural form of the class name to be specified explicitly.
+This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-ViewModelLayout_plural[view models].
For example:
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
index bc405f4..123f72b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -6,22 +6,21 @@
Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
-This is as an alternative to implementing xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or
-using the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself. (If either
-`title()` or `@Title` are present, then they will take precedence).
+This is as an alternative to implementing xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method, or using the xref:../rgant/rgant.adoc#_rgant-Title[`@Title`] annotation, within the class itself.
+(If either `title()` or `@Title` are present, then they will take precedence).
Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can
-use obtain a reference to the domain object from the event. From this they can, if they wish, specify a title for
-the domain object using the event's API.
+use obtain a reference to the domain object from the event.
+From this they can, if they wish, specify a title for the domain object using the event's API.
[NOTE]
====
-The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view model]s could be kept as minimal as possible, just defining the data.
+The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view model]s could be kept as minimal as possible, just defining the data.
UI events allow subscribers to provide UI hints, while xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin]s can be used to provide the behaviour.
====
-By default the event raised is `TitleUiEvent.Default`. For example:
+By default the event raised is `TitleUiEvent.Default`.
+For example:
[source,java]
----
@@ -31,8 +30,8 @@ public class ToDoItemDto {
}
----
-The purpose of the `titleUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for icon names and CSS classes.
+The purpose of the `titleUiEvent()` attribute is to allows a custom subclass to be emitted instead.
+A similar attribute is available for icon names and CSS classes.
For example:
@@ -86,26 +85,21 @@ public class SomeSubscriber extends AbstractSubscriber {
}
----
-The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to
-actually specify the title to be used.
+The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to actually specify the title to be used.
== Default, Doop and Noop events
-If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`),
-then the framework will, by default, post an event.
+If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `titleUiEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `titleUiEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `titleUiEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class,
-thn no event will be posted.
+And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class, thn no event will be posted.
== Raising events programmatically
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_actionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_actionDomainEvent.adoc
new file mode 100644
index 0000000..68f16e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_actionDomainEvent.adoc
@@ -0,0 +1,45 @@
+[[_rgant-DomainObject_actionDomainEvent]]
+= `actionDomainEvent()`
+: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 [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever an action of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
+Using xref:rgant.adoc#_rgant_Action_domainEvent[`@Action#domainEvent()`], the actual domain event class fired can be customised.
+the `@DomainObject#actionDomainEvent()` attribute allows a common event domain class to be fired for all of the actions of the domain object.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ actionDomainEvent=ToDoItem.ActionDomainEventDefault.class
+)
+public class ToDoItem {
+ public static class ActionDomainEventDefault
+ extends org.apache.isis.applib.services.eventbus.ActionDomainEvent<Object> { }
+ ...
+
+ public void updateDescription(final String description) {
+ this.description = description;
+ }
+
+}
+----
+
+
+Interactions with the property contributed by this mixin will emit the domain event of the subject (`ToDoItem`).
+
+One small difference between the events emitted by a "regular" action and a contributed action is that the source of the event (as in `event#getSource()` will be different.
+In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.
+
+However, the domain object is available using `event#getMixedIn()`.
+Even easier, `event#getSubject()` will always return the domain object (it returns the `#getMixedIn()` if present, otherwise the `#getSource()`.
+
+[NOTE]
+====
+Action domain events have generic types, with the (first and only) generic type indicating the event's source's type.
+
+Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply `Object` as their generic type.
+====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_collectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_collectionDomainEvent.adoc
new file mode 100644
index 0000000..22b39bf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_collectionDomainEvent.adoc
@@ -0,0 +1,62 @@
+[[_rgant-DomainObject_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 [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a collection of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
+Using xref:rgant.adoc#_rgant_Collection_domainEvent[`@Collection#domainEvent()`], the actual domain event class fired can be customised.
+the `@DomainObject#collectionDomainEvent()` attribute allows a common event domain class to be fired for all of the collections of the domain object.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ collectionDomainEvent=ToDoItem.CollectionDomainEventDefault.class
+)
+public class ToDoItem {
+ public static class CollectionDomainEventDefault
+ extends org.apache.isis.applib.services.eventbus.CollectionDomainEvent<Object> { }
+ ...
+
+ @Getter @Setter
+ private Set<Category> categories = Sets.newTreeSet();
+}
+----
+
+If there is a mixin for the domain object, then this will also honour the domain event.
+For example:
+
+[source,java]
+----
+@Mixin(method="coll")
+public class ToDoItem_related {
+ private final ToDoItem todoItem;
+ // constructor omitted
+
+ @Action(semantics = SemanticsOf.SAFE)
+ @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
+ @Collection
+ @CollectionLayout(defaultView = "table")
+ public List<ToDoItem> coll() { ... }
+}
+----
+
+Interactions with the collection contributed by this mixin will emit the domain event of the subject (`ToDoItem`).
+
+One small difference between the events emitted by a "regular" collection and a contributed action is that the source of the event (as in `event#getSource()` will be different.
+In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.
+
+However, the domain object is available using `event#getMixedIn()`.
+Even easier, `event#getSubject()` will always return the domain object (it returns the `#getMixedIn()` if present, otherwise the `#getSource()`.
+
+[NOTE]
+====
+Collection domain events have generic types, with the first generic type indicating the event's source's type, and the second generic type indicating the element type.
+
+Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply `Object` as their first generic type.
+
+They should _also_ have `Object` for their second generic type, because the element type of the various collections of the domain object will or could be different.
+====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
index 5046ee8..ebe5afe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
@@ -5,8 +5,7 @@
:_imagesdir: images/
-Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle
-event is fired.
+Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle event is fired.
Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can use the event to obtain a reference to the domain object.
The subscriber could then, for example, maintain an external datastore.
@@ -16,7 +15,8 @@ The subscriber could then, for example, maintain an external datastore.
The object should _not_ be modified during the persisted callback.
====
-By default the event raised is `ObjectPersistedEvent.Default`. For example:
+By default the event raised is `ObjectPersistedEvent.Default`.
+For example:
[source,java]
----
@@ -89,18 +89,14 @@ public class SomeSubscriber extends AbstractSubscriber {
== Default, Doop and Noop events
-If the `persistedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistedEvent.Default`),
-then the framework will, by default, post an event.
+If the `persistedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistedEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistedLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistedLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `persistedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectPersistedEvent.Doop` as such a subclass, so setting the `persistedLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectPersistedEvent.Doop` as such a subclass, so setting the `persistedLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `ObjectPersistedEvent.Noop`; if `persistedLifecycleEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `ObjectPersistedEvent.Noop`; if `persistedLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
index 928d55b..708e0ce 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -17,7 +17,8 @@ Another use case is to maintain "last updated by"/"last updated at" properties.
While you can roll your own, note that the framework provides built-in support for this use case through the xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
====
-By default the event raised is `ObjectPersistingEvent.Default`. For example:
+By default the event raised is `ObjectPersistingEvent.Default`.
+For example:
[source,java]
----
@@ -88,18 +89,14 @@ public class SomeSubscriber extends AbstractSubscriber {
== Default, Doop and Noop events
-If the `persistingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistingEvent.Default`),
-then the framework will, by default, post an event.
+If the `persistingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistingEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistingLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `persistingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectPersistingEvent.Doop` as such a subclass, so setting the `persistingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectPersistingEvent.Doop` as such a subclass, so setting the `persistingLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `ObjectPersistingEvent.Noop`; if `persistingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `ObjectPersistingEvent.Noop`; if `persistingLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_propertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_propertyDomainEvent.adoc
new file mode 100644
index 0000000..4784dfb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_propertyDomainEvent.adoc
@@ -0,0 +1,62 @@
+[[_rgant-DomainObject_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 [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a property of a domain object is interacted with then a domain event will be fired, for each of the various phases (hidden, disabled, validated, executing, executed).
+Using xref:rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`], the actual domain event class fired can be customised.
+the `@DomainObject#propertyDomainEvent()` attribute allows a common event domain class to be fired for all of the properties of the domain object.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ propertyDomainEvent=ToDoItem.PropertyDomainEventDefault.class
+)
+public class ToDoItem {
+ public static class PropertyDomainEventDefault
+ extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<Object> { }
+ ...
+
+ @Getter @Setter
+ private String description;
+}
+----
+
+
+If there is a mixin for the domain object, then this will also honour the domain event.
+For example:
+
+[source,java]
+----
+@Mixin(method="act")
+public class ToDoItem_priority {
+ private final ToDoItem todoItem;
+ // constructor omitted
+
+ @Action(semantics = SemanticsOf.SAFE)
+ @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
+ @Property
+ public Integer act() { ... }
+}
+----
+
+Interactions with the property contributed by this mixin will emit the domain event of the subject (`ToDoItem`).
+
+One small difference between the events emitted by a "regular" property and a contributed property is that the source of the event (as in `event#getSource()` will be different.
+In the former case it will be the domain object instance, in the latter it will be the mixin object instantiated automatically by the framework.
+
+However, the domain object is available using `event#getMixedIn()`.
+Even easier, `event#getSubject()` will always return the domain object (it returns the `#getMixedIn()` if present, otherwise the `#getSource()`.
+
+[NOTE]
+====
+Property domain events have generic types, with the first generic type indicating the event's source's type, and the second generic type indicating the property return type.
+
+Because an event specified at the class level might have either the domain object or a mixin for the domain object as its source, they should therefore use simply `Object` as their first generic type.
+
+They should _also_ have `Object` for their second generic type, because the return type of the various properties of the domain object will or could be different.
+====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
index 7f6833f..80f1054 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
@@ -43,17 +43,14 @@ public class InterestRate {
== `publishingPayloadFactory()`
-The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to
-be published by the publishing factory.
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
-Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be
-instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers
-this should avoid the necessity to query back for additional information.
+Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers.
+For at least some subscribers this should avoid the necessity to query back for additional information.
[WARNING]
====
-Be aware that this attribute is only honoured by the (deprecated)
-xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`], so should itself be considered as deprecated. It
-is ignored by the replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`],
+Be aware that this attribute is only honoured by the (deprecated) xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.
+It is ignored by the replacement xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`],
====
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
index e39e162..9f0aa43 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -13,12 +13,12 @@ One possible application is to maintain a full-text search database using link:h
[NOTE]
====
-Another use case is to maintain "last updated by"/"last updated at" properties. While you can roll your own, note that
-the framework provides built-in support for this use case through the
-xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+Another use case is to maintain "last updated by"/"last updated at" properties.
+While you can roll your own, note that the framework provides built-in support for this use case through the xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
====
-By default the event raised is `ObjectRemovingEvent.Default`. For example:
+By default the event raised is `ObjectRemovingEvent.Default`.
+For example:
[source,java]
----
@@ -28,8 +28,8 @@ public class ToDoItemDto {
}
----
-The purpose of the `removingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
+The purpose of the `removingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.
+A similar attribute is available for other lifecycle events.
For example:
@@ -91,18 +91,14 @@ public class SomeSubscriber extends AbstractSubscriber {
== Default, Doop and Noop events
-If the `removingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectRemovingEvent.Default`),
-then the framework will, by default, post an event.
+If the `removingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectRemovingEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.removingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.removingLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `removingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectRemovingEvent.Doop` as such a subclass, so setting the `removingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectRemovingEvent.Doop` as such a subclass, so setting the `removingLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `ObjectRemovingEvent.Noop`; if `removingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `ObjectRemovingEvent.Noop`; if `removingLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
index 0271fe4..86b8c84 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
@@ -5,18 +5,17 @@
:_imagesdir: images/
-Whenever a (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle
-event is fired.
+Whenever a (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle event is fired.
-Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object.
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can use the event to obtain a reference to the domain object.
[WARNING]
====
The object should _not_ be modified during the updated callback.
====
-By default the event raised is `ObjectUpdatedEvent.Default`. For example:
+By default the event raised is `ObjectUpdatedEvent.Default`.
+For example:
[source,java]
----
@@ -26,8 +25,8 @@ public class ToDoItemDto {
}
----
-The purpose of the `updatedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
+The purpose of the `updatedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.
+A similar attribute is available for other lifecycle events.
For example:
@@ -90,18 +89,14 @@ public class SomeSubscriber extends AbstractSubscriber {
== Default, Doop and Noop events
-If the `updatedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatedEvent.Default`),
-then the framework will, by default, post an event.
+If the `updatedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatedEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatedLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatedLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `updatedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectUpdatedEvent.Doop` as such a subclass, so setting the `updatedLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectUpdatedEvent.Doop` as such a subclass, so setting the `updatedLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `ObjectUpdatedEvent.Noop`; if `updatedLifecycleEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `ObjectUpdatedEvent.Noop`; if `updatedLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
index d2b74dc..f4a46bd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -5,22 +5,21 @@
:_imagesdir: images/
-Whenever a (persistent) domain object has been modified and is about to be updated to the database, an "updating"
-lifecycle event is fired.
+Whenever a (persistent) domain object has been modified and is about to be updated to the database, an "updating" lifecycle event is fired.
-Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can
-use the event to obtain a reference to the domain object. The subscriber could then, for example, update the object,
-or it could use it maintain an external datastore. One possible application is to maintain a full-text search database
-using link:https://lucene.apache.org/[Apache Lucene] or similar.
+Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] and can use the event to obtain a reference to the domain object.
+The subscriber could then, for example, update the object, or it could use it maintain an external datastore.
+One possible application is to maintain a full-text search database using link:https://lucene.apache.org/[Apache Lucene] or similar.
[NOTE]
====
-Another use case is to maintain "last updated by"/"last updated at" properties. While you can roll your own, note that
-the framework provides built-in support for this use case through the
+Another use case is to maintain "last updated by"/"last updated at" properties.
+While you can roll your own, note that the framework provides built-in support for this use case through the
xref:../rgcms/rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
====
-By default the event raised is `ObjectUpdatingEvent.Default`. For example:
+By default the event raised is `ObjectUpdatingEvent.Default`.
+For example:
[source,java]
----
@@ -30,8 +29,8 @@ public class ToDoItemDto {
}
----
-The purpose of the `updatingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
-attribute is available for other lifecycle events.
+The purpose of the `updatingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.
+A similar attribute is available for other lifecycle events.
For example:
@@ -94,15 +93,12 @@ public class SomeSubscriber extends AbstractSubscriber {
If the `updatingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatingEvent.Default`),
then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatingLifecycleEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatingLifecycleEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `updatingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ObjectUpdatingEvent.Doop` as such a subclass, so setting the `updatingLifecycleEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `ObjectUpdatingEvent.Doop` as such a subclass, so setting the `updatingLifecycleEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `ObjectUpdatingEvent.Noop`; if `updatingLifecycleEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `ObjectUpdatingEvent.Noop`; if `updatingLifecycleEvent` attribute is set to this class, then no event will be posted.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
index ac53113..85e528c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's properties, the events that are fired are:
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
+In the cases of the domain object's properties, the events that are fired are:
* hide phase: to check that the property is visible (has not been hidden)
* disable phase: to check that the property is usable (has not been disabled)
@@ -15,7 +16,8 @@ Whenever a domain object (or list of domain objects) is to be rendered, the fram
Subscribers subscribe through the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
-By default the event raised is `PropertyDomainEvent.Default`. For example:
+By default the event raised is `PropertyDomainEvent.Default`.
+For example:
[source,java]
----
@@ -26,10 +28,8 @@ public class ToDoItem {
}
----
-The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
-subclasses) to be defined instead. This attribute is also supported for
- xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions] and
- xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
+This attribute is also supported for xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[actions] and xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[properties].
For example:
@@ -56,7 +56,8 @@ This substantially reduces the boilerplate in the subclasses because no explicit
== Subscribers
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:../rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API.
+The examples below use the Guava API.
Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
@@ -77,17 +78,13 @@ or can be fine-grained (by subscribing to specific event subtypes):
----
@DomainService(nature=NatureOfService.DOMAIN)
public class SomeSubscriber extends AbstractSubscriber {
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.DueByChangedEvent ev) {
+ @org.axonframework.eventhandling.annotation.EventHandler // if using axon
+ @com.google.common.eventbus.Subscribe public void on(ToDoItem.DueByChangedEvent ev) {
...
}
}
----
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
The subscriber's method is called (up to) 5 times:
@@ -97,7 +94,8 @@ The subscriber's method is called (up to) 5 times:
* steps to perform prior to the property being modified
* steps to perform after the property has been modified.
-The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+The subscriber can distinguish these by calling `ev.getEventPhase()`.
+Thus the general form is:
[source,java]
----
@@ -123,25 +121,22 @@ public void on(PropertyDomainEvent ev) {
}
----
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
+If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
== Default, Doop and Noop events
-If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`),
-then the framework will, by default, post an event.
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`), then the framework will, by default, post an event.
-If this is not required, then the `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault`
-configuration property can be set to "false"; this will disable posting.
+If this is not required, then the `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
-will ensure that the event to be posted, irrespective of the configuration property setting.
+The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
-then no event will be posted.
+And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
@@ -149,6 +144,6 @@ then no event will be posted.
== Raising events programmatically
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
-wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] service.
+Normally events are only raised for interactions through the UI.
+However, events can be raised programmatically by wrapping the target object using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] service.
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_highlight-current-row.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_highlight-current-row.adoc
index 2853ad5..467ad24 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_highlight-current-row.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_hints-and-tips_highlight-current-row.adoc
@@ -36,8 +36,8 @@ Next, we define the domain service to act as the subscriber:
public class HomePageViewModel ... {
@DomainService(nature = NatureOfService.DOMAIN)
public static class CssHighlighter extends AbstractSubscriber {
- @EventHandler
- @Subscribe
+ @org.axonframework.eventhandling.annotation.EventHandler // if using axon
+ @com.google.common.eventbus.Subscribe // if using guava
public void on(DemoObject.CssClassUiEvent ev) {
if(getContext() == null) { return; }
if(ev.getSource() == getContext().getSelected()) { // <1>