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
The following commit(s) were added to refs/heads/master by this push:
new 3eb22e8 ISIS-2222: docs completed for @Property#publishing,
@Action#publishing
3eb22e8 is described below
commit 3eb22e86857bceb3ad619a9edb809503ddf8098a
Author: danhaywood <[email protected]>
AuthorDate: Tue Aug 18 13:48:03 2020 +0100
ISIS-2222: docs completed for @Property#publishing, @Action#publishing
still wip for @DomainObject#publishing
---
.../ActionPublishingJdo-description.adoc | 191 +++++++++++++--------
.../Action/publishing/ActionPublishingJdo.java | 50 +++++-
.../ActionPublishingJdo_mixinUpdateProperty.java | 7 +-
...hingJdo_mixinUpdatePropertyMetaAnnotation.java} | 22 ++-
...ixinUpdatePropertyMetaAnnotationOverridden.java | 11 +-
...onPublishingJdo_clearInteractionExecutions.java | 14 +-
.../ActionPublishingJdo_interactionExecutions.java | 15 +-
.../spiimpl/PublisherServiceSpiForActions.java | 23 ++-
...nObjectPublishingJdo_clearPublishedObjects.java | 8 +-
...DomainObjectPublishingJdo_publishedObjects.java | 17 +-
.../PublisherServiceSpiForDomainObject.java | 23 ++-
.../editing/PropertyEditingVm-description.adoc | 2 +-
.../PropertyPublishingJdo-description.adoc | 166 ++++++++++--------
.../Property/publishing/PropertyPublishingJdo.java | 10 +-
...tyPublishingJdo_clearInteractionExecutions.java | 16 +-
...ropertyPublishingJdo_interactionExecutions.java | 16 +-
.../spiimpl/PublisherServiceSpiForProperties.java | 24 ++-
17 files changed, 383 insertions(+), 232 deletions(-)
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo-description.adoc
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo-description.adoc
index c62d177..dfe075d 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo-description.adoc
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo-description.adoc
@@ -1,74 +1,117 @@
-CAUTION: todo - to update.
-
-//The `editing` semantic specifies that a property's value can be changed
through the UI:
-//
-//* for properties, the semantic can be specified using either the `@Property`
annotation, or a meta-annotation
-//
-//There is no corresponding semantic for parameters, parameters are implicitly
editable.
-//
-//== Class Level
-//
-//Usually editing of properties is discouraged; it is usually better to modify
state through an explicit action instead.
-//For that reason, editing of properties is disabled by default (though that
can be changed globally if necessary using the
`isis.applib.annotation.domain-object.editing` configuration property).
-//
-//Editing can also be specified at the class level.
-//This will override any configured defaults, but just for the properties of
that class:
-//
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=class]
-//----
-//
-//The property-level semantic can, in turn, overrides the configured or
class-level default.
-//
-//
-//== Annotated
-//
-//The `editing` semantic can be specified explicitly using an annotation:
-//
-//* for properties, using `@Property#editing()`:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=annotation]
-//----
-//<.> explicitly specifies the maximum length that can be entered for the
property
-//
-//The annotation could also be applied to a mixin, but would have little
effect because mixin properties are always read-only.
-//
-//== Meta-annotated
-//
-//The `editing` semantic can also be specified using a custom meta-annotation:
-//
-//* the meta-annotation is defined as:
-//+
-//[source,java]
-//----
-//include::EditingEnabledMetaAnnotation.java[tags=class]
-//----
-//<.> annotated for a property
-//<.> annotation can be applied to a property (either its getter or the field
directly)
-//
-//* and can be applied to a property:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=meta-annotated]
-//----
-//<.> semantic is inherited from the meta-annotation
-//
-//
-//
-//=== Meta-annotated Overridden
-//
-//The meta-annotation can itself be overridden:
-//
-//* in a property:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=meta-annotated-overridden]
-//----
-//<.> semantic from meta-annotation ...
-//<.> \... is overridden by the `@Property` annotation
-//
+The `publishing` semantic specifies that the invocation of an object action
should be published to registered implementation(s) of
link:https://isis.apache.org/refguide/2.0.0-M3/applib-svc/PublisherService.html#spi[`PublisherService`
SPI].
+This is performed _after_ the action has been invoked.
+
+The publishing from the framework to the SPI is in-memory.
+A typical SPI implementation would then publish over the network, or perhaps
store in a database as per the
link:https://microservices.io/patterns/data/transactional-outbox.html[outbox
pattern].
+
+TIP: The framework provides an
link:https://isis.apache.org/mappings/2.0.0-M3/outbox-publisher/about.html[out-of-the-box
implementation] of the outbox pattern.
+
+The semantic can be specified using either the `@Action` annotation, or
through a meta-annotation.
+
+== Annotated
+
+The `publisher` semantic can be specified explicitly using an annotation
through `@Action#publishing()`:
+
+* it can be applied to an action:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo.java[tags=annotation]
+----
+<.> explicitly specifies that invoking the action should be published.
+
+* or to a mixin:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo_mixinUpdateProperty.java[tags=class]
+----
+<.> explicitly specifies that invoking the mixin action should be published.
+
+
+== Meta-annotated
+
+The `publishing` semantic can also be specified using a custom meta-annotation:
+
+* the meta-annotation is defined as:
++
+[source,java,indent=0]
+----
+include::ActionPublishingEnabledMetaAnnotation.java[tags=class]
+----
+<.> annotated for an action
+<.> annotation can be applied to an action method or to a mixin
+
+* and can be applied to an action:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo.java[tags=meta-annotation]
+----
+<.> semantic is inherited from the meta-annotation
+
+* or to a mixin:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation.java[tags=class]
+----
+<.> semantic is inherited from the meta-annotation
+
+
+=== Meta-annotated Overridden
+
+The meta-annotation can itself be overridden:
+
+* for an action:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo.java[tags=meta-annotation-overridden]
+----
+<.> semantic from meta-annotation ...
+<.> \... is overridden by the `@Action` annotation
+
+* or on a mixin:
++
+[source,java,indent=0]
+----
+include::ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java[tags=class]
+----
+<.> semantic from meta-annotation ...
+<.> \... is overridden by the `@Action` annotation
+
+
+== PublisherService
+
+The demo provides a simple implementation of `PublisherService` that just
stores the DTOs in memory:
+
+[source,java]
+----
+include::spiimpl/PublisherServiceSpiForActions.java[tags=class]
+----
+<.> serializes to `InteractionDto`, as defined by the
link:https://isis.apache.org/refguide/2.0.0-M3/schema/ixn.html[Apache Isis
schema].
+
+The demo implementation also provides a way to query these executions:
+
+[source,java,indent=0]
+----
+include::spiimpl/PublisherServiceSpiForActions.java[tags=demo]
+----
+
+Supporting mixins surface this list as contributions on the object:
+
+* `interactionExecutions` collection:
++
+[source,java,indent=0]
+----
+include::spiimpl/ActionPublishingJdo_interactionExecutions.java[tags=class]
+----
+
+* `clearInteractionExecutions` action:
++
+[source,java,indent=0]
+----
+include::spiimpl/ActionPublishingJdo_clearInteractionExecutions.java[tags=class]
+----
+
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo.java
index bdba6ae..1556229 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo.java
@@ -52,6 +52,8 @@ public class ActionPublishingJdo implements
HasAsciiDocDescription {
public ActionPublishingJdo(String initialValue) {
this.property = initialValue;
+ this.propertyMetaAnnotated = initialValue;
+ this.propertyMetaAnnotatedOverridden = initialValue;
}
public String title() {
@@ -63,6 +65,16 @@ public class ActionPublishingJdo implements
HasAsciiDocDescription {
@MemberOrder(name = "annotation", sequence = "1")
@Getter @Setter
private String property;
+
+ @Property()
+ @MemberOrder(name = "meta-annotated", sequence = "1")
+ @Getter @Setter
+ private String propertyMetaAnnotated;
+
+ @Property()
+ @MemberOrder(name = "meta-annotated-overridden", sequence = "1")
+ @Getter @Setter
+ private String propertyMetaAnnotatedOverridden;
//end::property[]
//tag::annotation[]
@@ -73,7 +85,8 @@ public class ActionPublishingJdo implements
HasAsciiDocDescription {
, associateWithSequence = "1"
)
@ActionLayout(
- describedAs = "@Action(publishing = ENABLED)"
+ named = "Update Property"
+ , describedAs = "@Action(publishing = ENABLED)"
)
public ActionPublishingJdo updatePropertyUsingAnnotation(final String
value) {
setProperty(value);
@@ -86,24 +99,47 @@ public class ActionPublishingJdo implements
HasAsciiDocDescription {
//end::annotation[]
//tag::meta-annotation[]
- @ActionPublishingEnabledMetaAnnotation
+ @ActionPublishingEnabledMetaAnnotation // <.>
@Action(
semantics = SemanticsOf.IDEMPOTENT
- , associateWith = "property"
- , associateWithSequence = "2"
+ , associateWith = "propertyMetaAnnotated"
+ , associateWithSequence = "1"
)
@ActionLayout(
- describedAs = "@PublishingEnabledMetaAnnotation"
+ named = "Update Property"
+ , describedAs = "@PublishingEnabledMetaAnnotation"
)
public ActionPublishingJdo updatePropertyUsingMetaAnnotation(final String
value) {
- setProperty(value);
+ setPropertyMetaAnnotated(value);
return this;
}
public String default0UpdatePropertyUsingMetaAnnotation() {
- return getProperty();
+ return getPropertyMetaAnnotated();
}
//end::meta-annotation[]
+//tag::meta-annotation-overridden[]
+ @ActionPublishingDisabledMetaAnnotation // <.>
+ @Action(
+ publishing = Publishing.ENABLED // <.>
+ , semantics = SemanticsOf.IDEMPOTENT
+ , associateWith = "propertyMetaAnnotatedOverridden"
+ , associateWithSequence = "1"
+ )
+ @ActionLayout(
+ named = "Update Property"
+ , describedAs =
+ "@PublishingEnabledMetaAnnotation @Action(publishing = ENABLED)"
+ )
+ public ActionPublishingJdo
updatePropertyUsingMetaAnnotationButOverridden(final String value) {
+ setPropertyMetaAnnotatedOverridden(value);
+ return this;
+ }
+ public String default0UpdatePropertyUsingMetaAnnotationButOverridden() {
+ return getPropertyMetaAnnotatedOverridden();
+ }
+//end::meta-annotation-overridden[]
+
//tag::class[]
}
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdateProperty.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdateProperty.java
index 055771f..e0b28c4 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdateProperty.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdateProperty.java
@@ -7,13 +7,14 @@ import org.apache.isis.applib.annotation.SemanticsOf;
//tag::class[]
@Action(
- publishing = Publishing.ENABLED
+ publishing = Publishing.ENABLED // <.>
, semantics = SemanticsOf.IDEMPOTENT
, associateWith = "property"
- , associateWithSequence = "3"
+ , associateWithSequence = "2"
)
@ActionLayout(
- describedAs = "@Action(publishing = ENABLED)"
+ named = "Mixin Update Property"
+ , describedAs = "@Action(publishing = ENABLED)"
)
public class ActionPublishingJdo_mixinUpdateProperty {
// ...
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation.java
similarity index 60%
copy from
examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
copy to
examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation.java
index dd0416d..575e2a1 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation.java
@@ -6,35 +6,33 @@ import org.apache.isis.applib.annotation.Publishing;
import org.apache.isis.applib.annotation.SemanticsOf;
//tag::class[]
-@ActionPublishingDisabledMetaAnnotation // <.>
+@ActionPublishingEnabledMetaAnnotation // <.>
@Action(
- publishing = Publishing.ENABLED // <.>
- , semantics = SemanticsOf.IDEMPOTENT
- , associateWith = "property"
- , associateWithSequence = "4"
+ semantics = SemanticsOf.IDEMPOTENT
+ , associateWith = "propertyMetaAnnotated"
+ , associateWithSequence = "2"
)
@ActionLayout(
- describedAs =
- "@ActionPublishingDisabledMetaAnnotation " +
- "@Action(publishing = ENABLED)"
+ named = "Mixin Update Property"
+ , describedAs = "@ActionPublishingEnabledMetaAnnotation"
)
-public class ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden {
+public class ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation {
// ...
//end::class[]
private final ActionPublishingJdo actionPublishingJdo;
- public
ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden(ActionPublishingJdo
actionPublishingJdo) {
+ public
ActionPublishingJdo_mixinUpdatePropertyMetaAnnotation(ActionPublishingJdo
actionPublishingJdo) {
this.actionPublishingJdo = actionPublishingJdo;
}
//tag::class[]
public ActionPublishingJdo act(final String value) {
- actionPublishingJdo.setProperty(value);
+ actionPublishingJdo.setPropertyMetaAnnotated(value);
return actionPublishingJdo;
}
public String default0Act() {
- return actionPublishingJdo.getProperty();
+ return actionPublishingJdo.getPropertyMetaAnnotated();
}
}
//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
index dd0416d..d3e4ef1 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden.java
@@ -10,11 +10,12 @@ import org.apache.isis.applib.annotation.SemanticsOf;
@Action(
publishing = Publishing.ENABLED // <.>
, semantics = SemanticsOf.IDEMPOTENT
- , associateWith = "property"
- , associateWithSequence = "4"
+ , associateWith = "propertyMetaAnnotatedOverridden"
+ , associateWithSequence = "2"
)
@ActionLayout(
- describedAs =
+ named = "Mixin Update Property"
+ , describedAs =
"@ActionPublishingDisabledMetaAnnotation " +
"@Action(publishing = ENABLED)"
)
@@ -30,11 +31,11 @@ public class
ActionPublishingJdo_mixinUpdatePropertyMetaAnnotationOverridden {
//tag::class[]
public ActionPublishingJdo act(final String value) {
- actionPublishingJdo.setProperty(value);
+ actionPublishingJdo.setPropertyMetaAnnotatedOverridden(value);
return actionPublishingJdo;
}
public String default0Act() {
- return actionPublishingJdo.getProperty();
+ return actionPublishingJdo.getPropertyMetaAnnotatedOverridden();
}
}
//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_clearInteractionExecutions.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_clearInteractionExecutions.java
index 071785b..cde9d30 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_clearInteractionExecutions.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_clearInteractionExecutions.java
@@ -1,20 +1,20 @@
package demoapp.dom.annotDomain.Action.publishing.spiimpl;
-import java.util.List;
-
import javax.inject.Inject;
import org.apache.isis.applib.annotation.Action;
import org.apache.isis.applib.annotation.SemanticsOf;
-import org.apache.isis.schema.ixn.v2.InteractionDto;
import demoapp.dom.annotDomain.Action.publishing.ActionPublishingJdo;
+//tag::class[]
@Action(
semantics = SemanticsOf.IDEMPOTENT
, associateWith = "interactionExecutions"
)
public class ActionPublishingJdo_clearInteractionExecutions {
+ // ...
+//end::class[]
private final ActionPublishingJdo actionPublishingJdo;
@@ -22,11 +22,13 @@ public class ActionPublishingJdo_clearInteractionExecutions
{
this.actionPublishingJdo = actionPublishingJdo;
}
- public List<InteractionDto> act() {
+//tag::class[]
+ public ActionPublishingJdo act() {
publisherServiceSpiForActions.clear();
- return (List<InteractionDto>) actionPublishingJdo;
+ return actionPublishingJdo;
}
@Inject
- private PublisherServiceSpiForActions publisherServiceSpiForActions;
+ PublisherServiceSpiForActions publisherServiceSpiForActions;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_interactionExecutions.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_interactionExecutions.java
index b39ccba..e068dd9 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_interactionExecutions.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/ActionPublishingJdo_interactionExecutions.java
@@ -1,17 +1,22 @@
package demoapp.dom.annotDomain.Action.publishing.spiimpl;
+import java.util.LinkedList;
import java.util.List;
-import java.util.stream.Collectors;
import javax.inject.Inject;
import org.apache.isis.applib.annotation.Collection;
import org.apache.isis.schema.ixn.v2.InteractionDto;
+import lombok.val;
+
import demoapp.dom.annotDomain.Action.publishing.ActionPublishingJdo;
+//tag::class[]
@Collection
public class ActionPublishingJdo_interactionExecutions {
+ // ...
+//end::class[]
private final ActionPublishingJdo actionPublishingJdo;
@@ -19,12 +24,16 @@ public class ActionPublishingJdo_interactionExecutions {
this.actionPublishingJdo = actionPublishingJdo;
}
+//tag::class[]
public List<InteractionDto> coll() {
- return publisherServiceSpiForActions
+ val list = new LinkedList<InteractionDto>();
+ publisherServiceSpiForActions
.streamInteractionDtos()
- .collect(Collectors.toList());
+ .forEach(list::push); // reverse order
+ return list;
}
@Inject
private PublisherServiceSpiForActions publisherServiceSpiForActions;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/PublisherServiceSpiForActions.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/PublisherServiceSpiForActions.java
index 5b08b64..79500ad 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/PublisherServiceSpiForActions.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/publishing/spiimpl/PublisherServiceSpiForActions.java
@@ -12,6 +12,9 @@ import
org.apache.isis.applib.services.publish.PublisherService;
import org.apache.isis.applib.util.schema.InteractionDtoUtils;
import org.apache.isis.schema.ixn.v2.InteractionDto;
+import lombok.val;
+
+//tag::class[]
@Service
public class PublisherServiceSpiForActions implements PublisherService {
@@ -19,17 +22,14 @@ public class PublisherServiceSpiForActions implements
PublisherService {
@Override
public void publish(Interaction.Execution<?, ?> execution) {
-
- final InteractionDto dto =
- InteractionDtoUtils.newInteractionDto(execution,
InteractionDtoUtils.Strategy.DEEP);
-
+ val dto = InteractionDtoUtils.newInteractionDto( // <.>
+ execution, InteractionDtoUtils.Strategy.DEEP);
executions.add(dto);
}
+ // ...
+//end::class[]
- @Override
- public void publish(PublishedObjects publishedObjects) {
- }
-
+//tag::demo[]
public Stream<InteractionDto> streamInteractionDtos() {
return executions.stream();
}
@@ -37,5 +37,12 @@ public class PublisherServiceSpiForActions implements
PublisherService {
public void clear() {
executions.clear();
}
+//end::demo[]
+
+ @Override
+ public void publish(PublishedObjects publishedObjects) {
+ }
+//tag::class[]
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_clearPublishedObjects.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_clearPublishedObjects.java
index 6e8f888..05be0a8 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_clearPublishedObjects.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_clearPublishedObjects.java
@@ -6,13 +6,15 @@ import org.apache.isis.applib.annotation.Action;
import org.apache.isis.applib.annotation.SemanticsOf;
import
demoapp.dom.annotDomain.DomainObject.publishing.DomainObjectPublishingJdo;
-import
demoapp.dom.annotDomain.Property.publishing.spiimpl.PublisherServiceSpiForProperties;
+//tag::class[]
@Action(
semantics = SemanticsOf.IDEMPOTENT
, associateWith = "publishedObjects"
)
public class DomainObjectPublishingJdo_clearPublishedObjects {
+ // ...
+//end::class[]
private final DomainObjectPublishingJdo domainObjectPublishingJdo;
@@ -20,11 +22,13 @@ public class
DomainObjectPublishingJdo_clearPublishedObjects {
this.domainObjectPublishingJdo = domainObjectPublishingJdo;
}
+ //tag::class[]
public DomainObjectPublishingJdo act() {
publisherServiceSpiForDomainObject.clear();
return domainObjectPublishingJdo;
}
@Inject
- private PublisherServiceSpiForDomainObject
publisherServiceSpiForDomainObject;
+ PublisherServiceSpiForDomainObject publisherServiceSpiForDomainObject;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_publishedObjects.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_publishedObjects.java
index 1c2500e..5dbe083 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_publishedObjects.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/DomainObjectPublishingJdo_publishedObjects.java
@@ -1,29 +1,38 @@
package demoapp.dom.annotDomain.DomainObject.publishing.spiimpl;
+import java.util.LinkedList;
import java.util.List;
-import java.util.stream.Collectors;
import javax.inject.Inject;
import org.apache.isis.applib.annotation.Collection;
import org.apache.isis.schema.chg.v2.ChangesDto;
+import lombok.val;
+
import
demoapp.dom.annotDomain.DomainObject.publishing.DomainObjectPublishingJdo;
+//tag::class[]
@Collection
public class DomainObjectPublishingJdo_publishedObjects {
+ // ...
+//end::class[]
private final DomainObjectPublishingJdo domainObjectPublishingJdo;
public
DomainObjectPublishingJdo_publishedObjects(DomainObjectPublishingJdo
domainObjectPublishingJdo) {
this.domainObjectPublishingJdo = domainObjectPublishingJdo;
}
+//tag::class[]
public List<ChangesDto> coll() {
- return publisherServiceSpiForDomainObject
+ val list = new LinkedList<ChangesDto>();
+ publisherServiceSpiForDomainObject
.streamPublishedObjects()
- .collect(Collectors.toList());
+ .forEach(list::push); // reverse order
+ return list;
}
@Inject
- private PublisherServiceSpiForDomainObject
publisherServiceSpiForDomainObject;
+ PublisherServiceSpiForDomainObject publisherServiceSpiForDomainObject;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/PublisherServiceSpiForDomainObject.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/PublisherServiceSpiForDomainObject.java
index 9873f45..ccb27bf 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/PublisherServiceSpiForDomainObject.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/DomainObject/publishing/spiimpl/PublisherServiceSpiForDomainObject.java
@@ -9,25 +9,25 @@ import org.springframework.stereotype.Service;
import org.apache.isis.applib.services.iactn.Interaction;
import org.apache.isis.applib.services.publish.PublishedObjects;
import org.apache.isis.applib.services.publish.PublisherService;
-import org.apache.isis.applib.util.schema.InteractionDtoUtils;
import org.apache.isis.schema.chg.v2.ChangesDto;
-import org.apache.isis.schema.ixn.v2.InteractionDto;
+import lombok.val;
+
+//tag::class[]
@Service
public class PublisherServiceSpiForDomainObject implements PublisherService {
- private final List<ChangesDto> publishedObjects = new
ArrayList<ChangesDto>();
-
- @Override
- public void publish(Interaction.Execution<?, ?> execution) {
- }
+ private final List<ChangesDto> publishedObjects = new ArrayList<>();
@Override
public void publish(PublishedObjects publishedObjects) {
- final ChangesDto dto = publishedObjects.getDto();
+ val dto = publishedObjects.getDto();
this.publishedObjects.add(dto);
}
+ // ...
+//end::class[]
+//tag::demo[]
public Stream<ChangesDto> streamPublishedObjects() {
return publishedObjects.stream();
}
@@ -35,5 +35,12 @@ public class PublisherServiceSpiForDomainObject implements
PublisherService {
public void clear() {
publishedObjects.clear();
}
+//end::demo[]
+
+ @Override
+ public void publish(Interaction.Execution<?, ?> execution) {
+ }
+//tag::class[]
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/editing/PropertyEditingVm-description.adoc
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/editing/PropertyEditingVm-description.adoc
index 8e2bf73..e395122 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/editing/PropertyEditingVm-description.adoc
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/editing/PropertyEditingVm-description.adoc
@@ -30,7 +30,7 @@ The `editing` semantic can be specified explicitly using an
annotation:
----
include::PropertyEditingVm.java[tags=annotation]
----
-<.> explicitly specifies the maximum length that can be entered for the
property
+<.> explicitly specifies that the property is editable
The annotation could also be applied to a mixin, but would have little effect
because mixin properties are always read-only.
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo-description.adoc
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo-description.adoc
index c62d177..f12e92f 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo-description.adoc
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo-description.adoc
@@ -1,74 +1,92 @@
-CAUTION: todo - to update.
-
-//The `editing` semantic specifies that a property's value can be changed
through the UI:
-//
-//* for properties, the semantic can be specified using either the `@Property`
annotation, or a meta-annotation
-//
-//There is no corresponding semantic for parameters, parameters are implicitly
editable.
-//
-//== Class Level
-//
-//Usually editing of properties is discouraged; it is usually better to modify
state through an explicit action instead.
-//For that reason, editing of properties is disabled by default (though that
can be changed globally if necessary using the
`isis.applib.annotation.domain-object.editing` configuration property).
-//
-//Editing can also be specified at the class level.
-//This will override any configured defaults, but just for the properties of
that class:
-//
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=class]
-//----
-//
-//The property-level semantic can, in turn, overrides the configured or
class-level default.
-//
-//
-//== Annotated
-//
-//The `editing` semantic can be specified explicitly using an annotation:
-//
-//* for properties, using `@Property#editing()`:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=annotation]
-//----
-//<.> explicitly specifies the maximum length that can be entered for the
property
-//
-//The annotation could also be applied to a mixin, but would have little
effect because mixin properties are always read-only.
-//
-//== Meta-annotated
-//
-//The `editing` semantic can also be specified using a custom meta-annotation:
-//
-//* the meta-annotation is defined as:
-//+
-//[source,java]
-//----
-//include::EditingEnabledMetaAnnotation.java[tags=class]
-//----
-//<.> annotated for a property
-//<.> annotation can be applied to a property (either its getter or the field
directly)
-//
-//* and can be applied to a property:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=meta-annotated]
-//----
-//<.> semantic is inherited from the meta-annotation
-//
-//
-//
-//=== Meta-annotated Overridden
-//
-//The meta-annotation can itself be overridden:
-//
-//* in a property:
-//+
-//[source,java,indent=0]
-//----
-//include::PropertyEditingVm.java[tags=meta-annotated-overridden]
-//----
-//<.> semantic from meta-annotation ...
-//<.> \... is overridden by the `@Property` annotation
-//
+The `publishing` semantic specifies that the editing of an object property
should be published to registered implementation(s) of
link:https://isis.apache.org/refguide/2.0.0-M3/applib-svc/PublisherService.html#spi[`PublisherService`
SPI].
+This is performed _after_ the property has been changed.
+
+The publishing from the framework to the SPI is in-memory.
+A typical SPI implementation would then publish over the network, or perhaps
store in a database as per the
link:https://microservices.io/patterns/data/transactional-outbox.html[outbox
pattern].
+
+TIP: The framework provides an
link:https://isis.apache.org/mappings/2.0.0-M3/outbox-publisher/about.html[out-of-the-box
implementation] of the outbox pattern.
+
+The semantic can be specified using either the `@Property` annotation, or
through a meta-annotation.
+
+== Annotated
+
+The `publisher` semantic can be specified explicitly using an annotation
through `@Property#publishing()`:
+
+[source,java,indent=0]
+----
+include::PropertyPublishingJdo.java[tags=annotation]
+----
+<.> explicitly specifies that modifying the property should be published.
+
+The annotation could also be applied to a mixin, but would have little effect
because mixin properties are always read-only.
+
+== Meta-annotated
+
+The `publishing` semantic can also be specified using a custom meta-annotation:
+
+* the meta-annotation is defined as:
++
+[source,java]
+----
+include::PropertyPublishingEnabledMetaAnnotation.java[tags=class]
+----
+<.> annotated for a property
+<.> annotation can be applied to a property (either its getter or the field
directly)
+
+* and can be applied to a property:
++
+[source,java,indent=0]
+----
+include::PropertyPublishingJdo.java[tags=meta-annotated]
+----
+<.> semantic is inherited from the meta-annotation
+
+
+
+=== Meta-annotated Overridden
+
+The meta-annotation can itself be overridden:
+
+* in a property:
++
+[source,java,indent=0]
+----
+include::PropertyPublishingJdo.java[tags=meta-annotated-overridden]
+----
+<.> semantic from meta-annotation ...
+<.> \... is overridden by the `@Property` annotation
+
+
+== PublisherService
+
+The demo provides a simple implementation of `PublisherService` that just
stores the DTOs in memory:
+
+[source,java]
+----
+include::spiimpl/PublisherServiceSpiForProperties.java[tags=class]
+----
+<.> serializes to `InteractionDto`, as defined by the
link:https://isis.apache.org/refguide/2.0.0-M3/schema/ixn.html[Apache Isis
schema].
+
+The demo implementation also provides a way to query these executions:
+
+[source,java,indent=0]
+----
+include::spiimpl/PublisherServiceSpiForProperties.java[tags=demo]
+----
+
+Supporting mixins surface this list as contributions on the object:
+
+* `interactionExecutions` collection:
++
+[source,java,indent=0]
+----
+include::spiimpl/PropertyPublishingJdo_interactionExecutions.java[tags=class]
+----
+
+* `clearInteractionExecutions` action:
++
+[source,java,indent=0]
+----
+include::spiimpl/PropertyPublishingJdo_clearInteractionExecutions.java[tags=class]
+----
+
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo.java
index 7a6a0ef..56b6481 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/PropertyPublishingJdo.java
@@ -73,8 +73,8 @@ public class PropertyPublishingJdo implements
HasAsciiDocDescription {
//end::annotation[]
//tag::meta-annotated[]
- @Property()
@PropertyPublishingEnabledMetaAnnotation // <.>
+ @Property()
@PropertyLayout(
describedAs = "@PublishingEnabledMetaAnnotation"
)
@@ -85,14 +85,14 @@ public class PropertyPublishingJdo implements
HasAsciiDocDescription {
//end::meta-annotated[]
//tag::meta-annotated-overridden[]
- @PropertyPublishingEnabledMetaAnnotation // <.>
+ @PropertyPublishingDisabledMetaAnnotation // <.>
@Property(
- publishing = Publishing.DISABLED // <.>
+ publishing = Publishing.ENABLED // <.>
)
@PropertyLayout(
describedAs =
- "@PublishingEnabledMetaAnnotation " +
- "@Property(publishing = DISABLED)"
+ "@PublishingDisabledMetaAnnotation " +
+ "@Property(publishing = ENABLED)"
)
@MemberOrder(name = "meta-annotated-overridden", sequence = "1")
@XmlElement(required = false)
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_clearInteractionExecutions.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_clearInteractionExecutions.java
index 0762216..3454bbf 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_clearInteractionExecutions.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_clearInteractionExecutions.java
@@ -1,22 +1,20 @@
package demoapp.dom.annotDomain.Property.publishing.spiimpl;
-import java.util.List;
-import java.util.stream.Collectors;
-
import javax.inject.Inject;
import org.apache.isis.applib.annotation.Action;
-import org.apache.isis.applib.annotation.Collection;
import org.apache.isis.applib.annotation.SemanticsOf;
-import org.apache.isis.schema.ixn.v2.InteractionDto;
import demoapp.dom.annotDomain.Property.publishing.PropertyPublishingJdo;
+//tag::class[]
@Action(
semantics = SemanticsOf.IDEMPOTENT
, associateWith = "interactionExecutions"
)
public class PropertyPublishingJdo_clearInteractionExecutions {
+ // ...
+//end::class[]
private final PropertyPublishingJdo propertyPublishingJdo;
@@ -24,11 +22,13 @@ public class
PropertyPublishingJdo_clearInteractionExecutions {
this.propertyPublishingJdo = propertyPublishingJdo;
}
- public List<InteractionDto> act() {
+//tag::class[]
+ public PropertyPublishingJdo act() {
publisherServiceSpiForProperties.clear();
- return (List<InteractionDto>) propertyPublishingJdo;
+ return propertyPublishingJdo;
}
@Inject
- private PublisherServiceSpiForProperties publisherServiceSpiForProperties;
+ PublisherServiceSpiForProperties publisherServiceSpiForProperties;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_interactionExecutions.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_interactionExecutions.java
index 98ad7f9..b1adbca 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_interactionExecutions.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PropertyPublishingJdo_interactionExecutions.java
@@ -1,5 +1,6 @@
package demoapp.dom.annotDomain.Property.publishing.spiimpl;
+import java.util.LinkedList;
import java.util.List;
import java.util.stream.Collectors;
@@ -8,10 +9,15 @@ import javax.inject.Inject;
import org.apache.isis.applib.annotation.Collection;
import org.apache.isis.schema.ixn.v2.InteractionDto;
+import lombok.val;
+
import demoapp.dom.annotDomain.Property.publishing.PropertyPublishingJdo;
+//tag::class[]
@Collection
public class PropertyPublishingJdo_interactionExecutions {
+ // ...
+//end::class[]
private final PropertyPublishingJdo propertyPublishingJdo;
@@ -19,12 +25,16 @@ public class PropertyPublishingJdo_interactionExecutions {
this.propertyPublishingJdo = propertyPublishingJdo;
}
+//tag::class[]
public List<InteractionDto> coll() {
- return publisherServiceSpiForProperties
+ val list = new LinkedList<InteractionDto>();
+ publisherServiceSpiForProperties
.streamInteractionDtos()
- .collect(Collectors.toList());
+ .forEach(list::push); // reverse order
+ return list;
}
@Inject
- private PublisherServiceSpiForProperties publisherServiceSpiForProperties;
+ PublisherServiceSpiForProperties publisherServiceSpiForProperties;
}
+//end::class[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PublisherServiceSpiForProperties.java
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PublisherServiceSpiForProperties.java
index 46320ee..b196435 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PublisherServiceSpiForProperties.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/publishing/spiimpl/PublisherServiceSpiForProperties.java
@@ -10,9 +10,11 @@ import org.apache.isis.applib.services.iactn.Interaction;
import org.apache.isis.applib.services.publish.PublishedObjects;
import org.apache.isis.applib.services.publish.PublisherService;
import org.apache.isis.applib.util.schema.InteractionDtoUtils;
-import org.apache.isis.schema.chg.v2.ChangesDto;
import org.apache.isis.schema.ixn.v2.InteractionDto;
+import lombok.val;
+
+//tag::class[]
@Service
public class PublisherServiceSpiForProperties implements PublisherService {
@@ -20,17 +22,14 @@ public class PublisherServiceSpiForProperties implements
PublisherService {
@Override
public void publish(Interaction.Execution<?, ?> execution) {
-
- final InteractionDto dto =
- InteractionDtoUtils.newInteractionDto(execution,
InteractionDtoUtils.Strategy.DEEP);
-
+ val dto = InteractionDtoUtils.newInteractionDto( // <.>
+ execution, InteractionDtoUtils.Strategy.DEEP);
executions.add(dto);
}
+ // ...
+//end::class[]
- @Override
- public void publish(PublishedObjects publishedObjects) {
- }
-
+//tag::demo[]
public Stream<InteractionDto> streamInteractionDtos() {
return executions.stream();
}
@@ -38,5 +37,12 @@ public class PublisherServiceSpiForProperties implements
PublisherService {
public void clear() {
executions.clear();
}
+//end::demo[]
+
+ @Override
+ public void publish(PublishedObjects publishedObjects) {
+ }
+//tag::class[]
}
+//end::class[]
