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/03/03 07:09:29 UTC
[isis] 01/02: ISIS-2062: refguide docs for command service
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 0d99a61eaa4856335be5e3405bcbdce27f3f5f21
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 3 05:53:20 2020 +0000
ISIS-2062: refguide docs for command service
---
antora/supplemental-ui/css/site-custom.css | 4 +
.../examples/annotation/CommandExecuteIn.java | 21 ++-
.../examples/annotation/CommandPersistence.java | 13 ++
.../examples/services/bookmark/Bookmark.java | 17 ++-
.../examples/services/bookmark/BookmarkHolder.java | 2 -
.../services/bookmark/BookmarkService.java | 5 +-
.../examples/services/command/Command.java | 87 +++++++++---
.../examples/services/command/CommandContext.java | 1 -
.../services/command/spi/CommandService.java | 13 +-
.../services/confview/ConfigurationMenu.java | 2 +
.../applib-svc/pages/AcceptHeaderService.adoc | 4 +-
.../pages/ApplicationFeatureRepository.adoc | 2 +-
.../modules/applib-svc/pages/AuditerService.adoc | 1 -
.../modules/applib-svc/pages/BookmarkService.adoc | 23 +--
.../modules/applib-svc/pages/ClockService.adoc | 2 -
.../modules/applib-svc/pages/CommandContext.adoc | 157 +++++++++------------
.../modules/applib-svc/pages/CommandService.adoc | 48 +------
.../applib-svc/pages/ConfigurationMenu.adoc | 11 +-
.../applib-svc/pages/ConfigurationViewService.adoc | 17 +++
.../modules/applib-svc/pages/EmailService.adoc | 2 +-
.../applib-svc/pages/InteractionContext.adoc | 6 +-
.../modules/applib-svc/pages/MetricsService.adoc | 2 +-
.../modules/applib-svc/pages/PublisherService.adoc | 2 +-
.../main/adoc/modules/applib-svc/pages/about.adoc | 2 +-
.../isis/applib/annotation/CommandExecuteIn.java | 21 ++-
.../isis/applib/annotation/CommandPersistence.java | 13 ++
.../isis/applib/services/bookmark/Bookmark.java | 17 ++-
.../applib/services/bookmark/BookmarkHolder.java | 2 -
.../applib/services/bookmark/BookmarkService.java | 7 +-
.../isis/applib/services/command/Command.java | 89 +++++++++---
.../applib/services/command/CommandContext.java | 11 +-
.../services/command/spi/CommandService.java | 13 +-
.../services/confview/ConfigurationMenu.java | 10 +-
.../pages/ApplicationFeatureFactory.adoc | 4 +-
...ceInternal.adoc => AuditerDispatchService.adoc} | 12 +-
.../pages/ChangedObjectsService.adoc | 8 +-
...hService.adoc => PublisherDispatchService.adoc} | 12 +-
.../partials/_persistence-layer.adoc | 8 +-
.../runtime-services/partials/module-nav.adoc | 13 +-
.../adoc/modules/command-log/pages/about.adoc | 29 +++-
40 files changed, 441 insertions(+), 272 deletions(-)
diff --git a/antora/supplemental-ui/css/site-custom.css b/antora/supplemental-ui/css/site-custom.css
index 9c15656..206b737 100644
--- a/antora/supplemental-ui/css/site-custom.css
+++ b/antora/supplemental-ui/css/site-custom.css
@@ -2,6 +2,10 @@ div.paragraph code {
color: darkmagenta;
}
+div.paragraph a code {
+ color: cornflowerblue;
+}
+
.content .ulist {
margin-top: 0.2rem;
}
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
index 789ab07..d416983 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
@@ -28,17 +28,25 @@ package org.apache.isis.applib.annotation;
* {@link org.apache.isis.applib.annotation.Collection}.
* </p>
*/
+// tag::refguide[]
public enum CommandExecuteIn {
+// end::refguide[]
/**
* Execute synchronously in the "foreground", wait for the results.
*/
+// tag::refguide[]
FOREGROUND,
+// end::refguide[]
+
/**
* Execute "asynchronously" through the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, returning (if possible) the
* persisted {@link org.apache.isis.applib.services.command.Command command} object as a placeholder to the
* result.
*/
+// tag::refguide[]
BACKGROUND,
+// end::refguide[]
+
/**
* For commands that are replicated from a master onto a slave and are to be replayed (typically using the same
* mechanism as "regular" background commands, eg a background job).
@@ -47,13 +55,18 @@ public enum CommandExecuteIn {
* For framework use, not intended to be used in application code.
* </p>
*/
+// tag::refguide[]
REPLAYABLE,
+// end::refguide[]
+
/**
* For commands that have been excluded and will not run.
* These are typically for a replayable command that has hit an exception (which normally would prevent any further
* replayable commands from being replayed) and which the administrator has decided to skip.
*/
+// tag::refguide[]
EXCLUDED
+// end::refguide[]
;
public boolean isForeground() { return this == FOREGROUND; }
@@ -63,17 +76,13 @@ public enum CommandExecuteIn {
public static class Type {
-
private Type() {}
-
public static class Meta {
-
public static final int MAX_LEN = 10;
-
private Meta() {}
-
}
}
-
+// tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
index d8121f7..b518f5a 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
@@ -21,23 +21,36 @@ package org.apache.isis.applib.annotation;
/**
* Whether the command should be persisted.
*/
+// tag::refguide[]
public enum CommandPersistence {
+// end::refguide[]
+
/**
* (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should be persisted.
*/
+// tag::refguide[]
PERSISTED,
+// end::refguide[]
+
/**
* (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should only be persisted if
* another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should.
*/
+// tag::refguide[]
IF_HINTED,
+// end::refguide[]
+
/**
* (Even if the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should <i>not</i> be persisted (even if
* another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should).
*/
+// tag::refguide[]
NOT_PERSISTED;
+// end::refguide[]
+// tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
index d252b98..481db35 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
@@ -43,6 +43,7 @@ import lombok.val;
// tag::refguide[]
public class Bookmark implements Serializable {
+// end::refguide[]
private static final long serialVersionUID = 2L;
protected static final String SEPARATOR = ":";
@@ -51,32 +52,43 @@ public class Bookmark implements Serializable {
* corresponds directly to the object's specification-id
* @see <code>RootOid</code>
*/
+// tag::refguide[]
@NonNull private final String objectType;
@NonNull private final String identifier;
+// end::refguide[]
@Nullable private final String hintId;
+// tag::refguide[]
public static Bookmark of(String objectType, String identifier) {
return new Bookmark(objectType, identifier, /*hintId*/ null);
}
+ // ...
+
+// end::refguide[]
/**
* Round-trip with {@link #toString()} representation.
*/
+// tag::refguide[]
public static Optional<Bookmark> parse(@Nullable String str) {
+// end::refguide[]
if(str==null) {
return Optional.empty();
}
val tokenizer = new StringTokenizer(str, SEPARATOR);
int tokenCount = tokenizer.countTokens();
if(tokenCount==2) {
- return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken()));
+ return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken()));
}
if(tokenCount>2) {
- return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken("").substring(1)));
+ return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken("").substring(1)));
}
return Optional.empty();
+// tag::refguide[]
+ // ...
}
+// end::refguide[]
public OidDto toOidDto() {
val oidDto = new OidDto();
@@ -110,5 +122,6 @@ public class Bookmark implements Serializable {
return objectType + SEPARATOR + id;
}
+// tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder.java
index e1e01e7..64a8db8 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder.java
@@ -22,8 +22,6 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface BookmarkHolder {
-
Bookmark bookmark();
-
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
index 38f3be8..1751729 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
@@ -34,6 +34,7 @@ import lombok.val;
// tag::refguide[]
public interface BookmarkService {
+// end::refguide[]
/**
* Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
* was created for.
@@ -43,6 +44,7 @@ public interface BookmarkService {
* @param domainObject
* @return optionally a {@link Bookmark} representing given {@code domainObject}
*/
+// tag::refguide[]
Bookmark bookmarkFor(@Nullable Object domainObject);
default Bookmark bookmarkForElseThrow(Object domainObject) {
@@ -58,16 +60,17 @@ public interface BookmarkService {
// ...
}
-
Bookmark bookmarkFor(Class<?> cls, String identifier);
Object lookup(BookmarkHolder bookmarkHolder);
Object lookup(Bookmark bookmark);
+// end::refguide[]
/**
* As {@link #lookup(Bookmark)}, but down-casting to the specified type.
*/
+// tag::refguide[]
default <T> T lookup(Bookmark bookmark, Class<T> cls) {
return cls.cast(lookup(bookmark));
}
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
index 61644f6..2d441f9 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
@@ -96,15 +96,22 @@ import org.apache.isis.schema.cmd.v2.CommandDto;
// tag::refguide[]
public interface Command extends HasUniqueId {
+ // end::refguide[]
/**
* The user that created the command.
*/
- String getUser();
+ // tag::refguide[]
+ String getUser(); // <.>
+ // end::refguide[]
/**
+ *
* The date/time at which this command was created.
+ *
*/
- Timestamp getTimestamp();
+ // tag::refguide[]
+ Timestamp getTimestamp(); // <.>
+ // end::refguide[]
/**
* {@link Bookmark} of the target object (entity or service) on which this action was performed.
@@ -112,59 +119,87 @@ public interface Command extends HasUniqueId {
* <p>
* Will only be populated if a {@link BookmarkService} has been configured.
*/
- Bookmark getTarget();
+ // tag::refguide[]
+ Bookmark getTarget(); // <.>
+ // end::refguide[]
/**
+ *
* Holds a string representation of the invoked action, or the edited property, equivalent to
* {@link Identifier#toClassAndNameIdentityString()}.
*/
- String getMemberIdentifier();
+ // tag::refguide[]
+ String getMemberIdentifier(); // <.>
+ // end::refguide[]
/**
+ *
* A human-friendly description of the class of the target object.
*/
- String getTargetClass();
+ // tag::refguide[]
+ String getTargetClass(); // <.>
+ // end::refguide[]
/**
+ *
* The human-friendly name of the action invoked/property edited on the target object.
*
* <p>
* NB: in earlier versions, if the command represented an edit of a property, then it held the special value "{@value ACTION_IDENTIFIER_FOR_EDIT}". This is NO LONGER the case; it simply holds the member.
* </p>
*/
- String getTargetAction();
+ // tag::refguide[]
+ String getTargetAction(); // <.>
+ // end::refguide[]
/**
+ *
* A human-friendly description of the arguments with which the action was invoked.
*/
- String getArguments();
+ // tag::refguide[]
+ String getArguments(); // <.>
+ // end::refguide[]
/**
+ *
* A formal (XML or similar) specification of the action to invoke/being invoked.
*/
- String getMemento();
+ // tag::refguide[]
+ String getMemento(); // <.>
+ // end::refguide[]
/**
+ *
* The mechanism by which this command is to be executed, either synchronously "in the
* {@link CommandExecuteIn#FOREGROUND foreground}" or is to be executed asynchronously "in the
* {@link CommandExecuteIn#BACKGROUND background}" through the {@link BackgroundCommandService}.
*/
- CommandExecuteIn getExecuteIn();
+ // tag::refguide[]
+ CommandExecuteIn getExecuteIn(); // <.>
+ // end::refguide[]
+ // tag::refguide2[]
enum Executor {
+ // end::refguide2[]
/**
* Command being executed by the end-user.
*/
+ // tag::refguide2[]
USER,
+ // end::refguide2[]
/**
* Command being executed by a background execution service.
*/
+ // tag::refguide2[]
BACKGROUND,
+ // end::refguide2[]
/**
* Command being executed for some other reason, eg as result of redirect-after-post, or the homePage action.
*/
+ // tag::refguide2[]
OTHER
}
+ // end::refguide2[]
/**
* The (current) executor of this command.
@@ -185,7 +220,9 @@ public interface Command extends HasUniqueId {
* </ul>
*
*/
- Executor getExecutor();
+ // tag::refguide[]
+ Executor getExecutor(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the date/time at which the {@link Interaction} that
@@ -200,7 +237,9 @@ public interface Command extends HasUniqueId {
* See also {@link Interaction#getCurrentExecution()} and
* {@link Interaction.Execution#getStartedAt()}.
*/
- Timestamp getStartedAt();
+ // tag::refguide[]
+ Timestamp getStartedAt(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the date/time at which the {@link Interaction} that
@@ -215,13 +254,17 @@ public interface Command extends HasUniqueId {
* See also {@link Interaction#getCurrentExecution()} and
* {@link Interaction.Execution#getCompletedAt()}.
*/
- Timestamp getCompletedAt();
+ // tag::refguide[]
+ Timestamp getCompletedAt(); // <.>
+ // end::refguide[]
/**
* For actions created through the {@link BackgroundService} and {@link BackgroundCommandService},
* captures the parent action.
*/
- Command getParent();
+ // tag::refguide[]
+ Command getParent(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the exception stack
@@ -235,7 +278,9 @@ public interface Command extends HasUniqueId {
*
* See also {@link Interaction#getCurrentExecution()} and {@link org.apache.isis.applib.services.iactn.Interaction.Execution#getThrew()}.
*/
- String getException();
+ // tag::refguide[]
+ String getException(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds a {@link Bookmark} to the object returned by the corresponding action/property modification.
@@ -248,7 +293,9 @@ public interface Command extends HasUniqueId {
*
* See also {@link Interaction#getCurrentExecution()} and {@link org.apache.isis.applib.services.iactn.Interaction.Execution#getReturned()}.
*/
- Bookmark getResult();
+ // tag::refguide[]
+ Bookmark getResult(); // <.>
+ // end::refguide[]
/**
* Whether this command should ultimately be persisted (if the configured {@link BackgroundCommandService} supports
@@ -273,13 +320,16 @@ public interface Command extends HasUniqueId {
* {@link Command}. The hinting mechanism allows the service to suggest that the parent command be persisted so
* that the app can then provide a mechanism to find all child background commands for that original parent command.
*/
- CommandPersistence getPersistence();
+ // tag::refguide[]
+ CommandPersistence getPersistence(); // <.>
+ // end::refguide[]
/**
* Whether that this {@link Command} should be persisted, if possible.
*/
- boolean isPersistHint();
-// end::refguide[]
+ // tag::refguide[]
+ boolean isPersistHint(); // <.>
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
@@ -416,7 +466,6 @@ public interface Command extends HasUniqueId {
* @see #getPersistence()
*/
void setPersistHint(boolean persistHint);
-
}
/**
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
index 9e1242b..1eb6f24 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
@@ -69,7 +69,6 @@ public class CommandContext {
}
// tag::refguide[]
-
@Getter
private Command command;
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
index ac53347..8afa756 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
@@ -26,6 +26,7 @@ import org.apache.isis.applib.services.command.Command;
// tag::refguide[]
public interface CommandService {
+// end::refguide[]
/**
* Simply instantiates the appropriate instance of the {@link Command}.
*
@@ -34,13 +35,17 @@ public interface CommandService {
* {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
* </p>
*/
- Command create();
+// tag::refguide[]
+ Command create(); // <.>
+// end::refguide[]
/**
* Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
* of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
*/
- boolean persistIfPossible(Command command);
+// tag::refguide[]
+ boolean persistIfPossible(Command command); // <.>
+// end::refguide[]
/**
* "Complete" the command, typically meaning to indicate that the command is completed, and to
@@ -54,7 +59,7 @@ public interface CommandService {
* The framework will automatically have set the {@link Command#getCompletedAt()} property.
* </p>
*/
- void complete(final Command command);
-
+// tag::refguide[]
+ void complete(final Command command); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
index a400a9f..cbbd0e6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
@@ -38,6 +38,7 @@ import org.apache.isis.applib.annotation.SemanticsOf;
@DomainServiceLayout(menuBar = DomainServiceLayout.MenuBar.TERTIARY)
public class ConfigurationMenu {
+ // end::refguide[]
public static abstract class ActionDomainEvent
extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
@@ -51,6 +52,7 @@ public class ConfigurationMenu {
public static class ConfigurationDomainEvent
extends ActionDomainEvent {}
+ // tag::refguide[]
@Action(
domainEvent = ConfigurationDomainEvent.class,
semantics = SemanticsOf.SAFE
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService.adoc
index 744d3ad..2db2f1f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService.adoc
@@ -6,9 +6,9 @@
The `AcceptHeaderService` domain service is a xref:refguide:applib-ant:RequestScoped.adoc[`@RequestScoped`] service that simply exposes the HTTP `Accept` header to the domain.
Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.
-[NOTE]
+[TIP]
====
-As an alternative to performing content negotiation within the domain classes, the xref:core:runtime-services:ContentNegotiationService.adoc[`ContentNegotiationService`] and xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] SPI domain services allow the framework to perform the content negotiation responsibility.
+As an alternative to performing content negotiation within the domain classes, the xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] SPI domain service allows the framework to perform the content negotiation responsibility.
====
== API
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository.adoc
index 726bf8a..306976a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository.adoc
@@ -35,6 +35,6 @@ This implementation supports the following configuration properties:
== Related Services
-The default implementation of this service uses the internal `o.a.i.core.metamodel.services.appfeat.ApplicationFeatureFactory` service to instantiate `ApplicationFeature` instances.
+The default implementation of this service uses the internal xref:core:runtime-services:ApplicationFeatureFactory.adoc[`ApplicationFeatureFactory`] service to instantiate `ApplicationFeature` instances.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/AuditerService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/AuditerService.adoc
index f130269..9d08148 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/AuditerService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/AuditerService.adoc
@@ -1,4 +1,3 @@
-[[AuditerService]]
= `AuditerService`
: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:
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService.adoc
index f47c001..9ef5234 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService.adoc
@@ -3,17 +3,13 @@
:page-partial:
-The `BookmarkService` domain service (and its various supertypes) provides the ability to obtain a serializable ``o.a.i.applib.bookmarks.Bookmark`` for any (persisted) domain object, and to lookup domain objects given a ``Bookmark``.
+The `BookmarkService` domain service (and its various supertypes) provides the ability to obtain a serializable xref:BookmarkService.adoc#bookmark[`Bookmark`] for any (persisted) domain object, and to lookup domain objects given a xref:BookmarkService.adoc#bookmark[`Bookmark`].
This can then in turn be converted to and from a string.
-For example, a `Customer` object with:
+For example, a `Customer` object with an xref:refguide:applib-ant:DomainObject.adoc#objectType[object type] of "custmgmt.Customer" and an id of 123
+would correspond to a xref:BookmarkService.adoc#bookmark[`Bookmark`] with a string representation of "custmgmt.Customer|123".
-* an object type of "custmgmt.Customer" (as per xref:refguide:applib-ant:DomainObject.adoc#objectType[`DomainObject#objectType`] or equivalent) , and
-* an id=123
-
-could correspond to a `Bookmark` with a string representation of `custmgmt.Customer|123`.
-
-``Bookmark``s are useful to store a reference to an arbitrary object, although be aware that there is no referential integrity.
+Bookmarks are useful to store a reference to an arbitrary object, although be aware that there is no referential integrity.
Several of the extension libraries use bookmarks.
For example the xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] uses bookmarks to identify the object that is being modified.
@@ -32,6 +28,15 @@ The API defined by `BookmarkService` is:
include::refguide:applib-svc:example$services/bookmark/BookmarkService.java[tags="refguide"]
----
+=== `Bookmark`
+
+The `Bookmark` type is:
+
+[source,java]
+----
+include::refguide:applib-svc:example$services/bookmark/Bookmark.java[tags="refguide"]
+----
+
== Implementation
@@ -40,8 +45,6 @@ The core framework (xref:core:runtime-services:about.adoc[Runtime Services] modu
== Related Mixins
-=== `BookmarkHolder`
-
The `BookmarkHolder` interface is intended to be implemented by domain objects that use a `Bookmark` to reference a (single) domain object; an example might be a class such as the audit entry, mentioned above.
The interface is simply:
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc
index 76f761f..55ddf5a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc
@@ -34,5 +34,3 @@ Note that this domain service is also used by the framework itself to obtain the
This class (`o.a.i.applib.services.clock.ClockService`) is also the default implementation.
The time provided by this default implementation is based on the system clock.
-
-
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
index 07807aa..a8db91d 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandContext.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandContext.adoc
@@ -5,13 +5,13 @@
The `CommandContext` service is a xref:refguide:applib-ant:RequestScoped.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 `Command` object.
+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 `Command` to be pluggable.
+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 `Command` may then be persisted.
+the xref:CommandContext.adoc#command[`Command`] instance may then be persisted.
There are two main use cases:
@@ -21,12 +21,7 @@ There are two main use cases:
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.
-Commands 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 xref:refguide:applib-svc:PublisherService.adoc[`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 xref:refguide:applib-svc:AuditerService.adoc[`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
-In general, though, However, while persistent ``Command``s _can_ be used for these use cases, it is recommended instead to use the xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`] service and persistent implementations of the ``Interaction`` object, eg as provided by the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s publishmq module.
@@ -53,64 +48,51 @@ The `CommandContext` request-scoped service defines the following very simple AP
[source,java]
----
-@RequestScoped
-public class CommandContext {
- @Programmatic
- public Command getCommand() { /* ... */ }
-}
+include::refguide:applib-svc:example$services/command/CommandContext.java[tags="refguide"]
----
-The `Command` type referenced above is in fact an interface, defined as:
+=== `Command`
+
+The `Command` type in turn is defined as:
[source,java]
----
-public interface Command extends HasUniqueId {
-
- public abstract String getUser(); // <.>
- public abstract Timestamp getTimestamp(); // <.>
-
- public abstract Bookmark getTarget(); // <.>
- public abstract String getMemberIdentifier(); // <.>
- public abstract String getTargetClass(); // <.>
- public abstract String getTargetAction(); // <.>
- public String getArguments(); // <.>
- public String getMemento(); // <.>
-
- public ExecuteIn getExecuteIn(); // <.>
- public Executor getExecutor(); // <.>
- public Persistence getPersistence(); // <.>
- public boolean isPersistHint(); // <.>
-
- public abstract Timestamp getStartedAt(); // <.>
- public abstract Timestamp getCompletedAt(); // <.>
- public Command getParent(); // <.>
+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"]
+----
- public Bookmark getResult(); // <.>
- public String getException(); // <.>
+<.> whether that the command should be persisted, if persistence policy is "if hinted".
- @Deprecated
- int next(final String sequenceAbbr); // <.>
-}
-----
-<.> `getUser()` - is the user that initiated the action.
-<.> `getTimestamp()` - the date/time at which this action was created.
-<.> `getTarget()` - bookmark of the target object (entity or service) on which this action was performed
-<.> `getMemberIdentifier()` - holds a string representation of the invoked action
-<.> `getTargetClass()` - a human-friendly description of the class of the target object
-<.> `getTargetAction()` - a human-friendly name of the action invoked on the target object
-<.> `getArguments()` - a human-friendly description of the arguments with which the action was invoked
-<.> `getMemento()` - a formal (XML or similar) specification of the action to invoke/being invoked
-<.> `getExecuteIn()` - whether this command is executed in the foreground or background
-<.> `getExecutor()` - the (current) executor of this command, either user, or background service, or other (eg redirect after post).
-<.> `getPersistence()`- the policy controlling whether this command should ultimately be persisted (either "persisted", "if hinted", or "not persisted")
-<.> `isPersistHint()` - whether that the command should be persisted, if persistence policy is "if hinted".
-<.> `getStartedAt()` - the date/time at which this action started (same as `timestamp` property for foreground commands)
-<.> `getCompletedAt()` - the date/time at which this action completed.
-<.> `getParent()` - for actions created through the `BackgroundService`, captures the parent action
-<.> `getResult()` - bookmark to object returned by action, if any
-<.> `getException()` - exception stack trace if action threw exception
-<.> No longer used by the framework; see instead
-xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`] and `Interaction#next()`.
== Implementation
@@ -133,12 +115,7 @@ public class ToDoItem ... {
----
-[TIP]
-====
-As an alternative to annotating every action with `@Action#command()`, alternatively this can be configured as the default using `isis.services.command.actions` configuration property.
-
-See xref:refguide:applib-ant:Action.adoc#command[`@Action#command()`] and xref:refguide:config:configuring-core.adoc[runtime configuration] for further details.
-====
+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.
//The xref:refguide:applib-ant:Action.adoc#command[`@Action#command()`] annotation can also be used to specify whether the command should be performed in the background, for example:
@@ -190,24 +167,24 @@ 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 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();
-----
+//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();
+//----
@@ -215,14 +192,20 @@ String user = commandContext.getCommand().getUser();
== Related Services
-The xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service 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 `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.
+The xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service is very similar in nature to the xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`], in that the xref:refguide:applib-svc:CommandContext.adoc#command[`Command`] object accessed through it is very similar to the xref:refguide:applib-svc:InteractionContext.adoc#interaction[`Interaction`] object obtained from the xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`].
+The principle distinction is that while xref:refguide:applib-svc:CommandContext.adoc#command[`Command`] represents the __intention__ to invoke an action or edit a property, the xref:refguide:applib-svc:InteractionContext.adoc#interaction[`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:refguide:applib-ant:Action.adoc#command[`@Action#commandExecuteIn()`], or is explicitly created through the xref:refguide:applib-svc:BackgroundService.adoc[`BackgroundService`], then the actual interaction/execution is deferred until some other mechanism invokes the command (eg as described xref:userguide:btb:about.adoc#BackgroundCommandExecution[here]).
//The persistence of background commands requires a configured xref:refguide:applib-svc:_BackgroundCommandService.adoc[`BackgroundCommandService`]) to actually persist such commands for execution.
-``Command``s
+xref:refguide:applib-svc:CommandContext.adoc#command[`Command`]s
//- even if executed in the foreground -
can also be persisted by way of the xref:refguide:applib-svc:CommandService.adoc[`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:refguide:applib-svc:BackgroundService.adoc[`BackgroundService`]).
+
+Commands 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 xref:refguide:applib-svc:PublisherService.adoc[`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 xref:refguide:applib-svc:AuditerService.adoc[`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/api/applib/src/main/adoc/modules/applib-svc/pages/CommandService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandService.adoc
index 631f22a..bde3e44 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandService.adoc
@@ -3,12 +3,11 @@
:page-partial:
-
-The `CommandService` service supports the xref:refguide:applib-svc:CommandContext.adoc[`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:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service such that xref:refguide:applib-svc:CommandContext.adoc#command[`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:refguide:applib-svc:BackgroundService.adoc[`BackgroundService`], or implicitly by way of the xref:refguide:applib-ant:Action.adoc#command[`@Action#command()`] annotation.
-Persistent ``Command``s
+``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).
@@ -25,8 +24,6 @@ better traceability as the `Command` is also correlated with any published event
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:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`] service and persistent implementations of the ``Interaction`` object, eg as provided by the (non-ASF) link:https://platform.incode.org[Incode Platform^]'s publishmq module.
-
@@ -36,17 +33,13 @@ The `CommandService` service defines the following very simple API:
[source,java]
----
-public interface CommandService {
- Command create(); // <1>
- boolean persistIfPossible(Command command); // <2>
- void complete(Command command); // <3>
-}
+include::refguide:applib-svc:example$services/command/spi/CommandService.java[tags="refguide"]
----
-<1> Instantiate the appropriate instance of the `Command` (as defined by the
+<.> Instantiate the appropriate instance of the xref:refguide:applib-svc:CommandContext.adoc#command[`Command`] (as defined by the
xref:refguide:applib-svc:CommandContext.adoc[`CommandContext`] service).
Its members will be populated automatically by the framework.
-<2> Set the hint that the `Command` should be persisted if possible (when completed, see below).
-<3> "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. +
+<.> Set the hint that the `Command` should be persisted if possible (when completed, see below).
+<.> "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`.
@@ -54,34 +47,7 @@ The framework will automatically have set the `completedAt` property of the `Com
== Implementation
-WARNING: TODO: v2 - this is to move into the xref:mappings:ROOT:about.adoc[mappings catalogue].
-
-The (non-ASF) link:https://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
-
-* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
-
-//* implementation of the
-//xref:refguide:applib-svc:CommandService.adoc[`BackgroundCommandService`].
-
-All of these can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:about.adoc#vetoing-visibility[vetoing subscriber].
-
-
-
-=== Alternatives
-
-WARNING: TODO: v2 - this is to move into the xref:mappings:ROOT:about.adoc[mappings catalogue].
-
-The (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module provides an implementation of this service (`CommandService`), and also provides a number of related domain services (`CommandJdoRepository` and `CommandServiceJdoContributions`).
-//This module also provides service implementations of the xref:refguide:applib-svc:CommandService.adoc[`BackgroundCommandService`].
-
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:about.adoc#vetoing-visibility[vetoing subscriber].
-
-
+The xref:extensions:command-log:about.adoc[Command Log] extension provides an implementation of this service that persists commands to a database table.
== Related Services
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationMenu.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationMenu.adoc
index 923bc38..88993f1 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationMenu.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationMenu.adoc
@@ -2,15 +2,6 @@
: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:
+See xref:refguide:applib-svc:ConfigurationViewService.adoc[`ConfigurationViewService`].
-WARNING: TODO: v2: to document - UI to surface ConfigurationViewService; returns `ConfigurationProperty` view model.
-
-== API
-
-== Implementation
-
-== Related Services
-
-The configuration properties can also be obtained from the xref:refguide:config:about.adoc#isisconfiguration-domain-service[`IsisConfiguration`] domain service.
-These provide type-safe access to all `isis.*` configuration properties.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationViewService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationViewService.adoc
index 8aaa1dd..cbf9ae0 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationViewService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ConfigurationViewService.adoc
@@ -6,3 +6,20 @@
WARNING: TODO: v2: to document - backing service for ConfigurationMenu; returns `ConfigurationProperty` view model. Only returns `isis.\*` and `resteasy.*`
+== API
+
+[source,java]
+----
+include::refguide:applib-svc:example$services/confview/ConfigurationViewService.java[tags="refguide"]
+----
+
+
+== Implementation
+
+== Related Services
+
+The `ConfigurationMenu` provides a UI to acces
+
+
+The configuration properties can also be obtained from the xref:refguide:config:about.adoc#isisconfiguration-domain-service[`IsisConfiguration`] domain service.
+These provide type-safe access to all `isis.*` configuration properties.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/EmailService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/EmailService.adoc
index d67ceda..f93776d 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/EmailService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/EmailService.adoc
@@ -40,7 +40,7 @@ This sends email as an HTML message, using an external SMTP provider.
=== Configuration Properties
The default implementation defines the a number of configuration properties, under the `isis.core.runtime-services.email` key.
-See the xref:refguide:config:sections/isis.core.runtime-services.adoc#isis.core.runtime-services.email.port[configuration guide] for further details.
+See the xref:refguide:config:about.adoc[configuration guide] for further details.
=== Alternatives
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/InteractionContext.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/InteractionContext.adoc
index ac366c9..01bb334 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/InteractionContext.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/InteractionContext.adoc
@@ -31,7 +31,7 @@ of the interaction) by way of the xref:refguide:applib-cm:classes/mixins.adoc#Ha
-== API & Implementation
+== API
The public API of the service consists of several related classes:
@@ -164,9 +164,9 @@ public class PropertyEdit extends Execution {
<1> The object used as the new value of the property. Could be `null` if the property is being cleared.
-=== Alternate Implementations
+== Implementation
-Apache Isis' default implementation of `InteractionContext` class is automatically registered (it is annotated with `@DomainService`).
+This class (`o.a.i.applib.services.iactn.InteractionContext`) is also the default implementation.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/MetricsService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/MetricsService.adoc
index 0b8869f..95a7d6b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/MetricsService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/MetricsService.adoc
@@ -7,7 +7,7 @@
The `MetricsService` 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:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:core:runtime-services:PublishingServiceInternal.adoc[`PublishingServiceInternal`] domain service (to populate the `PublishedObjects` class.
+The service is used by the xref:refguide:applib-svc:InteractionContext.adoc[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] domain service (to populate the `PublishedObjects` class.
== API & Implementation
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/PublisherService.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/PublisherService.adoc
index 00d988e..1b31592 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/PublisherService.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/PublisherService.adoc
@@ -126,7 +126,7 @@ To support these use cases several other services are involved:
* the (internal) xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsService`] domain service is used to obtain the set of objects modified throughout the transaction
-* the (internal) xref:core:runtime-services:PublishingDispatchService.adoc[`PublisherDispatchService`] domain service filters these down to those changed objects that are also published (as per xref:refguide:applib-ant:DomainObject.adoc#publishing[`@DomainObject#publishing()`]) and delegates to the `PublisherService`.
+* the (internal) xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] domain service filters these down to those changed objects that are also published (as per xref:refguide:applib-ant:DomainObject.adoc#publishing[`@DomainObject#publishing()`]) and delegates to the `PublisherService`.
* the xref:refguide:applib-svc:MetricsService.adoc[`MetricsService`] is used to obtain the objects that are loaded throughout the transaction; this info is used in order to instantiate the `PublishedObjects` object passed through to the `PublisherService`.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/about.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/about.adoc
index 9a86c5e..3cbd717 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/about.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/about.adoc
@@ -181,7 +181,7 @@ Only domain objects specified to be published with xref:refguide:applib-ant:Doma
Note that it's possible for there to be more than one transaction per top-level interaction, by virtue of the xref:refguide:applib-svc:TransactionService.adoc[`TransactionService`].
====
-* Also at the end of each transaction, details of all changed properties are passed to any registered xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s) by way of the (internal) xref:core:runtime-services:AuditingServiceInternal.adoc[`AuditingServiceInternal`] domain service.
+* Also at the end of each transaction, details of all changed properties are passed to any registered xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s) by way of the (internal) xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] domain service.
Implementations of xref:refguide:applib-svc:CommandService.adoc[`CommandService`] can use the `Command#getMemento()` method to obtain a XML equivalent of that `Command`, reified using the xref:refguide:schema:cmd.adoc[`cmd.xsd`] schema.
This can be converted back into a `CommandDto` using the `CommandDtoUtils` utility class (part of the applib).
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
index 789ab07..d416983 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
@@ -28,17 +28,25 @@ package org.apache.isis.applib.annotation;
* {@link org.apache.isis.applib.annotation.Collection}.
* </p>
*/
+// tag::refguide[]
public enum CommandExecuteIn {
+// end::refguide[]
/**
* Execute synchronously in the "foreground", wait for the results.
*/
+// tag::refguide[]
FOREGROUND,
+// end::refguide[]
+
/**
* Execute "asynchronously" through the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, returning (if possible) the
* persisted {@link org.apache.isis.applib.services.command.Command command} object as a placeholder to the
* result.
*/
+// tag::refguide[]
BACKGROUND,
+// end::refguide[]
+
/**
* For commands that are replicated from a master onto a slave and are to be replayed (typically using the same
* mechanism as "regular" background commands, eg a background job).
@@ -47,13 +55,18 @@ public enum CommandExecuteIn {
* For framework use, not intended to be used in application code.
* </p>
*/
+// tag::refguide[]
REPLAYABLE,
+// end::refguide[]
+
/**
* For commands that have been excluded and will not run.
* These are typically for a replayable command that has hit an exception (which normally would prevent any further
* replayable commands from being replayed) and which the administrator has decided to skip.
*/
+// tag::refguide[]
EXCLUDED
+// end::refguide[]
;
public boolean isForeground() { return this == FOREGROUND; }
@@ -63,17 +76,13 @@ public enum CommandExecuteIn {
public static class Type {
-
private Type() {}
-
public static class Meta {
-
public static final int MAX_LEN = 10;
-
private Meta() {}
-
}
}
-
+// tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
index d8121f7..b518f5a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
@@ -21,23 +21,36 @@ package org.apache.isis.applib.annotation;
/**
* Whether the command should be persisted.
*/
+// tag::refguide[]
public enum CommandPersistence {
+// end::refguide[]
+
/**
* (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should be persisted.
*/
+// tag::refguide[]
PERSISTED,
+// end::refguide[]
+
/**
* (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should only be persisted if
* another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should.
*/
+// tag::refguide[]
IF_HINTED,
+// end::refguide[]
+
/**
* (Even if the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
* {@link org.apache.isis.applib.services.command.Command Command} object should <i>not</i> be persisted (even if
* another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should).
*/
+// tag::refguide[]
NOT_PERSISTED;
+// end::refguide[]
+// tag::refguide[]
}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
index d252b98..481db35 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
@@ -43,6 +43,7 @@ import lombok.val;
// tag::refguide[]
public class Bookmark implements Serializable {
+// end::refguide[]
private static final long serialVersionUID = 2L;
protected static final String SEPARATOR = ":";
@@ -51,32 +52,43 @@ public class Bookmark implements Serializable {
* corresponds directly to the object's specification-id
* @see <code>RootOid</code>
*/
+// tag::refguide[]
@NonNull private final String objectType;
@NonNull private final String identifier;
+// end::refguide[]
@Nullable private final String hintId;
+// tag::refguide[]
public static Bookmark of(String objectType, String identifier) {
return new Bookmark(objectType, identifier, /*hintId*/ null);
}
+ // ...
+
+// end::refguide[]
/**
* Round-trip with {@link #toString()} representation.
*/
+// tag::refguide[]
public static Optional<Bookmark> parse(@Nullable String str) {
+// end::refguide[]
if(str==null) {
return Optional.empty();
}
val tokenizer = new StringTokenizer(str, SEPARATOR);
int tokenCount = tokenizer.countTokens();
if(tokenCount==2) {
- return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken()));
+ return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken()));
}
if(tokenCount>2) {
- return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken("").substring(1)));
+ return Optional.of(Bookmark.of(tokenizer.nextToken(), tokenizer.nextToken("").substring(1)));
}
return Optional.empty();
+// tag::refguide[]
+ // ...
}
+// end::refguide[]
public OidDto toOidDto() {
val oidDto = new OidDto();
@@ -110,5 +122,6 @@ public class Bookmark implements Serializable {
return objectType + SEPARATOR + id;
}
+// tag::refguide[]
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder.java
index e1e01e7..64a8db8 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder.java
@@ -22,8 +22,6 @@ import org.apache.isis.applib.annotation.Programmatic;
// tag::refguide[]
public interface BookmarkHolder {
-
Bookmark bookmark();
-
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
index 38f3be8..ada7068 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
@@ -34,6 +34,7 @@ import lombok.val;
// tag::refguide[]
public interface BookmarkService {
+// end::refguide[]
/**
* Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
* was created for.
@@ -43,6 +44,7 @@ public interface BookmarkService {
* @param domainObject
* @return optionally a {@link Bookmark} representing given {@code domainObject}
*/
+// tag::refguide[]
Bookmark bookmarkFor(@Nullable Object domainObject);
default Bookmark bookmarkForElseThrow(Object domainObject) {
@@ -53,21 +55,22 @@ public interface BookmarkService {
return bookmark;
}
throw _Exceptions.illegalArgument(
- "cannot create bookmark for type %s", domainObject.getClass().getName());
+ "cannot create bookmark for type %s", domainObject.getClass().getName());
// tag::refguide[]
// ...
}
-
Bookmark bookmarkFor(Class<?> cls, String identifier);
Object lookup(BookmarkHolder bookmarkHolder);
Object lookup(Bookmark bookmark);
+// end::refguide[]
/**
* As {@link #lookup(Bookmark)}, but down-casting to the specified type.
*/
+// tag::refguide[]
default <T> T lookup(Bookmark bookmark, Class<T> cls) {
return cls.cast(lookup(bookmark));
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
index 61644f6..1230b7b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
@@ -96,15 +96,22 @@ import org.apache.isis.schema.cmd.v2.CommandDto;
// tag::refguide[]
public interface Command extends HasUniqueId {
+ // end::refguide[]
/**
* The user that created the command.
*/
- String getUser();
+ // tag::refguide[]
+ String getUser(); // <.>
+ // end::refguide[]
/**
+ *
* The date/time at which this command was created.
+ *
*/
- Timestamp getTimestamp();
+ // tag::refguide[]
+ Timestamp getTimestamp(); // <.>
+ // end::refguide[]
/**
* {@link Bookmark} of the target object (entity or service) on which this action was performed.
@@ -112,59 +119,87 @@ public interface Command extends HasUniqueId {
* <p>
* Will only be populated if a {@link BookmarkService} has been configured.
*/
- Bookmark getTarget();
+ // tag::refguide[]
+ Bookmark getTarget(); // <.>
+ // end::refguide[]
/**
+ *
* Holds a string representation of the invoked action, or the edited property, equivalent to
* {@link Identifier#toClassAndNameIdentityString()}.
*/
- String getMemberIdentifier();
+ // tag::refguide[]
+ String getMemberIdentifier(); // <.>
+ // end::refguide[]
/**
+ *
* A human-friendly description of the class of the target object.
*/
- String getTargetClass();
+ // tag::refguide[]
+ String getTargetClass(); // <.>
+ // end::refguide[]
/**
+ *
* The human-friendly name of the action invoked/property edited on the target object.
*
* <p>
* NB: in earlier versions, if the command represented an edit of a property, then it held the special value "{@value ACTION_IDENTIFIER_FOR_EDIT}". This is NO LONGER the case; it simply holds the member.
* </p>
*/
- String getTargetAction();
+ // tag::refguide[]
+ String getTargetAction(); // <.>
+ // end::refguide[]
/**
+ *
* A human-friendly description of the arguments with which the action was invoked.
*/
- String getArguments();
+ // tag::refguide[]
+ String getArguments(); // <.>
+ // end::refguide[]
/**
+ *
* A formal (XML or similar) specification of the action to invoke/being invoked.
*/
- String getMemento();
+ // tag::refguide[]
+ String getMemento(); // <.>
+ // end::refguide[]
/**
+ *
* The mechanism by which this command is to be executed, either synchronously "in the
* {@link CommandExecuteIn#FOREGROUND foreground}" or is to be executed asynchronously "in the
* {@link CommandExecuteIn#BACKGROUND background}" through the {@link BackgroundCommandService}.
*/
- CommandExecuteIn getExecuteIn();
+ // tag::refguide[]
+ CommandExecuteIn getExecuteIn(); // <.>
+ // end::refguide[]
+ // tag::refguide2[]
enum Executor {
+ // end::refguide2[]
/**
* Command being executed by the end-user.
*/
+ // tag::refguide2[]
USER,
+ // end::refguide2[]
/**
* Command being executed by a background execution service.
*/
+ // tag::refguide2[]
BACKGROUND,
+ // end::refguide2[]
/**
* Command being executed for some other reason, eg as result of redirect-after-post, or the homePage action.
*/
+ // tag::refguide2[]
OTHER
}
+ // end::refguide2[]
/**
* The (current) executor of this command.
@@ -185,7 +220,9 @@ public interface Command extends HasUniqueId {
* </ul>
*
*/
- Executor getExecutor();
+ // tag::refguide[]
+ Executor getExecutor(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the date/time at which the {@link Interaction} that
@@ -200,7 +237,9 @@ public interface Command extends HasUniqueId {
* See also {@link Interaction#getCurrentExecution()} and
* {@link Interaction.Execution#getStartedAt()}.
*/
- Timestamp getStartedAt();
+ // tag::refguide[]
+ Timestamp getStartedAt(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the date/time at which the {@link Interaction} that
@@ -215,13 +254,17 @@ public interface Command extends HasUniqueId {
* See also {@link Interaction#getCurrentExecution()} and
* {@link Interaction.Execution#getCompletedAt()}.
*/
- Timestamp getCompletedAt();
+ // tag::refguide[]
+ Timestamp getCompletedAt(); // <.>
+ // end::refguide[]
/**
* For actions created through the {@link BackgroundService} and {@link BackgroundCommandService},
* captures the parent action.
*/
- Command getParent();
+ // tag::refguide[]
+ Command getParent(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds the exception stack
@@ -235,7 +278,9 @@ public interface Command extends HasUniqueId {
*
* See also {@link Interaction#getCurrentExecution()} and {@link org.apache.isis.applib.services.iactn.Interaction.Execution#getThrew()}.
*/
- String getException();
+ // tag::refguide[]
+ String getException(); // <.>
+ // end::refguide[]
/**
* For an command that has actually been executed, holds a {@link Bookmark} to the object returned by the corresponding action/property modification.
@@ -248,7 +293,9 @@ public interface Command extends HasUniqueId {
*
* See also {@link Interaction#getCurrentExecution()} and {@link org.apache.isis.applib.services.iactn.Interaction.Execution#getReturned()}.
*/
- Bookmark getResult();
+ // tag::refguide[]
+ Bookmark getResult(); // <.>
+ // end::refguide[]
/**
* Whether this command should ultimately be persisted (if the configured {@link BackgroundCommandService} supports
@@ -273,13 +320,16 @@ public interface Command extends HasUniqueId {
* {@link Command}. The hinting mechanism allows the service to suggest that the parent command be persisted so
* that the app can then provide a mechanism to find all child background commands for that original parent command.
*/
- CommandPersistence getPersistence();
+ // tag::refguide[]
+ CommandPersistence getPersistence(); // <.>
+ // end::refguide[]
/**
* Whether that this {@link Command} should be persisted, if possible.
*/
- boolean isPersistHint();
-// end::refguide[]
+ // tag::refguide[]
+ boolean isPersistHint(); // <.>
+ // end::refguide[]
/**
* <b>NOT API</b>: intended to be called only by the framework.
@@ -340,7 +390,7 @@ public interface Command extends HasUniqueId {
/**
* <b>NOT API</b>: intended to be called only by the framework.
*/
- void setExecutor(final Executor executor);
+ void setExecutor(final Executor executor);
/**
* <b>NOT API</b>: intended to be called only by the framework.
@@ -416,7 +466,6 @@ public interface Command extends HasUniqueId {
* @see #getPersistence()
*/
void setPersistHint(boolean persistHint);
-
}
/**
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
index 9e1242b..9716944 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
@@ -53,7 +53,7 @@ import lombok.extern.log4j.Log4j2;
@Log4j2
public class CommandContext {
-// end::refguide[]
+ // end::refguide[]
public CommandContext() {
log.debug("init");
}
@@ -68,8 +68,7 @@ public class CommandContext {
log.debug("preDestroy");
}
-// tag::refguide[]
-
+ // tag::refguide[]
@Getter
private Command command;
@@ -80,12 +79,12 @@ public class CommandContext {
public void setCommand(final Command command) {
this.command = command;
}
-
+
public Optional<Executor> getCurrentExecutor() {
return Optional.ofNullable(getCommand())
- .map(Command::getExecutor);
+ .map(Command::getExecutor);
}
-
+
// tag::refguide[]
}
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
index ac53347..8afa756 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
@@ -26,6 +26,7 @@ import org.apache.isis.applib.services.command.Command;
// tag::refguide[]
public interface CommandService {
+// end::refguide[]
/**
* Simply instantiates the appropriate instance of the {@link Command}.
*
@@ -34,13 +35,17 @@ public interface CommandService {
* {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
* </p>
*/
- Command create();
+// tag::refguide[]
+ Command create(); // <.>
+// end::refguide[]
/**
* Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
* of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
*/
- boolean persistIfPossible(Command command);
+// tag::refguide[]
+ boolean persistIfPossible(Command command); // <.>
+// end::refguide[]
/**
* "Complete" the command, typically meaning to indicate that the command is completed, and to
@@ -54,7 +59,7 @@ public interface CommandService {
* The framework will automatically have set the {@link Command#getCompletedAt()} property.
* </p>
*/
- void complete(final Command command);
-
+// tag::refguide[]
+ void complete(final Command command); // <.>
}
// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationMenu.java b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationMenu.java
index a400a9f..7e83574 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationMenu.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationMenu.java
@@ -38,8 +38,9 @@ import org.apache.isis.applib.annotation.SemanticsOf;
@DomainServiceLayout(menuBar = DomainServiceLayout.MenuBar.TERTIARY)
public class ConfigurationMenu {
+ // end::refguide[]
public static abstract class ActionDomainEvent
- extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
+ extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
private final ConfigurationViewService configurationService;
@@ -49,15 +50,16 @@ public class ConfigurationMenu {
}
public static class ConfigurationDomainEvent
- extends ActionDomainEvent {}
+ extends ActionDomainEvent {}
+ // tag::refguide[]
@Action(
domainEvent = ConfigurationDomainEvent.class,
semantics = SemanticsOf.SAFE
- )
+ )
@ActionLayout(
cssClassFa = "fa-wrench"
- )
+ )
@MemberOrder(sequence = "500.900.1")
public Set<ConfigurationProperty> configuration(){
return configurationService.allProperties();
diff --git a/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ApplicationFeatureFactory.adoc
similarity index 89%
copy from extensions/core/command-log/adoc/modules/command-log/pages/about.adoc
copy to core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ApplicationFeatureFactory.adoc
index eebc1a9..ed5fb14 100644
--- a/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/ApplicationFeatureFactory.adoc
@@ -1,5 +1,5 @@
-= Command Log
+= `ApplicationFeatureFactory`
: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 [...]
-WARNING: TODO: v2 - will move this into the framework, update these docs
+WARNING: TODO: v2 - to document
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditingServiceInternal.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditerDispatchService.adoc
similarity index 71%
rename from core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditingServiceInternal.adoc
rename to core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditerDispatchService.adoc
index e6bc323..9f01a06 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditingServiceInternal.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/AuditerDispatchService.adoc
@@ -1,8 +1,8 @@
-= `AuditingServiceInternal`
+= `AuditerDispatchService`
: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 [...]
-The (internal) `AuditingServiceInternal` domain service acts as an internal facade to any registered xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] service(s).
+The (internal) `AuditerDispatchService` domain service acts as an internal facade to any registered xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] service(s).
It is responsible for obtaining the details of all changes to domain objects within an interaction, and then to call the configured ``AuditerService``(s) to actually create audit entries of those changes.
@@ -14,7 +14,7 @@ The SPI of the service is:
[source,java]
----
-public class AuditingServiceInternal {
+public class AuditerDispatchService {
public boolean canAudit(); // <1>
public void audit(); // <2>
}
@@ -22,13 +22,13 @@ public class AuditingServiceInternal {
<1> minor performance optimization as to whether any auditing services are actually enabled; checks to see if any xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] are enabled.
<2> uses the xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s).
-The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
+The service implementation is `o.a.i.c.r.s.auditing.AuditerDispatchService`.
== Registering the Service
-Apache Isis' default implementation of `AuditingServiceInternal` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+Apache Isis' default implementation of `AuditerDispatchService` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
== Related Classes
@@ -36,4 +36,4 @@ Apache Isis' default implementation of `AuditingServiceInternal` class is automa
The service delegates between the (internal) xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsServiceInternal`] domain service to the configured xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`](s).
If no such service(s) are configured, then _this_ service is in effect a no-op.
-The (internal) xref:core:runtime-services:PublishingDispatchService.adoc[`PublishingServiceInternal`] performs a similar function for the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
+The (internal) xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] performs a similar function for the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
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 dded5c4..afc82fe 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
@@ -3,7 +3,7 @@
The `ChangedObjectsServiceInternal` class 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:core:runtime-services:AuditingServiceInternal.adoc[`AuditingServiceInternal`] and xref:core:runtime-services:PublishingDispatchService.adoc[`PublishingServiceInternal`].
+This is then used by various other (internal) domain services, notably xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] and xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`].
@@ -32,9 +32,9 @@ public class ChangedObjectsServiceInternal {
----
<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:PublishingDispatchService.adoc[`PublishingServiceInternal`] to obtain details of and
+<3> 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:AuditingServiceInternal.adoc[`AuditingServiceInternal`] to obtain all pairs of
+<4> 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.
@@ -55,4 +55,4 @@ Apache Isis' default implementation of `ChangedObjectsServiceInternal` class is
== Related Classes
-Both the xref:core:runtime-services:AuditingServiceInternal.adoc[`AuditingServiceInternal`] and xref:core:runtime-services:PublishingDispatchService.adoc[`PublishingServiceInternal`] (internal) domain services query this object.
+Both the xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] and xref:core:runtime-services:PublisherDispatchService.adoc[`PublisherDispatchService`] (internal) domain services query this object.
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublishingDispatchService.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublisherDispatchService.adoc
similarity index 80%
rename from core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublishingDispatchService.adoc
rename to core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublisherDispatchService.adoc
index f50b4c9..57db4ed 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublishingDispatchService.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/pages/PublisherDispatchService.adoc
@@ -1,8 +1,8 @@
-= `PublishingServiceInternal`
+= `PublisherDispatchService`
: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 [...]
-The (internal) `PublishingDispatchService` domain service acts as an internal facade to any configured xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`] domain service(s).
+The (internal) `PublisherDispatchService` domain service acts as an internal facade to any configured xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`] domain service(s).
For published action invocations/ property edits, it provides an API for those member executions to call.
@@ -15,7 +15,7 @@ The SPI of the service is:
[source,java]
----
-public class PublishingServiceInternal {
+public class PublisherDispatchService {
void publishAction( // <1>
Interaction.Execution execution);
void publishProperty( // <2>
@@ -30,13 +30,13 @@ The `Execution` object will be an instance of `PropertyEdit` (see xref:refguide:
<3> to publish all changed objects that are to be published (with the xref:refguide:applib-ant:DomainObject.adoc#publishing[`@DomainObject#publishing`] annotation attribute or equivalent).
-The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`.
+The service implementation is `o.a.i.c.m.s.publishing.PublisherDispatchService`.
== Registering the Service
-Apache Isis' default implementation of `PublishingServiceInternal` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+Apache Isis' default implementation of `PublisherDispatchService` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
To use an alternative implementation, use Spring's link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/annotation/Order.html[`@Order`] annotation (as explained in the xref:refguide:applib-svc:about.adoc#overriding-the-services.adoc[introduction] to this guide).
@@ -45,4 +45,4 @@ To use an alternative implementation, use Spring's link:https://docs.spring.io/s
The service delegates between the (internal) xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsServiceInternal`] domain service to the configured xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
-The (internal) xref:core:runtime-services:AuditingServiceInternal.adoc[`AuditingServiceInternal`] performs a similar function for the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
+The (internal) xref:core:runtime-services:AuditerDispatchService.adoc[`AuditerDispatchService`] performs a similar function for the xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/_persistence-layer.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/_persistence-layer.adoc
index 2ccae08..2065687 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/_persistence-layer.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/_persistence-layer.adoc
@@ -23,8 +23,8 @@ Impl'n (g: a:)
-|xref:core:runtime-services:AuditingServiceInternal.adoc[`o.a.i.c.r.s.auditing.` +
-`AuditingServiceInternal`]
+|xref:core:runtime-services:AuditerDispatchService.adoc[`o.a.i.c.r.s.auditing.` +
+`AuditerDispatchService`]
|Co-ordinates between
xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsServiceInternal`] and
xref:core:runtime-services:AuditerService.adoc[`AuditerService`].
@@ -50,8 +50,8 @@ querying and for persisting objects.
|
-|xref:core:runtime-services:PublishingServiceInternal.adoc[`o.a.i.c.m.s.publishing.` +
-`PublishingServiceInternal`]
+|xref:core:runtime-services:PublisherDispatchService.adoc[`o.a.i.c.m.s.publishing.` +
+`PublisherDispatchService`]
|Co-ordinates between
xref:core:runtime-services:ChangedObjectsService.adoc[`ChangedObjectsServiceInternal`] and
xref:refguide:applib-svc:MetricsService.adoc[`MetricsService`] and the SPI services, and the
diff --git a/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/module-nav.adoc b/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/module-nav.adoc
index 88e1aca..b1ccd65 100644
--- a/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/module-nav.adoc
+++ b/core/runtimeservices/src/main/adoc/modules/runtime-services/partials/module-nav.adoc
@@ -1,16 +1,15 @@
* xref:core:runtime-services:about.adoc[Runtime Services]
-** xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService]
-** xref:core:runtime-services:RepresentationService.adoc[RepresentationService]
-
+** xref:core:runtime-services:ApplicationFeatureFactory.adoc[ApplicationFeatureFactory]
+** xref:core:runtime-services:AuditerDispatchService.adoc[AuditerDispatchService]
** xref:core:runtime-services:AuthenticationSessionProvider.adoc[AuthenticationSessionProvider]
+** xref:core:runtime-services:ChangedObjectsService.adoc[ChangedObjectsService]
** xref:core:runtime-services:CommandDtoServiceInternal.adoc[CommandDtoServiceInternal]
+** xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService]
** xref:core:runtime-services:InteractionDtoServiceInternal.adoc[InteractionDtoServiceInternal]
-
-** xref:core:runtime-services:AuditingServiceInternal.adoc[AuditingServiceInternal]
-** xref:core:runtime-services:ChangedObjectsService.adoc[ChangedObjectsServiceInternal]
+** xref:core:runtime-services:RepresentationService.adoc[RepresentationService]
** xref:core:runtime-services:PersistenceSessionServiceInternal.adoc[PersistenceSessionServiceInternal]
-** xref:core:runtime-services:PublishingDispatchService.adoc[PublishingDispatchService]
+** xref:core:runtime-services:PublisherDispatchService.adoc[PublisherDispatchService]
diff --git a/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc b/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc
index eebc1a9..b3fbba9 100644
--- a/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc
+++ b/extensions/core/command-log/adoc/modules/command-log/pages/about.adoc
@@ -1,5 +1,32 @@
= Command Log
: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 [...]
-WARNING: TODO: v2 - will move this into the framework, update these docs
+WARNING: TODO: v2 - to update
+
+The (non-ASF) link:https://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
+
+* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
+
+//* implementation of the
+//xref:refguide:applib-svc:CommandService.adoc[`BackgroundCommandService`].
+
+All of these can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
+
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:about.adoc#vetoing-visibility[vetoing subscriber].
+
+
+
+=== Alternatives
+
+WARNING: TODO: v2 - this is to move into the xref:mappings:ROOT:about.adoc[mappings catalogue].
+
+The (non-ASF) link:https://platform.incode.org[Incode Platform^]'s command module provides an implementation of this service (`CommandService`), and also provides a number of related domain services (`CommandJdoRepository` and `CommandServiceJdoContributions`).
+//This module also provides service implementations of the xref:refguide:applib-svc:CommandService.adoc[`BackgroundCommandService`].
+
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:userguide:btb:about.adoc#vetoing-visibility[vetoing subscriber].
+
+