[isis] 03/07: ISIS-2476: improves docs for property mementoSerialization

[da...@apache.org]

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

danhaywood pushed a commit to branch ISIS-439
in repository https://gitbox.apache.org/repos/asf/isis.git

commit bfe677306ce90f395a7735e517c70c94d5f884e0
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Jan 13 07:18:10 2021 +0000

    ISIS-2476: improves docs for property mementoSerialization
---
 ...PropertyMementoSerializationVm-description.adoc | 129 ++++++---------------
 .../PropertyMementoSerializationVm.java            |  15 ++-
 ...ropertyMementoSerializationVm_takeSnapshot.java |  31 ++---
 3 files changed, 61 insertions(+), 114 deletions(-)

diff --git a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm-description.adoc
index a86fcdc..0c0bd9b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm-description.adoc
@@ -1,135 +1,78 @@
 :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 [...]
 
-The `associateWith` element specifies an action has a relationship with another property or another collection of the domain class.
+The `mementoSerialization` element of the `@Property` annotation specifies whether a property should be included in an XML snapshot, as created by the `XmlSnapshotService`:
 
-* For properties, the association (currently) is used solely for layout purposes, so that the action will by default be rendered close to the property.
-+
-This can of course be overridden using `@ActionLayout` or the layout file
-
-* For collections, the association is also used for layout purposes, rendering the action near to the collection.
-+
-However, it is also used at a deeper level, because the action may have a collection parameter which is the same type as the collection elements.
-In the Wicket viewer, the collection is rendered with checkboxes; those selected objects are used as defaults for the action collection parameter.
-
-
-== Associated with Properties
-
-The `AssociateWithVm` class defines two properties, `text` and `anotherProperty`:
-
-[source,java]
-----
-include::ActionAssociateWithVm.java[tags=class-properties]
-----
-
-The regular `updateText` action is associated with the `text` property:
-
-[source,java,indent=0]
-----
-include::ActionAssociateWithVm.java[tags=action-associateWith-property]
-----
-<.> indicates the property to associate with
-<.> if there are multiple actions associated with the property, indicates their order in the UI
-
-Meanwhile the mixin `updateOtherProperty` is associated with the `otherProperty` property:
+The `takeSnapshot` mixin action shows how this service is used:
 
 [source,java,indent=0]
 ----
-include::ActionAssociateWithVm_updateOtherProperty.java[tags=class]
+include::PropertyMementoSerializationVm_takeSnapshot.java[tags=class]
 ----
-<.> indicates the property to associate with
-<.> indicates their order in the UI
 
+There are several use cases of the resultant XML; a common one is for adhoc auditing.
+Another is when there's a need to pass the state of an object (graph) into a supporting domain service, for example to perform a mail merge.
+All that is required is the state of the object, which can then be extracted, eg using XPath.
+This allows the domain object and service to have no direct knowledge of each other; the binding is entirely configuration driven.
 
-== Collection
 
-The `AssociateWithVm` class also defines the `children` collection:
 
-[source,java]
-----
-include::ActionAssociateWithVm.java[tags=class-collections-children]
-----
+== Annotations and Meta-annotations
 
-There are three actions associated with this collection:
+The example view model indicates which properties to include or exclude from the view model:
 
-* the `addChild` action:
+* with no annotation:
 +
 [source,java,indent=0]
 ----
-include::ActionAssociateWithVm.java[tags=action-associateWith-children-1]
+include::PropertyMementoSerializationVm.java[tags=no-annotation]
 ----
-<.> associates with the "children" collection
-<.> positioned first in the UI
++
+These will be included by default.
 
-* the `removeChild` action.
+* explicitly included:
 +
 [source,java,indent=0]
 ----
-include::ActionAssociateWithVm.java[tags=action-associateWith-children-2]
+include::PropertyMementoSerializationVm.java[tags=annotated-included]
 ----
-<.> associates with the "children" collection
-<.> positioned second in the UI
-<.> because this action is associated with a collection, no supporting `choices()` or `autoComplete(...)` is required to provide the parameter.
-Instead, the elements in the collection are automatically used.
-
-+
-TIP: an explicit `choices()` or `autoComplete(...)` supporting method can be provided to override the default usage of the collection elements if required.
 
-* the `removeChildren` action, which allows multiple children to be removed:
+* explicitly excluded:
 +
 [source,java,indent=0]
 ----
-include::ActionAssociateWithVm.java[tags=action-associateWith-children-3]
+include::PropertyMementoSerializationVm.java[tags=annotated-excluded]
 ----
-<.> associates with the "children" collection
-<.> positioned third in the UI
-<.> again, no supporting `choices()` or `autoComplete(...)` method is required.
-Instead, the elements of the collection are used as options.
-Also, each row in the collection is rendered with a checkbox, and those selected are used as the default for the parameter.
-
-== Mixin Actions
-
-The `AssociateWithVm` class also defines the `favorites` collection:
 
-[source,java]
+* included through a meta-annotation:
++
+[source,java,indent=0]
 ----
-include::ActionAssociateWithVm.java[tags=class-collections-favorites]
+include::PropertyMementoSerializationVm.java[tags=meta-annotated-included]
 ----
-
-There are three mixin actions associated with this collection:
-
-* the `makeFavorite` action.
-This takes a element from the "children" collectio and also adds to the "favorites" collection:
 +
-[source,java]
+where the meta-annotation is:
++
+[source,java,indent=0]
 ----
-include::child/ActionAssociateWithVm_makeFavorite.java[tags=class]
+include::MementoSerializationIncludedMetaAnnotation.java[tags=class]
 ----
-<.> associates with the "favorites" collection
-<.> positioned first in the UI
-<.> choices are taken from the "children" collection
 
