[IMPORTANT] Stricter validation of Isis vs JDO annotations...

[Dan Haywood <da...@haywood-associates.co.uk>]

Folks,

For those working off snapshots, just wanted to flag a change I've just
committed, ISIS-488 [1], that may break your code (assuming you are using
the JDO objectstore).

Currently, to specify that a property is not required in Isis, we use
@Optional.  If not present, then the property is assumed to be mandatory.

In JDO, though, the @javax.jdo.annotations.Column(allowNulls="true|false")
indicates whether a property is nullable.

If the "allowNulls" attribute is missing, or if there is no @Column
annotation, then the JDO spec says that the default is mandatory for
primitive types, optional for non-primitive types.

As you can see, there is room for inconsistency here between Isis and JDO,
either explicitly or implicitly.  eg:
- @Optional and @Column(allowNulls="false")
- no @Column but an @Optional for a primitive
- no @Column and no @Optional for a non-primitive

This last one is probably the most common, eg any String, BigDecimal or
LocalDate will be treated as mandatory by default by Isis, but optional by
default by JDO.

~~~
The change now teaches Isis to also honour @Column as a way of indicating
optionality.  It isnt necessary to specify "allowNulls" attribute, though
is highly recommended.  ie:

- @Column(allowNulls="false") now means mandatory for Isis
- @Column(allowNulls="true") now means optional for Isis (as if annotated
with @Optional)
- @Column() now means either mandatory/optional for Isis following the
defaults of JDO

As with all Isis annotations, *the @Column annotation must reside on the
getter method*, not on the field.

Here's the most important thing to know: *If there is an incompatibility
between Isis' and JDO, then Isis will not boot, and instead will report the
exception* (using the MetaModelValidator API).  In Estatio, we had to fix
235 incompatibilities; you may well have a similar number.  Make sure you
have some time free to fix up your codebase.

~~~
One last thing.  If using "rollup" (InheritanceStrategy.SUPERCLASS_TABLE)
inheritance mapping, then you'll find that a nominally mandatory property
in a subtype entity must be annotated as optional in JDO; this is because
other subtypes would have no value for this property.  Here, though, we
would want Isis to enforce that the property is mandatory - in a sense to
override the JDO default.

To support this I've added a new @Mandatory annotation, eg:

@javax.jdo.annotations.Inheritance(strategy =
InheritanceStrategy.SUPERCLASS_TABLE)
public class SomeSubclass extends SomeSuperclass {

    @javax.jdo.annotations.Column(allowNulls="false")
    @Mandatory
    public String getFoo() { ... }

Thanks for reading,

Dan


[1] https://issues.apache.org/jira/browse/ISIS-488