[37/51] [abbrv] isis git commit: ISIS-1133: @Column annotation

[da...@apache.org]

ISIS-1133: @Column annotation


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

Branch: refs/heads/master
Commit: 3975113228731caa02e7f64f4272509a38dc396d
Parents: 13767df
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Jun 4 08:08:12 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Jun 4 08:08:12 2015 +0100

----------------------------------------------------------------------
 ...ug_reference-annotations_manpage-Column.adoc | 146 +++++++++++++++++--
 1 file changed, 136 insertions(+), 10 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/39751132/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
index f1f2620..3f1f93c 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
@@ -5,24 +5,150 @@
 :_imagesdir: images/
 
 
-IMPORTANT: TODO - @javax.jdo.annotation.Column
+The JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).
 
+Apache Isis also parses and interprets this annotation in order to build up aspects of its metamodel.
 
-@Column(length, scale) ... for bigdecimals
-... derive bigdecimal value facet
+[WARNING]
+====
+Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel.  This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
 
-@Column(length) validates should = sum of @Digits(precision, fraction)
-@Column(scale)  validates should = @Digits(precision, fraction)
+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.
+====
 
+This section identifies which attributes of `@Column` are recognized and used by Isis.
 
-@Column(allowsNull)
-... if missing, and primitive then infer mandatory (per JDO spec)
-... if not missing, then used for mandatory facet  (unless overridden using @Property(optionality=MANDATORY) or @Mandatory)
 
 
-@Column(length) ... for strings
-... validates matches @MaxLength()
+== Nullability
 
+The `allowsNull()` attribute is used to specify if a property is required or is optional.
 
+For example:
 
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotations.Column(allowNulls="true")
+    public String getMiddleInitial() { ... }
+    public void setMiddleInitial(String middleInitial) { ... }
+----
 
+Isis also provides xref:_ug_reference-annotations_manpage-Property_optionality[`@Property#optionality()`] attribute.  If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Isis defaults differ.  Isis rule is straight-forward: properties are assumed to be required.  JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional.  Therefore a lack of either annotation can also trigger the fail-fast validation check.
+
+In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter.  But see the documentation for xref:_ug_reference-annotations_manpage-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
+
+
+
+== Length for ``String``s
+
+The `length()` attribute is used to specify the length of `java.lang.String` property types as they map to `varchar(n)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotations.Column(length=20)
+    public String getFirstName() { ... }
+    public void setFirstName(String firstName) { ... }
+    @javax.jdo.annotations.Column(allowNulls="true", length=1)
+    public String getMiddleInitial() { ... }
+    public void setMiddleInitial(String middleInitial) { ... }
+    @javax.jdo.annotations.Column(length=30)
+    public String getLastName() { ... }
+    public void setLastName(String lastName) { ... }
+----
+
+Isis also provides xref:_ug_reference-annotations_manpage-Property_maxLength[`@Property#maxLength()`] attribute.  If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+== Length/scale for ``BigDecimal``s
+
+
+The `length()` and `scale()` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+    @javax.jdo.annotations.Column(length=10, scale=2)
+    public BigDecimal getTotalOrdersToDate() { ... }
+    public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
+----
+
+For ``BigDecimal``s it is also possible to specify the xref:_ug_reference-annotations_manpage-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`.  There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
+
+If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+
+== Hints and Tips
+
+This seems to be a good place to describe some additional common mappings that use `@Column`.  Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Isis metamodel.
+
+
+=== Mapping foreign keys
+
+The `name()` attribute can be used to override the name of the column.  References to other objects are generally mapped as foreign key columns.  If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
+
+For example (taken from link:http://github.com/estatio/estatio[estatio] app):
+
+[source,java]
+----
+public class PartyRelationship {
+    @Column(name = "fromPartyId", allowsNull = "false")
+    public Party getFrom() { ... }
+    public void setFrom(Party from) { ... }
+    @Column(name = "toPartyId", allowsNull = "false")
+    public Party getTo() { ... }
+    public void setTo(Party to) { ... }
+    ...
+}
+----
+
+
+
+== Mapping ``Blob``s and ``Clob``s
+
+Isis provides custom value types for xref:_ug_reference-classes_value-types_manpage-Blob[`Blob`]s and xref:_ug_reference-classes_value-types_manpage-Clob[`Clob`]s.  These value types have multiple internal fields, meaning that they corresponding to multiple columns in the database.  Mapping this correctly requires using  `@Column` within JDO's `@Persistent` annotation.
+
+For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
+
+[source,java]
+----
+private Blob attachment;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+        @javax.jdo.annotations.Column(name = "attachment_name"),
+        @javax.jdo.annotations.Column(name = "attachment_mimetype"),
+        @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType = "BLOB", sqlType = "BLOB")
+})
+@Property(
+        domainEvent = AttachmentDomainEvent.class,
+        optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() { ... }
+public void setAttachment(Blob attachment) { ... }
+----
+
+And here's how to map a `Clob` (also taken from the todoapp):
+
+[source,java]
+----
+private Clob doc;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+        @javax.jdo.annotations.Column(name = "doc_name"),
+        @javax.jdo.annotations.Column(name = "doc_mimetype"),
+        @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+})
+@Property(
+        optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() { ... }
+public void setDoc(final Clob doc) { ... }
+----