-* the `noLongerFavorite` action.
-This just removes a selected element from the "children" collection:
+* excluded through a meta-annotation:
 +
-[source,java]
+[source,java,indent=0]
 ----
-include::child/ActionAssociateWithVm_noLongerFavorite.java[tags=class]
+include::PropertyMementoSerializationVm.java[tags=meta-annotated-excluded]
 ----
-<.> associates with the "children" collection
-<.> positioned second in the UI
-<.> because this action is associated with a collection, no supporting `choices()` or `autoComplete(...)` is required to provide the parameter.
-Instead, the elements in the collection are automatically used.
-
-* the `noLongerFavorites` action.
-This is similar to the previous action, but for multiple favorite elements:
 +
-[source,java]
+where the meta-annotation is:
++
+[source,java,indent=0]
 ----
-include::child/ActionAssociateWithVm_noLongerFavorites.java[tags=class]
+include::MementoSerializationExcludedMetaAnnotation.java[tags=class]
 ----
-<.> associates with the "favorites" collection
-<.> positioned third in the UI
-<.> because this action is associated with a collection, no supporting `choices()` or `autoComplete(...)` is required to provide the parameter.
-Instead, the elements in the collection are automatically used.
 
 
+
+== Snapshot
+
+TODO: inline the resultant snapshot
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm.java b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm.java
index a4e2f26..abb8b44 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm.java
@@ -32,11 +32,12 @@ import org.apache.isis.applib.annotation.Nature;
 import org.apache.isis.applib.annotation.Property;
 import org.apache.isis.applib.annotation.PropertyLayout;
 
-import demoapp.dom._infra.asciidocdesc.HasAsciiDocDescription;
 import lombok.Getter;
 import lombok.NoArgsConstructor;
 import lombok.Setter;
 
+import demoapp.dom._infra.asciidocdesc.HasAsciiDocDescription;
+
 @XmlRootElement(name = "root")
 @XmlType
 @XmlAccessorType(XmlAccessType.FIELD)
@@ -61,12 +62,15 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
         return "PropertyMementoSerializationVm";
     }
 
+//tag::no-annotation[]
     @Property()
     @MemberOrder(name = "no-annotations", sequence = "1")
     @XmlElement(required = true)
     @Getter @Setter
     private String text;
+//end::no-annotation[]
 
+//tag::annotated-not_specified[]
     @Property(
         mementoSerialization = MementoSerialization.NOT_SPECIFIED
     )
@@ -77,7 +81,9 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
     @XmlElement(required = true)
     @Getter @Setter
     private String notSpecifiedProperty;
+//end::annotated-not_specified[]
 
+//tag::annotated-excluded[]
     @Property(
         mementoSerialization = MementoSerialization.EXCLUDED
     )
@@ -88,7 +94,9 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
     @XmlElement(required = true)
     @Getter @Setter
     private String excludedProperty;
+//end::annotated-excluded[]
 
+//tag::annotated-included[]
     @Property(
         mementoSerialization = MementoSerialization.INCLUDED
     )
@@ -99,7 +107,9 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
     @XmlElement(required = true)
     @Getter @Setter
     private String includedProperty;
+//end::annotated-included[]
 
+//tag::meta-annotated-excluded[]
     @MementoSerializationExcludedMetaAnnotation     // <.>
     @Property()
     @PropertyLayout(
@@ -109,7 +119,9 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
     @XmlElement(required = true)
     @Getter @Setter
     private String metaAnnotatedProperty;
+//end::meta-annotated-excluded[]
 
+//tag::meta-annotated-included[]
     @MementoSerializationIncludedMetaAnnotation                 // <.>
     @Property(
         mementoSerialization = MementoSerialization.EXCLUDED    // <.>
@@ -123,5 +135,6 @@ public class PropertyMementoSerializationVm implements HasAsciiDocDescription {
     @XmlElement(required = true)
     @Getter @Setter
     private String metaAnnotatedPropertyOverridden;
+//end::meta-annotated-included[]
 
 }
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm_takeSnapshot.java b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm_takeSnapshot.java
index 7e97ae8..bb49d51 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm_takeSnapshot.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Property/mementoSerialization/PropertyMementoSerializationVm_takeSnapshot.java
@@ -36,33 +36,24 @@ import lombok.val;
 @RequiredArgsConstructor
 public class PropertyMementoSerializationVm_takeSnapshot {
 
-    @Inject
-    XmlSnapshotService xmlSnapshotService;
-    @Inject
-    XmlService xmlService;
-
-    // ...
-//end::class[]
-
-    private final PropertyMementoSerializationVm propertyMementoSerializationVm;
+    @Inject XmlSnapshotService xmlSnapshotService;
+    @Inject XmlService xmlService;
 
+    private final PropertyMementoSerializationVm vm;
 
 //tag::class[]
-    public Clob act() {
-        return snapshotUsing(propertyMementoSerializationVm);
-    }
-
-    private Clob snapshotUsing(
-            final Object parentVm) {
-        val builder = xmlSnapshotService.builderFor(parentVm);
+    public Clob act(String fileName) {
+        val builder = xmlSnapshotService.builderFor(vm);
         val snapshot = builder.build();
         val doc = snapshot.getXmlDocument();
-        return asClob(xmlService.asString(doc));
+        return asClob(xmlService.asString(doc), fileName);
+    }
+    public String default0Act() {
+        return "snapshot.xml";
     }
 
-
-    private static Clob asClob(final String xmlStr) {
-        return new Clob("snapshot.xml", "application/xml", xmlStr);
+    private static Clob asClob(final String xmlStr, final String fileName) {
+        return new Clob(fileName, "application/xml", xmlStr);
     }
 }
 //end::class[]