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:52 UTC

[44/51] [abbrv] isis git commit: ISIS-1133: @MemberOrder, @MemberGroupLayout, @NotPersistent, @PrimaryKey and so on.

ISIS-1133: @MemberOrder, @MemberGroupLayout, @NotPersistent, @PrimaryKey and so on.


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

Branch: refs/heads/master
Commit: 4c99a344ccf703a8ed286faf847188f3ef55a17d
Parents: e9ccddb
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 14:47:31 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 14:47:31 2015 +0100

----------------------------------------------------------------------
 ...e-annotations_manpage-MemberGroupLayout.adoc |  13 ++-
 ...ference-annotations_manpage-MemberOrder.adoc | 116 ++-----------------
 ...rence-annotations_manpage-NotPersistent.adoc |  10 +-
 ...eference-annotations_manpage-PrimaryKey.adoc |  12 +-
 .../_ug_reference-object-layout_static.adoc     |  28 ++++-
 .../src/main/asciidoc/user-guide/ug.adoc        |   2 +-
 6 files changed, 61 insertions(+), 120 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
index 5c3b8f9..3e8a513 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
@@ -6,4 +6,15 @@
 
 
 
-The `@MemberGroupLayout` annotation specifies how an object's properties and collections ...
\ No newline at end of file
+The `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns.  It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`] annotation.
+
+
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+
+The annotation defines two attributes, `name()` and `sequence()`.  Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
+
+
+[IMPORTANT]
+====
+As this is an important topic, there is a xref:_ug_reference-object-layout[separate chapter] that discussed object layout in full.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
index d34e252..3ab277f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
@@ -5,119 +5,21 @@
 :_imagesdir: images/
 
 
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions.  It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
 
+The annotation defines four attributes:
 
+* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
 
+* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
 
+* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
 
-[TIP]
-====
-We generally recommend that you use xref:_ug_reference-object-layout_dynamic[dynamic object layouts].
-====
-
-
-
-`@MemberOrder` is the recommended mechanism for specifying the order in
-which fields and/or actions are presented to the user. (`@ActionOrder`
-and `@FieldOrder` provide alternative, deprecated mechanisms).
-
-`@MemberOrder` is specified at the individual member level, relative to
-other members, as a string. The simplest convention is to use numbers -
-1, 2, 3 - though it is a better idea to leave gaps in the numbers - 10,
-20, 30 perhaps - such that a new member may be added without having to
-edit existing numbers. A useful alternative is to adopt the
-'dewey-decimal' notation - 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -
-which allows for an indefinite amount of future insertion, and allows
-subclasses to insert their class members as required.
-
-For example:
+* `right()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the right-most column
 
-[source,java]
-----
-public Class Customer {
-    @MemberOrder(sequence="2.1")
-    public String getAddress() {...}
-    public void setAddress(value as String) {...}
+Collections are always rendered in the "last" column.  This can appear either below the columns holding properties (if their column spans = 12), or can be rendered to the right of the property columns (if the spans of the property columns come to <12 leaving enough room for the span of the collection column).
 
-    @MemberOrder(sequence="1.1")
-    public String getFirstName() {...}
-    public void setFirstName(value as String) {...}
-
-    @MemberOrder(sequence="1.2")
-    public String getLastName() {...}
-    public void setLastName(value as String) {...}
-
-    @MemberOrder(sequence="3")
-    public Date getDateOfBirth() {...}
-    public void setDateOfBirth(value as Date) {...}
-    ...
-}
-----
-
-If a member does not have a specified order then it will be placed after
-those that are specified. Two members may have the same sequence
-specifier, but in such a case the relative ordering of those members
-will be indeterminate.
-
-
-[NOTE]
+[IMPORTANT]
 ====
-The xref:_ug_wicket-viewer[Wicket viewer] lays out an object's properties and its collections separately, in which case the relative member order of properties and collections will be evaluated separately. In general, though, consider the layout of all properties and collections together, and of all actions together.
+As this is an important topic, there is a xref:_ug_reference-object-layout[separate chapter] that discussed object layout in full.
 ====
-
-
-As a refinement to this, some viewers support the notion of grouping
-members together. In this case the `name` attribute can be specified.
-
-For example, the following can be used to group properties:
-
-[source,java]
-----
-public Class Customer {
-    @MemberOrder(name="General", sequence="1.1")
-    public String getFirstName() {...}
-    public void setFirstName(value as String) {...}
-
-    @MemberOrder(name="General", sequence="1.2")
-    public String getLastName() {...}
-    public void setLastName(value as String) {...}
-
-    @MemberOrder(name="Other", sequence="1")
-    public String getAddress() {...}
-    public void setAddress(value as String) {...}
-
-    @MemberOrder(name="Dates", sequence="1")
-    public Date getDateOfBirth() {...}
-    public void setDateOfBirth(value as Date) {...}
-    ...
-}
-----
-
-In this case the `sequence` is ordered with respect to the `name`. If
-using group names in this way, typically the `@MemberGroups` annotation
-<!--(see ?)--> should also be specified, allowing the order of the groups
-themselves to be sorted.
-
-Grouping can also be performed on actions. Some viewers (for example the
-Wicket viewer) support the idea that the group name can be the name of a
-collection. In this case, the action is rendered "near to" the
-collection (for example, to support add or remove of elements).
-
-For example:
-
-[source,java]
-----
-public Class Customer {
-
-    public List<CommunicationChannel> getCommunicationChannels() { ... }
-
-    ...
-    @MemberOrder(name="communicationChannels", sequence="1.1")
-    public void addCommunicationChannel(...) { ... }
-
-    @MemberOrder(name="communicationChannels", sequence="1.2")
-    public void removeCommunicationChannel(...) { ... }
-
-    ...
-}
-----

http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
index dfe78ba..7cc2efd 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
@@ -5,10 +5,14 @@
 :_imagesdir: images/
 
 
-IMPORTANT: TODO - @javax.jdo.annotation.NotPersistent
+The `@javax.jdo.annotation.NotPersistent` annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database.
 
+Apache Isis also uses this annotation, though (currently) only in the very minimal way to suppress checking of inconsistent metadata between JDO and Isis annotations (eg `@Column#allowsNull()` vs `@Property#optionality()`, or `@Column#length()` and `@Property#maxLength()`).
 
