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:26 UTC
[isis] branch ISIS-2524 updated (60308bd -> 6d0c723)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch ISIS-2524
in repository https://gitbox.apache.org/repos/asf/isis.git.
from 60308bd ISIS-2524: sketched out more fine-grained index generation
new 5577257 ISIS-2524: converts Action.adoc and ClockService.adoc to use hooks
new 6d0c723 ISIS-2524: reworks the refguide to show how they would link to the generated index pages instead (for Action.adoc and ClockService.adoc)
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../index/applib/annotation/Action_example.java | 74 ++++++++
.../services/clock/ClockService_example.java | 39 +++++
.../pages/index/applib/annotation/Action.adoc | 49 +++++-
.../pages/index/applib/annotation/Action/_api.adoc | 14 +-
.../applib/annotation/Action/_configuration.adoc | 26 +++
.../Action/_implementations_and_usage.adoc} | 44 +++--
.../Action/hooks/_introductory_notes.adoc} | 14 +-
.../Action/hooks/_related.adoc} | 22 +--
.../Action/{ => members}/associateWith.adoc | 1 +
.../{ => members}/associateWithSequence.adoc | 1 +
.../Action/{ => members}/commandDtoProcessor.adoc | 1 +
.../Action/{ => members}/commandPublishing.adoc | 1 +
.../Action/{ => members}/domainEvent.adoc | 1 +
.../index/applib/services/clock/ClockService.adoc | 43 ++++-
.../applib/services/clock/ClockService/_api.adoc | 8 +-
.../clock/ClockService/_configuration.adoc} | 24 +--
.../services/clock/ClockService/_description.adoc | 1 +
.../ClockService/_implementations_and_usage.adoc | 48 ++++++
.../_introductory_notes.adoc} | 33 +++-
.../{_implementations.adoc => hooks/_related.adoc} | 7 +-
.../clock/ClockService/{ => members}/getClock.adoc | 5 +
.../ClockService/{ => members}/getEpochMillis.adoc | 5 +
.../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 | 50 ------
.../applib-svc/partials/_core-domain-api.adoc | 5 +-
.../isis/applib/annotation/Action_example.java | 78 +++++++++
.../services/clock/ClockService_example.java | 39 +++++
36 files changed, 510 insertions(+), 905 deletions(-)
create mode 100644 antora/components/system/modules/generated/examples/index/applib/annotation/Action_example.java
create mode 100644 antora/components/system/modules/generated/examples/index/applib/services/clock/ClockService_example.java
create mode 100644 antora/components/system/modules/generated/pages/index/applib/annotation/Action/_configuration.adoc
copy antora/components/system/modules/generated/pages/index/applib/{services/clock/ClockService/_api.adoc => annotation/Action/_implementations_and_usage.adoc} (61%)
copy antora/components/system/modules/generated/pages/index/applib/{services/clock/ClockService/getEpochMillis.adoc => annotation/Action/hooks/_introductory_notes.adoc} (82%)
copy antora/components/system/modules/generated/pages/index/applib/{services/clock/ClockService.adoc => annotation/Action/hooks/_related.adoc} (67%)
rename antora/components/system/modules/generated/pages/index/applib/annotation/Action/{ => members}/associateWith.adoc (98%)
rename antora/components/system/modules/generated/pages/index/applib/annotation/Action/{ => members}/associateWithSequence.adoc (97%)
rename antora/components/system/modules/generated/pages/index/applib/annotation/Action/{ => members}/commandDtoProcessor.adoc (98%)
copy antora/components/system/modules/generated/pages/index/applib/annotation/Action/{ => members}/commandPublishing.adoc (98%)
rename antora/components/system/modules/generated/pages/index/applib/annotation/Action/{ => members}/domainEvent.adoc (99%)
rename antora/components/system/modules/generated/pages/index/applib/{annotation/Action/commandPublishing.adoc => services/clock/ClockService/_configuration.adoc} (58%)
create mode 100644 antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations_and_usage.adoc
copy antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/{getClock.adoc => hooks/_introductory_notes.adoc} (58%)
rename antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/{_implementations.adoc => hooks/_related.adoc} (85%)
rename antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/{ => members}/getClock.adoc (80%)
rename antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/{ => members}/getEpochMillis.adoc (78%)
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/associateWith.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/commandPublishing.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/domainEvent.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/executionPublishing.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/hidden.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/restrictTo.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/pages/Action/typeOf.adoc
delete mode 100644 api/applib/src/main/adoc/modules/applib-svc/pages/ClockService.adoc
create mode 100644 api/applib/src/test/java/org/apache/isis/applib/annotation/Action_example.java
create mode 100644 api/applib/src/test/java/org/apache/isis/applib/services/clock/ClockService_example.java
[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)
Posted by da...@apache.org.
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).
[isis] 01/02: ISIS-2524: converts Action.adoc and ClockService.adoc
to use hooks
Posted by da...@apache.org.
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 557725745db1dfdd841b6d42c2c304c198a620be
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Feb 5 10:28:54 2021 +0000
ISIS-2524: converts Action.adoc and ClockService.adoc to use hooks
---
.../index/applib/annotation/Action_example.java | 74 ++++++++++++++++++++
.../services/clock/ClockService_example.java | 39 +++++++++++
.../pages/index/applib/annotation/Action.adoc | 49 ++++++++++++--
.../pages/index/applib/annotation/Action/_api.adoc | 14 ++--
.../applib/annotation/Action/_configuration.adoc | 26 ++++++++
.../Action/_implementations_and_usage.adoc} | 44 ++++++++----
.../Action/hooks/_introductory_notes.adoc} | 14 +---
.../Action/hooks/_related.adoc} | 22 +++---
.../Action/{ => members}/associateWith.adoc | 1 +
.../{ => members}/associateWithSequence.adoc | 1 +
.../Action/{ => members}/commandDtoProcessor.adoc | 1 +
.../Action/{ => members}/commandPublishing.adoc | 1 +
.../Action/{ => members}/domainEvent.adoc | 1 +
.../index/applib/services/clock/ClockService.adoc | 43 ++++++++++--
.../applib/services/clock/ClockService/_api.adoc | 8 ++-
.../clock/ClockService/_configuration.adoc} | 24 ++++---
.../services/clock/ClockService/_description.adoc | 1 +
.../ClockService/_implementations_and_usage.adoc | 48 +++++++++++++
.../_introductory_notes.adoc} | 33 ++++++---
.../{_implementations.adoc => hooks/_related.adoc} | 7 +-
.../clock/ClockService/{ => members}/getClock.adoc | 5 ++
.../ClockService/{ => members}/getEpochMillis.adoc | 5 ++
.../modules/applib-svc/pages/ClockService.adoc | 20 +-----
.../isis/applib/annotation/Action_example.java | 78 ++++++++++++++++++++++
.../services/clock/ClockService_example.java | 39 +++++++++++
25 files changed, 504 insertions(+), 94 deletions(-)
diff --git a/antora/components/system/modules/generated/examples/index/applib/annotation/Action_example.java b/antora/components/system/modules/generated/examples/index/applib/annotation/Action_example.java
new file mode 100644
index 0000000..b5d0d1e
--- /dev/null
+++ b/antora/components/system/modules/generated/examples/index/applib/annotation/Action_example.java
@@ -0,0 +1,74 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.isis.applib.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+
+import javax.inject.Inject;
+
+import org.apache.isis.applib.events.domain.ActionDomainEvent;
+import org.apache.isis.applib.services.clock.ClockService;
+import org.apache.isis.applib.services.command.Command;
+import org.apache.isis.applib.services.commanddto.conmap.ContentMappingServiceForCommandDto;
+import org.apache.isis.applib.services.commanddto.conmap.ContentMappingServiceForCommandsDto;
+import org.apache.isis.applib.services.commanddto.processor.CommandDtoProcessor;
+import org.apache.isis.applib.services.iactn.Interaction.Execution;
+import org.apache.isis.applib.services.publishing.spi.CommandSubscriber;
+import org.apache.isis.applib.services.publishing.spi.ExecutionSubscriber;
+import org.apache.isis.applib.value.Blob;
+import org.apache.isis.applib.value.Clob;
+
+import lombok.Builder;
+import lombok.val;
+
+public class Action_example {
+
+ public static class Product { }
+
+ @Builder
+ public static class Order {
+ private Product product;
+ private int quantity;
+ }
+
+ public static class Customer {
+
+ public static class OrderPlaced extends ActionDomainEvent<Customer> {}
+
+ @Action(
+ semantics = SemanticsOf.NON_IDEMPOTENT // <.>
+ , domainEvent = OrderPlaced.class // <.>
+ , executionPublishing = Publishing.ENABLED // <.>
+ , associateWith = "orders" // <.>
+ )
+ public Order placeOrder(Product product, int quantity) {
+ return Order.builder()
+ .product(product)
+ .quantity(quantity)
+ .build();
+ }
+ }
+}
diff --git a/antora/components/system/modules/generated/examples/index/applib/services/clock/ClockService_example.java b/antora/components/system/modules/generated/examples/index/applib/services/clock/ClockService_example.java
new file mode 100644
index 0000000..7767bff
--- /dev/null
+++ b/antora/components/system/modules/generated/examples/index/applib/services/clock/ClockService_example.java
@@ -0,0 +1,39 @@
+package org.apache.isis.applib.services.clock;
+
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+
+import javax.inject.Inject;
+
+import org.apache.isis.applib.annotation.Action;
+
+import lombok.Builder;
+import lombok.val;
+
+public class ClockService_example {
+
+ public static class Product { }
+
+ @Builder
+ public static class Order {
+ private Product product;
+ private int quantity;
+ private LocalDateTime placedAt;
+ }
+
+ public static class Customer {
+
+ @Action
+ public Order placeOrder(Product product, int quantity) {
+ val now = clockService.getClock()
+ .localDateTime(ZoneId.systemDefault()); // <.>
+ return Order.builder()
+ .product(product)
+ .quantity(quantity)
+ .placedAt(now)
+ .build();
+ }
+ @Inject ClockService clockService;
+ }
+}
+
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action.adoc
index 8d84423..3c0fcc0 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action.adoc
@@ -3,13 +3,50 @@
include::Action/_description.adoc[]
-== API
+// automatically included if it exists
+include::Action/hooks/_introductory_notes.adoc[]
include::Action/_api.adoc[]
+== Class Members
-include::Action/associateWith.adoc[leveloffset=+1]
-include::Action/associateWithSequence.adoc[leveloffset=+1]
-include::Action/commandDtoProcessor.adoc[leveloffset=+1]
-include::Action/commandPublishing.adoc[leveloffset=+1]
-include::Action/domainEvent.adoc[leveloffset=+1]
+// ISIS-2524: we put the members down at the end. I've decided to put them into their own section.
+
+include::Action/members/associateWith.adoc[leveloffset=+2]
+include::Action/members/associateWithSequence.adoc[leveloffset=+2]
+include::Action/members/commandDtoProcessor.adoc[leveloffset=+2]
+include::Action/members/commandPublishing.adoc[leveloffset=+2]
+include::Action/members/domainEvent.adoc[leveloffset=+2]
+
+
+== Configuration
+
+// ISIS-2524: if there is relevant configuration properties (automatically generated), then include them here
+
+include::Action/_configuration.adoc[]
+
+== Examples
+// ISIS-2524: if any example is found in src/test/java, then it is copied over to the examples folder and post-processed so that callouts in the .java file are copied down below the [source] section. if there are no examples, then this section is omitted completely.
+
+[source,java]
+.Action_example.java
+----
+include::{examplesdir}/index/applib/annotation/Action_example.java[]
+----
+<.> non-idempotent action (this is the default, so could be omitted)
+<.> emits this event on the internal event bus, allowing subscribers to react to or possibly veto the action
+<.> emits the action invocation event in serialized form to the configured ExecutionPublisher service, typically to interact with external systems
+<.> associates the action with the "orders" member (probably a collection in this case). In this example this acts solely as a UI hint.
+
+
+
+== Implementations and Usage
+
+include::Action/_implementations_and_usage.adoc[]
+
+
+
+== Related
+// ISIS-2524: automatically included if it exists (under a 'Related' section header)
+
+include::Action/hooks/_related.adoc[]
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_api.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_api.adoc
index a6fb647..82be60d 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_api.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_api.adoc
@@ -1,5 +1,8 @@
: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 [...]
+== API
+
+// ISIS-2524: in the callouts, we only extract the first sentence. We use hyperlinks to the section headers later, where the entire text is available.
.Action.java
[source,java]
@@ -19,23 +22,24 @@
}
----
-<.> `[teal]#*_associateWith_*#` : `String`
+<.> `[teal]#xref:index/applib/annotation/Action.adoc#associatewith[associateWith()]#` : `String`
+
Associates this action with a property or collection, specifying its id.
-<.> `[teal]#*_associateWithSequence_*#` : `String`
+<.> `[teal]#xref:index/applib/annotation/Action.adoc#associatewithsequence[associateWithSequence()]#` : `String`
+
Specifies the sequence/order in the UI for an action that's been associated with a property or collection.
-<.> `[teal]#*_commandDtoProcessor_*#` : `Class<? extends CommandDtoProcessor>`
+<.> `[teal]#xref:index/applib/annotation/Action.adoc#commanddtoprocessor[commandDtoProcessor()]#` : `Class<? extends CommandDtoProcessor>`
+
The xref:system:generated:index/applib/services/commanddto/processor/CommandDtoProcessor.adoc[CommandDtoProcessor] to process this command's DTO.
-<.> `[teal]#*_commandPublishing_*#` : `xref:system:generated:index/applib/annotation/Publishing.adoc[Publishing]`
+<.> `[teal]#xref:index/applib/annotation/Action.adoc#commandpublishing[commandPublishing()]#` : `xref:system:generated:index/applib/annotation/Publishing.adoc[Publishing]`
+
Whether action invocations, captured as xref:system:generated:index/applib/services/command/Command.adoc[Command] s, should be published to xref:system:generated:index/applib/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] s.
-<.> `[teal]#*_domainEvent_*#` : `Class<? extends ActionDomainEvent<?>>`
+<.> `[teal]#xref:index/applib/annotation/Action.adoc#domainevent[domainEvent()]#` : `Class<? extends ActionDomainEvent<?>>`
+
Indicates that an invocation of the action should be posted to the _org.apache.isis.applib.services.eventbus.EventBusService event bus_ using a custom (subclass of) xref:system:generated:index/applib/events/domain/ActionDomainEvent.adoc[ActionDomainEvent] .
+
etc...
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_configuration.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_configuration.adoc
new file mode 100644
index 0000000..1894632
--- /dev/null
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_configuration.adoc
@@ -0,0 +1,26 @@
+: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 [...]
+
+
+
+// ISIS-2524: if there are any configuration parameters that are relevant, then they could be automatically brought in here.
+
+// to identify the parameters, would either be by convention, alternatively by a javadoc hint in the configuration parameter as to which classes it related to.
+
+[source,yaml]
+.application.yaml
+----
+isis:
+ applib:
+ annotation:
+ action:
+ commandPublishing: NONE | IGNORE_SAFE | IGNORE_QUERY_ONLY | ALL <.>
+ executionPublishing: NONE | IGNORE_SAFE | IGNORE_QUERY_ONLY | NONE <.>
+ explicit: false | true <.>
+ domainEvent:
+ postForDefault: false | true <.>
+----
+<.> yada yada yada
+<.> yada yada yada
+<.> yada yada yada
+<.> yada yada yada
+// ISIS-2524: extracted from javadoc of IsisConfiguration)
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_implementations_and_usage.adoc
similarity index 61%
copy from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc
copy to antora/components/system/modules/generated/pages/index/applib/annotation/Action/_implementations_and_usage.adoc
index c4e82e2..8b4d526 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/_implementations_and_usage.adoc
@@ -1,22 +1,38 @@
-
: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 [...]
+
+
+To use this type:
+
+* `@Import` the `IsisModuleApplib` module either directly or indirectly:
++
[source,java]
-.ClockService.java
----
-interface ClockService {
- VirtualClock getClock() // <.>
- long getEpochMillis() // <.>
+import org.apache.isis.applib.*;
+
+@Configuration
+@Import({
+ IsisModuleApplib.class,
+ ...
+})
+...
+public class MyModule {
}
----
-<.> `[teal]#*_getClock()_*#` : `VirtualClock`
-+
---
-Returns a xref:system:generated:index/applib/clock/VirtualClock.adoc[] through which time can be manipulated
---
-<.> `[teal]#*_getEpochMillis()_*#` : `long`
+* add the Maven dependency:
+
---
-yada yada yada
---
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-applib</artifactId>
+ </dependency>
+ ...
+</dependencies>
+----
+
+// ISIS-2524: automatically generated
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_introductory_notes.adoc
similarity index 82%
copy from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc
copy to antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_introductory_notes.adoc
index 33ad02d..98a3e24 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_introductory_notes.adoc
@@ -1,16 +1,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 [...]
-= getEpochMillis()
+: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 [...]
-[source,java]
-.ClockService.java
-----
-interface ClockService {
- ...
- long getEpochMillis()
- ...
-}
-----
+\... if this file exists, then these are some additional introductory notes to be include'd after the initial description (no section header beforehand) ...
-yada yada
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_related.adoc
similarity index 67%
copy from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc
copy to antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_related.adoc
index 0a3111d..042304a 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/hooks/_related.adoc
@@ -1,17 +1,19 @@
-= 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 [...]
-
-include::ClockService/_description.adoc[]
+: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 [...]
-== Api
+See also:
-include::ClockService/_api.adoc[leveloffset=+1]
+* xref:index/applib/annotation/ActionLayout.adoc[]
++
+for UI hints relating to actions
-== Implementations
+* xref:index/applib/annotation/Property.adoc[]
++
+for domain semantics of domain object properties.
-include::ClockService/_implementations.adoc[]
+* xref:index/applib/annotation/Collection.adoc[]
++
+for domain semantics of domain object properties.
-include::ClockService/getClock.adoc[leveloffset=+1]
-include::ClockService/getEpochMillis.adoc[leveloffset=+1]
+// This page would be automatically included at the end, if it exists.
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWith.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWith.adoc
similarity index 98%
rename from antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWith.adoc
rename to antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWith.adoc
index c29a492..6deb171 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWith.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWith.adoc
@@ -1,6 +1,7 @@
: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 [...]
+[#associatewith]
= associateWith()
[source,java]
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWithSequence.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWithSequence.adoc
similarity index 97%
rename from antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWithSequence.adoc
rename to antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWithSequence.adoc
index 7183b10..ecf430b 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/associateWithSequence.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/associateWithSequence.adoc
@@ -1,6 +1,7 @@
: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 [...]
+[#associatewithsequence]
= associateWithSequence()
[source,java]
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandDtoProcessor.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandDtoProcessor.adoc
similarity index 98%
rename from antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandDtoProcessor.adoc
rename to antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandDtoProcessor.adoc
index 62134d4..4202c8c 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandDtoProcessor.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandDtoProcessor.adoc
@@ -1,6 +1,7 @@
: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 [...]
+[#commanddtoprocessor]
= commandDtoProcessor()
[source,java]
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandPublishing.adoc
similarity index 98%
copy from antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc
copy to antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandPublishing.adoc
index 5eeaf1c..7352051 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/commandPublishing.adoc
@@ -1,6 +1,7 @@
: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 [...]
+[#commandpublishing]
= commandPublishing()
[source,java]
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/domainEvent.adoc b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/domainEvent.adoc
similarity index 99%
rename from antora/components/system/modules/generated/pages/index/applib/annotation/Action/domainEvent.adoc
rename to antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/domainEvent.adoc
index 7a52f20..bdde9fe 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/domainEvent.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/annotation/Action/members/domainEvent.adoc
@@ -1,6 +1,7 @@
: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 [...]
+[#domainevent]
= domainEvent()
[source,java]
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc
index 0a3111d..9872e9b 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService.adoc
@@ -3,15 +3,46 @@
include::ClockService/_description.adoc[]
-
-== Api
+// automatically included if it exists
+include::ClockService/hooks/_introductory_notes.adoc[]
include::ClockService/_api.adoc[leveloffset=+1]
-== Implementations
-include::ClockService/_implementations.adoc[]
+== Class Members
+
+// ISIS-2524: we put the members down at the end. I've decided to put them into their own section.
+
+include::ClockService/members/getClock.adoc[leveloffset=+2]
+include::ClockService/members/getEpochMillis.adoc[leveloffset=+2]
+
+
+
+== Configuration
+
+// ISIS-2524: if there is relevant configuration properties (automatically generated), then include them here
+
+include::ClockService/_configuration.adoc[]
+
+== Examples
+// ISIS-2524: if any example is found in src/test/java, then it is copied over to the examples folder and post-processed so that callouts in the .java file are copied down below the [source] section. if there are no examples, then this section is omitted completely.
+
+[source,java]
+.ClockService_example.java
+----
+include::{examplesdir}/index/applib/services/clock/ClockService_example.java[]
+----
+<.> obtains the date/time from the `VirtualClock` provided by `ClockService`.
+
+
+== Implementations and Usage
+
+include::ClockService/_implementations_and_usage.adoc[]
+
+
+
+== Related
+// ISIS-2524: automatically included if it exists (under a 'Related' section header)
-include::ClockService/getClock.adoc[leveloffset=+1]
-include::ClockService/getEpochMillis.adoc[leveloffset=+1]
+include::ClockService/hooks/_related.adoc[]
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc
index c4e82e2..40298bb 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_api.adoc
@@ -1,6 +1,10 @@
: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 [...]
+== Api
+
+// ISIS-2524: in the callouts, we only extract the first sentence. We use hyperlinks to the section headers later, where the entire text is available.
+
[source,java]
.ClockService.java
----
@@ -9,13 +13,13 @@ interface ClockService {
long getEpochMillis() // <.>
}
----
-<.> `[teal]#*_getClock()_*#` : `VirtualClock`
+<.> `[teal]#xref:index/applib/services/clock/ClockService.adoc#getclock[#getClock()]#` : `VirtualClock`
+
--
Returns a xref:system:generated:index/applib/clock/VirtualClock.adoc[] through which time can be manipulated
--
-<.> `[teal]#*_getEpochMillis()_*#` : `long`
+<.> `[teal]#xref:index/applib/services/clock/ClockService.adoc#getepochmillis[#getEpochMillis()]#` : `long`
+
--
yada yada yada
diff --git a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_configuration.adoc
similarity index 58%
rename from antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc
rename to antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_configuration.adoc
index 5eeaf1c..adc8eb8 100644
--- a/antora/components/system/modules/generated/pages/index/applib/annotation/Action/commandPublishing.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_configuration.adoc
@@ -1,16 +1,20 @@
: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 [...]
-= commandPublishing()
-[source,java]
-----
-@interface Action {
- // ...
- Publishing commandPublishing() default Publishing.NOT_SPECIFIED;
- // ...
-}
-----
+// ISIS-2524: if there are any configuration parameters that are relevant, then they could be automatically brought in here.
-Whether action invocations, captured as xref:system:generated:index/applib/services/command/Command.adoc[Command] s, should be published to xref:system:generated:index/applib/services/publishing/spi/CommandSubscriber.adoc[CommandSubscriber] s.
+// to identify the parameters, would either be by convention, alternatively by a javadoc hint in the configuration parameter as to which classes it related to.
+[source,yaml]
+.application.yaml
+----
+isis:
+ services:
+ clock-service:
+ foo: xxx // <.>
+ bar: yyy // <.>
+----
+<.> Foo - yada yada yada
+// ISIS-2524: extracted from javadoc of IsisConfiguration)
+<.> Bar - yada yada yada
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_description.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_description.adoc
index 43ebed3..e16feb1 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_description.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_description.adoc
@@ -2,3 +2,4 @@
This service allows an application to be decoupled from the system time. The most common use case is in support of testing scenarios, to "mock the clock". Use of this service also opens up the use of centralized co-ordinated time management through a centralized time service.
+// ISIS-2524: corresponds to the javadoc taken from the top-level class.
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations_and_usage.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations_and_usage.adoc
new file mode 100644
index 0000000..61272d0
--- /dev/null
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations_and_usage.adoc
@@ -0,0 +1,48 @@
+: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 [...]
+
+
+
+// ISIS-2524: this section only if an interface
+This interface is implemented by:
+
+* `org.apache.isis.core.runtimeservices.clock.ClockServiceDefault`.
+
+
+// ISIS-2524: it's possible that we could have multiple implementations, in which case we would want to have subsections for each possibly implementation. Each would identify the implementation, and then provide the usage instructions.
+
+
+// ISIS-2524: for this section, we specify usage of an implementation of there is one. For annotations and concrete classes, it will be the owning module of the class itself.
+To use this type:
+
+* `@Import` the `IsisModuleCoreRuntimeServices` module either directly or indirectly:
++
+[source,java]
+----
+import org.apache.isis.core.runtimeservices.*;
+
+@Configuration
+@Import({
+ IsisModuleCoreRuntimeServices.class,
+ ...
+})
+...
+public class MyModule {
+}
+----
+
+* add the Maven dependency:
++
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ ...
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-runtimeservices</artifactId>
+ </dependency>
+ ...
+</dependencies>
+----
+
+// ISIS-2524: automatically generated
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_introductory_notes.adoc
similarity index 58%
copy from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc
copy to antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_introductory_notes.adoc
index 35ad3f7..f692176 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_introductory_notes.adoc
@@ -1,16 +1,33 @@
+
: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 [...]
-= getClock()
+\... if this file exists, then these are some additional introductory notes to be include'd after the initial description (no section header beforehand) ...
+
+\... some relevant diagram etc:
-[source,java]
-.ClockService.java
+[plantuml]
----
+hide empty members
+
+class Customer {
+ placeOrder(Product p): Order
+}
+
+Customer -d-> "0..*" Order
+Order -r-> Product
+Customer -l-> ClockService : <<injected>>
+ClockService .-> VirtualClock : <<provides>>
+Customer .-> VirtualClock : <<reads from>>
+
+class Order {
+ LocalDate: placedOn
+}
+class Product {}
interface ClockService {
- ...
- VirtualClock getClock()
- ...
+ getClock(): VirtualClock
+}
+interface VirtualClock {
+ now()
}
----
-
-Returns a xref:system:generated:index/applib/clock/VirtualClock.adoc[] through which time can be manipulated
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_related.adoc
similarity index 85%
rename from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations.adoc
rename to antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_related.adoc
index aa85119..cc45dc0 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/_implementations.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/hooks/_related.adoc
@@ -1,6 +1,9 @@
+
: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 [...]
-This service is implemented by:
+See also
+
+* xref:index/applib/clock/VirtualClock.adoc[]
-* `org.apache.isis.core.runtimeservices.clock.ClockServiceDefault`.
+// This page would be automatically included at the end, if it exists.
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getClock.adoc
similarity index 80%
rename from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc
rename to antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getClock.adoc
index 35ad3f7..3f248df 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getClock.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getClock.adoc
@@ -1,5 +1,7 @@
: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 [...]
+// ISIS-2524 - automatically generated stable anchor
+[#getclock]
= getClock()
@@ -12,5 +14,8 @@ interface ClockService {
...
}
----
+// ISIS-2524 - highlights just the member we are referring to; ellipses (...) indicate that other members have been omitted.
Returns a xref:system:generated:index/applib/clock/VirtualClock.adoc[] through which time can be manipulated
+
+// ISIS-2524 : this is the javadoc for that memet
diff --git a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getEpochMillis.adoc
similarity index 78%
rename from antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc
rename to antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getEpochMillis.adoc
index 33ad02d..09c49fc 100644
--- a/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/getEpochMillis.adoc
+++ b/antora/components/system/modules/generated/pages/index/applib/services/clock/ClockService/members/getEpochMillis.adoc
@@ -1,5 +1,7 @@
: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 [...]
+// ISIS-2524 - automatically generated stable anchor
+[#getepochmillis]
= getEpochMillis()
@@ -12,5 +14,8 @@ interface ClockService {
...
}
----
+// ISIS-2524 - highlights just the member we are referring to; ellipses (...) indicate that other members have been omitted.
yada yada
+
+// ISIS-2524 : this is the javadoc for that memet
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 7af112d..8b0e273 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
@@ -23,28 +23,10 @@ Apache Isis provides such a facade through the `ClockService`.
include::system:generated:page$index/applib/services/clock/ClockService.adoc[leveloffset=+2]
-TODO example migration
-.Deprecated Docs
-[WARNING]
-================================
-
-== API
-
-The API defined by `ClockService` is:
-
-[source,java]
-----
-include::refguide:applib-svc:example$services/clock/ClockService.java[tags="refguide"]
-----
+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.
-================================
-
-== Implementation
-
-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/test/java/org/apache/isis/applib/annotation/Action_example.java b/api/applib/src/test/java/org/apache/isis/applib/annotation/Action_example.java
new file mode 100644
index 0000000..196dfc5
--- /dev/null
+++ b/api/applib/src/test/java/org/apache/isis/applib/annotation/Action_example.java
@@ -0,0 +1,78 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.isis.applib.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+
+import javax.inject.Inject;
+
+import org.apache.isis.applib.events.domain.ActionDomainEvent;
+import org.apache.isis.applib.services.clock.ClockService;
+import org.apache.isis.applib.services.command.Command;
+import org.apache.isis.applib.services.commanddto.conmap.ContentMappingServiceForCommandDto;
+import org.apache.isis.applib.services.commanddto.conmap.ContentMappingServiceForCommandsDto;
+import org.apache.isis.applib.services.commanddto.processor.CommandDtoProcessor;
+import org.apache.isis.applib.services.iactn.Interaction.Execution;
+import org.apache.isis.applib.services.publishing.spi.CommandSubscriber;
+import org.apache.isis.applib.services.publishing.spi.ExecutionSubscriber;
+import org.apache.isis.applib.value.Blob;
+import org.apache.isis.applib.value.Clob;
+
+import lombok.Builder;
+import lombok.val;
+
+public class Action_example {
+
+ public static class Product { }
+
+ @Builder
+ public static class Order {
+ private Product product;
+ private int quantity;
+ }
+
+ public static class Customer {
+
+ public static class OrderPlaced extends ActionDomainEvent<Customer> {}
+
+ @Action(
+ semantics = SemanticsOf.NON_IDEMPOTENT // <.>
+ , domainEvent = OrderPlaced.class // <.>
+ , executionPublishing = Publishing.ENABLED // <.>
+ , associateWith = "orders" // <.>
+ )
+ public Order placeOrder(Product product, int quantity) {
+ return Order.builder()
+ .product(product)
+ .quantity(quantity)
+ .build();
+ }
+ }
+}
+// <.> non-idempotent action (this is the default, so could be omitted)
+// <.> emits this event on the internal event bus, allowing subscribers to react to or possibly veto the action
+// <.> emits the action invocation event in serialized form to the configured ExecutionPublisher service, typically to interact with external systems
+// <.> associates the action with the "orders" member (probably a collection in this case). In this example this acts solely as a UI hint.
diff --git a/api/applib/src/test/java/org/apache/isis/applib/services/clock/ClockService_example.java b/api/applib/src/test/java/org/apache/isis/applib/services/clock/ClockService_example.java
new file mode 100644
index 0000000..865d5ed
--- /dev/null
+++ b/api/applib/src/test/java/org/apache/isis/applib/services/clock/ClockService_example.java
@@ -0,0 +1,39 @@
+package org.apache.isis.applib.services.clock;
+
+import java.time.LocalDateTime;
+import java.time.ZoneId;
+
+import javax.inject.Inject;
+
+import org.apache.isis.applib.annotation.Action;
+
+import lombok.Builder;
+import lombok.val;
+
+public class ClockService_example {
+
+ public static class Product { }
+
+ @Builder
+ public static class Order {
+ private Product product;
+ private int quantity;
+ private LocalDateTime placedAt;
+ }
+
+ public static class Customer {
+
+ @Action
+ public Order placeOrder(Product product, int quantity) {
+ val now = clockService.getClock()
+ .localDateTime(ZoneId.systemDefault()); // <.>
+ return Order.builder()
+ .product(product)
+ .quantity(quantity)
+ .placedAt(now)
+ .build();
+ }
+ @Inject ClockService clockService;
+ }
+}
+// <.> obtains the date/time from the `VirtualClock` provided by `ClockService`.