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/15 16:03:38 UTC
isis git commit: ISIS-1291: updating docs for new services. Also
IsisTransaction now to clears the changed object properties rather than
AuditingService,
otherwise PublisherService would mis-report the metric of number of changed
object properties.
Repository: isis
Updated Branches:
refs/heads/master 55d3029a6 -> e74c7a9ab
ISIS-1291: updating docs for new services. Also IsisTransaction now to clears the changed object properties rather than AuditingService, otherwise PublisherService would mis-report the metric of number of changed object properties.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/e74c7a9a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/e74c7a9a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/e74c7a9a
Branch: refs/heads/master
Commit: e74c7a9abd5380af93802cfaeb70ab41a4ee1f6d
Parents: 55d3029
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun May 15 16:44:59 2016 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun May 15 16:44:59 2016 +0100
----------------------------------------------------------------------
.../guides/_rgsvc_api_BackgroundService.adoc | 2 +-
...roundService_BackgroundCommandExecution.adoc | 2 +-
.../guides/_rgsvc_api_CommandContext.adoc | 31 +++-
.../guides/_rgsvc_api_InteractionContext.adoc | 178 ++++++++++++++++++-
.../guides/_rgsvc_api_MetamodelService.adoc | 2 +-
.../guides/_rgsvc_api_MetricsService.adoc | 40 ++++-
.../guides/_rgsvc_application-layer-api.adoc | 3 +-
.../_rgsvc_application-layer-internal-spi.adoc | 18 +-
.../guides/_rgsvc_application-layer-spi.adoc | 2 +
.../guides/_rgsvc_bootstrapping-spi.adoc | 7 +
.../asciidoc/guides/_rgsvc_core-domain-api.adoc | 7 +
.../asciidoc/guides/_rgsvc_integration-api.adoc | 9 +
.../asciidoc/guides/_rgsvc_metadata-api.adoc | 8 +
.../guides/_rgsvc_persistence-layer-api.adoc | 5 +
.../_rgsvc_persistence-layer-internal-spi.adoc | 2 +
.../guides/_rgsvc_persistence-layer-spi.adoc | 2 +
.../_rgsvc_presentation-layer-internal-spi.adoc | 4 +
.../guides/_rgsvc_presentation-layer-spi.adoc | 2 +
.../_rgsvc_spi_AuditingServiceInternal.adoc | 39 +++-
...rgsvc_spi_ChangedObjectsServiceInternal.adoc | 62 ++++++-
.../_rgsvc_spi_CommandDtoServiceInternal.adoc | 11 +-
...rgsvc_spi_InteractionDtoServiceInternal.adoc | 35 +++-
.../guides/_rgsvc_spi_PublisherService.adoc | 11 +-
.../_rgsvc_spi_PublishingServiceInternal.adoc | 70 +++++++-
.../isis/applib/services/iactn/Interaction.java | 50 ++++--
.../ixn/InteractionDtoServiceInternal.java | 12 +-
.../auditing/AuditingServiceInternal.java | 20 +--
.../system/transaction/IsisTransaction.java | 2 +
28 files changed, 572 insertions(+), 64 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
index ad79859..694664f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
@@ -8,7 +8,7 @@
The `BackgroundService2` domain service, and also the companion
xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService2`] SPI service, enable commands
to be persisted such that they may be invoked in the background. (The `BackgroundService2` and
-`BackgroundCommandService2` extensions to these services introduced in `1.13.0-SNAPSHOT`).
+`BackgroundCommandService2` extensions to these services have been introduced in `1.13.0-SNAPSHOT`).
The `BackgroundService2` is responsible for capturing a memento representing the command in a typesafe way,
and persisting it rather than executing it directly.
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
index 3acf433..fede5f0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService_BackgroundCommandExecution.adoc
@@ -1,5 +1,5 @@
[[_rgsvc_api_BackgroundService_BackgroundCommandExecution]]
-= `BackgroundCommandExecution` abstract class
+= `BackgroundCommandExec'n` abstract class
: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/
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_CommandContext.adoc
index 1f9c5c2..17a3773 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_CommandContext.adoc
@@ -150,11 +150,13 @@ This requires that an implementation of xref:rgsvc.adoc#_rgsvc_spi_CommandServic
== Interacting with the services
-Typically the domain objects have little need to interact with the `CommandContext` and `Command` directly; what is more useful is that these are persisted in support of the various use cases identified above.
+Typically domain objects will have little need to interact with the `CommandContext` and `Command` directly; what is
+more useful is that these are persisted in support of the various use cases identified above.
One case however where a domain object might want to obtain the `Command` is to determine whether it has been invoked in the foreground, or in the background. It can do this using the `getExecutedIn()` method:
-Although not often needed, this then allows the domain object to access the `Command` object through the `CommandContext` service. To expand th above example:
+Although not often needed, this then allows the domain object to access the `Command` object through the
+`CommandContext` service. To expand th above example:
[source,java]
@@ -177,11 +179,11 @@ public class ToDoItem ... {
If run in the background, it might then notify the user (eg by email) if all work is done.
-This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the `DomainObjectContainer`, using:
+This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`], using:
[source,java]
----
-String user = container.getUser().getName();
+String user = userService.getUser().getName();
----
If running in the background, however, then the current user will be the credentials of the background process, for example as run by a Quartz scheduler job.
@@ -214,6 +216,21 @@ in the xref:rgsvc.adoc#_rgsvc_intro_overriding-the-services[introduction] to thi
== Related Services
-As discussed above, the supporting xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] enables `Command` objects to be persisted. Other related services are the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`] and xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]). For `BackgroundService` captures commands for execution in the background, while the [BackgroundCommandService] persists such commands for 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.
\ No newline at end of file
+The xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] service is very similar in nature to the xref:rgsvc.adoc#_rgsvc_api_InteactionContext[`InteactionContext`], in that the
+`Command` object accessed through it is very similar to the `Interaction` object obtained from the `InteractionContext`.
+The principle distinction is that while `Command` represents the __intention__ to invoke an action or edit a property,
+the `Interaction` (and contained ``Execution``s) represents the actual execution.
+
+Most of the time a `Command` will be followed directly by its corresponding `Interaction`. However, if the `Command`
+is annotated to run in the background (using xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
+is explicitly created through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
+interaction/execution is deferred until some other mechanism invokes the command (eg as described
+xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]). The persistence of background commands
+requires a configured xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]) to actually
+persist such commands for execution.
+
+``Command``s - even if executed in the foreground - can also be persisted by way of the
+xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`]. Implementations of `CommandService` and
+`BackgroundCommandService` are intended to go together, so that child ``Command``s persistent (to be executed in the
+background) can be associated with their parent ``Command``s (executed in the foreground, with the background `Command`
+created explicitly through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]).
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
index 293b664..6046d4d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_InteractionContext.adoc
@@ -6,4 +6,180 @@
-NOTE: TODO
\ No newline at end of file
+The `InteractionContext` (`1.13.0-SNAPSHOT`) is a request-scoped domain service that is used to obtain the current `Interaction`.
+
+An `Interaction` generally consists of a single top-level `Execution`, either to invoke an action or to edit a property. If that top-level action or property uses xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] to invoke child actions/properties, then those sub-executions are captured as a call-graph. The `Execution` is thus a graph structure.
+
+If a bulk action is performed (as per an action annotated using xref:rgant.adoc#_rgant-Action_invokeOn[`@Action#invokeOn()`]), then this will result in multiple ``Interaction``s, one per selected object (not one `Interaction` with multiple top-level ``Execution``s).
+
+
+
+
+== API & Implementatin
+
+The public API of the service consists of several related classes:
+
+* `InteractionContext` domain service itself:
+* `Interaction` class, obtainable from the `InteractionContext`
+* `Execution` class, obtainable from the `Interaction`.
+
+The `Execution` class itself is abstract; there are two subclasses, `ActionInvocation` and `PropertyEdit`.
+
+=== `InteractionContext`
+
+The public API of the `InteractionContext` domain service itself consists of simply:
+
+[source,java]
+----
+@RequestScoped
+public class InteractionContext {
+ public Interaction getInteraction(); // <1>
+}
+----
+<1> Returns the currently active {@link Interaction} for this thread.
+
+This class is concrete (is also the implementation).
+
+
+=== `Interaction`
+
+The public API of the `Interaction` class consists of:
+
+[source,java]
+----
+public class Interaction {
+ public UUID getTransactionId(); // <1>
+ public Execution getPriorExecution(); // <2>
+ public Execution getCurrentExecution(); // <3>
+ public List<Execution> getExecutions(); // <4>
+ public int next(final String sequenceId); // <5>
+}
+----
+<1> The unique identifier of this interaction. This will be the same value as held in `Command` (obtainable from xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
+<2> The member `Execution` (action invocation or property edit) that preceded the current one.
+<3> The current execution.
+<4> * Returns a (list of) execution}s in the order that they were pushed. Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
+<5> Generates numbers in a named sequence. Used by the framework both to number successive interaction ``Execution``s and for events published by the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
+
+This class is concrete (is also the implementation).
+
+
+=== `Interaction.Execution`
+
+The `Interaction.Execution` (static nested) class represents an action invocation/property edit as a node in a
+call-stack execution graph. Sub-executions can be performed using the
+xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+
+It has the following public API:
+
+[source,java]
+----
+public abstract class Execution {
+ public Interaction getInteraction(); // <1>
+ public InteractionType getInteractionType(); // <2>
+ public String getMemberIdentifier(); // <3>
+ public Object getTarget(); // <4>
+
+ public String getTargetClass(); // <5>
+ public String getTargetMember();
+
+ public Execution getParent(); // <6>
+ public List<Execution> getChildren();
+
+ public AbstractDomainEvent getEvent(); // <7>
+
+ public Timestamp getStartedAt(); // <8>
+ public Timestamp getCompletedAt();
+
+ public Object getReturned(); // <9>
+ public Exception getThrew();
+
+ public T getDto(); // <10>
+}
+----
+<1> The owning `Interaction`.
+<2> Whether this is an action invocation or a property edit.
+<3> A string uniquely identifying the action or property (similar to Javadoc syntax).
+<4> The object on which the action is being invoked or property edited. In the case of a mixin this will be the mixin object itself (rather than the mixed-in object).
+<5> A human-friendly description of the class of the target object, and of the name of the action invoked/property
+edited on the target object.
+<6> The parent action/property that invoked this action/property edit (if any), and any actions/property edits made in
+turn via the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
+<7> The domain event fired via the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] representing the
+execution of this action invocation/property edit.
+<8> The date/time at which this execution started/completed.
+<9> The object returned by the action invocation/property edit, or the exception thrown. For `void` methods and for actions returning collections, the value will be `null`.
+<10> A DTO (instance of the xref:rgcms.adoc#_rgcms_schema_ixn["ixn" schema]) being a serializable representation of this action invocation/property edit.
+
+
+
+There are two concrete subclasses of `Execution`.
+
+The first is `ActionInvocation`, representing the execution of an action being invoked:
+
+[source,java]
+----
+public class ActionInvocation extends Execution {
+ public List<Object> getArgs(); // <1>
+}
+----
+<1> The objects passed in as the arguments to the action's parameters. Any of these could be `null`.
+
+
+The second is `PropertyEdit`, and naturally enough represents the execution of a property being edited:
+
+[source,java]
+----
+public class PropertyEdit extends Execution {
+ public Object getNewValue(); // <1>
+}
+----
+<1> The object used as the new value of the property. Could be `null` if the property is being cleared.
+
+
+
+== Interacting with the services
+
+Typically domain objects will have little need to interact with the `InteractionContext` and `Interaction` directly.
+The services are used within the framework however, primarily to support the
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, and to emit domain events over the
+xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `InteractionContext` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+The framework also takes responsibility for instantiating the `Interaction`, using the
+xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`].
+
+[NOTE]
+====
+Unlike the similar xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (discussed
+xref:rgsvc.adoc#_rgsvc_api_InteractionContext_Related-Classes[below]) there is no domain service to different
+implementations of `Interaction` to be used. If this were to be needed, then a custom implementation of
+ xref:rgsvc.adoc#_rgsvc_api_FactoryService[`FactoryService`] could always used).
+====
+
+
+
+
+[[_rgsvc_api_InteractionContext_Related-Classes]]
+== Related Classes
+
+This service is very similar in nature to xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`], in that the
+`Interaction` object accessed through it is very similar to the `Command` object obtained from the `CommandContext`.
+The principle distinction is that while `Command` represents the __intention__ to invoke an action or edit a property,
+the `Interaction` (and contained ``Execution``s) represents the actual execution.
+
+Most of the time a `Command` will be followed directly by its corresponding `Interaction`. However, if the `Command`
+is annotated to run in the background (using xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`], or
+is explicitly created through the xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`], then the actual
+interaction/execution is deferred until some other mechanism invokes the command (eg as described
+xref:ugbtb.adoc#_ugbtb_headless-access_BackgroundCommandExecution[here]).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
index 31951dc..801a720 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetamodelService.adoc
@@ -40,7 +40,7 @@ public interface MetaModelService2 {
== Implementation
-The framework provides a default implementation of this service (`org.apache.isis.core.metamodel.services.metamodel.MetaModelServiceDefault`).
+The framework provides a default implementation of this service, `o.a.i.c.m.services.metamodel.MetaModelServiceDefault`.
== Registering the Service
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
index 7d8b50a..497b9aa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
@@ -6,4 +6,42 @@
-NOTE: TODO
\ No newline at end of file
+The `MetricsService` (`1.13.0-SNAPSHOT`) is a request-scoped domain service that hooks into the JDO/DataNucleus
+ObjectStore to provide a number of counters relating to numbers of object loaded, dirtied etc.
+
+The service is used by the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
+the `PublishedObjects` class.
+
+
+== API & Implementation
+
+The API of the service is:
+
+[source,java]
+----
+@RequestScoped
+public interface MetricsService {
+ int numberObjectsLoaded(); // <1>
+ int numberObjectsDirtied(); // <2>
+ int numberObjectPropertiesModified(); // <3>
+}
+----
+<1> The number of objects that have, so far in this request, been loaded from the database. Corresponds to the number of times that `javax.jdo.listener.LoadLifecycleListener#postLoad(InstanceLifecycleEvent)` is fired.
+<2> The number of objects that have, so far in this request, been dirtied/will need updating in the database); a good measure of the footprint of the interaction. Corresponds to the number of times that `javax.jdo.listener.DirtyLifecycleListener#preDirty(InstanceLifecycleEvent)` callback is fired.
+<3> The number of individual properties of objects that were modified; a good measure of the amount of work being done in the interaction. Corresponds to the number of times that the xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]'s `audit(...)` method will be called as the transaction completes.
+
+The framework provides a default implementation of this API, namely `o.a.i.c.r.s.metrics.MetricsServiceDefault`.
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `MetricsService` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+== Related Services
+
+The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] also captures the metrics gathered by the
+`MetricsService` and publishes them as part of the `PublishedObjects` class (part of its SPI).
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
index cfce965..66bc8a4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-api.adoc
@@ -142,7 +142,8 @@ Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
index 4c5f352..ff44729 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
@@ -35,7 +35,10 @@ Impl'n (g: a:)
|xref:rgsvc.adoc#_rgsvc_api_CommandDtoServiceInternal[`o.a.i.c.` +
`m.s.command` +
`CommandDtoServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Creates memento of current action invocation, for use either as a reified command or for implementations of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|(`1.13.0-SNAPSHOT`) Creates memento of current action invocation, for use as a serializable XML reified command. The
+most notable usage of this is to allow the execution of the `Command` to be deferred to run in the background (via
+xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`] or
+xref:rgant.adoc#_rgant-Property_command[`@Property#commandExecuteIn()`].
|`CommandDtoService-` +
`InternalServiceDefault` +
``o.a.i.c.r.s.command`` +
@@ -43,12 +46,25 @@ Impl'n (g: a:)
|
+|xref:rgsvc.adoc#_rgsvc_api_InteractionDtoServiceInternal[`o.a.i.c.` +
+`m.s.ixn` +
+`InteractionDtoServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|`CommandDtoService-` +
+`InternalServiceDefault` +
+``o.a.i.c.m.s.command`` +
+``isis-core-metamodel``
+|
+
+
|===
Key:
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-spi.adoc
index 3e4928c..5d39986 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-spi.adoc
@@ -69,6 +69,8 @@ Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_bootstrapping-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_bootstrapping-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_bootstrapping-spi.adoc
index e4c1628..2a176fd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_bootstrapping-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_bootstrapping-spi.adoc
@@ -35,6 +35,13 @@ Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[
|===
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+
include::_rgsvc_spi_ClassDiscoveryService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_core-domain-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_core-domain-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_core-domain-api.adoc
index c827cf7..420443c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_core-domain-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_core-domain-api.adoc
@@ -112,6 +112,8 @@ Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
@@ -141,7 +143,12 @@ There is also a number of deprecated domain services.
Key:
+Key:
+
* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_integration-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_integration-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_integration-api.adoc
index b615241..ce8f42a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_integration-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_integration-api.adoc
@@ -103,6 +103,15 @@ The table below summarizes the integration APIs defined by Apache Isis. It also
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+
+
+
include::_rgsvc_api_BookmarkService.adoc[leveloffset=+1]
include::_rgsvc_api_DeepLinkService.adoc[leveloffset=+1]
include::_rgsvc_api_EmailService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_metadata-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_metadata-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_metadata-api.adoc
index 7c81a52..32631dd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_metadata-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_metadata-api.adoc
@@ -82,6 +82,14 @@ within the metamodel.
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+
+
include::_rgsvc_api_ApplicationFeatureRepository.adoc[leveloffset=+1]
include::_rgsvc_api_LayoutService.adoc[leveloffset=+1]
include::_rgsvc_api_MetamodelService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-api.adoc
index f9c35cf..84a62cf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-api.adoc
@@ -72,10 +72,15 @@ The table below summarizes the persistence layer APIs defined by Apache Isis. I
|===
+
+
+
Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
index b0afbcf..ce019a9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
@@ -70,6 +70,8 @@ xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
Key:
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-spi.adoc
index 0cfc5da..8dc3635 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-spi.adoc
@@ -90,6 +90,8 @@ Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:rgant.adoc#_rgant-DomainService[`@DomainService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
index daa49e1..9e9d3c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
@@ -57,6 +57,10 @@ Impl'n (g: a:)
Key:
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
index e435761..8c8aedb 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
@@ -178,6 +178,8 @@ Key:
* `o.a.i` is an abbreviation for `org.apache.isis`
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
index e82f506..ba7eaa0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
@@ -5,5 +5,42 @@
:_imagesdir: images/
+The (internal) `AuditingServiceInternal` domain service (`1.13.0-SNAPSHOT`) acts as an internal facade to any
+configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. It is responsible for obtaining the details
+of all changes to domain objects within an interaction, and then to call the configured `AuditingService` to actually
+create audit entries of those changes.
-NOTE: TODO
\ No newline at end of file
+The service is a no-op if there is no configured `AuditingService`.
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public class AuditingServiceInternal {
+ public boolean canAudit(); // <1>
+ public void audit(); // <2>
+}
+----
+<1> whether auditing is enabled; checks to see if any xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured.
+<2> uses the xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
+
+The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `AuditingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+== Related Classes
+
+The service delegates between the (internal) xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. If no such `AuditingService` is configured, this service is in effect a no-op.
+
+The (internal) xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] performs a similar function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
index f6bedac..d701127 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
@@ -5,5 +5,65 @@
:_imagesdir: images/
+The `ChangedObjectsServiceInternal` class (`1.13.0-SNAPSHOT`) is an (internal) request-scoped domain service that is
+responsible for collecting the details of all changes to domain objects within an interaction. This is then used by
+various other (internal) domain services, notably
+xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`].
-NOTE: TODO
\ No newline at end of file
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+@RequestScoped
+public class ChangedObjectsServiceInternal {
+ public void enlistCreated(final ObjectAdapter adapter); // <1>
+ public void enlistUpdating(final ObjectAdapter adapter);
+ public void enlistDeleting(final ObjectAdapter adapter);
+
+ public boolean hasChangedAdapters(); // <2>
+
+ public Map<ObjectAdapter, PublishedObject.ChangeKind> getChangeKindByEnlistedAdapter(); // <3>
+ public int numberObjectsDirtied();
+ public int numberObjectPropertiesModified();
+
+ public Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> getChangedObjectProperties(); // <4>
+
+ public void clearChangedObjectProperties(); // <5>
+}
+----
+<1> Enlists an object that has just been created, updated or deleted, capturing the pre-modification values of the properties.
+<2> Used by the framework to determine whether to set the "persist hint" on the `Command` object (as per xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
+<3> Used by xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] to obtain details of and
+counters of all objects changed within the transaction.
+<4> Used by xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] to obtain all pairs of
+pre/post values of changed properties
+<5> Called by the framework to for clean up after auditing and publishing has completed.
+
+For enlisted objects, if just created, then a dummy value `"[NEW]"` is used for the pre-modification value; if just
+deleted, then a dummy value `"[DELETED]"` is used for the post-modification value. The post-modification values of
+properties are captured when the transaction commits.
+
+
+The service implementation is `o.a.i.c.r.s.changes.ChangedObjectsServiceInternal`.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `ChangedObjectsServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+
+== Related Classes
+
+Both the xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] (internal) domain services query
+this object.
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
index 65e47a4..c047752 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
@@ -19,7 +19,7 @@ The SPI of the service is:
[source,java]
----
-public interface CommandMementoService {
+public interface CommandDtoServiceInternal {
@Deprecated
ActionInvocationMemento asActionInvocationMemento( // <1>
Method m,
@@ -48,8 +48,13 @@ XML) that represents the __intention__ to invoke an action on a target object (o
bulk actions). If an action, it can also be either mixin action or a contributed action.
<3> Returns a JAXB DTO that represents the intention to edit (set or clear) a property on a target (or possibly many
targets, for symmetry with actions).
-<4> add the arguments of an action to an `ActionDto`.
-<5> add the new value argument of a property to a `PropertyDto`.
+<4> add the arguments of an action to an `ActionDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to populate the parameters of the equivalent `ActionInvocationDto`.
+<5> add the new value argument of a property to a `PropertyDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to set the the new value of the equivalent `PropertyEditDto`.
The SPI is implemented by `o.a.i.c.r.s.command.CommandDtoServiceInternalServiceDefault`.
+
+
+== Related Services
+
+The design of this service is similar to that of xref:rgsvc.adoc#_rgsvc_spi_InteractionDtoServiceInternal[`InteractionDtoServiceInternal`], used to create the `MemberExecutionDto` (from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]).
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_InteractionDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_InteractionDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_InteractionDtoServiceInternal.adoc
index 4667671..12d25bf 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_InteractionDtoServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_InteractionDtoServiceInternal.adoc
@@ -6,4 +6,37 @@
-NOTE: TODO
\ No newline at end of file
+The `InteractionDtoServiceInternal` internal domain service (`1.13.0-SNAPSHOT`) is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property. The DTO is in all cases a subclass of `MemberExecutionDto`, from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema], and subsequently accessible from the `Interaction` object (per the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service).
+
+
+== SPI & Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public interface InteractionDtoServiceInternal {
+ ActionInvocationDto asActionInvocationDto( // <1>
+ ObjectAction objectAction,
+ ObjectAdapter targetAdapter,
+ List<ObjectAdapter> argumentAdapters);
+ PropertyEditDto asPropertyEditDto( // <2>
+ OneToOneAssociation property,
+ ObjectAdapter targetAdapter,
+ ObjectAdapter newValueAdapterIfAny);
+ ActionInvocationDto updateResult( // <3>
+ ActionInvocationDto actionInvocationDto,
+ ObjectAction objectAction,
+ Object resultPojo);
+}
+----
+<1> called by the framework when invoking an action, to create a DTO capturing the details of the action invocation (target, arguments etc).
+<2> called by the framework when editing a property, to create a DTO (for the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) capturing the details of the property edit (target, new value etc).
+<3> called by the framework to attach the result of an action invocation to the aforementioned DTO.
+
+The service is implemented by `o.a.i.core.runtime.services.ixn.InteractionDtoServiceInternalDefault`.
+
+
+== Related Services
+
+The design of this service is similar to that of xref:rgsvc.adoc#_rgsvc_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`], used to create the `CommandDto` (from the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema]).
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
index 6facd35..8aa3eaa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
@@ -48,11 +48,12 @@ The full API of `PublishedObjects` itself is:
[source,java]
----
public interface PublishedObjects extends HasTransactionId, HasUsername {
- UUID getTransactionId(); // <1>
- String getUsername(); // <2>
- Timestamp getCompletedAt(); // <3>
- ChangesDto getDto(); // <4>
- int getNumberLoaded(); // <5>
+ UUID getTransactionId(); // <1>
+ String getUsername(); // <2>
+ Timestamp getCompletedAt(); // <3>
+ ChangesDto getDto(); // <4>
+
+ int getNumberLoaded(); // <5>
int getNumberCreated();
int getNumberUpdated();
int getNumberDeleted();
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingServiceInternal.adoc
index 58eabcd..cc96da2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingServiceInternal.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingServiceInternal.adoc
@@ -5,4 +5,72 @@
:_imagesdir: images/
-NOTE: TODO
\ No newline at end of file
+The (internal) `PublishingServiceInternal` domain service (`1.13.0-SNAPSHOT`) acts as an internal facade to any
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or (deprecated in `1.13.0-SNAPSHOT`)
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] domain services.
+
+For published action invocations/ property edits, it provides an API for those member executions to call.
+
+For published objects, it provides an API for the framework to call at the end of the interaction; it obtains details
+of the changed objects (from the
+xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`]) and filters them to just
+those objects that are to be published; these are then passed through to any configured `PublisherService` or
+`PublishingService` implementations.
+
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public class PublishingServiceInternal {
+ void publishAction(
+ Interaction.Execution execution, // <1>
+ ObjectAction objectAction, // <2>
+ IdentifiedHolder identifiedHolder,
+ ObjectAdapter targetAdapter,
+ List<ObjectAdapter> parameterAdapters,
+ ObjectAdapter resultAdapter);
+ void publishProperty( // <3>
+ Interaction.Execution execution);
+ void publishObjects(); // <4>
+}
+----
+<1> to publish an action invocation, as represented by the specified member `Execution` parameter and with the
+xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation attribute or equivalent, to any configured
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance of
+`ActionInvocation` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+<2> the remaining parameters are to support the publishing of the action to any configured
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] services (deprecated in `1.13.0-SNAPSHOT`).
+<3> to publish a property edit, as as represented by the specified member `Execution` parameter and with the
+xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation attribute or equivalent, to any
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance
+of `PropertyEdit` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+<4> to publish all changed objects that are to be published (with the
+xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation attribute or equivalent).
+
+
+The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `PublishingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+== Related Classes
+
+The service delegates between the (internal)
+xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and
+ xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+
+The (internal) xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] performs a similar
+function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the
+changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/core/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java b/core/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
index 9281bae..e693996 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
@@ -110,15 +110,24 @@ public class Interaction implements HasTransactionId {
}
/**
- * Implemented by the framework (and modelled after {@link Callable}), is the implementation
+ * <b>NOT API</b>: intended only to be implemented by the framework.
+ *
+ * <p>
+ * (Modelled after {@link Callable}), is the implementation
* by which the framework actually performs the interaction.
- * @param <T>
*/
public interface MemberExecutor<T extends Execution> {
Object execute(final T currentExecution);
}
-
+ /**
+ * <b>NOT API</b>: intended to be called only by the framework.
+ *
+ * <p>
+ * Use the provided {@link MemberExecutor} to invoke an action, with the provided
+ * {@link ActionInvocation} capturing the details of said action.
+ * </p>
+ */
public Object execute(
final MemberExecutor<ActionInvocation> memberExecutor,
final ActionInvocation actionInvocation) {
@@ -128,6 +137,14 @@ public class Interaction implements HasTransactionId {
return executeInternal(memberExecutor, actionInvocation);
}
+ /**
+ * <b>NOT API</b>: intended to be called only by the framework.
+ *
+ * <p>
+ * Use the provided {@link MemberExecutor} to edit a property, with the provided
+ * {@link PropertyEdit} capturing the details of said property edit.
+ * </p>
+ */
public Object execute(
final MemberExecutor<PropertyEdit> memberExecutor,
final PropertyEdit propertyEdit) {
@@ -165,15 +182,7 @@ public class Interaction implements HasTransactionId {
}
/**
- * The current (most recently pushed) {@link org.apache.isis.applib.services.eventbus.AbstractDomainEvent}.
- *
- * <p>
- * Note that the {@link org.apache.isis.applib.services.eventbus.AbstractDomainEvent} itself is mutable,
- * as its {@link AbstractDomainEvent#getEventPhase()} phase} changes from
- * {@link org.apache.isis.applib.services.eventbus.AbstractDomainEvent.Phase#EXECUTING executing} to
- * {@link org.apache.isis.applib.services.eventbus.AbstractDomainEvent.Phase#EXECUTED executed}. The
- * event returned from this method will always be in one or other of these phases.
- * </p>
+ * The current (most recently pushed) {@link Execution}.
*/
@Programmatic
public Execution getCurrentExecution() {
@@ -233,7 +242,7 @@ public class Interaction implements HasTransactionId {
}
/**
- * Returns a (list of) graph(es) indicating the domain events in the order that they were pushed.
+ * Returns a (list of) {@link Execution}s in the order that they were pushed. Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
*
* <p>
* Each {@link Execution} represents a call stack of domain events (action invocations or property edits),
@@ -310,7 +319,7 @@ public class Interaction implements HasTransactionId {
* Represents an action invocation/property edit as a node in a call-stack execution graph, with sub-interactions
* being made by way of the {@link WrapperFactory}).
*/
- public static class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
+ public static abstract class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
//region > fields, constructor
@@ -321,7 +330,7 @@ public class Interaction implements HasTransactionId {
private final Interaction interaction;
private final InteractionType interactionType;
- public Execution(
+ protected Execution(
final Interaction interaction,
final InteractionType interactionType,
final String memberIdentifier,
@@ -383,6 +392,9 @@ public class Interaction implements HasTransactionId {
return parent;
}
+ /**
+ * <b>NOT API</b>: intended to be called only by the framework.
+ */
public void setParent(final Execution<?,?> parent) {
this.parent = parent;
if(parent != null) {
@@ -407,7 +419,7 @@ public class Interaction implements HasTransactionId {
* this action invocation/property edit.
*
* <p>
- * This event field is called by the framework before the action invocation/property edit itself;
+ * This event field is set by the framework before the action invocation/property edit itself;
* if read by the executing action/property edit method it will be in the
* {@link AbstractDomainEvent.Phase#EXECUTING executing} phase.
* </p>
@@ -529,7 +541,7 @@ public class Interaction implements HasTransactionId {
enum When {
BEFORE {
@Override
- public void syncMetrics(
+ void syncMetrics(
final Execution<?, ?> execution,
final Timestamp timestamp,
final int numberObjectsLoaded,
@@ -551,7 +563,7 @@ public class Interaction implements HasTransactionId {
},
AFTER {
- @Override public void syncMetrics(
+ @Override void syncMetrics(
final Execution<?, ?> execution,
final Timestamp timestamp,
final int numberObjectsLoaded,
@@ -600,7 +612,7 @@ public class Interaction implements HasTransactionId {
}
//endregion
- public abstract void syncMetrics(
+ abstract void syncMetrics(
final Execution<?,?> teExecution,
final Timestamp timestamp,
final int numberObjectsLoaded,
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/ixn/InteractionDtoServiceInternal.java
----------------------------------------------------------------------
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/ixn/InteractionDtoServiceInternal.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/ixn/InteractionDtoServiceInternal.java
index 6b5fe90..4f1d6e8 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/ixn/InteractionDtoServiceInternal.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/services/ixn/InteractionDtoServiceInternal.java
@@ -36,16 +36,16 @@ public interface InteractionDtoServiceInternal {
List<ObjectAdapter> argumentAdapters);
@Programmatic
- ActionInvocationDto updateResult(
- ActionInvocationDto actionInvocationDto,
- ObjectAction objectAction,
- Object resultPojo);
-
- @Programmatic
PropertyEditDto asPropertyEditDto(
OneToOneAssociation property,
ObjectAdapter targetAdapter,
ObjectAdapter newValueAdapterIfAny);
+ @Programmatic
+ ActionInvocationDto updateResult(
+ ActionInvocationDto actionInvocationDto,
+ ObjectAction objectAction,
+ Object resultPojo);
+
}
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/core/runtime/src/main/java/org/apache/isis/core/runtime/services/auditing/AuditingServiceInternal.java
----------------------------------------------------------------------
diff --git a/core/runtime/src/main/java/org/apache/isis/core/runtime/services/auditing/AuditingServiceInternal.java b/core/runtime/src/main/java/org/apache/isis/core/runtime/services/auditing/AuditingServiceInternal.java
index d3cfebe..a4a6c5c 100644
--- a/core/runtime/src/main/java/org/apache/isis/core/runtime/services/auditing/AuditingServiceInternal.java
+++ b/core/runtime/src/main/java/org/apache/isis/core/runtime/services/auditing/AuditingServiceInternal.java
@@ -57,21 +57,15 @@ public class AuditingServiceInternal {
final Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> changedObjectProperties =
changedObjectsServiceInternal.getChangedObjectProperties();
- try {
- if(!canAudit()) {
- return;
- }
-
- final String currentUser = userService.getUser().getName();
- final java.sql.Timestamp currentTime = clockService.nowAsJavaSqlTimestamp();
+ if(!canAudit()) {
+ return;
+ }
- for (Map.Entry<AdapterAndProperty, PreAndPostValues> auditEntry : changedObjectProperties) {
- auditChangedProperty(currentTime, currentUser, auditEntry);
- }
+ final String currentUser = userService.getUser().getName();
+ final java.sql.Timestamp currentTime = clockService.nowAsJavaSqlTimestamp();
- } finally {
- // not needed in production, but is required for integration testing
- changedObjectsServiceInternal.clearChangedObjectProperties();
+ for (Map.Entry<AdapterAndProperty, PreAndPostValues> auditEntry : changedObjectProperties) {
+ auditChangedProperty(currentTime, currentUser, auditEntry);
}
}
http://git-wip-us.apache.org/repos/asf/isis/blob/e74c7a9a/core/runtime/src/main/java/org/apache/isis/core/runtime/system/transaction/IsisTransaction.java
----------------------------------------------------------------------
diff --git a/core/runtime/src/main/java/org/apache/isis/core/runtime/system/transaction/IsisTransaction.java b/core/runtime/src/main/java/org/apache/isis/core/runtime/system/transaction/IsisTransaction.java
index 920d6d1..9a4cac4 100644
--- a/core/runtime/src/main/java/org/apache/isis/core/runtime/system/transaction/IsisTransaction.java
+++ b/core/runtime/src/main/java/org/apache/isis/core/runtime/system/transaction/IsisTransaction.java
@@ -430,6 +430,8 @@ public class IsisTransaction implements TransactionScopedComponent {
setAbortCause(new IsisTransactionManagerException(ex));
completeCommandAndInteractionAndClearDomainEvents();
throw ex;
+ } finally {
+ changedObjectsServiceInternal.clearChangedObjectProperties();
}
}