+[NOTE]
+====
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel.  This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
 
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method.  Therefore ensure that the annotation is placed there.
+====
 
-@NotPersistent
-... minimally, to skip checking for inconsistent metadata for @Column and Isis annotations

http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
index e07de63..5be6424 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
@@ -5,13 +5,15 @@
 :_imagesdir: images/
 
 
-IMPORTANT: TODO - @javax.jdo.annotation.PrimaryKey
 
+The `@javax.jdo.annotation.PrimaryKey` annotation is used by JDO/DataNucleus to indicate that a property is used as the primary key for an entity with application-managed identity.
 
-@PrimaryKey
-... marked as optional so never initialized
-... marked as disabled, so implicitly read-only
-
+Apache Isis also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only).
 
+[NOTE]
+====
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel.  This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/application_identity.html[XML metadata].
 
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method.  Therefore ensure that the annotation is placed there.
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
index deeec43..75aba77 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
@@ -11,7 +11,26 @@ Metadata providing UI hints can be specified either statically, using annotation
 
 == `@MemberOrder`
 
-To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used.
+The `@MemberOrder` annotation is used to specify the relative order of domain class properties, collections and actions.
+
+The annotation defines two attributes, `name()` and `sequence()`.  Their usage depends on the member type:
+
+* for properties, the `name()` is used to group properties together.  The `sequence()` then orders properties within these groups. If no `name()` is specified then the property is placed in a fallback "General" group, called "General". +
++
+The name of these "member groups" are then referenced by xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`].
+
+* for collections, the `name()` attribute is (currently) unused.  The `sequence()` orders collections relative to one another
+
+* for actions, the `name()` attribute associates an action with either a property or with a collection. +
++
+If the `name()` attribute matches a property name, then the action's button is rendered close to the property, according to xref:_ug_reference-annotations_manpage-ActionLayout_position[`@ActionLayout#position()`] attribute. +
++
+On the other hand if the `name() attribute matches a collection name, then the action's button is rendered on the collection's header. +
++
+If there is no `name()` value, then the action is considered to pertain to the object as a whole, and its button is rendered close to the object's icon and title.
++
+Within any of these, the `sequence()` then determines the relative ordering of the action with respect to other actions that have been similarly associated with properties/collections or left as "free-standing".
+
 
 For example:
 
@@ -64,14 +83,17 @@ public class ToDoItem {
 
 will associate the `completed()` and `notYetCompleted()` actions with the `complete` property, and will associate the `add()` and `remove()` actions with the `dependencies` collection.
 
-If the `name` attribute is omitted, then the action is rendered near the header. Note also that the `@MemberOrder`'s `name` attribute has no meaning for collections.
+
+The value of `sequence()` is a string.  The simplest convention (as shown in the example above) is to use numbers -- 1, 2, 3 -- though it is a better idea to leave gaps in the numbers -- 10, 20, 30 perhaps -- such that a new member may be added without having to edit existing numbers.  A useful alternative is to adopt the 'dewey-decimal' notation -- 1, 1.1, 1.2, 2, 3, 5.1.1, 5.2.2, 5.2, 5.3 -- which allows for an indefinite amount of future insertion.  It also allows subclasses to insert their class members as required.
 
 
 
 
 == `@MemberGroupLayout`
 
-The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column. It also specifies the relative width.
+The `@MemberGroupLayout` annotation specifies the relative positioning of property groups as being either in a left column, a middle column or in a right column.  The annotation also specifies the relative width of the columns.
+
+The property groups in this case are those that are inferred from the `@MemberOrder#name()` attribute.
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/4c99a344/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc b/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
index dbbf215..339478e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
@@ -14,7 +14,7 @@
 //include::_ug_how-tos.adoc[leveloffset=+1]
 //include::_ug_more-advanced.adoc[leveloffset=+1]
 
-//include::_ug_reference-annotations.adoc[leveloffset=+1]
+include::_ug_reference-annotations.adoc[leveloffset=+1]
 //include::_ug_reference-methods.adoc[leveloffset=+1]
 //include::_ug_reference-services-api.adoc[leveloffset=+1]
 //include::_ug_reference-services-spi.adoc[leveloffset=+1]