You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2020/11/22 13:56:15 UTC
[isis] branch ISIS-2444 updated (fcbad30 -> cad0dcf)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git.
discard fcbad30 ISIS-2444: completes action semantics example
add 4bc3acf ISIS-2464: adoc: fix (and add additional) system overview links
new cad0dcf ISIS-2444: completes action semantics example
This update added new revisions after undoing existing revisions.
That is to say, some revisions that were in the old version of the
branch are not in the new version. This situation occurs
when a user --force pushes a change and generates a repository
containing something like this:
* -- * -- B -- O -- O -- O (fcbad30)
\
N -- N -- N refs/heads/ISIS-2444 (cad0dcf)
You should already have received notification emails for all of the O
revisions, and so the following emails describe only the N revisions
from the common base, B.
Any revisions marked "omit" are not gone; other references still
refer to them. Any revisions marked "discard" are gone forever.
The 1 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:
.../components/docs/modules/ROOT/pages/about.adoc | 2 +-
.../ROOT/pages/landing-page/components.adoc | 3 ++-
.../ROOT/partials/module-nav/components.adoc | 4 ++++
.../reference-services/commands-and-events.png | Bin 156975 -> 177438 bytes
.../reference-services/commands-and-events.pptx | Bin 24163 -> 25197 bytes
.../isis/applib/services/command/Command.java | 4 ++--
.../publish/CommandPublisherDefault.java | 2 +-
7 files changed, 10 insertions(+), 5 deletions(-)
[isis] 01/01: ISIS-2444: completes action semantics example
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit cad0dcf91218d8ab76046468ab5bba473793054c
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Nov 22 13:10:41 2020 +0000
ISIS-2444: completes action semantics example
---
.../semantics/ActionSemanticsVm-description.adoc | 131 +++++++++++++++++++--
.../Action/semantics/ActionSemanticsVm.java | 50 +++-----
2 files changed, 139 insertions(+), 42 deletions(-)
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm-description.adoc
index f1a4801..3e3402f 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm-description.adoc
@@ -60,6 +60,8 @@ This is also sometimes called _query-only_.
The framework does not verify or ensure that the action results in no side-effects; the annotation is taken "on trust".
====
+Safe actions are called using HTTP GET when invoked through the Restful Objects' REST API.
+
Both regular and mixin actions can be annotated:
* on regular actions; the `reportPropertyForSafe` action is annotated as having safe semantics:
@@ -68,9 +70,9 @@ Both regular and mixin actions can be annotated:
----
include::ActionSemanticsVm.java[tags=action-semantics-safe]
----
-<.> safe semantics, meaning that invoking the action results in no permanent change of state
+<.> safe semantics, meaning invoking the action results in no permanent change of state
-* on mixin actions; `reportPropertyForSafe` is annotated with safe sematics
+* on mixin actions; `mixinReportPropertyForSafe` is annotated with safe semantics
+
[source,java]
----
@@ -78,18 +80,133 @@ include::ActionSemanticsVm_mixinReportPropertyForSemanticsSafe.java[tags=class]
----
<.> safe semantics, meaning that invoking the action results in no permanent change of state
-*TODO: safe and request cacheable*
+=== Safe and Request Cacheable
+
+Since invoking a safe query-only action will often return the same result (at least for some short period of time), the framework also provides a variant that will automatically cache the result for the duration of the interaction (HTTP request).
+
+To leverage this, the action must be invoked "through" the framework, in other words using the `WrapperFactory` service.
+
+To demonstrate this, the demo app declares the following action:
+
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-safe-and-request-cacheable]
+----
+<.> the result of invoking this action will be cached for the duration of the interaction (HTTP request)
+<.> the action need not be exposed in the end-user
+<.> for the purpose of the demo, counts the number of times invoked
+
+This action can then be invoked through the `WrapperFactory`:
+
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-safe-and-request-cacheable-caller]
+----
+<.> invoke the action 5 times
+<.> skips the check that the action is hidden
+<.> reports on the number of times the action was actually executed
+
+In this case the called action should indicate it was only executed once.
== Annotated as Idempotent
-*TODO: idempotent*
-*TODO: idempotent are you sure*
+Annotating an action as idempotent means that it will change the state of the system, but invoking more than once will not change the state of the system further.
+
+Idempotent actions are called using HTTP PUT when invoked through the Restful Objects' REST API.
+
+Both regular and mixin actions can be annotated:
+
+* on regular actions; the `setToValuePropertyForIdempotent` action is annotated as having idempotent semantics:
++
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-idempotent]
+----
+<.> idempotent semantics
+
+* on mixin actions; `mixinSetToValueForPropertySemanticsIdempotent` is annotated with idempotent sematics
++
+[source,java]
+----
+include::ActionSemanticsVm_mixinSetToValueForPropertySemanticsIdempotent.java[tags=class]
+----
+<.> idempotent semantics
+
+
+=== Are you sure?
+
+Because an idempotent action will change the state of the system, the framework offers a variant that will cause the viewer to render an "are you sure?" pop-up.
+
+Both regular and mixin actions can be annotated:
+
+* on regular actions; the `setToValuePropertyForIdempotentAreYouSure` action is annotated as having idempotent "are you sure" semantics:
++
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-idempotent-are-you-sure]
+----
+<.> idempotent semantics, with "are you sure" prompt
+
+* on mixin actions; `mixinSetToValueForPropertySemanticsIdempotent` is annotated with idempotent "are you sure" semantics
++
+[source,java]
+----
+include::ActionSemanticsVm_mixinSetToValueForPropertySemanticsIdempotentAreYouSure.java[tags=class]
+----
+<.> idempotent semantics, with "are you sure" prompt
+
== Annotated as Not Idempotent
-*TODO: non idempotent*
-*TODO: non idempotent are you sure*
+Annotating an action as non-idempotent means that it will change the state of the system, and invoking more than once will change the state of the system further.
+
+If an action is not annotated with the `semantics` element, it is considered to be non-idempotent.
+
+Non-idempotent actions are called using HTTP POST when invoked through the Restful Objects' REST API.
+
+Both regular and mixin actions can be annotated:
+
+* on regular actions; the `incrementByAmountPropertyForNonIdempotent` action is annotated as having non-idempotent semantics:
++
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-non-idempotent]
+----
+<.> non-idempotent semantics
+
+* on mixin actions; `mixinSetToValueForPropertySemanticsIdempotent` is annotated with non-idempotent semantics
++
+[source,java]
+----
+include::ActionSemanticsVm_mixinIncrementByAmountNonIdempotent.java[tags=class]
+----
+<.> non-idempotent semantics
+
+
+=== Are you sure ?
+
+Because an non-idempotent action will change the state of the system, the framework offers a variant that will cause the viewer to render an "are you sure?" pop-up.
+
+Both regular and mixin actions can be annotated:
+
+* on regular actions; the `incrementByAmountPropertyForNonIdempotentAreYouSure` action is annotated as having non-idempotent "are you sure" semantics:
++
+[source,java,indent=0]
+----
+include::ActionSemanticsVm.java[tags=action-semantics-non-idempotent-are-you-sure]
+----
+<.> non-idempotent semantics, with "are you sure" prompt
+
+* on mixin actions; `mixinIncrementNonIdempotentAreYouSure` is annotated with non-idempotent "are you sure" semantics
++
+[source,java]
+----
+include::ActionSemanticsVm_mixinIncrementNonIdempotentAreYouSure.java[tags=class]
+----
+<.> non-idempotent semantics, with "are you sure" prompt
++
+NOTE: Because this action takes no parameters, then the pop-up will be triggered for the action button itself (rather than the OK button of the action prompt form).
== Meta-annotated
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm.java b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm.java
index 1d81648..73e15d3 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/annotDomain/Action/semantics/ActionSemanticsVm.java
@@ -174,40 +174,37 @@ public class ActionSemanticsVm implements HasAsciiDocDescription {
}
//end::action-semantics-safe[]
-//tag::action-semantics-safe-and-request-cacheable[]
+//tag::action-semantics-safe-and-request-cacheable-caller[]
@Action(
- semantics = SemanticsOf.SAFE_AND_REQUEST_CACHEABLE // <.>
+ semantics = SemanticsOf.SAFE
, associateWith = "propertyForSafeAndRequestCacheable"
, associateWithSequence = "1"
)
@ActionLayout(
- named = "Report",
- describedAs =
- "@Action(semantics = SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)"
+ named = "Report"
+ , describedAs = "@Action(semantics = SemanticsOf.SAFE)"
)
public ActionSemanticsVm reportPropertyForSafeAndRequestCacheable() {
int val = 0;
- for (int i=0; i<5; i++) {
- val = wrapperFactory.wrap(this, control().withSkipRules())
+ for (int i=0; i<5; i++) { // <.>
+ val = wrapperFactory.wrap(this, control().withSkipRules()) // <.>
.queryPropertyForSafeAndRequestCacheable();
}
messageService.informUser(String.format(
"Action 'queryPropertyForSafeAndRequestCacheable' returns %d " +
- "and was invoked 5 times in this action but was executed %d times."
+ "and was invoked 5 times in this action but was executed %d times." // <.>
, val, numberOfTimesActionSafeAndRequestCacheableWasExecuted));
return this;
}
+//end::action-semantics-safe-and-request-cacheable-caller[]
+//tag::action-semantics-safe-and-request-cacheable[]
@Action(
- semantics = SemanticsOf.SAFE_AND_REQUEST_CACHEABLE // <.>
- , hidden = Where.EVERYWHERE
- )
- @ActionLayout(
- describedAs =
- "@Action(semantics = SemanticsOf.SAFE_AND_REQUEST_CACHEABLE)"
+ semantics = SemanticsOf.SAFE_AND_REQUEST_CACHEABLE // <.>
+ , hidden = Where.EVERYWHERE // <.>
)
public int queryPropertyForSafeAndRequestCacheable() {
- ++numberOfTimesActionSafeAndRequestCacheableWasExecuted;
+ ++numberOfTimesActionSafeAndRequestCacheableWasExecuted; // <.>
return getPropertyForSafeAndRequestCacheable();
}
transient int numberOfTimesActionSafeAndRequestCacheableWasExecuted = 0;
@@ -220,9 +217,8 @@ public class ActionSemanticsVm implements HasAsciiDocDescription {
, associateWithSequence = "1"
)
@ActionLayout(
- named = "Set to Value",
- describedAs =
- "@Action(semantics = SemanticsOf.IDEMPOTENT)"
+ named = "Set to Value"
+ , describedAs = "@Action(semantics = SemanticsOf.IDEMPOTENT)"
)
public ActionSemanticsVm setToValuePropertyForIdempotent(final int value) {
setPropertyForIdempotent(value);
@@ -241,8 +237,7 @@ public class ActionSemanticsVm implements HasAsciiDocDescription {
)
@ActionLayout(
named = "Set to Value",
- describedAs =
- "@Action(semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE)"
+ describedAs = "@Action(semantics = SemanticsOf.IDEMPOTENT_ARE_YOU_SURE)"
)
public ActionSemanticsVm setToValuePropertyForIdempotentAreYouSure(final int value) {
setPropertyForIdempotentAreYouSure(value);
@@ -260,21 +255,6 @@ public class ActionSemanticsVm implements HasAsciiDocDescription {
, associateWithSequence = "1"
)
@ActionLayout(
- named = "Increment"
- , describedAs =
- "@Action(semantics = SemanticsOf.NON_IDEMPOTENT)"
- )
- public ActionSemanticsVm incrementPropertyForNonIdempotent() {
- setPropertyForNonIdempotent(getPropertyForNonIdempotent() + 1);
- return this;
- }
-
- @Action(
- semantics = SemanticsOf.NON_IDEMPOTENT // <.>
- , associateWith = "propertyForNonIdempotent"
- , associateWithSequence = "2"
- )
- @ActionLayout(
named = "Increment by Amount"
, describedAs =
"@Action(semantics = SemanticsOf.NON_IDEMPOTENT)"