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 2020/09/20 15:10:13 UTC
[isis] 02/02: ISIS-2222: updates doc examples and generated config
ref docs
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2222
in repository https://gitbox.apache.org/repos/asf/isis.git
commit b2db57a78e96041f942aff8841fe7e03a59194ae
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Sep 20 16:09:37 2020 +0100
ISIS-2222: updates doc examples and generated config ref docs
---
.../examples/events/domain/ActionDomainEvent.java | 22 ---
.../services/iactn/InteractionContext.java | 3 +-
.../modules/applib-svc/pages/CommandContext.adoc | 177 ---------------------
.../pages/ChangedObjectsService.adoc | 20 +--
.../pages/CommandDtoServiceInternal.adoc | 8 +-
5 files changed, 15 insertions(+), 215 deletions(-)
diff --git a/api/applib/src/main/adoc/modules/applib-classes/examples/events/domain/ActionDomainEvent.java b/api/applib/src/main/adoc/modules/applib-classes/examples/events/domain/ActionDomainEvent.java
index f891fe1..0fe46cb 100644
--- a/api/applib/src/main/adoc/modules/applib-classes/examples/events/domain/ActionDomainEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-classes/examples/events/domain/ActionDomainEvent.java
@@ -67,28 +67,6 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
public ActionDomainEvent() {
}
- // // -- command
- // private Command command;
- //
- // /**
- // * @deprecated - use {@link CommandContext#getCommand()} to obtain the current {@link Command}.
- // */
- // @Deprecated
- // public Command getCommand() {
- // return command;
- // }
- //
- // /**
- // * Not API - set by the framework.
- // *
- // * @deprecated - the corresponding {@link #getCommand()} should not be called, instead use {@link CommandContext#getCommand()} to obtain the current {@link Command}.
- // */
- // @Deprecated
- // public void setCommand(Command command) {
- // this.command = command;
- // }
-
-
// tag::refguide[]
@Getter
private SemanticsOf semantics;
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
index de41f1e..b6579ea 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
@@ -77,7 +77,6 @@ public class InteractionContext implements TransactionScopeListener, DisposableB
this.interaction = interaction;
}
- // tag::refguide[]
@Override
public void onTransactionEnded() {
@@ -92,5 +91,7 @@ public class InteractionContext implements TransactionScopeListener, DisposableB
setInteraction(null);
}
+ // tag::refguide[]
+ // ...
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandContext.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandContext.adoc
deleted file mode 100644
index 5170943..0000000
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandContext.adoc
+++ /dev/null
@@ -1,177 +0,0 @@
-= `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 [...]
-:page-partial:
-
-
-CAUTION: TODO v2 - to update, has been removed so that instead Interaction holds the Command, which in turn is accessed from InteractionContext.
-
-The `CommandContext` service is a xref:refguide:applib-ant:IsisSessionScope.adoc[request-scoped] service that reifies the invocation of an action on a domain object into an object itself.
-This reified information is encapsulated within the xref:CommandContext.adoc#command[`Command`] object.
-
-By default, the command is held in-memory only; once the action invocation has completed, the command object is gone.
-The optional supporting xref:refguide:applib-svc:CommandService.adoc[`CommandService`] enables the implementation of xref:CommandContext.adoc#command[`Command`] to be pluggable.
-With an appropriate implementation
-// TODO: v2: update for extensions (eg as provided by the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module's xref:refguide:applib-svc:CommandService.adoc[`CommandService`])
-the xref:CommandContext.adoc#command[`Command`] instance may then be persisted.
-
-There are two main use cases:
-
-* to allow invocation of ``Command``s to be deferred, for example to be invoked in the background
-
-* to allow ``Command``s to be replicated and replayed to another system (usually for testing or dual-running/migration purposes).
-
-This is normally done using the `CommandWithDto` subtype, that can return a representation of the `Command` as an XML instance of the xref:refguide:schema:cmd.adoc[`cmd.xsd`] schema, which also captures a unique transactionId (GUID) for the command.
-
-
-
-
-
-
-
-
-
-
-
-== API
-
-The `CommandContext` request-scoped service defines the following very simple API:
-
-[source,java]
-----
-include::refguide:applib-svc:example$services/command/CommandContext.java[tags="refguide"]
-----
-
-=== `Command`
-
-The `Command` type in turn is defined as:
-
-[source,java]
-----
-include::refguide:applib-svc:example$services/command/Command.java[tags="refguide"]
-----
-
-<.> user that initiated the action.
-<.> date/time at which this action was created.
-<.> bookmark of the target object (entity or service) on which this action was performed
-<.> holds a string representation of the invoked action
-<.> human-friendly description of the class of the target object
-<.> human-friendly name of the action invoked on the target object
-<.> human-friendly description of the arguments with which the action was invoked <.> formal (XML or similar) specification of the action to invoke/being invoked
-<.> whether this command is executed in the foreground or background
-+
-[source,java,indent=0]
-----
-include::refguide:applib-ant:example$annotation/CommandExecuteIn.java[tags="refguide"]
-----
-
-<.> the (current) executor of this command:
-+
-[source,java,indent=0]
-----
-include::refguide:applib-svc:example$services/command/Command.java[tags="refguide2"]
-----
-
-<.> date/time at which this action started (same as `timestamp` property for foreground commands) <.> date/time at which this action completed.
-<.> for actions created through the `BackgroundService`, captures the parent action <.> exception stack trace, if action threw exception <.> bookmark to object returned by action, if any <.> the policy controlling whether this command should ultimately be persisted:
-+
-[source,java,indent=0]
-----
-include::refguide:applib-ant:example$annotation/CommandPersistence.java[tags="refguide"]
-----
-
-<.> whether that the command should be persisted, if persistence policy is "if hinted".
-
-== Implementation
-
-The `o.a.i.applib.services.command.CommandContext` is also the default implementation of the service.
-
-The implementation of `Command` will provided by the xref:refguide:applib-svc:CommandService.adoc[`CommandService`] SPI.
-
-== Usage
-
-The typical way to indicate that an action should be treated as a command is to annotate it with the xref:refguide:applib-ant:Action.adoc#command[`@Action#command()`] annotation.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(command=CommandReification.ENABLED)
- public ToDoItem completed() { /* ... */ }
-}
-----
-
-As an alternative to annotating every action with xref:refguide:applib-ant:Action.adoc#command[`@Action#command()`], use the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.action.command[`isis.applib.annotation.action.command`] to define a global default.
-
-
-
-
-
-== Interacting with the services
-
-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 the above example:
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(
- command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.BACKGROUND
- )
- public ToDoItem completed() {
- ...
- Command currentCommand = commandContext.getCommand();
- ...
- }
- @Inject
- CommandContext commandContext;
-}
-----
-
-
-//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 xref:refguide:applib-svc:UserService.adoc[`UserService`], using:
-//
-//[source,java]
-//----
-//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.
-//
-//The domain object can still obtain the original ("effective") user that caused the job to be created, using:
-//
-//[source,java]
-//----
-//String user = commandContext.getCommand().getUser();
-//----
-
-
-
-
-
-== Related Services
-
-The implementation of xref:refguide:applib-svc:CommandContext.adoc#command[`Command`] is provided by the xref:refguide:applib-svc:CommandService.adoc[`CommandService`].
-The default implementation of that service creates an in-memory instance, but other implementations might choose to persist the `Command`, eg so its execution can be deferred, or replayed.
-
-
-The xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service itself is very similar in nature to the xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`], in that the `Command` object accessed through it is very similar to the xref:refguide:applib-svc:InteractionContext.adoc#interaction[`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.
-
-
-
-``Command``s are often combined with implementations of the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`] and sometimes also the xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`]:
-
-* the `PublisherService` publishes interactions as they have is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
-* if a `AuditerService` 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
-
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ChangedObjectsService.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ChangedObjectsService.adoc
index 2657ce4..c105d43 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ChangedObjectsService.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ChangedObjectsService.adoc
@@ -17,28 +17,28 @@ The SPI of the service is:
----
@IsisSessionScope
public class ChangedObjectsService {
- public void enlistCreated(final ObjectAdapter adapter); // <1>
+ public void enlistCreated(final ObjectAdapter adapter); // <.>
public void enlistUpdating(final ObjectAdapter adapter);
public void enlistDeleting(final ObjectAdapter adapter);
- public boolean hasChangedAdapters(); // <2>
+ public boolean hasChangedAdapters(); // <.>
- public Map<ObjectAdapter, PublishingChangeKind> getChangeKindByEnlistedAdapter(); // <3>
+ public Map<ObjectAdapter, PublishingChangeKind> getChangeKindByEnlistedAdapter(); // <.>
public int numberObjectsDirtied();
public int numberObjectPropertiesModified();
- public Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> getChangedObjectProperties(); // <4>
+ public Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> getChangedObjectProperties(); // <.>
- public void clearChangedObjectProperties(); // <5>
+ public void clearChangedObjectProperties(); // <.>
}
----
-<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:refguide:applib-svc:CommandContext.adoc[`CommandContext`]).
-<3> Used by xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] to obtain details of and
+<.> Enlists an object that has just been created, updated or deleted, capturing the pre-modification values of the properties.
+<.> Used by the framework to determine whether to send the completed `Command` to xref:refguide:applib-svc:CommandServiceListener.adoc[`CommandServiceListener`], for example so that it can be persisted).
+<.> Used by xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] to obtain details of and
counters of all objects changed within the transaction.
-<4> Used by xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] to obtain all pairs of
+<.> Used by xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] 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.
+<.> 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
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/CommandDtoServiceInternal.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/CommandDtoServiceInternal.adoc
index 822c29b..7ba37a7 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/CommandDtoServiceInternal.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/CommandDtoServiceInternal.adoc
@@ -4,11 +4,9 @@
WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-The `CommandDtoServiceInternal` is responsible for creating an memento of the current action
-invocation or property edit, to store in the `Command` object (from
-xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`]). This memento is a JAXB DTO being an instance of the
-xref:refguide:schema:cmd.adoc["cmd" schema], so can be reified so that its execution can be deferred until later,
-as a xref:refguide:applib-svc:BackgroundCommandService.adoc[background command].
+The `CommandDtoServiceInternal` is responsible for creating an memento of the current action invocation or property edit, to store in the `Command` object.
+This memento is a JAXB DTO being an instance of the
+xref:refguide:schema:cmd.adoc["cmd" schema], so can be reified either for persistence (through xref:refguide:applib-svc:CommandServiceListener.adoc[`CommandServiceListener`]) or async execution (through xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`].)