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/04 02:14:58 UTC

isis git commit: ISIS-1133: working on annotations (finally done the core ones...)

Repository: isis
Updated Branches:
  refs/heads/ISIS-1133 238e21d4d -> 13767df55


ISIS-1133: working on annotations (finally done the core ones...)


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/13767df5
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/13767df5
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/13767df5

Branch: refs/heads/ISIS-1133
Commit: 13767df55e6613bac4346ba8f81e1c769aa825b5
Parents: 238e21d
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 01:14:54 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 01:14:54 2015 +0100

----------------------------------------------------------------------
 ...ug_reference-annotations_aaa_deprecated.adoc |  4 +-
 ...erence-annotations_manpage-ActionLayout.adoc | 18 ++++++++
 ...ce-annotations_manpage-CollectionLayout.adoc | 22 ++++++++-
 ...tations_manpage-Collection_notPersisted.adoc | 29 ++++++++----
 ...notations_manpage-Parameter_optionality.adoc | 10 +---
 ...erence-annotations_manpage-Programmatic.adoc | 10 ----
 ..._reference-annotations_manpage-Property.adoc |  2 -
 ...ence-annotations_manpage-PropertyLayout.adoc | 31 +++----------
 ...notations_manpage-Property_notPersisted.adoc | 39 ++++++++++++----
 ...nnotations_manpage-Property_optionality.adoc | 48 +-------------------
 10 files changed, 100 insertions(+), 113 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
index 8a80ad4..362f5f4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
@@ -142,7 +142,9 @@ For domain service, use xref:_ug_reference-annotations_manpage-DomainService_nat
 
 |`@Ignore`
 |Exclude this method from the metamodel.
-|xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`]
+|xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`]. +
+
+`@Ignore` was deprecated because it can easily clash with `@org.junit.Ignore`.
 |Domain
 |
 

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
index fde78ed..9641a50 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
@@ -99,6 +99,24 @@ public class ToDoItems {
 
 
 
+
+As an alternative to using the `@ActionLayout` annotation, a dynamic layout using  xref:_ug_wicket-viewer_layout_dynamic-object-layout[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"notYetComplete": {
+    "actionLayout": {
+        "bookmarking": "AS_ROOT",
+        "cssClass": "x-key",
+        "cssClassFa": "fa-checkbox",
+        "describedAs": "Mark the todo item as not complete after all",
+        "hidden": "NOWHERE"
+    }
+}
+----
+
+
+
 include::_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
index d18c91b..3cf83c6 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
@@ -78,8 +78,7 @@ public class ToDoItem {
         namedEscaped=false,
         describedAs="Other todo items that must be completed before this one",
         labelPosition=LabelPosition.LEFT,
-        render=EAGERLY
-        typicalLength=80)
+        render=EAGERLY)
     public SortedSet<ToDoItem> getDependencies() { ... }
     ...
 }
