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 2021/02/05 10:32:28 UTC
[isis] 02/02: ISIS-2524: reworks the refguide to show how they
would link to the generated index pages instead (for Action.adoc and
ClockService.adoc)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2524
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 6d0c7233b41c76f4363346cd186a2c85692c7f15
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Feb 5 10:32:05 2021 +0000
ISIS-2524: reworks the refguide to show how they would link to the generated index pages instead (for Action.adoc and ClockService.adoc)
---
.../main/adoc/modules/applib-ant/pages/Action.adoc | 90 ----------
.../applib-ant/pages/Action/associateWith.adoc | 89 ----------
.../applib-ant/pages/Action/commandPublishing.adoc | 142 ---------------
.../applib-ant/pages/Action/domainEvent.adoc | 191 ---------------------
.../pages/Action/executionPublishing.adoc | 55 ------
.../modules/applib-ant/pages/Action/hidden.adoc | 56 ------
.../applib-ant/pages/Action/restrictTo.adoc | 42 -----
.../modules/applib-ant/pages/Action/semantics.adoc | 81 ---------
.../modules/applib-ant/pages/Action/typeOf.adoc | 32 ----
.../modules/applib-ant/partials/module-nav.adoc | 4 +-
.../modules/applib-svc/pages/ClockService.adoc | 32 ----
.../applib-svc/partials/_core-domain-api.adoc | 5 +-
12 files changed, 7 insertions(+), 812 deletions(-)
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
deleted file mode 100644
index a2923bc..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-[#Action]
-= `@Action`
-
-: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 `@Action` annotation groups together all domain-specific metadata for an invokable action on a domain object or domain service.
-
-[source,java]
-----
-include::refguide:applib-ant:example$annotation/Action.java[tags="refguide"]
-----
-
-<.> xref:refguide:applib-ant:Action.adoc#associateWith[`associateWith()`]
-+
-associates an action with another property or collection of the action.
-
-<.> `associateWithSequence()`
-+
-the ordering of multiple actions associated with another property/collection.
-
-<.> `commandDtoProcessor()`
-+
-If the xref:extensions:command-replay:about.adoc[Command Replay] extension is being used (for regression testing), provides a mechanism to process the `CommandDto` before being replicated from primary to secondary system
-
-<.> xref:refguide:applib-ant:Action.adoc#commandPublishing[`commandPublishing()`]
-+
-Whether the action invocation should be published to registered xref:refguide:applib-svc:CommandSubscriber.adoc[`CommandSubscriber`]s as a `Command` object, that captures the details of this invocation. Typically so it can be logged using the xref:extensions:command-log:about.adoc[Command Log] extension (for auditing or for regression testing using xref:extensions:command-replay:about.adoc[Command Replay]).
-
-<.> xref:refguide:applib-ant:Action.adoc#domainEvent[`domainEvent()`]
-+
-The event type to be posted to the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execute).
-
-<.> xref:refguide:applib-ant:Action.adoc#executionPublishing[`executionPublishing()`]
-+
-Whether the action invocation should be published to registered xref:refguide:applib-svc:ExecutionSubscriber.adoc[`ExecutionSubscriber`]s as an `Execution` object, that captures the details of this invocation.
-
-<.> xref:refguide:applib-ant:Action.adoc#hidden[`hidden()`]
-+
-Indicates where (in the UI) the action should be hidden from the user.
-
-<.> xref:refguide:applib-ant:Action.adoc#restrictTo[`restrictTo()`]
-+
-Whether the action is only available in prototyping mode, or whether it is available also in production mode.
-
-<.> xref:refguide:applib-ant:Action.adoc#semantics[`semantics()`]
-+
-The action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change; if not whether the results can be cached for the remainder of the request).
-+
-The `...ARE_YOU_SURE` variants cause a confirmation dialog to be displayed in the xref:vw:ROOT:about.adoc[Wicket viewer].
-
-<.> xref:refguide:applib-ant:Action.adoc#typeOf[`typeOf()`]
-+
-If the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { }
- @Action(
- commandPublishing=Publishing.ENABLED,
- commandExecuteIn=CommandExecuteIn.FOREGROUND, // <.>
- commandPersistence=CommandPersistence.NOT_PERSISTED, // <.>
- domainEvent=CompletedEvent.class,
- hidden = Where.NOWHERE, // <.>
- executionPublishing = Publishing.ENABLED,
- semantics = SemanticsOf.IDEMPOTENT
- )
- public ToDoItem completed() { /* ... */ }
-}
-----
-<.> default value, so could be omitted
-<.> default value, so could be omitted
-<.> default value, so could be omitted
-
-
-
-
-
-include::Action/associateWith.adoc[leveloffset=+1]
-include::Action/commandPublishing.adoc[leveloffset=+1]
-include::Action/domainEvent.adoc[leveloffset=+1]
-include::Action/executionPublishing.adoc[leveloffset=+1]
-include::Action/hidden.adoc[leveloffset=+1]
-include::Action/restrictTo.adoc[leveloffset=+1]
-include::Action/semantics.adoc[leveloffset=+1]
-include::Action/typeOf.adoc[leveloffset=+1]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/associateWith.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/associateWith.adoc
deleted file mode 100644
index 2d136e3..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/associateWith.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[#associateWith]
-= `associateWith()`
-
-: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:
-
-
-
-
-The `associateWith` attribute allows an action to be associated with other properties or collections of the same domain object.
-The optional `associateWithSequence` attribute specifies the order of the action in the UI.
-
-For example, an `Order` could have a collection of ``OrderItem``s, and might provide actions to add and remove items:
-
-[source,java]
-----
-public class Order {
-
- @Getter @Setter
- @Collection
- private final SortedSet<OrderItem> items = ...
-
- @Action(
- associateWith="items", // <.>
- associateWithSequence="1" ) // <.>
- public Order addItem(Product p, int quantity) {
- // ...
- }
-
- @Action(
- associateWith="items", // <.>
- associateWithSequence="2" ) // <.>
- public Order removeItem(OrderItem item) {
- // ...
- }
-
- // ...
-}
-----
-
-<.> matches the name of the collection
-<.> first action in the list of all associated actions
-<.> matches the name of the collection
-<.> second action in the list of all associated actions
-
-These actions - `addItem()` and `removeItem()` can be thought of as associated with with the `items` collection because that is the state that they primarily affect.
-
-In the user interface associated actions are rendered close to the member to which they relate.
-
-[NOTE]
-====
-The same effect can be accomplished using `@MemberOrder` or with the `.layout.xml` file.
-====
-
-== Inferred Defaults and Choices
-
-If an action is associated with a collection, then any scalar or collection parameter of the action that is the same type as that collection will automatically have a list of choices provided for it, being the items of the associated collection.
-
-This is only done provided that there isn't already an explicit `choicesNXxx()` or `autoCompleteNXxx()` supporting method.
-However, this list of choices _does_ take priority over any choices that are inferred from the parameter type itself (as per either an `@DomainObject(autoCompleteRepository=...)` or `@DomainObject(bounded=...)`).
-
-In addition, if the action has a collection parameter of the same type as the associated collection, then the Wicket viewer will render the collection with checkboxes.
-The user can use these checkboxes can be used to select the items of the action parameter.
-
-For example, suppose we have a "removeItems(...)" action:
-
-[source,java]
-----
-import lombok.Getter;
-import lombok.Setter;
-
-public class Order {
-
- @Getter @Setter
- @Collection
- private final SortedSet<OrderItem> items = ...
-
- @Action(
- associateWith="items",
- associateWithSequence="2" )
- public Order removeItems(SortedSet<OrderItem> items) {
- // ...
- }
-
- // ...
-}
-----
-
-The Wicket viewer will then render the "items" collection with checkboxes, and any selected items will be used as the pre-selected set of items if the action is invoked.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/commandPublishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/commandPublishing.adoc
deleted file mode 100644
index 43b63e8..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/commandPublishing.adoc
+++ /dev/null
@@ -1,142 +0,0 @@
-= Command Processing
-
-: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 - publishing/auditing got a complete overhaul
-
-Every action invocation (and xref:Property.adoc#command[property edit] for that matter) is normally reified into a concrete `Command` object, basically a wrapper around the XML invocation xref:schema:cmd.adoc[Command] schema that also captures some timing metrics about the execution as well as the outcome.
-
-The main uses cases are:
-
-* as a means to allow asynchronous child commands to be executed, using the xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] service;
-
-* as a means to audit (persist) commands, by implementing the xref:refguide:applib-svc:CommandSubscriber.adoc[`CommandServiceListener`] SPI.
-+
-The xref:extensions:command-log:about.adoc[Command Log] extension _does_ provide such an implementation.
-+
-TIP: Another option to achieve this is to use the xref:refguide:applib-svc:ExecutionSubscriber.adoc[`PublisherService`] SPI.
-
-* to replay commands onto a secondary system, for regression testing.
-+
-This is implemented by the xref:extensions:command-replay:about.adoc[Command Replay] extension, working in conjunction with the xref:extensions:command-log:about.adoc[Command Log] extension.
-
-
-[#commandPublishing]
-== `commandPublishing`
-
-The `commandPublishing()` attribute can be used to explicitly enable or disable command publishing for the action.
-
-
-
-[#commanddtoprocessor]
-== `commandDtoProcessor`
-
-The `commandDtoProcessor` attribute allows an implementation of `CommandDtoProcessor` to be specified.
-This interface has the following API:
-
-[source,java]
-----
-public interface CommandDtoProcessor {
- CommandDto process( // <.>
- CommandDto dto); // <.>
-}
-----
-<.> The returned `CommandDto`.
-This will typically be the `CommandDto` passed in, but may be supplemented in some way.
-<.> The `CommandDto` obtained already from the `Command`.
-
-This interface is used by the framework-provided implementations of `ContentMappingService` for the REST API, allowing ``Command``s implementations that also implement `CommandWithDto` to be further customised as they are serialized out.
-The primary use case for this capability is in support of master/slave replication.
-
-* on the master, ``Command``s are serialized to XML.
-This includes the identity of the target object and the argument values of all parameters.
-
-+
-[IMPORTANT]
-====
-However, any ``Blob``s and ``Clob``s are deliberately excluded from this XML (they are instead stored as references).
-This is to prevent the storage requirements for `Command` from becoming excessive.
-A `CommandDtoProcessor` can be provided to re-attach blob information if required.
-====
-
-* replaying ``Command``s requires this missing parameter information to be reinstated.
-The `CommandDtoProcessor` therefore offers a hook to dynamically re-attach the missing `Blob` or `Clob` argument.
-
-As a special case, returning `null` means that the command's DTO is effectively excluded when retrieving the list of commands.
-If replicating from master to slave, this effectively allows certain commands to be ignored.
-The `CommandDtoProcessor.Null` class provides a convenience implementation for this requirement.
-
-[NOTE]
-====
-If `commandDtoProcessor()` is specified, then `commandPublishing()` is assumed to be ENABLED.
-====
-
-=== Example implementation
-
-Consider the following method:
-
-[source,java]
-----
-@Action(
- domainEvent = IncomingDocumentRepository.UploadDomainEvent.class,
- commandDtoProcessor = DeriveBlobArg0FromReturnedDocument.class
-)
-public Document upload(final Blob blob) {
- final String name = blob.getName();
- final DocumentType type = DocumentTypeData.INCOMING.findUsing(documentTypeRepository);
- final ApplicationUser me = meService.me();
- String atPath = me != null ? me.getAtPath() : null;
- if (atPath == null) {
- atPath = "/";
- }
- return incomingDocumentRepository.upsertAndArchive(type, atPath, name, blob);
-}
-----
-
-The `Blob` argument will not be persisted in the memento of the `Command`, but the information is implicitly available in the `Document` that is returned by the action.
-The `DeriveBlobArg0FromReturnedDocument` processor retrieves this information and dynamically adds:
-
-[source,java]
-----
-public class DeriveBlobArg0FromReturnedDocument
- extends CommandDtoProcessorForActionAbstract {
-
- @Override
- public CommandDto process(Command command, CommandDto commandDto) {
- final Bookmark result = commandWithDto.getResult();
- if(result == null) {
- return commandDto;
- }
- try {
- final Document document = bookmarkService.lookup(result, Document.class);
- if (document != null) {
- ParamDto paramDto = getParamDto(commandDto, 0);
- CommonDtoUtils.setValueOn(paramDto, ValueType.BLOB, document.getBlob(), bookmarkService);
- }
- } catch(Exception ex) {
- return commandDto;
- }
- return commandDto;
- }
- @Inject
- BookmarkService bookmarkService;
-}
-----
-
-=== Null implementation
-
-The null implementation can be used to simply indicate that no DTO should be returned for a `Command`.
-The effect is to ignore it for replay purposes:
-
-[source,xml]
-----
-pubc interface CommandDtoProcessor {
- ...
- class Null implements CommandDtoProcessor {
- public CommandDto process(Command command, CommandDto commandDto) {
- return null;
- }
- }
-}
-----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/domainEvent.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/domainEvent.adoc
deleted file mode 100644
index 8f1acd2..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/domainEvent.adoc
+++ /dev/null
@@ -1,191 +0,0 @@
-[#domainEvent]
-= `domainEvent()`
-
-: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:
-
-
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object.
-In the cases of the domain object's actions, the events that are fired are:
-
-* hide phase: to check that the action is visible (has not been hidden)
-* disable phase: to check that the action is usable (has not been disabled)
-* validate phase: to check that the action's arguments are valid
-* pre-execute phase: before the invocation of the action
-* post-execute: after the invocation of the action
-
-Subscribers subscribe through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] and can influence each of these phases.
-
-By default the event raised is `ActionDomainEvent.Default`.
-For example:
-
-[source,java]
-----
-public class ToDoItem {
-
- @Action()
- public ToDoItem completed() {
- // ...
- }
- ...
-}
-----
-
-The `domainEvent` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { } // <1>
- @Action(domainEvent=CompletedEvent.class)
- public ToDoItem completed() { /* ... */ }
-}
-----
-
-The benefit is that subscribers can be more targeted as to the events that they subscribe to.
-
-[NOTE]
-====
-The framework provides no-arg constructor and will initialize the domain event using (non-API) setters rather than through the constructor.
-This substantially reduces the boilerplate required in subclasses because no explicit constructor is required.
-====
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe to events posted through the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`].
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ActionDomainEvent.class)
- public void on(ActionDomainEvent ev) {
- ...
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
- @EventListener(ToDoItem.CompletedEvent.class)
- public void on(ToDoItem.CompletedEvent ev) {
- ...
- }
-}
-----
-
-The subscriber's method is called (up to) 5 times:
-
-* whether to veto visibility (hide)
-* whether to veto usability (disable)
-* whether to veto execution (validate)
-* steps to perform prior to the action being invoked
-* steps to perform after the action has been invoked
-
-The subscriber can distinguish these by calling `ev.getEventPhase()`.
-Thus the general form is:
-
-[source,java]
-----
-import org.springframework.context.event.EventListener;
-import org.springframework.stereotype.Service;
-
-@Service
-public class SomeSubscriber {
-
- @EventListener(ActionDomainEvent.class)
- public void on(ActionDomainEvent ev) {
- switch(ev.getEventPhase()) {
-
- case HIDE: // <.>
- break;
- case DISABLE: // <.>
- break;
- case VALIDATE: // <.>
- break;
-
- case EXECUTING:
- break;
- case EXECUTED:
- break;
- }
- }
-}
-----
-
-<.> call `ev.hide()` or `ev.veto("")` to hide the action
-
-<.> call `ev.disable("...")` or `ev.veto("...")` to disable the action
-
-<.> call ev.invalidate("...") or ev.veto("...") if action arguments are invalid
-
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception.
-If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-== Default, Doop and Noop events
-
-If the `domainEvent` attribute is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`), then the framework will, by default, post an event.
-
-If this is not required, then the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault` configuration property can be set to "false"; this will disable posting.
-
-On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
-The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.
-
-And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` attribute is set to this class, then no event will be posted.
-
-=== Class-level default
-
-Sometimes a subscriber is interested in all of the actions of a given class, though not any individual action.
-A common use case is to hide or disable all actions for some particular object for some particular user group.
-
-For this use, the default action domain event can be annotated using `@DomainObject`:
-
-[source,java]
-----
-@DomainObject(
- actionDomainEvent=ToDoItem.ActionDomainEvent.class
-)
-public class ToDoItem {
- public static class ActionDomainEvent extends
- org.apache.isis.applib.events.domain.ActionDomainEvent<Object> { }
- // ...
-
- public void updateDescription(final String description) {
- this.description = description;
- }
-
-}
-----
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI.
-However, events can be raised programmatically either by calling the xref:refguide:applib-svc:EventBusService.adoc[`EventBusService`] API directly, or by emulating the UI by wrapping the target object using the xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] domain service.
-
-== See also
-
-This attribute is also supported for:
-
-* xref:refguide:applib-ant:Collection.adoc#domainEvent[collections] and
-* xref:refguide:applib-ant:Property.adoc#domainEvent[properties].
-
-
-
-
-
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/executionPublishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/executionPublishing.adoc
deleted file mode 100644
index 3ee2bda..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/executionPublishing.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-[#executionPublishing]
-= `executionPublishing()`
-
-: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 - publishing/auditing got a complete overhaul
-
-The `executionPublishing` attribute determines whether and how an action invocation is published via the registered implementation of xref:refguide:applib-svc:ExecutionSubscriber.adoc[`ExecutionSubscriber`].
-
-A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-The xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.action.publishing[`isis.applib.annotation.action.executionPublishing`] configuration property is used to determine the whether the action is published:
-
-* `all`
-+
-all action invocations are published
-
-* `ignoreSafe` (or `ignoreQueryOnly`)
-+
-invocations of actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
-
-* `none`
-+
-no action invocations are published
-
-If there is no configuration property in `application.properties` then publishing is automatically enabled.
-
-This default can be overridden on an action-by-action basis; if `executionPublishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Action(executionPublishing=Publishing.ENABLED) // <.>
- public Invoice generateInvoice(...) {
- // ...
- }
-}
-----
-
-<.> because set to enabled, will be published irrespective of the configured value.
-
-== See also
-
-This attribute is also supported for:
-
-* xref:refguide:applib-ant:DomainObject.adoc#entityChangePublishing[domain objects]
-+ where it controls whether changed objects are published as events, and for
-
-* xref:refguide:applib-ant:Property.adoc#executionPublishing[properties]
-+
-where it controls whether property edits are published as events.
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
deleted file mode 100644
index d88e4f9..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[#hidden]
-= `hidden()`
-
-: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:
-
-
-
-
-Actions can be hidden at the domain-level, indicating that they are not visible to the end-user.
-
-[TIP]
-====
-It is also possible to use xref:refguide:applib-ant:ActionLayout.adoc#hidden[`@ActionLayout#hidden`] or xref:userguide:fun:ui.adoc#object-layout[file-based layouts] such that the action can be hidden at the view layer.
-Both options are provided with a view that in the future the view-layer semantics may be under the control of (expert) users, whereas domain-layer semantics should never be overridden or modified by the user.
-====
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Action(hidden=Where.EVERYWHERE)
- public void updateStatus() {
- // ...
- }
-
- ...
-}
-----
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The action should be hidden at all times.
-
-* `Where.NOWHERE` +
-+
-The action should not be hidden.
-
-
-The other values of the `Where` enum have no meaning for a collection.
-
-
-
-
-
-== See also
-
-This attribute can also be applied to:
-
-* xref:refguide:applib-ant:Property.adoc#hidden[properties]
-* xref:refguide:applib-ant:Collection.adoc#hidden[collections].
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
deleted file mode 100644
index 20b0283..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[#restrictTo]
-= `restrictTo()`
-
-: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:
-
-
-
-By default actions are available irrespective of the xref:refguide:config:about.adoc#deployment-types[deployment mode].
-The `restrictTo` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Action
- public Order placeNewOrder() {
- // ...
- }
- @Action(semantics=SemanticsOf.SAFE)
- public List<Order> listRecentOrders() {
- // ...
- }
-
- @Action(restrictTo=RestrictTo.PROTOTYPING) // <.>
- public List<Order> listAllOrders() {
- // ...
- }
- ...
-}
-----
-
-<.> Only visible in prototype mode.
-
-In this case the listing of all orders (in the `listAllOrders()` action) probably doesn't make sense for production; there could be thousands or millions.
-However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.
-
-
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
deleted file mode 100644
index 9d7e29f..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[#semantics]
-= `semantics()`
-r
-: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:
-
-
-
-The `semantics` attribute describes whether the invocation modifies state of the system, and if so whether it does so idempotently.
-If the action invocation does _not_ modify the state of the system, in other words is safe, then it also can beused to specify whether the results of the action can be cached automatically for the remainder of the request.
-
-The attribute was originally introduced for the xref:vro:ROOT:about.adoc[RestfulObjects viewer] in order that action invocations could be using the appropriate `HTTP` verb (`GET`, `PUT` and `POST`).
-
-The table below summarizes the semantics:
-
-[cols="2,1,3,1",options="header"]
-|===
-| Semantic
-| Changes state
-| Effect of multiple calls
-| HTTP verb +
-(Restful Objects)
-
-| `SAFE_AND_REQUEST_CACHEABLE`
-| No
-| Will always return the same result each time invoked (within a given request scope)
-| `GET`
-
-| `SAFE`
-| No
-| Might result in different results each invocation
-| `GET`
-
-| `IDEMPOTENT` +
-`IDEMPOTENT_ARE_YOU_SURE`
-| Yes
-| Will make no further changes if called multiple times (eg sets a property or adds to a `Set`). +
-The "are you sure" variant requires that the user must explicitly confirm the action.
-| `PUT`
-
-| `NON_IDEMPOTENT` +
-`NON_IDEMPOTENT_ARE_YOU_SURE`
-| Yes
-| Might change the state of the system each time called (eg increments a counter or adds to a `List`). +
-The "are you sure" variant requires that the user must explicitly confirm the action.
-| `POST`
-
-|===
-
-The actions' semantics are also used by the core runtime as part of the in-built concurrency checkng; invocation of a safe action (which includes request-cacheable) does _not_ perform a concurrency check, whereas non-safe actions _do_ perform a concurrency check.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Action(semantics=SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)
- public CreditRating checkCredit() {
- // ...
- }
-
- @Action(semantics=SemanticsOf.IDEMPOTENT)
- public void changeOfAddress(Address address) {
- // ...
- }
-
- @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
- public Order placeNewOrder() {
- // ...
- }
-
- // ...
-}
-----
-
-Actions that are safe and request-cacheable automatically use the xref:refguide:applib-svc:QueryResultsCache.adoc[`QueryResultsCache`] service to cache the result of the method.
-Note though that the results of this caching will only be apparent if the action is invoked from another method using the xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] service.
-
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/typeOf.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/typeOf.adoc
deleted file mode 100644
index 9c8efee..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/typeOf.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[#typeOf]
-= `typeOf()`
-
-: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:
-
-
-
-The `typeOf` attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type.
-
-For example:
-
-[source,java]
-----
-public void AccountService {
-
- @Action(typeOf=Customer.class)
- public List errantAccounts() {
- return customers.allNewCustomers();
- }
- ...
-
- @Inject CustomerRepository customers;
-}
-----
-
-In general we recommend that you use generics instead, eg `List<Customer>`.
-
-== See also
-
-This attribute can also be specified for xref:refguide:applib-ant:Collection.adoc#typeOf[collections].
-
diff --git a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
index e7cd240..280ceb1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/partials/module-nav.adoc
@@ -3,7 +3,9 @@
* xref:refguide:applib-ant:about.adoc[Annotations]
-** xref:refguide:applib-ant:Action.adoc[Action]
+** xref:system:generated:index/applib/annotation/Action.adoc[Action]
+// ISIS-2524: in the refguide, we remove the manually written Action.adoc completely, and instead just link to the generated index.
+
** xref:refguide:applib-ant:ActionLayout.adoc[ActionLayout]
** xref:refguide:applib-ant:Collection.adoc[Collection]
** xref:refguide:applib-ant:CollectionLayout.adoc[CollectionLayout]
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
deleted file mode 100644
index 8b0e273..0000000
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-= `ClockService`
-
-: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:
-
-
-
-
-Most applications deal with dates and times in one way or another.
-For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the `Invoice`, otherwise a penalty may be levied.
-
-However, such date/time related functionality can quickly complicate automated testing: "today+30" will be a different value every time the test is run.
-
-Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC).
-While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
-
-Therefore it's common to provide a domain service whose responsibility is to provide the current time.
-This service can be injected into any domain object (and can be mocked out for unit testing).
-Apache Isis provides such a facade through the `ClockService`.
-
-
-== API
-
-include::system:generated:page$index/applib/services/clock/ClockService.adoc[leveloffset=+2]
-
-
-include::system:generated:page$index/applib/clock/VirtualClock.adoc[leveloffset=+2]
-
-Note that this domain service is also used by the framework itself to obtain the time, so it acts as an SPI as well.
-
-
-
diff --git a/api/applib/src/main/adoc/modules/applib-svc/partials/_core-domain-api.adoc b/api/applib/src/main/adoc/modules/applib-svc/partials/_core-domain-api.adoc
index 4004378..15ed762 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/partials/_core-domain-api.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/partials/_core-domain-api.adoc
@@ -14,7 +14,10 @@ The core/domain APIs provide general-purpose services to the domain objects, for
|Implementation
-|xref:refguide:applib-svc:ClockService.adoc[ClockService]
+|xref:system:generated:index/applib/services/clock/ClockService.adoc[]
+// ISIS-2524: in the refguide, we remove the manually written ClockService.adoc completely, and instead just link to the generated index.
+
+
|Access the current time (and for testing, allow the time to be changed)
|
* API is also implementation (concrete class).