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 2015/06/05 13:56:58 UTC
[50/51] [abbrv] isis git commit: ISIS-1133: last of the reserved
methods (not lifecycle ones yet, though).
ISIS-1133: last of the reserved methods (not lifecycle ones yet, though).
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/c8b11b7a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/c8b11b7a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/c8b11b7a
Branch: refs/heads/master
Commit: c8b11b7af813e0d63f9394ecd836479cb19a47cd
Parents: 9656a71
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Jun 5 01:12:00 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Jun 5 01:12:00 2015 +0100
----------------------------------------------------------------------
...erence-methods_reserved_manpage-disable.adoc | 94 +++++++++++++++++++-
...eference-methods_reserved_manpage-getId.adoc | 12 ++-
...reference-methods_reserved_manpage-hide.adoc | 31 ++++++-
...rence-methods_reserved_manpage-validate.adoc | 20 ++++-
4 files changed, 149 insertions(+), 8 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/c8b11b7a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
index 865a3bf..37b8a48 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
@@ -4,9 +4,99 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+One use case that Isis supports is that of a domain object with a lifecycle whereby at some stage it should become immutable: all its properties/collections should be disabled, and/or its actions become not invokable.
+It would be painful to have to write a separate xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`] method for each and every member, so instead Isis allows a single `disable...(...)` method to be implemented that is applied to all members.
-Disable all or some of an object's properties
+The signature of the method is:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+Note that Isis' xref:_ug_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.
+
+For example:
+
+[source,java]
+----
+public String disable(Identifier.Type identifierType) {
+ return !calendarService.isOfficeHours(clock.today()
+ ? "Cannot modify objects outside of office hours"
+ : null;
+}
+----
+
+See also the similar methods to xref:_ug_reference-methods_reserved_manpage-hide[`hide()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+With this approach we define, for a given domain class, a base `PropertyDomainEvent`, `CollectionDomainEvent` and `ActionDomainEvent`. A good pattern is to make these nested static classes. For example:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public static abstract class PropertyDomainEvent<T>
+ extends ToDoAppDomainModule.PropertyDomainEvent<ToDoItem, T> {
+ ...
+ }
+ ...
+}
+----
+
+where in turn:
+
+[source,java]
+----
+public final class ToDoAppDomainModule {
+ private ToDoAppDomainModule(){}
+ public abstract static class PropertyDomainEvent<S,T>
+ extends org.apache.isis.applib.services.eventbus.PropertyDomainEvent<S,T> {
+ ...
+ }
+ ...
+}
+----
+
+Then, each property/collection/action emits either these base domain events or their own subclass:
+
+[source,java]
+----
+public class ToDoItem ... {
+ public static class DescriptionDomainEvent
+ extends PropertyDomainEvent<String> {
+ ...
+ }
+ @Property(
+ domainEvent = DescriptionDomainEvent.class
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+A vetoing subscriber can then subscribe to the domain events and veto access, eg:
+
+[source,java]
+----
+@DomainObject
+public class VetoOutOfOfficeHours {
+ @Subscribe
+ public void on(ToDoItem.PropertyDomainEvent ev) {
+ if(!calendarService.isOfficeHours(clock.today()) {
+ ev.veto("Cannot modify objects outside of office hours");
+ }
+ }
+ ...
+}
+----
+
+Obviously there's an awful lot more boilerplate here, but there's also a lot more flexibility.
http://git-wip-us.apache.org/repos/asf/isis/blob/c8b11b7a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
index 10757e1..34bda78 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
@@ -4,8 +4,16 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+The `getId()` method applies only to domain services, and allows a unique identifer to be provided for that service.
+
+This identifier corresponds in many ways to the xref:_ug_reference-annotations_manpage-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]'s REST API.
+
+If the identifier is omitted, the services fully qualified class name is used.
+
+[TIP]
+====
+Unlike domain objects, where the use of an object type is strongly encouraged (eg using xref:_ug_reference-annotations_manpage-PersistenceCapable[`@PersistenceCapable`]), it matters much less if an id is specified for domain services. The principle benefit is shorter URLs in the REST API.
+====
-Provides an optional unique identifier of a service.
http://git-wip-us.apache.org/repos/asf/isis/blob/c8b11b7a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
index 4155c3d..af3c492 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
@@ -4,9 +4,36 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+One use case that Isis supports is that of a domain object with a lifecycle whereby at some stage some number of the object's members should be hidden. For example, for an object that at some stage is logically immutable, we might want to make all its properties/collections unmodifiable and hide all its actions.
-Hide all or some of an object's properties
+While we could write a separate xref:_ug_reference-methods_prefixes_manpage-hide[`hide...()`] method for each and every action, this could become painful. So instead Isis allows a single `hide...(...)` method to be implemented that is applied to all members.
+
+The signature of the method is:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) { ... }
+----
+
+where `Identifier.Type` is part of the Isis applib (nested static class of `o.a.i.applib.Identifier`) to distinguish between an interaction with an action, a property or an action.
+
+For example:
+
+[source,java]
+----
+public boolean hide(Identifier.Type identifierType) {
+ return identifierType == Identifier.Type.ACTION && isFrozen();
+}
+----
+
+See also the similar method to xref:_ug_reference-methods_reserved_manpage-disable[`disable()`] object members en-masse.
+
+
+== Alternatives
+
+An alternative design -- and one that could be easily argued is actually more flexible -- is to leverage domain events with vetoing subscribers.
+
+There is further discussion on this approach in xref:_ug_reference-methods_reserved_manpage-disable[here].
http://git-wip-us.apache.org/repos/asf/isis/blob/c8b11b7a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
index 8940abb..0afba4b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
@@ -4,8 +4,24 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+The `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-Validate the object's state prior to persisting.
+
+[WARNING]
+====
+(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
+====
+
+
+The signature of the method is:
+
+[source,java]
+----
+public String validate() { ... }
+----
+
+where the returned string is the reason that the invocation is vetoed.
+
+Note that Isis' xref:_ug_more-advanced_i18n[i18n support] extends this so that the returned reason can also be internationalized.