[isis] 01/02: ISIS-1569: adds documentation for this service

[da...@apache.org]

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

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

commit eb27901540402761359f63c0f35f49569b033f93
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Feb 8 14:19:48 2018 +0000

    ISIS-1569: adds documentation for this service
---
 .../guides/rgsvc/_rgsvc_application-layer-api.adoc | 14 ++++++-
 ...rgsvc_application-layer-api_CommandContext.adoc |  2 +-
 ...plication-layer-api_CommandExecutorService.adoc | 45 ++++++++++++++++++++++
 3 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
index 7d13989..3701e97 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api.adoc
@@ -37,7 +37,8 @@ It also lists their corresponding implementation, either a default implementatio
 `services.background` +
 `BackgroundService`]
 |Programmatic persistence of commands to be persisted (so can be executed by a background mechanism, eg scheduler)
-|`BackgroundServiceDefault` +
+|`BackgroundService-`
+`Default` +
 ``o.a.i.core`` +
 ``isis-core-runtime``
 |depends on: +
@@ -58,6 +59,17 @@ xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`CommandSer
 The xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_InteractionContext[`InteractionContext`] manages the actual execution of the command.
 
 
+|xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_CommandExecutorService[`o.a.i.applib.` +
+`services.command` +
+`CommandExecutorService`]
+|Executes the specified `Command`.
+|`CommandExecutorService-`
+`Default` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|
+
+
 |xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_DtoMappingHelper[`o.a.i.applib.` +
 `services.dto` +
 `DtoMappingHelper`]
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandContext.adoc
index f39ab29..2449256 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandContext.adoc
@@ -1,4 +1,4 @@
-[[_rgsvc_application-layer-api_CommandContext]]
+    [[_rgsvc_application-layer-api_CommandContext]]
 = `CommandContext`
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
 :_basedir: ../../
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandExecutorService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandExecutorService.adoc
new file mode 100644
index 0000000..afda737
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_application-layer-api_CommandExecutorService.adoc
@@ -0,0 +1,45 @@
+[[_rgsvc_application-layer-api_CommandExecutorService]]
+= `CommandExecutorService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `CommandExecutorService` domain service is provides the ability to execute a specified `Command`, optionally running the command with the identity of the user captured in that `Command`.
+
+In fact, the service requires that the implementation of the `Command` being executed implements the `CommandWithDto` sub-interface.
+This allows the xref:../rgcms/rgcms.adoc#_rgcms_schema-cmd[`CommandDto`] memento to be extracted, from which the action can be invoked/property edited.
+
+The primary use case for this service is to allow the replay of commands, eg for regression testing.
+This is implemented by the (non-ASF) link:http://platform.incode.org/modules/spi/command/spi-command-replay.html[command replay module].
+(The command replay module also provides a decorator implementation of this service that allows the command to be re-executed at the same _time_ as the original command, leveraging the `TickingClock` implementation provided by the framework).
+
+
+== API & Implementation
+
+The `CommandExecutorService` defines the following API:
+
+[source,java]
+----
+public interface CommandExecutorService {
+    enum SudoPolicy {
+        NO_SWITCH,
+        SWITCH,
+    }
+    void executeCommand(
+            SudoPolicy sudoPolicy,          // <1>
+            CommandWithDto commandWithDto); // <2>
+}
+----
+<1> whether to switch the effective user for the duration of executing the `Command`.
+Behind the scenes this uses the xref:rgsvc.adoc#_rgsvc_testing_SudoService[`SudoService`].
+<2> provided `Command` must implement `CommandDto`.
+
+When the `Command` is executed, it will also be returned by xref:rgsvc.adoc#_rgsvc_application-layer-api_CommandContext[`CommandContext`].
+Any associated objects that implement `HasTransactionId` (audit entries and the like) will therefore have the correct transactionId and will correctly be associated with the `Command` being executed.
+
+The framework provides a default implementation of this service,
+`o.a.i.core.runtime.services.background.CommandExecutorServiceDefault`
+
+

-- 
To stop receiving notification emails like this one, please contact
danhaywood@apache.org.