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:31 UTC
[23/51] [abbrv] isis git commit: ISIS-1133: working on annotations.
ISIS-1133: working on annotations.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/6192bae9
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/6192bae9
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/6192bae9
Branch: refs/heads/master
Commit: 6192bae999c4fd678bb4f73f685807b166123f43
Parents: 4a9da14
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Jun 1 17:54:14 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Jun 1 17:54:14 2015 +0100
----------------------------------------------------------------------
...ug_reference-annotations_manpage-Action.adoc | 6 +-
...ence-annotations_manpage-Action_command.adoc | 12 +-
...-annotations_manpage-Action_domainEvent.adoc | 11 +-
...rence-annotations_manpage-Action_typeOf.adoc | 11 +-
...eference-annotations_manpage-Collection.adoc | 20 ++-
...otations_manpage-Collection_domainEvent.adoc | 11 +-
...tations_manpage-Collection_notPersisted.adoc | 29 +++-
...e-annotations_manpage-Collection_typeOf.adoc | 22 ++-
...nnotations_manpage-DomainObject_editing.adoc | 166 +++----------------
..._reference-annotations_manpage-Property.adoc | 22 ++-
...nnotations_manpage-Property_domainEvent.adoc | 9 +-
.../_ug_runtime_configuring-core.adoc | 45 ++++-
.../isis/applib/annotation/Collection.java | 9 +-
.../apache/isis/applib/annotation/Property.java | 9 +-
14 files changed, 169 insertions(+), 213 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
index b3b36ff..dbebc3b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
@@ -32,7 +32,7 @@ The table below summarizes the annotation's attributes.
|`commandPersistence()`
-|`PERSISTED`,`NOT_PERSISTED`,`IF_HINTED` +
+|`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
(`PERSISTED`)
|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] has been configured).
@@ -44,7 +44,7 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-Action_hidden[`hidden()`]
-|`EVERYWHERE`,`NOWHERE` +
+|`EVERYWHERE`, `NOWHERE` +
(`NOWHERE`)
|indicates where (in the UI) the action should be hidden from the user.
@@ -63,7 +63,7 @@ Currently this is only supported for no-arg actions.
|whether changes to the object should be published to the registered xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
|`publishingPayloadFactory()`
-|subtype of `PublishingPayloadFactoryForAction` (none)
+|subtype of `PublishingPayloadFactory-` `ForAction` (none)
|specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
index ee189a1..ef687bc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
@@ -28,10 +28,6 @@ If background ``Command``s are used, then an external scheduler, using xref:_ug_
-
-
-== `command()`
-
The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service).
The default is `AS_CONFIGURED`, meaning that the configuration property `isis.services.command.actions` is used to determine the whether the action is reified:
@@ -40,7 +36,7 @@ The default is `AS_CONFIGURED`, meaning that the configuration property `isis.se
+
all actions are reified
-* `ignoreSafe` (or `ignoreQueryOnly`)+
+* `ignoreSafe` (or `ignoreQueryOnly`) +
+
actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
@@ -84,7 +80,8 @@ To explain this last alternative:
public class Order {
@Action(
command=CommandReification.ENABLED,
- commandPersistence=CommandPersistence.IF_HINTED)
+ commandPersistence=CommandPersistence.IF_HINTED
+ )
public Invoice generateInvoice(...) { ... }
}
----
@@ -99,7 +96,8 @@ public class Order {
@Command(
command=CommandReification.ENABLED,
commandExecuteIn=CommandExecuteIn.FOREGROUND,
- commandPersistence=CommandPersistence.NOT_PERSISTED)
+ commandPersistence=CommandPersistence.NOT_PERSISTED
+ )
public Invoice generateInvoice(...) { ... }
}
----
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
index f6ea76a..e164b80 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
@@ -28,6 +28,12 @@ public class ToDoItem {
The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead.
+
+[NOTE]
+====
+As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Collection_domainEvent[collection] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
+====
+
For example:
[source,java]
@@ -50,11 +56,6 @@ public class ToDoItem {
The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-[NOTE]
-====
-As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Collection_domainEvent[collection] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-====
-
== Subscribers
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
index bbf4258..368048f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
@@ -8,6 +8,12 @@
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.
+[NOTE]
+====
+This attribute can also be specified for xref:_ug_reference-annotations_manpage-Collection_typeOf[collections].
+====
+
+
For example:
[source,java]
@@ -24,4 +30,7 @@ public void AccountService {
}
----
-
+[TIP]
+====
+In general we recommend that you use generics instead, eg `List<Customer>`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
index 7e0b064..c4da812 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
@@ -25,7 +25,7 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-Collection_editing[`editing()`]
-|`ENABLED`,`DISABLED`,`AS_CONFIGURED` +
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
(`AS_CONFIGURED`)
|whether a collection can be added to or removed from within the UI
@@ -36,18 +36,26 @@ The table below summarizes the annotation's attributes.
|xref:_ug_reference-annotations_manpage-Collection_hidden[`hidden()`]
-|
-|
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
|xref:_ug_reference-annotations_manpage-Collection_notPersisted[`notPersisted()`]
-|
-|
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
+
|xref:_ug_reference-annotations_manpage-Collection_typeOf[`typeOf()`]
|
-|
+|hints as to the run-time type of the objects within that collection (as a fallback)
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
index dd85549..3cc55a5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
@@ -34,6 +34,12 @@ public class ToDoItem {
The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead.
+[NOTE]
+====
+As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
+====
+
+
For example:
[source,java]
@@ -56,11 +62,6 @@ public class ToDoItem {
The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-[NOTE]
-====
-As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-====
-
== Subscribers
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
index f101ee9..792025a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
@@ -6,29 +6,40 @@
+The (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`].
-IMPORTANT: WIP ... this section
-
-The `@NotPersisted` annotation indicates that the property is not to be
-persisted.
-
-
-[TIP]
+[WARNING]
====
-In many cases the same thing can be achieved simply by providing the property with a 'getter' but no 'setter'.
+This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additional annotate the collection for this.
====
+
For example:
[source,java]
----
public class Order {
-
@NotPersisted
public Order getPreviousOrder() {...}
public void setPreviousOrder(Order previousOrder) {...}
+ ...
+}
+----
+Historically this annotation also hinted as to whether the collection's contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @NotPersisted // <1>
+ @javax.jdo.annotations.NotPersistent // <2>
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
...
}
----
+<1> ignored by Isis
+<2> ignored by JDO/DataNucleus
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
index 381f39f..456e014 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
@@ -5,29 +5,27 @@
:_imagesdir: images/
-
-IMPORTANT: WIP ... this section
-
-
-The `@TypeOf` annotation is used to specify the type of elements in a collection, when for whatever reason it is not possible to use generics.
+The `typeOf()` attribute specifies the expected type of an element contained within 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.
[NOTE]
====
-Given that Apache Isis only supports Java 1.7 and later, it's not that obvious what such a reason might be...
+This attribute can also be specified for xref:_ug_reference-annotations_manpage-Action_typeOf[actions].
====
-
For example:
[source,java]
----
-public void AccountService {
- @TypeOf(Customer.class)
- public List errantAccounts() {
- return CustomerDatabase.allNewCustomers();
- }
+public void Customer {
+ @TypeOf(Order.class)
+ public SortedSet getOutstandingOrders() { ... }
...
}
----
+[TIP]
+====
+In general we recommend that you use generics instead, eg `SortedSet<Order>`.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
index 913bc33..0f1e08c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
@@ -6,172 +6,48 @@
+The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only). The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
-IMPORTANT: WIP ... this section
+The default is `AS_CONFIGURED`, meaning that the configuration property `isis.objects.editing` is used to determine the whether the object is modifiable:
-
-[NOTE]
-====
-Fully supported by: Wicket viewer; other viewers do not yet support the `where` attribute.
-====
-
-
-
-The `@Disabled` annotation means that the member cannot be used in any instance of the class. When applied to the property it means that the user may not modify the value of that property (though it may still be modified programmatically). When applied to an action method, it means that the user cannot invoke that method.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Disabled
- public void assessCreditWorthiness() { ... }
-
- @Disabled
- public int getInitialCreditRating(){ ... }
- public void setInitialCreditRating(int initialCreditRating) { ... }
-}
-----
-
-Note that if an action is marked as `@Disabled`, it will be shown on the
-user interface but cannot ever be invoked. The only possible reason we
-can think to do this is during prototyping, to indicate an action that
-is still to be developed. If a method is intended for programmatic use,
-but not intended ever to be invoked directly by a user, then it should
-be marked as `@Hidden` instead.
-
-This annotation can also take two parameter indicating where (in the UI)
-it is to be disabled, and when (in the object's lifecycle) it is to be
-disabled. For example:
-
-[source,java]
-----
-public class Customer {
- (when=When.UNTIL_PERSISTED)
- public void assessCreditWorthiness() { ... }
-}
-----
-
-would disable the action until the object has been saved. And:
-
-[source,java]
-----
-public class Customer {
- (where=Where.PARENTED_TABLES)
- public void getFirstName() { ... }
-}
-----
-
-would disable the property in parented tables but not in regular object
-forms (though note: this would only be used by viewers that provide
-in-table editing capability).
-
-The acceptable values for the `where` parameter are:
-
-* `Where.ANYWHERE` +
+* `true` +
+
-The member should be disabled everywhere.
+the object's properties and collections are modifiable.
-* `Where.OBJECT_FORMS` +
+* `false`+
+
-The member should be disabled when displayed within an object form.
-For most viewers, this applies to property and collection members,
-not actions.
-
-* `Where.PARENTED_TABLES` +
-+
-The member should be disabled when displayed as a column of a table
-within a parent object's collection. For most (all?) viewers, this
-will have meaning only if applied to a property member.
-
-* `Where.STANDALONE_TABLES` +
-+
-The member should be disabled when displayed as a column of a table
-showing a standalone list of objects, for example as returned by a
-repository query. For most (all?) viewers, this will have meaning
-only if applied to a property member.
-
-* `Where.ALL_TABLES` +
-+
-The member should be disabled when displayed as a column of a table,
-either an object's * collection or a standalone list. This combines
-`PARENTED_TABLES` and `STANDALONE_TABLES`
-
-* `Where.NOWHERE` +
-+
-Has no meaning for the `@Disabled` annotation (though is used by the
-`@Hidden` annotation which also uses the `Where` enum<!--, see ?-->).
-
-The acceptable values for the `when` parameter are:
-
-* `When.ALWAYS` +
-+
-The member should be disabled at all times.
-
-* `When.NEVER` +
-+
-The member should never be disabled (unless disabled through some
-other mechanism, for example an imperative disableXxx() supporting
-method)..
-
-* `When.ONCE_PERSISTED` +
-+
-The member should be enabled for transient objects, but disabled for
-persisted objects.
-
-* `When.UNTIL_PERSISTED` +
-+
-The member should be disabled for transient objects, but enabled for
-persisted objects.
-
-By default the annotated property or action is always disabled (ie
-defaults to `Where.ANYWHERE`, `When.ALWAYS`).
+the object's properties and collections are read-only, ie _not_ modifiable.
+If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
+[TIP]
+====
+In other words, editing can be disabled globally for an application by setting:
+[source,ini]
+----
+isis.objects.editing=false
+----
+We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+====
-The `@Immutable` annotation may be applied to a class, and indicates to the framework that the state of such objects may not be changed. The viewers will prevent any change through the user interface, and moreover the object stores will reject any changes to the objects that might have occurred programmatically.
+This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
For example:
[source,java]
----
-@Immutable
+@DomainObject(
+ editing=Editing.DISABLED,
+ editingDisabledReason="Reference data, so cannot be modified"
+)
public class Country {
...
}
----
-This annotation can also take a single parameter indicating when it is
-to become immutable. For example:
-
-[source,java]
-----
-@Immutable(When.ONCE_PERSISTED)
-public class Email {
- ...
-}
-----
-
-This would allow the user to create an email object and set it up, and
-then prevent any changes once it has been saved.
-
-The acceptable values for the parameter are:
-
-* `When.ALWAYS`
-
-* `When.NEVER`
-
-* `When.ONCE_PERSISTED`
-
-* `When.UNTIL_PERSISTED`
-
-By default the annotated property or action is always immutable (ie
-defaults to `When.ALWAYS`).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
index b1bd4c0..e810f31 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
@@ -28,14 +28,16 @@ It is also possible to apply the annotation to actions of domain services that a
|the event type to be posted to the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
-|xref_ug_reference-annotations_manpage-Property_editing[`editing()`]
-|
-|
+|xref:_ug_reference-annotations_manpage-Property_editing[`editing()`]
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
+(`AS_CONFIGURED`)
+|whether a property can be modified or cleared from within the UI
|xref:_ug_reference-annotations_manpage-Property_hidden[`hidden()`]
-|
-|
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
|xref:_ug_reference-annotations_manpage-Property_maxLength[`maxLength()`]
@@ -49,8 +51,14 @@ It is also possible to apply the annotation to actions of domain services that a
|xref:_ug_reference-annotations_manpage-Property_notPersisted[`notPersisted()`]
-|
-|
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
|xref:_ug_reference-annotations_manpage-Property_optionality[`optionality()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
index b41b67f..c009601 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
@@ -28,6 +28,11 @@ public class ToDoItem {
The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead.
+[NOTE]
+====
+As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
+====
+
For example:
[source,java]
@@ -52,10 +57,6 @@ public class ToDoItem {
The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-[NOTE]
-====
-As you might expect, it is also possible to influence the domain event type raised for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
index 1d89386..1061659 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
@@ -16,7 +16,7 @@ Configuration properties for the viewers can be found in the <<Wicket Viewer>> c
|===
|Property
|Value +
-(_default value_)
+(default value)
|Description
|`isis.services`
@@ -32,38 +32,53 @@ Configuration properties for the viewers can be found in the <<Wicket Viewer>> c
`translation.po.mode`
| `read`,`write`
|Whether to force the `TranslationService` into either read or write mode. +
+
See xref:_ug_more-advanced_i18n[i18n support] to learn more about the translation service.
|`isis.services.` +
`command.actions`
| `all`,`ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically reified into commands (for actions annotated with xref:_ug_reference-annotations_manpage-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
+|Whether actions should be automatically reified into commands (for actions annotated with xref:_ug_reference-annotations_manpage-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`]. +
+
+`ignoreQueryOnly` is an alias for `ignoreSafe`.
|`isis.services.` +
`publish.actions`
| `all`,`ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically published (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
+|Whether actions should be automatically published (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
+
+`ignoreQueryOnly` is an alias for `ignoreSafe`.
+
+|`isis.object.` +
+`editing`
+| `true`,`false` (`true`)
+|Whether objects' properties and collections can be edited directly (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]); see xref:_ug_runtime_configuring-core_isis-objects-editing[below] for further discussion.
|`isis.persistor.` +
`disableConcurrencyChecking`
-| `true`,`false` (`_false_`)
-| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
+| `true`,`false` (`false`)
+| Disables concurrency checking globally. +
+
+Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
|`isis.reflector.facet.` +
`cssClassFa.patterns`
|regex:fa-icon,regex2:fa-icon2,...
|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:http://fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
+
See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
|`isis.reflector.facet.` +
`cssClass.patterns`
|regex:css1,regex2:css2,...
|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
+
See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
|`isis.reflector.facets`
|`FQCN`
-|Fully qualified class names of a custom implementation of `ProgrammingModel` interface.
+|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
+
See xref:_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
|`isis.reflector.facets.` +
@@ -76,24 +91,40 @@ See xref:_ug_extending_programming-model_finetuning[finetuning the programming m
`exclude`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
+
See xref:_ug_extending_programming-model_finetuning[finetuning the programming model] for more details.
|`isis.reflector.validator`
|`FQCN`
|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
+
See xref:_ug_extending_programming-model_custom-validator[Custom Validator] to learn more.
|`isis.reflector.validator.` +
`allowDeprecated`
-| `true`,`false` (`_true_`)
+| `true`,`false` (`true`)
| Whether deprecated annotations or naming conventions are tolerated or not. If not, then a metamodel validation error will be triggered, meaning the app won't boot (fail-fast).
|`isis.reflector.` +
`layoutMetadataReaders`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:_ug_wicket-viewer_layout_dynamic-object-layout[dynamic layout]s. +
+
See xref:_ug_extending_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
|===
+
+[[_ug_runtime_configuring-core_isis-objects-editing]]
+== `isis.objects.editing`
+
+This configuration property in effect allows editing to be disabled globally for an application:
+
+[source,ini]
+----
+isis.objects.editing=false
+----
+
+We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/core/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
index 7649a21..ee7e3d4 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
@@ -24,6 +24,9 @@ import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+
+import javax.jdo.annotations.NotPersistent;
+
import org.apache.isis.applib.services.eventbus.CollectionDomainEvent;
/**
@@ -92,7 +95,11 @@ public @interface Collection {
/**
- * Indicates that the property should not be persisted.
+ * Indicates that the collection should be excluded from snapshots.
+ *
+ * <p>
+ * To ensure that the collection is actually not persisted in the objectstore, also annotate with {@link NotPersistent}.
+ * </p>
*/
boolean notPersisted() default false;
http://git-wip-us.apache.org/repos/asf/isis/blob/6192bae9/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
index 339f5ac..84586ce 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
@@ -24,6 +24,9 @@ import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
+
+import javax.jdo.annotations.NotPersistent;
+
import org.apache.isis.applib.services.eventbus.PropertyDomainEvent;
import org.apache.isis.applib.spec.Specification;
@@ -117,7 +120,11 @@ public @interface Property {
// //////////////////////////////////////
/**
- * Indicates that the property should not be persisted.
+ * Indicates that the property should be excluded from snapshots.
+ *
+ * <p>
+ * To ensure that the property is actually not persisted in the objectstore, also annotate with {@link NotPersistent}.
+ * </p>
*/
boolean notPersisted() default false;