You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2018/01/24 15:16:55 UTC
[isis] 19/20: ISIS-1569: updates docs for CommandService and cmd
schema
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-1569-replay-commands
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 150894bff4adafd9915153423e352a849a7e1268
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Jan 24 10:35:24 2018 +0000
ISIS-1569: updates docs for CommandService and cmd schema
---
.../asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc | 53 ++++++++++++++--------
...rgsvc_application-layer-spi_CommandService.adoc | 39 ++++++++--------
2 files changed, 54 insertions(+), 38 deletions(-)
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
index 33ec4e8..a0597b3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-cmd.adoc
@@ -5,14 +5,15 @@
:_imagesdir: images/
-
The command ("cmd") schema defines the serialized form of the __intention__ to invoke an action or to
edit a property.
+It can be supplemented with optional timings capturing the actual invocation of a command (introduced to support the replication of commands in a master/slave arrangement).
+
[NOTE]
====
-Mixin actions are represented as regular actions on the mixed-in object. In other words, the fact that the actual
-implementation of the action is defined by a mixin is an implementation detail only.
+Mixin actions are represented as regular actions on the mixed-in object.
+In other words, the fact that the actual implementation of the action is defined by a mixin is an implementation detail only.
====
[[__rgcms_schema-cmd_commandDto]]
@@ -43,35 +44,51 @@ The `commandDto` root element is defined as:
<xs:element name="user" type="xs:string"/> <!--6-->
<xs:element name="targets" type="com:oidsDto"/> <!--7-->
<xs:element name="member" type="memberDto"/> <!--8-->
+ <xs:element name="timings" type="memberDto" minOccurs="0"/> <!--9-->
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+
+ <xs:element name="commandsDto"> <!--10-->
+ <xs:annotation>
+ <xs:documentation>Collection of commandDto's</xs:documentation>
+ </xs:annotation>
+ <xs:complexType>
+ <xs:sequence minOccurs="1" maxOccurs="unbounded">
+ <xs:element ref="commandDto"/>
</xs:sequence>
</xs:complexType>
</xs:element>
+
...
</xs:schema>
----
-<1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
+<1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
<2> uses complex types defined in the xref:../rgcms/rgcms.adoc#_rgcms_schema_common["common" schema].
-<3> definition of the `commandDto` root element. The corresponding XML will use this as its top-level element.
+<3> definition of the `commandDto` root element.
+The corresponding XML will use this as its top-level element.
<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
-<5> unique identifier for the transaction in which this command is created. The transaction Id is used to correlate
-to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
+<5> unique identifier for the transaction in which this command is created.
+The transaction Id is used to correlate to the xref:../rgcms/rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
xref:../rgcms/rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
<6> the name of the user who created the command (whose intention it is to invoke the action/edit the property).
<7> the target object (or objects) to be invoked.
A bulk action will create multiple commands, each with only a single target.
(A future version of the framework may also support a single bulk command against this multiple targets, ie all-or-nothing).
<8> the `memberDto`, defined below, the captures the action/property and arguments/new value.
+<9> optional timings for the invocation of a command.
+<10> groups multiple commands together.
-The `CommandDto` DTO corresponding to the `commandDto` root element can be marshalled to/from XML using the
-`CommandDtoUtils` class.
+The `CommandDto` DTO corresponding to the `commandDto` root element can be marshalled to/from XML using the `CommandDtoUtils` class.
+The `CommandsDto` DTO allows multiple commands to be marshalled together.
+This was introduced to support replication of commands in a master/slave arrangement (eg for regression testing).
[[__rgcms_schema-cmd_memberDto]]
== `memberDto` and subtypes
-The `memberDto` complex type is an abstract type representing the intention to either invoke an action or to edit a
-property. The `actionDto` and `propertyDto` are the concrete subtypes:
+The `memberDto` complex type is an abstract type representing the intention to either invoke an action or to edit a property.
+The `actionDto` and `propertyDto` are the concrete subtypes:
[source,xml]
@@ -108,13 +125,13 @@ property. The `actionDto` and `propertyDto` are the concrete subtypes:
</xs:complexType>
</xs:schema>
----
-<1> the `memberDto` is an abstract type. Its primary responsibility is simply to identify the member (action or
-property).
+<1> the `memberDto` is an abstract type.
+Its primary responsibility is simply to identify the member (action or property).
<2> the formal identifier (fully qualified class name + member name) of the member being interacted with (action or property).
<3> the "logical" formal identifier (object type, as per `@DomainObject(objectType=)`, + member name) of the member being interacted with (action or property).
<4> the `interactionType` attribute indicates whether the member is an action or a property.
-<5> the `actionDto` complex type captures the set of parameters (also including the argument values) with which to
-invoke the action. The `paramsDto` type is defined xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_ancillary[below].
+<5> the `actionDto` complex type captures the set of parameters (also including the argument values) with which to invoke the action.
+The `paramsDto` type is defined xref:../rgcms/rgcms.adoc#__rgcms_schema-cmd_ancillary[below].
<6> the `propertyDto` complex type captures the new value (possibly `null`) to set the property to.
In general the `logicalMemberIdentifier` should be used in preference to the `memberIdentifier` because will not (necessarily) have to change if the class is moved during a refactoring.
@@ -149,6 +166,6 @@ The schema also defines a small number of supporting types:
</xs:schema>
----
<1> the `paramsDto` is simply the list of parameter/arguments.
-<2> the `paramDto` complex type essentially combines a parameter with its corresponding argument: a named value that
-has a type. It extends the `valueWithTypeDto` complex type taken from the
+<2> the `paramDto` complex type essentially combines a parameter with its corresponding argument: a named value that has a type.
+It extends the `valueWithTypeDto` complex type taken from the
xref:../rgcms/rgcms.adoc#_rgcms_schema-common["common"] schema.
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
index 9b541bf..ce1e550 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-spi_CommandService.adoc
@@ -6,32 +6,29 @@
-The `CommandService` service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service such
-that `Command` objects (that reify the invocation of an action/edit of a property on a domain object) can be persisted.
+The `CommandService` service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service such that `Command` objects (that reify the invocation of an action/edit of a property on a domain object) can be persisted.
The primary use case for persistent ``Command``s is in support of background commands; they act as a parent to any background commands that can be persisted either explicitly using the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`], or implicitly by way of the xref:../rgant/rgant.adoc#_rgant-Action_command[`@Action#command()`] annotation.
+Persistent ``Command``s also support the ability to replicate from a master to a slave instance of an application.
+One use case for this is for regression testing, allowing a production usages to be replayed against a new release candidate, eg after upgrading that application to a new version of Apache Isis itself (or some other dependency).
+
There are a number of related use cases:
* they enable profiling of the running application (which actions are invoked then most often, what is their response time)
* if xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublisherService[`PublisherService`] or
-xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`] (latter deprecated) is configured, they provide
-better traceability as the `Command` is also correlated with any published events, again through the unique
-`transactionId` GUID
+xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`] (latter deprecated) is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
* if xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuderService[`AuditerService`] or
-xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (latter deprecated) is configured, they provide better audit
-information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of
-the action) through the `transactionId` GUID
+xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditService[`AuditingService`] (latter deprecated) is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the `transactionId` GUID
-However, while persistent ``Command``s _can_ be used for these use cases, it is recommended instead to use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_InteractionContext[`InteractionContext`] service and persistent implementations of the
-``Interaction`` object, eg as provided by the (non-ASF) link:http://platform.incode.org[Incode Platform^]'s publishmq module.
+However, while persistent ``Command``s _can_ be used for these use cases, it is recommended instead to use the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_InteractionContext[`InteractionContext`] service and persistent implementations of the ``Interaction`` object, eg as provided by the (non-ASF) link:http://platform.incode.org[Incode Platform^]'s publishmq module.
== Screencast
-The link:https://www.youtube.com/watch?v=tqXUZkPB3EI[screencast] below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
+The link:https://www.youtube.com/watch?v=tqXUZkPB3EI[screencast] below provides a run-through of the command (profiling) service, auditing service, publishing service.
+It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
[NOTE]
@@ -56,21 +53,22 @@ public interface CommandService {
}
----
<1> Instantiate the appropriate instance of the `Command` (as defined by the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service). Its members will be populated automatically by
-the framework.
+xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`] service).
+Its members will be populated automatically by the framework.
<2> Deprecated and *IS NOT CALLED* by the framework.
The framework automatically populates the ``Command``'s `timestamp`, `user` and `transactionId` fields, so there is no need for the service implementation to initialize any of these.
In particular, the ``Command`` will already have been initialized with the provided `transactionId` argument.
<3> Set the hint that the `Command` should be persisted if possible (when completed, see below).
-<4> "Complete" the command, typically meaning that the command should be persisted it if its `Command#getPersistence()`
-flag and persistence hint (`Command#isPersistHint()`) indicate that it should be. +
+<4> "Complete" the command, typically meaning that the command should be persisted it if its `Command#getPersistence()` flag and persistence hint (`Command#isPersistHint()`) indicate that it should be. +
+
The framework will automatically have set the `completedAt` property of the `Command`.
+
== Implementation
-The (non-ASF) link:http://platform.incode.org[Incode Platform^]'s command module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
+The (non-ASF) link:http://platform.incode.org[Incode Platform^]'s command module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store.
+It further provides a number of supporting services:
* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted ``Command``s
@@ -97,12 +95,13 @@ If contributions are not required in the UI, these can be suppressed either usin
== Related Services
-As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be
-persisted. This is closely related to the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
+As discussed above, this service supports the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be persisted.
+This is closely related to the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
-The services provided by this module combines very well with the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditingService[`AuditingService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
+The services provided by this module combines very well with the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditingService[`AuditingService`].
+The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
You may also want to configure the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_PublishingService[`PublishingService`].
--
To stop receiving notification emails like this one, please contact
danhaywood@apache.org.