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 2016/05/13 13:30:57 UTC
[1/2] isis git commit: ISIS-1291: documentation on command and events.
Repository: isis
Updated Branches:
refs/heads/ISIS-1291 138dc57a0 -> 7ebbb70c1
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/chg/chg-1.0.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/chg/chg-1.0.xsd b/adocs/documentation/src/main/asciidoc/schema/chg/chg-1.0.xsd
new file mode 100644
index 0000000..e793d71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/schema/chg/chg-1.0.xsd
@@ -0,0 +1,97 @@
+\ufeff<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xs:schema targetNamespace="http://isis.apache.org/schema/chg"
+ elementFormDefault="qualified"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://isis.apache.org/schema/chg"
+ xmlns:com="http://isis.apache.org/schema/common"
+ >
+
+ <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="../common/common-1.0.xsd"/>
+
+ <xs:element name="changesDto">
+ <xs:annotation>
+ <xs:documentation>The changes (create/update/delete) to one or more domain objects within a transaction. (nb: only published objects are included in these lists).
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="majorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="1">
+ <xs:annotation>
+ <xs:documentation>The major version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="minorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="0">
+ <xs:annotation>
+ <xs:documentation>The minor version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="transactionId" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Transaction id within which this change occurred.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="completedAt" type="xs:dateTime" minOccurs="0" maxOccurs="1">
+ <xs:annotation>
+ <xs:documentation>The point in time that these changes were completed.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="user" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>The name of the user that performed this transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="objects" type="objectsDto"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:complexType name="objectsDto">
+ <xs:annotation>
+ <xs:documentation>A set of changes to domain objects.</xs:documentation>
+ </xs:annotation>
+ <xs:sequence>
+ <xs:element name="created" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects created within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="updated" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects updated within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="deleted" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects deleted within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+
+</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/chg/chg.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/chg/chg.xsd b/adocs/documentation/src/main/asciidoc/schema/chg/chg.xsd
new file mode 100644
index 0000000..e793d71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/schema/chg/chg.xsd
@@ -0,0 +1,97 @@
+\ufeff<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xs:schema targetNamespace="http://isis.apache.org/schema/chg"
+ elementFormDefault="qualified"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://isis.apache.org/schema/chg"
+ xmlns:com="http://isis.apache.org/schema/common"
+ >
+
+ <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="../common/common-1.0.xsd"/>
+
+ <xs:element name="changesDto">
+ <xs:annotation>
+ <xs:documentation>The changes (create/update/delete) to one or more domain objects within a transaction. (nb: only published objects are included in these lists).
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="majorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="1">
+ <xs:annotation>
+ <xs:documentation>The major version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="minorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="0">
+ <xs:annotation>
+ <xs:documentation>The minor version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="transactionId" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Transaction id within which this change occurred.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="completedAt" type="xs:dateTime" minOccurs="0" maxOccurs="1">
+ <xs:annotation>
+ <xs:documentation>The point in time that these changes were completed.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="user" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>The name of the user that performed this transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="objects" type="objectsDto"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:complexType name="objectsDto">
+ <xs:annotation>
+ <xs:documentation>A set of changes to domain objects.</xs:documentation>
+ </xs:annotation>
+ <xs:sequence>
+ <xs:element name="created" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects created within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="updated" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects updated within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="deleted" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>The list of objects deleted within the transaction.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+
+</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/cmd/cmd.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/cmd/cmd.xsd b/adocs/documentation/src/main/asciidoc/schema/cmd/cmd.xsd
new file mode 100644
index 0000000..8f34661
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/schema/cmd/cmd.xsd
@@ -0,0 +1,151 @@
+\ufeff<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xs:schema targetNamespace="http://isis.apache.org/schema/cmd"
+ elementFormDefault="qualified"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://isis.apache.org/schema/cmd"
+ xmlns:com="http://isis.apache.org/schema/common">
+
+ <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="../common/common-1.0.xsd"/>
+
+ <xs:element name="commandDto">
+ <xs:annotation>
+ <xs:documentation>Represents v1.0 of this schema.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="majorVersion" type="xs:string" minOccurs="1" maxOccurs="1" default="1">
+ <xs:annotation>
+ <xs:documentation>The major version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="minorVersion" type="xs:string" minOccurs="1" maxOccurs="1" default="1">
+ <xs:annotation>
+ <xs:documentation>Introduced in v1.1. The minor version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="transactionId" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Transaction id for this command, a unique identifier.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="targets" type="com:oidsDto">
+ <xs:annotation>
+ <xs:documentation>For regular actions, represents the entity/entities or view model(s) upon which the action is to be invoked. For mixin actions, is the object(s) being mixed-into (the constructor arg to the mixin). For contributed actions, is the domain service (the contributee object will be one of the action arguments within the payload). Note that this means that bulk contributed actions cannot be reified as a memento (for this use case, implement as a mixin action instead).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="member" type="memberDto">
+ <xs:annotation>
+ <xs:documentation>The action or property (identifier and parameter arguments) to be invoked on the target object(s).</xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="user" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>The name of the user that initiated/created this command.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:complexType name="memberDto" abstract="true">
+ <xs:annotation>
+ <xs:documentation>Represents the information required to be able to invoke an action or modify a property on the target(s). Specifically, is the identifier of the action/property, along with the parameter arguments. Is subclassed by 'actionDto' and 'propertyDto'.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:sequence>
+ <xs:element name="memberIdentifier" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Formal identifier of the member being interacted with (action or property).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="interactionType" type="com:interactionType">
+ <xs:annotation>
+ <xs:documentation>Indicates whether this is an intention to invoke an action, or edit a property.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ </xs:complexType>
+
+ <xs:complexType name="actionDto">
+ <xs:annotation>
+ <xs:documentation>Captures the information required to be able to invoke an action on the target(s).
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexContent>
+ <xs:extension base="memberDto">
+ <xs:sequence>
+ <xs:element name="parameters" type="paramsDto">
+ <xs:annotation>
+ <xs:documentation>The list of parameter/argument values for this action invocation.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="propertyDto">
+ <xs:annotation>
+ <xs:documentation>Captures the information required to be able to modify a property on the target(s).
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexContent>
+ <xs:extension base="memberDto">
+ <xs:sequence>
+ <xs:element name="newValue" type="com:valueWithTypeDto"/>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="paramsDto">
+ <xs:annotation>
+ <xs:documentation>A list of of parameter/argument values.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:sequence minOccurs="0" maxOccurs="unbounded">
+ <xs:element name="parameter" type="paramDto"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:complexType name="paramDto">
+ <xs:annotation>
+ <xs:documentation>Defines an action parameter: its name, type and value (ie provided argument).
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexContent>
+ <xs:extension base="com:valueWithTypeDto">
+ <xs:attribute name="name" use="required" type="xs:string"/>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+
+</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/common/common-1.0.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/common/common-1.0.xsd b/adocs/documentation/src/main/asciidoc/schema/common/common-1.0.xsd
index ecf6b01..041208c 100644
--- a/adocs/documentation/src/main/asciidoc/schema/common/common-1.0.xsd
+++ b/adocs/documentation/src/main/asciidoc/schema/common/common-1.0.xsd
@@ -188,5 +188,4 @@
</xs:restriction>
</xs:simpleType>
-
</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/common/common.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/common/common.xsd b/adocs/documentation/src/main/asciidoc/schema/common/common.xsd
index ecf6b01..041208c 100644
--- a/adocs/documentation/src/main/asciidoc/schema/common/common.xsd
+++ b/adocs/documentation/src/main/asciidoc/schema/common/common.xsd
@@ -188,5 +188,4 @@
</xs:restriction>
</xs:simpleType>
-
</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/ixn/ixn-1.0.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/ixn/ixn-1.0.xsd b/adocs/documentation/src/main/asciidoc/schema/ixn/ixn-1.0.xsd
index 86e64e7..a6d123a 100644
--- a/adocs/documentation/src/main/asciidoc/schema/ixn/ixn-1.0.xsd
+++ b/adocs/documentation/src/main/asciidoc/schema/ixn/ixn-1.0.xsd
@@ -35,7 +35,7 @@
</xs:annotation>
<xs:complexType>
<xs:sequence>
- <xs:element name="majorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="2">
+ <xs:element name="majorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="1">
<xs:annotation>
<xs:documentation>The major version of the schema that an XML instance was created using.
</xs:documentation>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/schema/ixn/ixn.xsd
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/schema/ixn/ixn.xsd b/adocs/documentation/src/main/asciidoc/schema/ixn/ixn.xsd
new file mode 100644
index 0000000..a6d123a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/schema/ixn/ixn.xsd
@@ -0,0 +1,227 @@
+\ufeff<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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 agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<xs:schema targetNamespace="http://isis.apache.org/schema/ixn"
+ elementFormDefault="qualified"
+ xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://isis.apache.org/schema/ixn"
+ xmlns:cmd="http://isis.apache.org/schema/cmd"
+ xmlns:com="http://isis.apache.org/schema/common"
+>
+
+ <xs:import namespace="http://isis.apache.org/schema/common" schemaLocation="../common/common-1.0.xsd"/>
+ <xs:import namespace="http://isis.apache.org/schema/cmd" schemaLocation="../cmd/cmd-1.0.xsd"/>
+
+ <xs:element name="interactionDto">
+ <xs:annotation>
+ <xs:documentation>Represents v1.0 of this schema, replacing and generalizing the earlier 'actionInvocationMemento'.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="majorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="1">
+ <xs:annotation>
+ <xs:documentation>The major version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="minorVersion" type="xs:string" minOccurs="0" maxOccurs="1" default="0">
+ <xs:annotation>
+ <xs:documentation>The minor version of the schema that an XML instance was created using.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="transactionId" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Transaction id within which this member was interacted with (action invoked/property edited); can be used to locate the corresponding Command object (which may have been persisted).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="execution" type="memberExecutionDto"/>
+ </xs:sequence>
+ </xs:complexType>
+
+ </xs:element>
+
+ <xs:complexType name="memberExecutionDto" abstract="true">
+ <xs:annotation>
+ <xs:documentation>Represents either an action invocation or a property edit. Is subclassed by both.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:sequence>
+ <xs:element name="id" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Unique identifier for this individual member interaction, in the format "transactionId.sequence" (where 'transactionId' is part of the owning 'memberInteractionMementoDto' and 'sequence' is defined below).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="sequence" type="xs:int">
+ <xs:annotation>
+ <xs:documentation>Unique sequence number of an individual member interaction within a transaction. There could be many such member interactions (within a single transaction ) for two reasons: either a single top-level interaction could call sub-interactions (by virtue of WrapperFactory), or there may be a bulk action interaction against many targets.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="target" type="com:oidDto" minOccurs="1" maxOccurs="1">
+ <xs:annotation>
+ <xs:documentation>For target domain object being interacted with. For regular actions/properties, represents the entity or view model upon which the action is to be invoked/property edited. For mixin actions/properties, is the object being mixed-into (the constructor arg to the mixin). For contributed actions/properties, is the domain service (the contributee object will be one of the action arguments within the payload).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="memberIdentifier" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>Formal identifier (class name and member name) of the member being interacted with (action or property).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="user" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>The name of the user that invoked this action. Note that this isn't necessarily the user that initiated the original command; the SudoService may be being used to temporarily switch the effective user.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="title" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>User-friendly title of the 'target' object.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="metrics" type="metricsDto">
+ <xs:annotation>
+ <xs:documentation>Profiling metrics capturng the this time/number of objects affected as a result of performing this member interaction (invoke the action, or edit the property).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="threw" type="exceptionDto" minOccurs="0" maxOccurs="1">
+ <xs:annotation>
+ <xs:documentation>Captures any exception thrown by an action. Either the 'returned' or the 'threw' element will be populated.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="childExecutions" minOccurs="0" maxOccurs="1">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="execution" type="memberExecutionDto" minOccurs="0" maxOccurs="unbounded">
+ <xs:annotation>
+ <xs:documentation>Capture interactions with other members from this interaction, using the WrapperFactory service. Typically this will be actions invoking other actions, but it is also possible for an action to perform a property edit, and - much rarer - for a property edit to invoke an action. Whatever; these interactions nest together into a call/stack, more generally into a graph.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ <xs:attribute name="interactionType" type="com:interactionType">
+ <xs:annotation>
+ <xs:documentation>Indicates whether this is an intention to invoke an action, or edit a property.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:attribute>
+ </xs:complexType>
+
+ <xs:complexType name="actionInvocationDto">
+ <xs:complexContent>
+ <xs:extension base="memberExecutionDto">
+ <xs:sequence>
+ <xs:element name="parameters" type="cmd:paramsDto">
+ <xs:annotation>
+ <xs:documentation>The list of parameter/argument values for this action invocation.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="returned" type="com:valueWithTypeDto" minOccurs="0" maxOccurs="1">
+ <xs:annotation>
+ <xs:documentation>The value returned by this action (including the type of that returned value). Either the 'returned' or the 'threw' element (from 'memberExecutionDto') will be populated.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="propertyEditDto">
+ <xs:complexContent>
+ <xs:extension base="memberExecutionDto">
+ <xs:sequence>
+ <xs:element name="newValue" type="com:valueWithTypeDto"/>
+ </xs:sequence>
+ </xs:extension>
+ </xs:complexContent>
+ </xs:complexType>
+
+ <xs:complexType name="metricsDto">
+ <xs:sequence>
+ <xs:element name="timings" type="com:periodDto">
+ <xs:annotation>
+ <xs:documentation>The time taken to perform the member interaction (invoke the action, or edit the property).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="objectCounts" type="objectCountsDto">
+ <xs:annotation>
+ <xs:documentation>How many objets were affected by the member interaction.
+ </xs:documentation>
+ </xs:annotation>
+
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+
+ <xs:complexType name="objectCountsDto">
+ <xs:sequence>
+ <xs:element name="loaded" type="com:differenceDto">
+ <xs:annotation>
+ <xs:documentation>The number of objects loaded.
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="dirtied" type="com:differenceDto">
+ <xs:annotation>
+ <xs:documentation>The number of objects dirtied (ie updated).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="propertiesModified" type="com:differenceDto">
+ <xs:annotation>
+ <xs:documentation>The number of individual properties of objects that were modified (each such change would correspond to a separate call to AuditingService if configured).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ </xs:sequence>
+
+ </xs:complexType>
+
+ <xs:complexType name="exceptionDto">
+ <xs:annotation>
+ <xs:documentation>Captures any exception thrown by an action invocation. Use as the xsd:type of the 'threw' element.
+ </xs:documentation>
+ </xs:annotation>
+ <xs:sequence>
+ <xs:element name="message" type="xs:string"/>
+ <xs:element name="stackTrace" type="xs:string">
+ <xs:annotation>
+ <xs:documentation>A formatted stack trace. (A future version of the 'exceptionDto' element might refine this to more easily parseable stack trace elements).
+ </xs:documentation>
+ </xs:annotation>
+ </xs:element>
+ <xs:element name="causedBy" type="exceptionDto" minOccurs="0" maxOccurs="1"/>
+ </xs:sequence>
+ </xs:complexType>
+
+</xs:schema>
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/screencasts.adoc b/adocs/documentation/src/main/asciidoc/screencasts.adoc
index 3e5339a..d4f1985 100644
--- a/adocs/documentation/src/main/asciidoc/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/screencasts.adoc
@@ -135,13 +135,13 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=dfRZeYqzMtI[012^] +
-Implementing business logic using a (no-arg) action, and associating with a property using either the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotations or using xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[dynamic (XML) layouts].
+Implementing business logic using a (no-arg) action, and associating with a property using either the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotations or using xref:ugfun.adoc#_ugfun_object-layout_dynamic_xml[dynamic (XML) layouts].
|x||||||||x|
|link:https://www.youtube.com/watch?v=0naoVsWppuQ[013^] +
-Invoking (no-arg) action on multiple objects at once (using xref:rgant.adoc#_rgant_Action_invokeOn[`@Action#invokeOn()`], and using the xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] domain service for a smoother end-user experience.
+Invoking (no-arg) action on multiple objects at once (using xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`], and using the xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] domain service for a smoother end-user experience.
|||x||||||x|
@@ -161,7 +161,7 @@ Using the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`], xref:rgcms.a
|link:https://www.youtube.com/watch?v=7ToRKBOeemM[015^] +
-Moving the responsibility to specify the icon for a domain object out and into a subscriber, using the xref:rgcms.adoc#_rgcms_classes_uievent_IconUiEvent[`IconUiEvent`] as per the xref:rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] annotation
+Moving the responsibility to specify the icon for a domain object out and into a subscriber, using the xref:rgcms.adoc#_rgcms_classes_uievent_IconUiEvent[`IconUiEvent`] as per the xref:rgant.adoc#_rgant-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] annotation
||||||x||||
@@ -221,7 +221,7 @@ Demonstrates how the end-user can copy and share URLs for domain objects - inclu
|link:https://www.youtube.com/watch?v=a0QQLT_16To[021^] +
-Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:ugvw.adoc[Wicket viewer], and how the developer can ensure that xref:rgant.adoc#_rgant_DomainObjectLayout_bookmarking[domain objects] and (xref:rgant.adoc#_rgant_Action_semantics[query-only]) xref:rgant.adoc#_rgant_ActionLayout_bookmarking[actions] can be bookmarked.
+Demonstrates how the end-user can use bookmarks and breadcrumbs within Apache Isis' xref:ugvw.adoc[Wicket viewer], and how the developer can ensure that xref:rgant.adoc#_rgant-DomainObjectLayout_bookmarking[domain objects] and (xref:rgant.adoc#_rgant-Action_semantics[query-only]) xref:rgant.adoc#_rgant-ActionLayout_bookmarking[actions] can be bookmarked.
|||x|||||||
@@ -267,7 +267,7 @@ Using a domain event xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[sub
|link:https://www.youtube.com/watch?v=qj4bMkQRBUY[026^] +
-Using the xref:rgant.adoc#_rgant_Title[`@Title`] annotation (instead of the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method) to obtain the title of a domain object, so that the end-user can distinguish one object from another.
+Using the xref:rgant.adoc#_rgant-Title[`@Title`] annotation (instead of the xref:rgcms.adoc#_rgcms_methods_reserved_title[`title()`] reserved method) to obtain the title of a domain object, so that the end-user can distinguish one object from another.
|x||||||||x|
@@ -280,7 +280,7 @@ Using the xref:rgant.adoc#_rgant_Title[`@Title`] annotation (instead of the xref
|link:https://www.youtube.com/watch?v=yi52Gbd3lmY[027^] +
-How to write an xref:ugtst.adoc#_ugtst_integ-test-support[integration test] for an xref:rgant.adoc#_rgant_Mixin[mixin].
+How to write an xref:ugtst.adoc#_ugtst_integ-test-support[integration test] for an xref:rgant.adoc#_rgant-Mixin[mixin].
||x||||||||
@@ -303,7 +303,7 @@ Using link:https://projectlombok.org/[Project Lombok] to remove boilerplate from
|link:https://www.youtube.com/watch?v=AXuxULuRtm0[029^] +
-Using the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] module to remove boilerplate from your domain object (xref:rgant.adoc#_rgant_ParameterLayout_named[`@ParameterLayout#named()`] annotation attribute on action parameters).
+Using the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] module to remove boilerplate from your domain object (xref:rgant.adoc#_rgant-ParameterLayout_named[`@ParameterLayout#named()`] annotation attribute on action parameters).
|||||x|||x||
@@ -324,7 +324,7 @@ How to validate action parameters using a supporting xref:rgcms.adoc#_rgcms_meth
|link:https://www.youtube.com/watch?v=1Vlzob89pYI[031^] +
-How to validate action parameters using the xref:rgant.adoc#_rgant_Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] and the Specification interface.
+How to validate action parameters using the xref:rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] and the Specification interface.
|||||||||x|
@@ -383,7 +383,7 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=1SCyBlMM2Bo[037^] +
-How to hide properties as columns in tables (parented collections or standalone collections), using the dynamic XML layout (equivalent to xref:rgant.adoc#_rgant_PropertyLayout_hidden[`@PropertyLayout#hidden()`]).
+How to hide properties as columns in tables (parented collections or standalone collections), using the dynamic XML layout (equivalent to xref:rgant.adoc#_rgant-PropertyLayout_hidden[`@PropertyLayout#hidden()`]).
||||x||||||
@@ -428,7 +428,7 @@ Using BigDecimal as a property within a domain object, also demonstrating the "s
|link:https://www.youtube.com/watch?v=n9Oy0m2bplw[042^] +
-How to use the xref:rgant.adoc#_rgant_Digits[`@Digits`] annotation for action parameters of type ``java.math.BigDecimal``.
+How to use the xref:rgant.adoc#_rgant-Digits[`@Digits`] annotation for action parameters of type ``java.math.BigDecimal``.
|||||||||x|
@@ -447,7 +447,7 @@ How to use the supporting xref:rgcms.adoc#_rgcms_methods_prefixes_default[`defau
|link:https://www.youtube.com/watch?v=qAJDGxztWIQ[044^] +
-How to use xref:rgant.adoc#_rgant_DomainObject_bounded[`@DomainObject#bounded()`] so that a drop-down list is automatically provided for any parameters to actions that are for (domain entity) reference types.
+How to use xref:rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`] so that a drop-down list is automatically provided for any parameters to actions that are for (domain entity) reference types.
|||||||||x|
@@ -483,7 +483,7 @@ extension.
|link:https://www.youtube.com/watch?v=0YoFa44Xr6M[049^] +
-Using the xref:rgant.adoc#_rgant_Programmatic[`@Programmatic`] annotation to exclude methods from a domain object
+Using the xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`] annotation to exclude methods from a domain object
(eg implementing methods of an interface as defined by the (non-ASF)
http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 ] wicket extension) that would
otherwise be part of the Apache Isis metamodel (and thus show up in the UI).
@@ -552,7 +552,7 @@ How to rename a menu (on the top-level menubar) as rendered in the xref:ugvw.ado
|link:https://www.youtube.com/watch?v=mgHqRxQrp28[058^] +
-How to rename various elements (collections, title) of the xref:rgant.adoc#_rgant_HomePage[home page] view model,
+How to rename various elements (collections, title) of the xref:rgant.adoc#_rgant-HomePage[home page] view model,
for an improved initial page.
||||||||||x
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/core/applib/src/main/java/org/apache/isis/applib/annotation/InvokedOn.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/InvokedOn.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/InvokedOn.java
index 66f001f..896b107 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/InvokedOn.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/InvokedOn.java
@@ -28,6 +28,9 @@ public enum InvokedOn {
public boolean isObject() { return this == OBJECT; }
public boolean isCollection() { return this == COLLECTION; }
+ /**
+ * @deprecated - because the {@link Bulk} annotation is deprecated.
+ */
@Deprecated
public static InvokedOn from(final Bulk.InteractionContext.InvokedAs invokedAs) {
if (invokedAs == null) return null;
@@ -37,6 +40,9 @@ public enum InvokedOn {
throw new IllegalArgumentException("Unrecognized bulk interactionContext invokedAs: " + invokedAs);
}
+ /**
+ * @deprecated - because the {@link Bulk} annotation is deprecated.
+ */
@Deprecated
public static Bulk.InteractionContext.InvokedAs from(final InvokedOn invokedOn) {
if (invokedOn == null) return null;
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForAction.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForAction.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForAction.java
index 4a3a93e..2d437cc 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForAction.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForAction.java
@@ -21,29 +21,53 @@ package org.apache.isis.applib.annotation;
import java.util.List;
import org.apache.isis.applib.Identifier;
import org.apache.isis.applib.services.publish.EventPayload;
+import org.apache.isis.applib.services.publish.PublisherService;
+import org.apache.isis.applib.services.publish.PublishingService;
+/**
+ * @deprecated - supports the deprecated {@link PublishingService}; use instead {@link PublisherService} (which ignores {@link Action#publishingPayloadFactory()} but is otherwise more flexible.
+ */
+@Deprecated
public interface PublishingPayloadFactoryForAction {
+ /**
+ * @deprecated - because {@link PublishingService} is deprecated.
+ */
+ @Deprecated
@Programmatic
public EventPayload payloadFor(Identifier actionIdentifier, Object target, List<Object> arguments, Object result);
/**
* Adapter to subclass if have an existing {@link org.apache.isis.applib.annotation.PublishedObject.PayloadFactory}.
+ *
+ * @deprecated
*/
@Deprecated
public abstract class Adapter implements PublishingPayloadFactoryForAction {
private final PublishedAction.PayloadFactory payloadFactory;
+ /**
+ * @deprecated
+ */
+ @Deprecated
public Adapter(final PublishedAction.PayloadFactory payloadFactory) {
this.payloadFactory = payloadFactory;
}
+ /**
+ * @deprecated
+ */
+ @Deprecated
@Override
public EventPayload payloadFor(Identifier actionIdentifier, Object target, List<Object> arguments, Object result) {
return payloadFactory.payloadFor(actionIdentifier, target, arguments, result);
}
+ /**
+ * @deprecated
+ */
+ @Deprecated
public PublishedAction.PayloadFactory getPayloadFactory() {
return payloadFactory;
}
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForObject.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForObject.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForObject.java
index fb3df0d..f223b6e 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForObject.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/PublishingPayloadFactoryForObject.java
@@ -19,29 +19,53 @@
package org.apache.isis.applib.annotation;
import org.apache.isis.applib.services.publish.EventPayload;
+import org.apache.isis.applib.services.publish.PublisherService;
+import org.apache.isis.applib.services.publish.PublishingService;
+/**
+ * @deprecated - supports the deprecated {@link PublishingService}; use instead {@link PublisherService} (which ignores {@link DomainObject#publishingPayloadFactory()} but is otherwise more flexible.
+ */
+@Deprecated
public interface PublishingPayloadFactoryForObject {
+ /**
+ * @deprecated - because {@link PublishingService} is deprecated.
+ */
+ @Deprecated
@Programmatic
public EventPayload payloadFor(Object changedObject, PublishingChangeKind publishingChangeKind);
/**
* Adapter to subclass if have an existing {@link org.apache.isis.applib.annotation.PublishedObject.PayloadFactory}.
+ *
+ * @deprecated
*/
@Deprecated
public static class Adapter implements PublishingPayloadFactoryForObject {
private final PublishedObject.PayloadFactory payloadFactory;
+ /**
+ * @deprecated
+ */
+ @Deprecated
public Adapter(final PublishedObject.PayloadFactory payloadFactory) {
this.payloadFactory = payloadFactory;
}
+ /**
+ * @deprecated
+ */
+ @Deprecated
@Override
public EventPayload payloadFor(final Object changedObject, final PublishingChangeKind publishingChangeKind) {
return payloadFactory.payloadFor(changedObject, PublishingChangeKind.from(publishingChangeKind));
}
+ /**
+ * @deprecated
+ */
+ @Deprecated
public PublishedObject.PayloadFactory getPayloadFactory() {
return payloadFactory;
}
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/core/applib/src/main/java/org/apache/isis/applib/services/publish/PublishingService.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/publish/PublishingService.java b/core/applib/src/main/java/org/apache/isis/applib/services/publish/PublishingService.java
index 52ebd9d..8acd912 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/publish/PublishingService.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/publish/PublishingService.java
@@ -29,14 +29,9 @@ import org.apache.isis.applib.annotation.Programmatic;
* annotation, and an action is marked to be published using the
* {@link org.apache.isis.applib.annotation.PublishedAction} annotation.
*
- * <p>
- * There are currently two implementations, <tt>PublishingServiceJdo</tt> (part of the
- * <tt>o.a.i.module:isis-module-publishing-jdo</tt>) and the demo
- * {@link org.apache.isis.applib.services.publish.PublishingService.Stderr}.
- *
- * <p>
- * To use either service, must include on the classpath and also register the service (eg in <tt>isis.properties</tt>).
+ * @deprecated - use the {@link PublisherService} instead.
*/
+@Deprecated
public interface PublishingService {
/**
@@ -49,10 +44,27 @@ public interface PublishingService {
@Programmatic
void publish(EventMetadata metadata, EventPayload payload);
+ /**
+ * @deprecated - not every implementation will use an {@link EventSerializer}, so this ought not to have been
+ * defined in the interface.
+ */
+ @Programmatic
+ @Deprecated
+ void setEventSerializer(EventSerializer eventSerializer);
+
+
+ /**
+ * @deprecated
+ */
+ @Deprecated
class Stderr implements PublishingService {
private EventSerializer eventSerializer = new EventSerializer.Simple();
+ /**
+ * @deprecated
+ */
+ @Deprecated
@Hidden
@Override
public void publish(EventMetadata metadata, EventPayload payload) {
@@ -60,18 +72,16 @@ public interface PublishingService {
System.err.println(serializedEvent);
}
+ /**
+ * @deprecated
+ */
+ @Deprecated
@Override
public void setEventSerializer(EventSerializer eventSerializer) {
this.eventSerializer = eventSerializer;
}
}
- /**
- * @deprecated - not every implementation will use an {@link EventSerializer}, so this ought not to have been defined in the interface.
- */
- @Programmatic
- @Deprecated
- void setEventSerializer(EventSerializer eventSerializer);
}
[2/2] isis git commit: ISIS-1291: documentation on command and events.
Posted by da...@apache.org.
ISIS-1291: documentation on command and events.
Also:
- adding missing schemas in adocs documentation (for hosting on the web).
- updating bad links to @Xxx_aaa in multiple files
- deprecating some methods in applib API.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/7ebbb70c
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/7ebbb70c
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/7ebbb70c
Branch: refs/heads/ISIS-1291
Commit: 7ebbb70c115636f872d13bb1c367916febc961c3
Parents: 138dc57
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri May 13 14:30:52 2016 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri May 13 14:30:52 2016 +0100
----------------------------------------------------------------------
.../_migration-notes_1.11.0-to-1.12.0.adoc | 12 +-
.../main/asciidoc/_release-notes_1.12.0.adoc | 6 +-
.../asciidoc/guides/_dg_asciidoc-templates.adoc | 4 +-
.../guides/_rgant-ParameterLayout_named.adoc | 2 +-
.../asciidoc/guides/_rgant_aaa_deprecated.adoc | 2 +-
.../asciidoc/guides/_rgcms_classes_layout.adoc | 10 +-
.../main/asciidoc/guides/_rgcms_schema-aim.adoc | 10 +
.../main/asciidoc/guides/_rgcms_schema-chg.adoc | 11 +
.../main/asciidoc/guides/_rgcms_schema-cmd.adoc | 11 +
.../main/asciidoc/guides/_rgcms_schema-ixn.adoc | 12 +
.../src/main/asciidoc/guides/_rgcms_schema.adoc | 33 ++-
.../guides/_rgsvc_api_AcceptHeaderService.adoc | 2 +-
.../_rgsvc_api_HomePageProviderService.adoc | 2 +-
.../guides/_rgsvc_api_LayoutService.adoc | 6 +-
.../guides/_rgsvc_api_SwaggerService.adoc | 4 +-
.../src/main/asciidoc/guides/_rgsvc_intro.adoc | 126 +++++++++-
.../_rgsvc_spi_ContentMappingService.adoc | 2 +-
.../asciidoc/guides/_rgsvc_spi_GridService.adoc | 6 +-
.../guides/_rgsvc_spi_GridSystemService.adoc | 10 +-
.../guides/_rgsvc_spi_PublishingService.adoc | 96 ++++----
.../guides/_rgsvc_spi_RoutingService.adoc | 6 +-
.../src/main/asciidoc/guides/_ugbtb_i18n.adoc | 2 +-
...gbtb_programming-model_custom-validator.adoc | 2 +-
.../guides/_ugbtb_view-models_jaxb.adoc | 4 +-
...aqs_how-to-handle-void-and-null-results.adoc | 2 +-
...un_faqs_how-to-implement-a-spellchecker.adoc | 4 +-
.../_ugfun_object-layout_dynamic_xml.adoc | 6 +-
.../guides/_ugfun_object-layout_static.adoc | 12 +-
.../reference-services/commands-and-events.png | Bin 0 -> 83946 bytes
.../reference-services/commands-and-events.pptx | Bin 0 -> 43674 bytes
.../src/main/asciidoc/schema/chg/chg-1.0.xsd | 97 ++++++++
.../src/main/asciidoc/schema/chg/chg.xsd | 97 ++++++++
.../src/main/asciidoc/schema/cmd/cmd.xsd | 151 ++++++++++++
.../main/asciidoc/schema/common/common-1.0.xsd | 1 -
.../src/main/asciidoc/schema/common/common.xsd | 1 -
.../src/main/asciidoc/schema/ixn/ixn-1.0.xsd | 2 +-
.../src/main/asciidoc/schema/ixn/ixn.xsd | 227 +++++++++++++++++++
.../src/main/asciidoc/screencasts.adoc | 26 +--
.../isis/applib/annotation/InvokedOn.java | 6 +
.../PublishingPayloadFactoryForAction.java | 24 ++
.../PublishingPayloadFactoryForObject.java | 24 ++
.../services/publish/PublishingService.java | 36 +--
42 files changed, 951 insertions(+), 146 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/_migration-notes_1.11.0-to-1.12.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.11.0-to-1.12.0.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.11.0-to-1.12.0.adoc
index 811e5cd..7c5c39f 100644
--- a/adocs/documentation/src/main/asciidoc/_migration-notes_1.11.0-to-1.12.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.11.0-to-1.12.0.adoc
@@ -18,10 +18,10 @@ The major new feature in 1.12.0 is xref:ugfun.adoc#_ugfun_object-layout_dynamic_
much enhanced support for custom layouts.
The new `Xxx.layout.xml` file is optional; without it domain objects will
-continue to be rendered as before, using metadata from annotations (xref:rgant.adoc#_rgant_DomainObjectLayout[`@DomainObjectLayout`],
-xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`],
-xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and
-xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`]), and also from any xref:ugfun.adoc#_ugfun_object-layout_dynamic[`Xxx.layout.json`]
+continue to be rendered as before, using metadata from annotations (xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],
+xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],
+xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] and
+xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]), and also from any xref:ugfun.adoc#_ugfun_object-layout_dynamic[`Xxx.layout.json`]
file that might already exist. There is therefore no requirement to move to the new more flexible XML-based layout.
If you do want to start using the new format, then you will find that 1.12.0 provides a mixin action (available in
@@ -60,8 +60,8 @@ of these members by subscribing to their respective domain events.
== JAXB view models are editable
-All xref:rgant.adoc#_rgant_XmlRootElement[`@XmlRootElement`] view models are now implicitly editable. Therefore any
-view models that should be read-only should have editing attribute disabled using xref:rgant.adoc#_rgant_DomainObject_editing[`@DomainObject#editing()`] (or use a xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to veto editability).
+All xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] view models are now implicitly editable. Therefore any
+view models that should be read-only should have editing attribute disabled using xref:rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] (or use a xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to veto editability).
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/_release-notes_1.12.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_release-notes_1.12.0.adoc b/adocs/documentation/src/main/asciidoc/_release-notes_1.12.0.adoc
index 79b63e9..8d5e1c2 100644
--- a/adocs/documentation/src/main/asciidoc/_release-notes_1.12.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/_release-notes_1.12.0.adoc
@@ -49,18 +49,18 @@ corresponding domain event.
* link:https://issues.apache.org/jira/browse/ISIS-1329[ISIS-1329] - Extend hint support for "show all"
* link:https://issues.apache.org/jira/browse/ISIS-1327[ISIS-1327] - Change the view mode of the select2 (value drop down) to be a simple text field.
* link:https://issues.apache.org/jira/browse/ISIS-1324[ISIS-1324] - Allow multiple different views of same collection in a layout (xref:rgfun.adoc#_ugfun_object-layout_dynamic_xml[dynamic XML layouts])
-* link:https://issues.apache.org/jira/browse/ISIS-1323[ISIS-1323] - Deprecate @CollectionLayout#renderType, since is duplicated by xref:rgant.adoc#_rgant_CollectionLayout_defaultView[`@CollectionLayout#defaultView()`]
+* link:https://issues.apache.org/jira/browse/ISIS-1323[ISIS-1323] - Deprecate @CollectionLayout#renderType, since is duplicated by xref:rgant.adoc#_rgant-CollectionLayout_defaultView[`@CollectionLayout#defaultView()`]
* link:https://issues.apache.org/jira/browse/ISIS-1322[ISIS-1322] - Mixins not exposing the mixedin object in events (for subscribers to veto).
* link:https://issues.apache.org/jira/browse/ISIS-1321[ISIS-1321] - Extend xref:rgsvc.adoc#_rgsvc_api_MetaModelService[`MetaModelService`] to allow CSV of metamodel to be downloaded.
* link:https://issues.apache.org/jira/browse/ISIS-1320[ISIS-1320] - Move xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] to applib (and simplify)
* link:https://issues.apache.org/jira/browse/ISIS-1312[ISIS-1312] - Improve xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbServiceDefault#xsd(...)`] to correctly reference the Isis common schema imports.
* link:https://issues.apache.org/jira/browse/ISIS-1300[ISIS-1300] - Allow the enablement of the WicketSource plugin to be configurable, and disabled by default
-* link:https://issues.apache.org/jira/browse/ISIS-1299[ISIS-1299] - xref:rgant.adoc#_rgant_ViewModel[`@ViewModel`] and xref:rgant.adoc#_rgant_XmlRootElement[`@XmlRootElement`] view models should automatically support isCloneable.
+* link:https://issues.apache.org/jira/browse/ISIS-1299[ISIS-1299] - xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] and xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] view models should automatically support isCloneable.
* link:https://issues.apache.org/jira/browse/ISIS-1298[ISIS-1298] - Fix deprecated annotation use for ViewModel.Cloneable#clone
* link:https://issues.apache.org/jira/browse/ISIS-1295[ISIS-1295] - Run integration tests using thread-local, to allow "complete" tests that also exercise, eg Quartz jobs.
* link:https://issues.apache.org/jira/browse/ISIS-1240[ISIS-1240] - Derive icon from service when not provided
* link:https://issues.apache.org/jira/browse/ISIS-1239[ISIS-1239] - For wicket ui, use a cookie or similar to remember the hint from last time (xref:rgfun.adoc#_ugfun_object-layout_dynamic_xml[dynamic XML layouts])
-* link:https://issues.apache.org/jira/browse/ISIS-1228[ISIS-1228] - Reorganizing/splitting out xref:rgant.adoc#_rgant_DomainObjectContainer[`@DomainObjectContainer`] service.
+* link:https://issues.apache.org/jira/browse/ISIS-1228[ISIS-1228] - Reorganizing/splitting out xref:rgant.adoc#_rgant-DomainObjectContainer[`@DomainObjectContainer`] service.
* link:https://issues.apache.org/jira/browse/ISIS-1048[ISIS-1048] - Make view model URLs more secure, eg through a private key (xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]).
* link:https://issues.apache.org/jira/browse/ISIS-1037[ISIS-1037] - Support layout.xml as well as layout.json (xref:rgfun.adoc#_ugfun_object-layout_dynamic_xml[dynamic XML layouts])
* link:https://issues.apache.org/jira/browse/ISIS-806[ISIS-806] - In Wicket viewer, shouldn't be possible to invoke an action if editing a form.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
index 45db996..71960fb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_asciidoc-templates.adoc
@@ -141,9 +141,9 @@ a hyperlink to a bookmark within the reference guide for annotations, where:
for example:
-pass:[<pre>xref:rgant.adoc#_rgant_aaa_main[Core annotations\]</pre>]
+pass:[<pre>xref:rgant.adoc#_rgant-aaa_main[Core annotations\]</pre>]
-|xref:rgant.adoc#_rgant_aaa_main[Core annotations]
+|xref:rgant.adoc#_rgant-aaa_main[Core annotations]
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_named.adoc
index 586c205..f870e85 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_named.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant-ParameterLayout_named.adoc
@@ -10,7 +10,7 @@ The `named()` attribute explicitly specifies the action parameter's name. This a
Unlike most other aspects of the Apache Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code. Without other information, Apache Isis uses the object's type (`int`, `String` etc) as the name instead. This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
-The `named()` attribute (or the xref:rgant.adoc#_rgant_aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
+The `named()` attribute (or the xref:rgant.adoc#_rgant-aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
As of Java 8, the Java reflection API has been extended. The (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension provides support for this. Note that your application must (obviously) be running on Java 8, and be compiled with the `-parameters` compile flag for javac.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
index 3a52807..d294a24 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgant_aaa_deprecated.adoc
@@ -7,7 +7,7 @@
As Apache Isis has evolved and grown, we found ourselves adding more and more annotations; but most of these related to either an object type (entity, view model, service) or an object member (property, collection, action). Over time it became harder and harder for end programmers to discover these new features.
-Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:rgant.adoc#_rgant_aaa_main[above].
+Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:rgant.adoc#_rgant-aaa_main[above].
The annotations listed in the table below are still supported by Apache Isis, but will be retired in Apache Isis v2.0.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_layout.adoc
index bdc9af0..9e6c8dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_layout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_classes_layout.adoc
@@ -15,7 +15,7 @@ The `org.apache.isis.applib.layout` package defines a number of classes that all
The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:ugvw.adoc[Wicket viewer] components capable of rendering that grid system. In principle it is
also possible to extend the layout architecture for other grid systems. The component classes, though, are intended to be reusable across all grid systems.
-The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:rgant.adoc#_rgant_DomainObjectLayout[`@DomainObjectLayout`]
+The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`]
All of the classes in this package are JAXB-annotated, meaning that they can be serialized to/from XML (the `component` classes in the `http://isis.apache.org/applib/layout/component` XSD namespace, the bootstrap 3 grid classes in the `http://isis.apache.org/applib/layout/grid/bootstrap3` XSD namespace). This ability to serialize to/from XML is used by the xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`], the default implementation of which reads the grid layout for a domain class from a `.layout.xml` file on the classpath.
@@ -33,13 +33,13 @@ A fieldset (previously also called a property group or member group) of a number
* layout data classes, which correspond to the similarly named annotations:
-** `PropertyLayoutData`, corresponding to the xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] annotation;
+** `PropertyLayoutData`, corresponding to the xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] annotation;
-** `CollectionLayoutData`, corresponding to the xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`] annotation;
+** `CollectionLayoutData`, corresponding to the xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] annotation;
-** `ActionLayoutData`, corresponding to the xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] annotation;
+** `ActionLayoutData`, corresponding to the xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] annotation;
-** `DomainObjectLayoutData`, corresponding to the xref:rgant.adoc#_rgant_DomainObjectLayout[`@DomainObjectLayout`] annotation.
+** `DomainObjectLayoutData`, corresponding to the xref:rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] annotation.
In addition, the component package includes `Grid`, representing the top level container for a custom layout for a domain object. `Grid` itself is merely an interface, but it also defines the visitor pattern to make it easy for validate and normalize the grid layouts. The `GridAbstract` convenience superclass provides a partial implementation of this visitor pattern.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
index 29f9bb3..ad642a0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
@@ -5,8 +5,18 @@
:_imagesdir: images/
+
The "aim" schema defines the serialized form (or memento) of an action invocation.
+[WARNING]
+====
+This schema has been removed in `1.13.0-SNAPSHOT`, replaced with xref:rgcms.adoc#_rgcms_schema-ixn[ixn.xsd] (for action
+invocations/property edits) and with xref:rgcms.adoc#_rgcms_schema-cmd[cmd.xsd] (commands, ie the __intention__ to
+invoke an action/edit a property).
+
+The remaining content on this page describes how `CommandContext` works up to v1.12.x. However, as of `1.13.0-SNAPSHOT` the `CommandContext` uses its own `cmd.xsd` schema).
+====
+
Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc_api_CommandContext[CommandContext] service. Using the
`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
new file mode 100644
index 0000000..39528ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
@@ -0,0 +1,11 @@
+[[_rgcms_schema-chg]]
+= Changes (`1.13.0-SNAPSHOT`)
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The "chg" schema (`1.13.0-SNAPSHOT`) defines the serialized form identifying which objects have been created, updated
+or deleted as the result of invoking an action or editing a property.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
new file mode 100644
index 0000000..e0f5e75
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
@@ -0,0 +1,11 @@
+[[_rgcms_schema-cmd]]
+= Command (`1.13.0-SNAPSHOT`)
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The "cmd" schema (`1.13.0-SNAPSHOT`) defines the serialized form of the __intention__ to invoke an action or to
+edit a property.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
new file mode 100644
index 0000000..5a4ca36
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
@@ -0,0 +1,12 @@
+[[_rgcms_schema-ixn]]
+= Interaction Execution (`1.13.0-SNAPSHOT`)
+: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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The "ixn" schema (`1.13.0-SNAPSHOT`) defines the serialized form of an action invocation or a property edit. In fact,
+it actually defines a callgraph of such executions for those cases where the
+xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
index 65f2d1e..f3eef8c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
@@ -6,19 +6,32 @@
Most applications need to integrate with other apps in the enterprise. To facilitate such integration scenarios,
-Apache Isis defines two standard XSD schemas:
+Apache Isis defines a number of standard XSD schemas:
-* the xref:rgcms.adoc#_rgcms_schema-common[common schema], which defines the `oidDto` complex type: the object's type and its identifier. +
-+
-It also defines some two further XSD types, which are building blocks used in...
-* the xref:rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema, which allows action invocations to be captured
-and reified. +
-+
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module uses this XML format
-to publish messages onto an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
+* the xref:rgcms.adoc#_rgcms_schema-cmd[command] schema (`1.13.0-SNAPSHOT`), which captures the __intention__ of a user
+to invoke an action or edit a property
+
+* the xref:rgcms.adoc#_rgcms_schema-ixn[interaction execution] schema (`1.13.0-SNAPSHOT`), which captures the actual execution of an action invocation/property edit
+
+* the xref:rgcms.adoc#_rgcms_schema-chg[changes] schema (`1.13.0-SNAPSHOT`), which captures which objects have been
+created, updated or deleted as the result of an execution of an action invocation/property edit
+
+* the xref:rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema (deprecated in `1.13.0-SNAPSHOT`, replaced by
+either "cmd" or "ixn"), which allows action invocations to be captured and reified.
+
+These each use XSD types defined by the xref:rgcms.adoc#_rgcms_schema-common[common schema] (most notably the `oidDto`
+complex type which identifies a domain object).
+
+(As of `1.13.0-SNAPSHOT`) the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] and
+http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules uses these schemas to reify
+corresponding applib objects (`Command`, `Interaction.Execution` and `PublishedObjects`), either to persist or
+publishing using an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
The sections below discuss these schemas in more detail.
-include::_rgcms_schema-common.adoc[leveloffset=+1]
+include::_rgcms_schema-cmd.adoc[leveloffset=+1]
+include::_rgcms_schema-ixn.adoc[leveloffset=+1]
+include::_rgcms_schema-chg.adoc[leveloffset=+1]
include::_rgcms_schema-aim.adoc[leveloffset=+1]
+include::_rgcms_schema-common.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
index feb42d0..9e9a62c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
@@ -49,7 +49,7 @@ The diagram below illustrated this:
image::{_imagesdir}reference-services-api/acceptheaderservice.png[width="700px",link="{_imagesdir}reference-services-api/acceptheaderservice.png"]
-The REST request is submitted to a domain service with a xref:rgant.adoc#_rgant_DomainService_nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram). This uses the `AcceptHeaderService` to obtain the values of the
+The REST request is submitted to a domain service with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram). This uses the `AcceptHeaderService` to obtain the values of the
HTTP `Accept` header. Based on this it delegates to the appropriate underlying domain service (with a nature of
`DOMAIN` so that they are not exposed in the REST API at all).
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
index 0fced94..7065303 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_HomePageProviderService.adoc
@@ -7,7 +7,7 @@
This service simply provides access to the home page object (if any) that is returned from the domain service
-action annotated with xref:rgant.adoc#_rgant_HomePage[`@HomePage`].
+action annotated with xref:rgant.adoc#_rgant-HomePage[`@HomePage`].
It is originally introduced to support the default implementation of
xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`], but was factored out to support alternative implementations
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
index 7302290..df5a1bb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_LayoutService.adoc
@@ -48,9 +48,9 @@ XML, and how much (if any) will be obtained elsewhere, typically from annotation
|===
| Style
-|xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]
+|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
+| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
|`COMPLETE`
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
index 94366e6..985eff2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_SwaggerService.adoc
@@ -38,9 +38,9 @@ public interface SwaggerService {
}
----
<1> Generate a Swagger spec for use by third-party clients, ie public use. This specification is restricted only to
-xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:rgant.adoc#_rgant_DomainService_nature[nature] of `VIEW_REST_ONLY`.
+xref:ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
<2> Generate a Swagger spec for use only by internally-managed clients, ie private internal use. This specification includes domain entities and all menu domain services (as well as any view models).
-<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:rgant.adoc#_rgant_Action_restrictTo[prototype] actions.
+<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
<4> Swagger specs can be written either in JSON or YAML format.
Isis provides a default implementation of the service, `o.a.i.core.metamodel.services.swagger.SwaggerServiceDefault`.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
index e9840b1..726c417 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
@@ -12,34 +12,46 @@
The domain services also group into various broad categories. Many support functionality of the various layers of the
system (presentation layer, application layer, core domain, persistence layer); others exist to allow the domain objects
-to integrate with other bounded contexts, or provide various metadata (eg for development-time tooling). The diagram below shows these categories:
+to integrate with other bounded contexts, or provide various metadata (eg for development-time tooling). The diagram
+below shows these categories:
image::{_imagesdir}reference-services/categories.png[width="600px",link="{_imagesdir}reference-services/categories.png"]
A small number of domain services can be considered both API and SPI; a good example is the xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails,
-but is also used by the framework to support the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality supported by the xref:ugvw.adoc#[Wicket viewer]. The same is true of the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events for xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] etc.
+but is also used by the framework to support the xref:ugvw.adoc#_ugvw_features_user-registration[user registration]
+functionality supported by the xref:ugvw.adoc#[Wicket viewer]. The same is true of the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events,
+but is also used by the framework to automatically emit events for
+xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] etc.
-For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
+For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only
+the strictly SPI services.
-This rest of this guide is broken out into several chapters, one for each of the various types/categories of domain service.
+This rest of this guide is broken out into several chapters, one for each of the various types/categories of domain
+service.
[[_rgsvc_intro_public-api]]
-== Public API
+== Public API vs Internal Services
The vast majority of Apache Isis' domain services are defined in Apache Isis' applib (`o.a.i.core:isis-core-applib`
module) as stable, public classes. Importantly, this also minimizes the coupling between your code and Apache Isis,
allowing you to easily mock out these services in your unit tests.
+The framework also defines a number of "internal" services. These are not part of the framework's formal API, in that
+they use classes that are outside of the applib. These are documented here, but should be thought of as part of the
+internal design of the framework, and are liable to change from release to release.
+
+
[[_rgsvc_intro_using-the-services]]
== Using the services
-Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service as an annotated field and Apache Isis will inject the service into your object.
+Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service
+as an annotated field and Apache Isis will inject the service into your object.
For example:
@@ -79,17 +91,23 @@ xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s ``in
[[_rgsvc_intro_overriding-the-services]]
== Overriding the services
-The framework provides default implementations for many of the domain services. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
+The framework provides default implementations for many of the domain services. This is convenient, but sometimes you
+will want to replace the default implementation with your own service implementation.
-The trick is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
+The trick is to use the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+attribute, specifying a low number (typically `"1"`).
[NOTE]
====
-For a small number of domain services, all implementations are used (following the chain-of-responsibility pattern), not just the first one. The services in question are: xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`], xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], and
+For a small number of domain services, all implementations are used (following the chain-of-responsibility pattern),
+not just the first one. The services in question are:
+xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`],
+xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], and
xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`].
====
-For example, suppose you wanted to provide your own implementation of xref:rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`]. Here's how:
+For example, suppose you wanted to provide your own implementation of
+xref:rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`]. Here's how:
[source,java]
----
@@ -109,7 +127,9 @@ public class MyLocaleProvider implements LocaleProvider {
<1> takes precedence over the default implementation.
-It's also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the default); this is also possible and quite easy (if using `1.10.0` or later). The idea is to have the framework inject all implementations of the service, and then to delegate to the first one that isn't "this" one:
+It's also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the
+default); this is also possible and quite easy (if using `1.10.0` or later). The idea is to have the framework
+inject all implementations of the service, and then to delegate to the first one that isn't "this" one:
[source,java]
----
@@ -137,3 +157,87 @@ public class MyLocaleProvider implements LocaleProvider {
The above code could be improved by caching the delegateLocaleProvider once located (rather than searching each time).
+
+[[_rgsvc_intro_commands-and-events]]
+== Command and Events (`1.13.0-SNAPSHOT`)
+
+A good number of the domain services manage the execution of action invocations/property edits, along with the state
+of domain objects that are modified as a result of these. These services capture information which can then be used
+for various purposes, most notably for auditing or for publishing events, or for deferring execution such that the
+execution be performed in the background at some later date.
+
+The diagram below shows how these services fit together. The outline boxes are services while the coloured boxes
+represent data structures - defined in the applib and therefore accessible to domain applications - which hold various
+information about the executions.
+
+image::{_imagesdir}reference-services/commands-and-events.png[width="960px",link="{_imagesdir}reference-services/commands-and-events.png"]
+
+
+To explain:
+
+* the (request-scoped) xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] captures the user's intention to
+invoke an action or edit a property; this is held by the `Command` object.
+
+* if a xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] has been configured, then this will be used to
+create the `Command` object implementation, generally so that it can then also be persisted. +
++
+If the action or property is annotated to be invoked in the background (using
+xref:rgant.adoc#_rgant-Action_command[`@Action#command...()`] or
+xref:rgant.adoc#_rgant-Property_command[`@Property#command...()`]) then no further work is done. But,
+if the action/property is to be executed in the foreground, then the interaction continues.
+
+* the (request-scoped) xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service acts as a
+factory for the ``Interaction`` object, which keeps track of the call-graph of executions (``Interaction.Execution``)
+of either action invocations or property edits. In the majority of cases there is likely to be just a single top-level
+node of this graph, but for applications that use the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
+extensively each successive call results in a new child execution.
+
+* before and after each action invocation/property edit, a xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] is
+may be broadcast to all subscribers. Whether this occurs depends on whether the action/property has been annotated
+(using xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`] or
+xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]). +
++
+(Note that susbcribers will also receive events for vetoing the action/property; this is not shown on the diagram).
+
+* As each execution progresses, and objects that are modified are "enlisted" into the (internal)
+xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service. Metrics as
+to which objects are merely loaded into memory are also captured using the
+xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] (not shown on the diagram).
+
+* At the end of each execution, details of that execution are published through the (internal)
+xref:rgsvc.adoc#_rgsvc_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service. This is only done for
+actions/properties annotated appropriate (with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] or
+xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]). +
++
+The internal service delegates in turn to any registered
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (deprecated) and also to any
+registered xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]s (there may be more than one).
+
+* At the end of all executions, details of all changed objects are published, again through the (internal)
+xref:rgsvc.adoc#_rgsvc_spi_PublisherServiceInternal[`PublisherServiceInternal`] to any registered `PublishingService`
+or `PublisherService` implementations. Only domain objects specified to be published with
+xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] are published.
+
+* Also at the end of all executions, details of all changed properties are passed to any registered
+xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] by way of the (internal)
+xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] domain service.
+
+Implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can use the `Command#getMemento()`
+method to obtain a XML equivalent of that `Command`, reified using the xref:rgcms.adoc#_rgcms_schema-cmd[`cmd.xsd`]
+schema. This can be converted back into a `CommandDto` using the `CommandDtoUtils` utility class (part of the applib).
+
+Similarly, implementations of xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] can use the
+`InteractionDtoUtils` utility class to obtain a `InteractionDto` representing the interaction, either just for a single
+execution or for the entire call-graph. This can be converted into XML in a similar fashion.
+
+Likewise, the `PublishedObjects` class passed to the `PublisherService` at the end of the interaction provides the
+`PublishedObjects#getDto()` method which returns a `ChangesDto` instance. This can be converted into XML using the
+`ChangesDtoUtils` utility class.
+
+One final point: multiple xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] implementations are supported
+because different implementations may have different responsibilities. For example, the (non-ASF)
+http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module is responsible for publishing
+messages onto an ActiveMQ event bus, for inter-system communication. However, the SPI can also be used for profiling;
+each execution within the call-graph contains metrics of the number of objects loaded or modified as a result of that
+execution, and thus could be used for application profiling. The framework provides a default
+`PublisherServiceLogging` implementation that logs this using SLF4J.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc
index 3c0aba6..b187808 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc
@@ -19,7 +19,7 @@ See xref:rgsvc.adoc#_rgsvc_spi_ContentNegotiationService[`ContentNegotiationServ
Unlike most other domain services, the framework (that is, `ContentNegotiationService`) will check _all_ available
implementations of `ContentMappingService` to convert the domain object to the requested media type, rather than merely
the first implementation found; in other words it uses the chain-of-responsibility pattern. Services are checked
-in the ordering defined by xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+in the ordering defined by xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
The mapped object used will be the first non-`null` result returned by an implementation.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
index 8df4b5e..91ff854 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
@@ -38,9 +38,9 @@ public interface GridService {
<3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class. Just delegates to corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`].
<4> returns a new instance of a xref:rgcms.adoc#_rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file. If none exists, will return null (and the calling xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
<5> returns a default grid, eg two columns in ratio 4:8. Used when no existing grid layout exists for a domain class.
-<6> validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<7> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<8> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
+<6> validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
+<7> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
+<8> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
The first four methods just delegate to the corresponding methods in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], while the last four delegate to the corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]. The service inspects the ``Grid``'s concrete class to determine which actual `GridSystemService` instance to delegate to.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
index 3fa29b3..7538d8f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
@@ -18,7 +18,7 @@ The framework provides a single such grid implementation, namely for Bootstrap3.
Unlike most other domain services, the framework will check _all_ available implementations of `GridSystemService` to
obtain available grid systems, rather than merely the first implementation found; in other words it uses the
chain-of-responsibility pattern. Services are called in the order defined by
-xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
Note though that each concrete implementation must also provide corresponding Wicket viewer components capable of
interpreting the grid layout.
@@ -42,14 +42,14 @@ public interface GridSystemService<G extends Grid> {
}
----
<1> The concrete subclass of `Grid` supported by this implementation. As noted in the introduction, there can be multiple implementations of this service, but there can only be one implementation per concrete subclass. As is normal practice,
-the service with the lowest xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] takes precedence.
+the service with the lowest xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] takes precedence.
<2> the target namespace for this grid system. This is used when generating the XML. The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3`.
<3> the schema location for the XSD. The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3/bootstrap3.xsd`.
<4> a default grid, eg two columns in ratio 4:8. Used when no existing grid layout exists for a domain class.
-<5> Validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the
+<5> Validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the
`@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<6> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<7> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
+<6> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
+<7> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
== Implementation
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
index 10ca7d8..d5b1ad8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
@@ -6,7 +6,13 @@
-The `PublishingService2` API (the `PublishingService2` subinterface has been added in `1.13.0-SNAPSHOT`) is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations and of changed objects. A typical use case is to publish onto a pub/sub bus such as link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Camel] to keep other systems up to date.
+The `PublishingService` API is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations and of changed objects. A typical use case is to publish onto a pub/sub bus such as link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Camel] to keep other systems up to date.
+
+
+[WARNING]
+====
+This service is deprecated, replaced with xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] (`1.13.0-SNAPSHOT`).
+====
@@ -16,20 +22,17 @@ The SPI defined by the service is:
[source,java]
----
-public interface PublishingService2 {
+@Deprecated
+public interface PublishingService {
public void publish(
EventMetadata metadata, // <1>
EventPayload payload); // <2>
- public void republish(Command); // <3>
- @Deprecated
- void setEventSerializer(EventSerializer eventSerializer); // <4>
+ void setEventSerializer(EventSerializer eventSerializer); // <3>
}
----
<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`], date/time etc
<2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
-<3> (`1.13.0-SNAPSHOT`) allow a `Command` representing an action to be republished by the application (eg if an error occurred). Note that this relies upon the `Command#getMemento()` to
-return serialized xref:rgcms.adoc#_rgcms_schema-aim[action invocation memento].
-<4> injects in the xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] service. This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
+<3> injects in the xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] service. This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
@@ -47,36 +50,19 @@ The serialized form returned by `EventSerializer` must be in a form that the `Pu
== Implementation
-The framework provides no default implementations of this service. There are however two implementations available in
-the (non-ASF) link:http://isisaddons.org[Isis Addons].
-
-=== isis-module-publishing
-
The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an
implementation (`org.isisaddons.module.publishing.dom.PublishingService`) that persists each
event as a `PublishedEvent` entity. This holds the serialized form of the event metadata and payload as translated
into a string by the injected `EventSerializer`. The module also provides its own implementation of `EventSerializer`,
-namely `RestfulObjectsSpecEventSerializer`, which represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional
+namely `RestfulObjectsSpecEventSerializer`, which represents the event payload using the representation defined by the
+link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional
JSON nodes.
The `PublishedEvent` entity also has a `state` field taking the values either "QUEUED" or "PROCESSED". The intention
here is that an event bus can poll this table to grab pending events and dispatch them to downstream systems. When
``PublishedEvent``s are persisted initially they always take the value "QUEUED".
-=== isis-module-publishmq
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an
-implementation (`org.isisaddons.module.publismq.dom.servicespi.PublishingServiceUsingActiveMq`) that publishes each
-action invocation as an event on an link:http://activemq.apache.org[ActiveMQ] message queue. These are converted into
-a canonical XML form (the xref:rgcms.adoc#_rgcms_schema-aim[ActionInvocationMemento] schema) using the
-`ActionInvocationMementoDtoUtils` class; the idea
-being that subscribers on the ActiveMQ message queue can then query back for further information, for example using
-the xref:ugvro.adoc#[RestfulObjects viewer].
-
-[NOTE]
-====
-At the time of writing this implementation does not publish changed object events.
-====
+The framework provides no default implementations of this service.
@@ -89,7 +75,14 @@ To indicate that a changed object should be published is to annotate it with the
It is also possible to "fine-tune" the `EventPayload` using the `#publishingFactory()` attribute (for both annotations). By default the `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the action invocation provides details of the action arguments and result (if any) of that action. However, the payload does not (by default) include any information about the new state of these objects. It is therefore the responsibility of the subscriber to call back to Apache Isis to determine any information that has not been published.
-Although the representations (if using the Restful Object serializer and Restful Objects viewer) does include hrefs for the objects, this nevertheless requires an additional network call to obtain this information).
+[NOTE]
+====
+The replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] does __not__ support the concept of "payload factories" (but is otherwise more flexible).
+====
+
+
+Although the representations (if using the Restful Object serializer and Restful Objects viewer) does include hrefs
+for the objects, this nevertheless requires an additional network call to obtain this information).
In some circumstances, then, it may make more sense to eagerly "push" information about the change to the subscriber by including that state within the payload.
@@ -99,8 +92,8 @@ For actions, we implement the `PublishingPayloadFactoryForAction` (in `o.a.i.app
[source,java]
----
+@Deprecated
public interface PublishingPayloadFactoryForAction {
- @Programmatic
public EventPayload payloadFor(
Identifier actionIdentifier,
Object target,
@@ -115,9 +108,8 @@ For objects, the interface to implement is `PublishingPayloadFactoryForObject`:
[source,java]
----
+@Deprecated
public interface PublishingPayloadFactoryForObject {
-
- @Programmatic
public EventPayload payloadFor(
Object changedObject,
PublishingChangeKind publishingChangeKind); // <1>
@@ -161,10 +153,10 @@ public class ToDoItemChangedPayloadFactory implements PublishingPayloadFactoryFo
There is no default implementation of this service provided by the core Apache Isis framework.
-Both the (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishing[publishing] module and the
-http://github.com/isisaddons/isis-module-publishmq[publishmq] module provide implementations of this service.
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
-then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
+The (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishing[publishing] module provides an
+implementation of this service. Assuming that an `AppManifest` is being used to
+xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then this can be activated by updating
+the `pom.xml` and updating the `AppManifest#getModules()` method.
The modules also provide services that contribute to the UI. If contributions are not required in the UI, these can be
suppressed either using security or by implementing a
@@ -176,13 +168,31 @@ xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
== Related Services
-The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`].
-
-The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
-
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
-
-
+The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from
+Apache Isis to some other system. Here the only events published are those that action invocations (for actions
+annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects
+annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`].
+
+The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] is intended as a replacement for this service. The
+use case for `PublisherService` is the same: coarse-grained publishing of events for system-to-system interactions. It
+is in most respects more flexible though: events are published both for action invocations (annotated with
+xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and also for property edits (annotated with
+xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]. It also publishes changed objects (for objects
+annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]). However, rather than
+publishing one event for every changed objects, it publishes a single event that identifies all objects created,
+updated or deleted.
+
+Another significant difference between `PublishingService` and `PublisherService` is in the content of the events
+themselves. While the former uses the xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] to create an
+ad-hoc serialization of the action being invoked, the latter uses the xref:rgcms.adoc#_rgcms_schema[DTOs/XML schemas]
+as a formal specification of the nature of the interaction (action invocation, property edit or changed objects).
+
+The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] meanwhile differs from both `PublishingService` and
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] in that it is intended for fine-grained
+publish/subscribe for object-to-object interactions within an Apache Isis domain object model. The event propagation
+is strictly in-memory, and there are no restrictions on the object acting as the event; it need not be serializable,
+for example. (That said, it is possible to obtain a serialization of the action invocation/property edit causing the
+current event to be raised using xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service).
== Design Notes
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
index 3f7e8fc..452d9a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
@@ -18,7 +18,7 @@ of the implementation to figure out what the "owning" object might be.
* if an action returns `null` or is `void`, then return some other "useful" object. +
+
-For example, return the home page (eg as defined by the xref:rgant.adoc#_rgant_HomePage[`@HomePage`] annotation).
+For example, return the home page (eg as defined by the xref:rgant.adoc#_rgant-HomePage[`@HomePage`] annotation).
Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]; it is ignored by the xref:ugvro.adoc#[Restful Objects] viewer.
@@ -28,7 +28,7 @@ Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]
Unlike most other domain services, the framework will check _all_ available implementations of
`RoutingService` to return a route, rather than the first implementation found; in other words it uses the
chain-of-responsibility pattern. Services are called in the order defined by
-xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]). The route used will be the
+xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]). The route used will be the
result of the first implementation checked that declares that it can provide a route.
====
@@ -58,7 +58,7 @@ The framework provides a default implementation which will always return the ori
if a `null` or `void` was provided. It uses the xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
There can be multiple implementations of `RoutingService` registered. These are checked in turn (chain of responsibility
-pattern), ordered according to xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+pattern), ordered according to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
(as explained in the xref:rgsvc.adoc#_rgsvc_intro_overriding-the-services[introduction] to this guide).
The route from the first service that returns `true` from its `canRoute(...)` method will be used.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
index d24faff..a717fcc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_i18n.adoc
@@ -541,7 +541,7 @@ msgstr "<i>Quantit�</i>"
For this to work, the `namedEscaped()` attribute must be specified using either the
xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layout] json file, or using an annotation such as
-xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] or xref:rgant.adoc#_rgant_ParameterLayout[`@ParameterLayout`].
+xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
index 9f2bbd3..5c70835 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_programming-model_custom-validator.adoc
@@ -10,7 +10,7 @@ For example, the validator will detect any orphaned supporting methods (eg `hide
[NOTE]
====
-The support for xref:rgant.adoc#_rgant_aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
+The support for xref:rgant.adoc#_rgant-aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
====
You can also impose your own application-specific rules by installing your own metamodel validator. To give just one example, you could impose naming standards such as ensuring that a domain-specific abbreviation such as "ISBN" is always consistently capitalized wherever it appears in a class member.
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
index 692e6f2..23889c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
@@ -16,8 +16,8 @@ most powerful of all the various ways of writing view models:
* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
+
-In contrast, using xref:rgant.adoc#_rgant_ViewModel[`@ViewModel`] (or its
-xref:rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of
+In contrast, using xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its
+xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of
properties, but not collections. And if using the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`]
interface, then the programmer must write all the state management (lots of boilerplate).
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
index 885f22b..8a749c5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
@@ -21,7 +21,7 @@ page "no results". When clicking the back button in the browser the user sees
null response or invoking a void action. But how to implement this?_
One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service. The default implementation will either return
-the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant_HomePage[`@HomePage`]) if
+the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if
one exists.
The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
index 8c2599a..afa113f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
@@ -15,9 +15,9 @@ One way to implement is to use the xref:rgsvc.adoc#_rgsvc_api_EventBusService[ev
* Set up a xref:rgcsm.adoc#_rgcsm_classes_domainevent[domain event] xref:rgcsm.adoc#_rgcsm_classes_super_AbstractSubscriber[subscriber] that can veto the changes.
-* if the change is made through an action, you can use xref:rgant.adoc#_rgant_Action_domainEvent[`@Action#domainEvent()`].
+* if the change is made through an action, you can use xref:rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`].
-if if the change is made through an edit, you can use xref:rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`].
+if if the change is made through an edit, you can use xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`].
You'll need some way to know which fields should be spell checked. Two ways spring to mind:
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
index a63d821..e14a286 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_dynamic_xml.adoc
@@ -326,9 +326,9 @@ below summarises the choices:
|===
| Style
-|xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`]
-| xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`]
-| xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]
+|xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]
+| xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]
+| xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]
|`COMPLETE`
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
index c62755d..6bd895d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugfun_object-layout_static.adoc
@@ -18,9 +18,9 @@ Tabs and tabgroups are only supported using xref:ugfun.adoc#_ugfun_object-layout
== `@MemberOrder`
-The xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation is used to specify the relative order of domain class properties, collections and actions.
+The xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is used to specify the relative order of domain class properties, collections and actions.
-The annotation defines two attributes, xref:rgant.adoc#_rgant_MemberOrder_name[`name()`] and xref:rgant.adoc#_rgant_MemberOrder_sequence[`sequence()`]. Their usage depends on the member type:
+The annotation defines two attributes, xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] and xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`]. Their usage depends on the member type:
* for properties, the `name()` is used to group properties together into a member group (also called a property group
or a fieldset. The `sequence()` then orders properties within these groups. If no `name()` is specified then the
@@ -67,7 +67,7 @@ public class ToDoItem {
This defines three property (or member) groups, "General", "Detail" and "Misc"; "General" is the default if no `name` attribute is specified. Properties in the same member group are rendered together, as a fieldset.
-In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:rgant.adoc#_rgant_MemberOrder_name[`name()`] attribute, holding the value of the property or collection.
+In addition, actions can optionally be associated (rendered close to) either properties or actions. This is done by overloading the ``@MemberOrder``'s xref:rgant.adoc#_rgant-MemberOrder_name[`name()`] attribute, holding the value of the property or collection.
For example:
@@ -94,7 +94,7 @@ public class ToDoItem {
will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
-The value of xref:rgant.adoc#_rgant_MemberOrder_sequence[`sequence()`] is a string. The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.
+The value of xref:rgant.adoc#_rgant-MemberOrder_sequence[`sequence()`] is a string. The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.
Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion. It also allows subclasses to insert their class members as required.
@@ -103,7 +103,7 @@ Even better is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1
== `@MemberGroupLayout`
-The xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column. The annotation also specifies the relative width of the columns.
+The xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation specifies the relative positioning of property groups/fieldsets as being either in a left column, a middle column or in a right column. The annotation also specifies the relative width of the columns.
The property groups/fieldsets in this case are those that are inferred from the `@MemberOrder#name()` attribute.
@@ -111,7 +111,7 @@ The property groups/fieldsets in this case are those that are inferred from the
====
It is also possible to combine `@MemberOrder` with dynamic layouts, either using xref:ugfun.adoc#_ugfun_object-layout_xml[XML] or xref:ugfun.adoc#_ugfun_object-layout_dynamic[JSON]. The layout file defines only the regions of a grid structure (fieldsets/columns etc), but does __not__ specify the properties/collections/actions within those grid regions. The `@MemberOrder` annotation in effect "binds" the properties or collections to those regions of the grid.
-When dynamic layouts are used this way, the xref:rgant.adoc#_rgant_MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:rgant.adoc#_rgant_ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant_PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant_CollectionLayout[`@CollectionLayout`]) are all still honoured.
+When dynamic layouts are used this way, the xref:rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`] annotation is essentially ignored, but the metadata from the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation (and the other layout annotations, xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) are all still honoured.
====
For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.png
new file mode 100644
index 0000000..733b577
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/7ebbb70c/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.pptx b/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.pptx
new file mode 100644
index 0000000..c454636
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services/commands-and-events.pptx differ