@@ -87,6 +86,25 @@ public class ToDoItem {
 
 
 
+As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using  xref:_ug_wicket-viewer_layout_dynamic-object-layout[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"dependencies": {
+    "collectionLayout": {
+        "cssClass": "x-key",
+        "named": "Todo items that are <i>dependencies</i> of this item.",
+        "namedEscaped": false,
+        "describedAs": "Other todo items that must be completed before this one",
+        "labelPosition": "LEFT",
+        "render": "EAGERLY"
+    }
+}
+----
+
+
+
+
 
 include::_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc[leveloffset=+1]
 include::_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/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 1444a4f..53c84e4 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
@@ -11,7 +11,7 @@ The (somewhat misnamed) `notPersisted()` attribute indicates that the collection
 
 [WARNING]
 ====
-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.
+This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore.  See below for details as to how to additionally annotate the collection for this.
 ====
 
 
@@ -19,10 +19,10 @@ For example:
 
 [source,java]
 ----
-public class Order {
-    @NotPersisted
-    public Order getPreviousOrder() {...}
-    public void setPreviousOrder(Order previousOrder) {...}
+public class Customer {
+    @Collection(notPersisted=true)
+    public SortedSet<Order> getPreviousOrders() {...}
+    public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
     ...
 }
 ----
@@ -33,14 +33,25 @@ For example:
 
 [source,java]
 ----
-public class Order {
-    @NotPersisted                              // <1>
+public class Customer {
+    @Collection(notPersisted=true)             // <1>
     @javax.jdo.annotations.NotPersistent       // <2>
-    public Order getPreviousOrder() {...}
-    public void setPreviousOrder(Order previousOrder) {...}
+    public SortedSet<Order> getPreviousOrders() {...}
+    public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
     ...
 }
 ----
 <1> ignored by Isis
 <2> ignored by JDO/DataNucleus
 
+
+
+Alternatively, if the collection is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Customer {
+    public SortedSet<Order> getPreviousOrders() {...}
+    ...
+}
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
index 8d98853..777604b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
@@ -15,15 +15,7 @@ By default, Apache Isis assumes that all parameters of an action are required (m
 The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero).  If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
 ====
 
-The values for the attribute are:
-
-- `OPTIONAL` +
-+
-The parameter is optional
-
-- `MANDATORY` +
-+
-The parameter is mandatory
+The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
index c119120..064bf1d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
@@ -25,13 +25,3 @@ public class Customer implements Comparable<Customer> {
 Note that `@Programmatic` does not simply imply `@Hidden`; it actually means that the class member will not be part of the Isis metamodel.
 
 
-
-
-`@Ignore` (deprecated) is equivalent to using `@Programmatic`.
-
-[TIP]
-====
-The `@Programmatic` annotation was introduced because `@Ignore` can easily clash with `@org.junit.Ignore`.
-====
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/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 a9fd831..7fa9eb3 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
@@ -4,8 +4,6 @@
 :_basedir: ../
 :_imagesdir: images/
 
-IMPORTANT: TODO
-
 
 The `@Property` annotation applies to properties collecting together all domain semantics within a single annotation.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
index eaaf297..81bcf0b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
@@ -106,31 +106,12 @@ As an alternative to using the `@PropertyLayout` annotation, a dynamic layout us
 
 [source,javascript]
 ----
-{
-    "span": 6,
-    "memberGroups": {
-        "Other": {
-            "members": {
-                ...
-                "description": {
-                    "propertyLayout": {
-                        "cssClass": "x-key",
-                        "describedAs": "What needs to be done",
-                        "labelPosition": "LEFT",
-                        "typicalLength": 80
-                    }
-                },
-                "notes": {
-                    "propertyLayout": {
-                        "describedAs": "Additional notes"
-                        "labelPosition": "TOP",
-                        multiLine=8
-                    }
-                },
-                ....
-            }
-        },
-        ...
+"description": {
+    "propertyLayout": {
+        "cssClass": "x-key",
+        "describedAs": "What needs to be done",
+        "labelPosition": "LEFT",
+        "typicalLength": 80
     }
 }
 ----

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
index df17dc3..af7dcc0 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
@@ -7,15 +7,12 @@
 
 
 
-IMPORTANT: WIP ... this section
+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`].  This attribute is also supported for xref:_ug_reference-annotations_manpage-Collection_notPersisted[collections].
 
-The `@NotPersisted` annotation indicates that the property is not to be
-persisted.
 
-
-[NOTE]
+[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 property is not persisted in the JDO/DataNucleus objectstore.  See below for details as to how to additionally annotate the property for this.
 ====
 
 
@@ -24,15 +21,41 @@ For example:
 [source,java]
 ----
 public class Order {
-
-    @NotPersisted
+    @Property(notPersisted=true)
     public Order getPreviousOrder() {...}
     public void setPreviousOrder(Order previousOrder) {...}
+    ...
+}
+----
+
+Historically this annotation also hinted as to whether the property's value contents should be persisted in the object store.  However, the JDO/DataNucleus objectstore does not recognize this annotation.  Thus, to ensure that a property is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
 
+For example:
+
+[source,java]
+----
+public class Order {
+    @Property(notPersisted=true)               // <1>
+    @javax.jdo.annotations.NotPersistent       // <2>
+    public Order getPreviousOrder() {...}
+    public void setPreviousOrder(Order previousOrder) {...}
     ...
 }
 ----
+<1> ignored by Isis
+<2> ignored by JDO/DataNucleus
+
+
 
 
 
+Alternatively, if the property is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Order {
+    public Order getPreviousOrder() {...}
+    ...
+}
+----
 

http://git-wip-us.apache.org/repos/asf/isis/blob/13767df5/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
index 7ccbbd1..fec4556 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
@@ -106,15 +106,7 @@ public class Customer {
 The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero).  If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
 ====
 
-The values for the attribute are:
-
-- `OPTIONAL` +
-+
-The parameter is optional
-
-- `MANDATORY` +
-+
-The parameter is mandatory
+The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
 
 For example:
 
@@ -135,41 +127,3 @@ public class Customer {
 ----
 
 
-
-
-
-
-
-
-
-By default, the system assumes that all properties of an object are required, and therefore will not let the user save a new object unless a value has been specified for each property. Similarly, by default, the system assumes that all parameters in an action are required and will not let the user execute that action unless values have been specified for each parameter.
-
-To indicate that either a property, or an action parameter, is optional, use the `@Optional` annotation.
-
-
-[TIP]
-====
-The `@Optional`annotation has no meaning for a primitive property (or parameter) such as `int` - because primitives will always return a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`).
-====
-
-
-
-For example:
-
-[source,java]
-----
-public class Order {
-    public Product getProduct() { ... }
-
-    public java.util.Date getShipDate() { ... }
-    public void setShipDate(Date java.util.shipDate) { ... }
-
-    @Optional
-    public String getComments() { ... }
-    public void setComments(String comments) { ... }
-}
-----
-
-Here the `product` and `shipDate` properties are both required, but the
-`comments` property is optional.
-