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 2017/01/22 15:55:10 UTC
[14/14] isis-site git commit: ISIS-785: further updates to
fundamentals guide, now with section on collection action parameters
ISIS-785: further updates to fundamentals guide, now with section on collection action parameters
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/6445cd4a
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/6445cd4a
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/6445cd4a
Branch: refs/heads/asf-site
Commit: 6445cd4abdceaa215d31583a64d5524f0677ec78
Parents: 22e1e43
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Jan 22 15:47:04 2017 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun Jan 22 15:47:04 2017 +0000
----------------------------------------------------------------------
content/guides/ugfun.html | 716 +-
content/guides/ugfun.pdf | 32683 ++++++++++++++++++++++++++-------------
2 files changed, 22276 insertions(+), 11123 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis-site/blob/6445cd4a/content/guides/ugfun.html
----------------------------------------------------------------------
diff --git a/content/guides/ugfun.html b/content/guides/ugfun.html
index 3b57b1a..1a704e1 100644
--- a/content/guides/ugfun.html
+++ b/content/guides/ugfun.html
@@ -3028,7 +3028,8 @@ The implementation delegates to an <code>SimpleObjectRepository</code> service,
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
<td>The <code>javax.inject.Inject</code> annotation instructs Apache Isis framework to inject the <code>SimpleObjectRepository</code> service into this domain object.
-The framework can inject into not just other domain services but will also automatically into domain entities and view models.</td>
+The framework can inject into not just other domain services but will also automatically into domain entities and view models.
+There is further discussion of service injection <a href="#_ugfun_how-tos_class-structure_inject-services">below</a>.</td>
</tr>
</table>
</div>
@@ -3125,21 +3126,74 @@ It’s also possible (using annotations) to define a link table to hold fore
The <a href="guides/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a> uses this approach.</p>
</div>
<div class="sect4">
-<h5 id="_value_vs_reference_types">Value vs Reference Types</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_value-vs-reference-types">Value vs Reference Types</h5>
<div class="paragraph">
<p>Properties can be either a value types (strings, int, date and so on) or be a reference to another object (for example, an <code>Order</code> referencing the <code>Customer</code> that placed it).</p>
</div>
<div class="paragraph">
+<p>For example, to map a string value type:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="directive">private</span> <span class="predefined-type">String</span> notes;</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>using <a href="https://projectlombok.org/">Project Lombok</a> annotations to reduce boilerplate</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>You could also add the <code>@Property</code> annotation if you wished:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Property</span>
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> <span class="predefined-type">String</span> notes;</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Although in this case it is not required in this case (none of its attributes have been set).</p>
+</div>
+<div class="paragraph">
+<p>Or to map a reference type:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> Customer customer;</code></pre>
+</div>
+</div>
+<div class="paragraph">
<p>It’s ok for a <a href="#_ugfun_how-tos_class-structure_class-definition_entities">domain entity</a> to reference another domain entity, and for a <a href="#_ugfun_how-tos_class-structure_class-definition_view-models">view model</a> to reference both view model and domain entities.
However, it isn’t valid for a domain entity to hold a persisted reference to view model (DataNucleus will not know how to persist that view model).</p>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>For further details on mapping associations, see the JDO/DataNucleus documentation for <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html">one-to-many</a> associations, <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html">many-to-one</a> associations, <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html">many-to-many</a> associations, and so on.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
<p>For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
The table in the <a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">Properties vs Parameters</a> section provides a handy reference of each.</p>
</div>
</div>
<div class="sect4">
-<h5 id="_optional_properties">Optional Properties</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_optional-properties">Optional Properties</h5>
<div class="paragraph">
<p>(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg <code>int</code>, <code>boolean</code>), but optional if a reference type (eg <code>String</code>, <code>BigDecimal</code> etc).
To override optionality in JDO/DataNucleus the <code>@Column(allowsNull="…​")</code> annotations is used.</p>
@@ -3153,32 +3207,32 @@ These defaults can also be overridden using Apache Isis' own annotations, specif
To counteract that, Apache Isis also recognizes and honours JDO’s <code>@Column(allowsNull=…​)</code>.</p>
</div>
<div class="paragraph">
-<p>For example, rather than:</p>
+<p>For example, you can write:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
-<span class="annotation">@Property</span>(optionality=Optionality.OPTIONAL)
<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
<span class="directive">private</span> LocalDate date;</code></pre>
</div>
</div>
<div class="paragraph">
-<p>you should instead simply write:</p>
+<p>rather than the more verbose:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+<span class="annotation">@Property</span>(optionality=Optionality.OPTIONAL)
<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
<span class="directive">private</span> LocalDate date;</code></pre>
</div>
</div>
<div class="paragraph">
-<p>In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).</p>
+<p>The framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).</p>
</div>
</div>
<div class="sect4">
-<h5 id="_editable_properties">Editable Properties</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_editable-properties">Editable Properties</h5>
<div class="paragraph">
<p>Apache Isis provides the capability to allow individual properties to be modified.
This is specified using the <code>@Property(editing=…​)</code> attribute.</p>
@@ -3189,7 +3243,7 @@ This is specified using the <code>@Property(editing=…​)</code> attri
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Property</span>(editing = Editing.ENABLED)
-<span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
<span class="directive">private</span> <span class="predefined-type">String</span> notes;</code></pre>
</div>
</div>
@@ -3198,7 +3252,7 @@ This is specified using the <code>@Property(editing=…​)</code> attri
</div>
</div>
<div class="sect4">
-<h5 id="_ignoring_properties">Ignoring Properties</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_ignoring-properties">Ignoring Properties</h5>
<div class="paragraph">
<p>By default Apache Isis will automatically render all properties in the <a href="#ugvw.adoc">UI</a> or in the <a href="#ugvro.adoc">REST API</a>.
To get Apache Isis to ignore a property (exclude it from its metamodel), annotate the getter using <code>@Programmatic</code>.</p>
@@ -3213,7 +3267,7 @@ Again, this is independent of Apache Isis.</p>
</div>
</div>
<div class="sect4">
-<h5 id="_derived_properties">Derived Properties</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_derived-properties">Derived Properties</h5>
<div class="paragraph">
<p>Derived properties are those with a getter but no setter.
Provided that the property has not been annotated with <code>@Programmatic</code>, these will still be rendered in the UI, but they will be read-only (not editable) and their state will not be persisted.</p>
@@ -3259,71 +3313,9 @@ AddressService addressService;
</tr>
</table>
</div>
-<div class="sect5">
-<h6 id="_handling_mandatory_properties_in_subtypes">Handling Mandatory Properties in Subtypes</h6>
-<div class="paragraph">
-<p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>"table per hierarchy", or "rollup" (<code>InheritanceStrategy.SUPERCLASS_TABLE</code>)<br></p>
-<div class="paragraph">
-<p>whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up</p>
-</div>
-</li>
-<li>
-<p>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p>
-<div class="paragraph">
-<p>whereby is a table for both superclass and subclass, in 1:1 correspondence</p>
-</div>
-</li>
-<li>
-<p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p>
-<div class="paragraph">
-<p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.</p>
-</div>
-<div class="paragraph">
-<p>In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the <code>@Property(optionality=Optionality.MANDATORY)</code> annotation.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubtype</span> <span class="directive">extends</span> SomeSuperType {
- <span class="annotation">@javax</span>.jdo.annotations.Column(allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
- <span class="annotation">@Property</span>(optionality=Optionality.MANDATORY)
- <span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
- <span class="directive">private</span> LocalDate date;
-}</code></pre>
-</div>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The <code>@Property(optionality=…​)</code> annotation is equivalent to the older but still supported <code>@Optional</code> annotation and <code>@Mandatory</code> annotations.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
</div>
<div class="sect4">
-<h5 id="_mapping_code_string_code_s_length">Mapping <code>String</code>s (Length)</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_mapping-strings">Mapping <code>String</code>s (Length)</h5>
<div class="paragraph">
<p>By default JDO/DataNucleus will map string properties to a <code>VARCHAR(255)</code>.
To limit the length, use the <code>@Column(length=…​)</code> annotation.</p>
@@ -3368,7 +3360,7 @@ To avoid this extra query, the annotation should indicate that the property is i
</div>
</div>
<div class="sect4">
-<h5 id="_mapping_code_bigdecimal_code_s_precision">Mapping <code>BigDecimal</code>s (Precision)</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_mapping-bigdecimals">Mapping <code>BigDecimal</code>s (Precision)</h5>
<div class="paragraph">
<p>Working with <code>java.math.BigDecimal</code> properties takes a little care due to scale/precision issues.</p>
</div>
@@ -3413,7 +3405,7 @@ To avoid this extra query, the annotation should indicate that the property is i
</div>
</div>
<div class="sect4">
-<h5 id="_mapping_code_blob_code_s_and_code_clob_code_s">Mapping <code>Blob</code>s and <code>Clob</code>s</h5>
+<h5 id="_ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs">Mapping <code>Blob</code>s and <code>Clob</code>s</h5>
<div class="paragraph">
<p>Apache Isis configures JDO/DataNucleus so that the properties of type <code>org.apache.isis.applib.value.Blob</code> and <code>org.apache.isis.applib.value.Clob</code> can also be persisted.</p>
</div>
@@ -3422,7 +3414,7 @@ To avoid this extra query, the annotation should indicate that the property is i
However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.</p>
</div>
<div class="sect5">
-<h6 id="_mapping_code_blob_code_s">Mapping <code>Blob</code>s</h6>
+<h6 id="_ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-blobs">Mapping <code>Blob</code>s</h6>
<div class="paragraph">
<p>For example, in the <code>ToDoItem</code> class (of the <a href="https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442">todoapp example app</a> (non-ASF) the <code>attachment</code> property is as follows:</p>
</div>
@@ -3480,7 +3472,7 @@ There can be differences in behaviour between JDBC drivers.</p>
</div>
</div>
<div class="sect5">
-<h6 id="_mapping_code_clob_code_s">Mapping <code>Clob</code>s</h6>
+<h6 id="_ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-clobs">Mapping <code>Clob</code>s</h6>
<div class="paragraph">
<p>Mapping <code>Clob`s works in a very similar way, but the `jdbcType</code> and <code>sqlType</code> attributes will, respectively, be <code>CLOB</code> and <code>LONGVARCHAR</code>:</p>
</div>
@@ -3520,7 +3512,7 @@ There can be differences in behaviour between JDBC drivers.</p>
</div>
</div>
<div class="sect5">
-<h6 id="_mapping_to_varbinary_or_varchar">Mapping to VARBINARY or VARCHAR</h6>
+<h6 id="_ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs_mapping-to-varbinary-or-varchar">Mapping to VARBINARY or VARCHAR</h6>
<div class="paragraph">
<p>Instead of mapping to a sqlType of <code>LONGVARBINARY</code> (or perhaps <code>BLOB</code>), you might instead decide to map to a <code>VARBINARY</code>.
The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a <code>VARBINARY</code> the data is held on-row and so you will need to specify a length.</p>
@@ -3546,6 +3538,68 @@ The difference is whether the binary data is held "on-row" or as a pointer "off-
</div>
</div>
</div>
+<div class="sect4">
+<h5 id="_ugfun_how-tos_class-structure_properties_handling-mandatory-properties-in-subtypes">Handling Mandatory Properties in Subtypes</h5>
+<div class="paragraph">
+<p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>"table per hierarchy", or "rollup" (<code>InheritanceStrategy.SUPERCLASS_TABLE</code>)<br></p>
+<div class="paragraph">
+<p>whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up</p>
+</div>
+</li>
+<li>
+<p>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p>
+<div class="paragraph">
+<p>whereby is a table for both superclass and subclass, in 1:1 correspondence</p>
+</div>
+</li>
+<li>
+<p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p>
+<div class="paragraph">
+<p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.</p>
+</div>
+<div class="paragraph">
+<p>In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the <code>@Property(optionality=Optionality.MANDATORY)</code> annotation.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubtype</span> <span class="directive">extends</span> SomeSuperType {
+ <span class="annotation">@javax</span>.jdo.annotations.Column(allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+ <span class="annotation">@Property</span>(optionality=Optionality.MANDATORY)
+ <span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+ <span class="directive">private</span> LocalDate date;
+}</code></pre>
+</div>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The <code>@Property(optionality=…​)</code> annotation is equivalent to the older but still supported <code>@Optional</code> annotation and <code>@Mandatory</code> annotations.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
</div>
<div class="sect3">
<h4 id="_ugfun_how-tos_class-structure_collections">4.1.3. Collections</h4>
@@ -3589,19 +3643,9 @@ For example, a <code>placeOrder(…​)</code> action will likely add to
<p>Since writing getter and setter methods adds quite a bit of boilerplate, it’s common to use <a href="https://projectlombok.org/">Project Lombok</a> to code generate these methods at compile time (using Java’s annotation processor) simply by adding the <code>@lombok.Getter</code> and <code>@lombok.Setter</code> annotations to the field.</p>
</div>
<div class="sect4">
-<h5 id="_value_vs_reference_types_2">Value vs Reference Types</h5>
-<div class="paragraph">
-<p>Apache Isis can (currently) only provide a UI for collections of references.
-While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as <code>@Programmatic</code> so that they are ignored by Apache Isis.</p>
-</div>
-<div class="paragraph">
-<p>If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained <a href="#_ugfun_how-tos_simulating-collections-of-values">elsewhere</a>.</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_one_to_many_collections">One-to-many collections</h5>
+<h5 id="_mapping_bidir_1_m">Mapping bidir 1:m</h5>
<div class="paragraph">
-<p>Bidirectional one-to-many collections are one of the most common collection types.
+<p>Bidirectional one-to-many collections are one of the most common types of associations between two entities.
In the parent object, the collection can be defined as:</p>
</div>
<div class="listingblock">
@@ -3685,111 +3729,408 @@ JDO/Datanucleus does support the mapping of these other types, but RDBMS are set
</td>
<td class="content">
<div class="paragraph">
-<p>JDO/DataNucleus does also support <code>java.util.Map</code> as a collection type, but this is not supported by Apache Isis.
-If you do use this collection type, then annotate the getter with <code>@Programmatic</code> so that it is ignored by the Apache Isis framework.</p>
+<p>For further details on mapping associations, see the JDO/DataNucleus documentation for <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html">one-to-many</a> associations, <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html">many-to-one</a> associations, <a href="http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html">many-to-many</a> associations, and so on.</p>
+</div>
+<div class="paragraph">
+<p>Also, while JDO/DataNucleus itself supports <code>java.util.Map</code> as a collection type, this is not supported by Apache Isis.
+If you do wish to use this collection type, then annotate the getter with <code>@Programmatic</code> so that it is ignored by the Apache Isis framework.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
+<div class="sect4">
+<h5 id="_value_vs_reference_types">Value vs Reference Types</h5>
+<div class="paragraph">
+<p>Apache Isis can (currently) only provide a UI for collections of references.
+While you can use DataNucleus to persist collections/arrays of value types, such properties must be annotated as <code>@Programmatic</code> so that they are ignored by Apache Isis.</p>
+</div>
+<div class="paragraph">
+<p>If you want to visualize an array of value types in Apache Isis, then one option is to wrap value in a view model, as explained <a href="#_ugfun_how-tos_simulating-collections-of-values">elsewhere</a>.</p>
+</div>
+</div>
</div>
<div class="sect3">
<h4 id="_ugfun_how-tos_class-structure_actions">4.1.4. Actions</h4>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>While <a href="#_ugfun_how-tos_class-structure_properties">properties</a> and <a href="#_ugfun_how-tos_class-structure_collections">collections</a> define the state held by a domain object (its "know what" responsibilities), actions define the object’s behaviour (its "know how-to" responsibilities).</p>
+</div>
+<div class="paragraph">
+<p>An application whose domain objects have only/mostly "know-what" responsibilities is pretty dumb: it requires that the end-user know the business rules and doesn’t modify the state of the domain objects such that they are invalid (for example, an "end date" being before a "start date").
+Such applications are often called CRUD applications (create/read/update/delete).</p>
+</div>
+<div class="paragraph">
+<p>In more complex domains, it’s not realistic/feasible to expect the end-user to have to remember all the different business rules that govern the valid states for each domain objects.
+So instead actions allow those business rules to be encoded programmatically.
+An Apache Isis doesn’t try to constrain the end-user as to way in which they interact with the user (it doesn’t attempt to define a rigid business process) but it does aim to ensure that business rule invariants are maintained, that is that business objects aren’t allowed to go into an invalid state.</p>
+</div>
+<div class="paragraph">
+<p>For simple domain applications, you may want to start prototyping only with properties, and only later introduce actions (representing the most common business operations).
+But an alternative approach, recommended for more complex applications, is actually to start the application with all properties non-editable.
+Then, as the end-user requires the ability to modify some state, there is a context in which to ask the question "why does this state need to change?" and "are their any side-effects?" (ie, other state that changes at the same time, or other behaviour that should occur).
+If the state change is simple, for example just being able to correct an invalid address, or adding a note or comment, then that can probably be modelled as a simple editable property.
+But if the state change is more complex, then most likely an action should be used instead.</p>
+</div>
+<div class="sect4">
+<h5 id="_ugfun_how-tos_class-structure_actions_defining-actions">Defining actions</h5>
+<div class="paragraph">
+<p>Broadly speaking, actions are all the <code>public</code> methods that are not getters or setters which represent properties or collections.
+This is a slight simplification; there are a number of other method prefixes (such as <code>hide</code> or <code>validate</code>) that represent <a href="#_ugfun_how-tos_business-rules">business rules</a>); these also not treated as actions.
+And, any method that are annotated with <code>@Programmatic</code> will also be excluded.
+But by and large, all other methods such as <code>placeOrder(…​)</code> or <code>approveInvoice(…​)</code> will be treated as actions.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT) <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="directive">public</span> ShoppingBasket addToBasket(
+ Product product,
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="type">int</span> quantity
+ ) {
+ ...
+ return <span class="local-variable">this</span>;
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td><code>@Action</code> annotation is optional but used to specify additional domain semantics (such as being idempotent).</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>The names of action parameters (as rendered in the UI) will by default be the parameter types, not the paramter names.
+For the <code>product</code> parameter this is reasonable, but not so for the <code>quantity</code> parameter (which would by default show up with a name of "int".
+The <code>@ParameterLayout</code> annotation provides a UI hint to the framework.</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<p>The (non-ASF) Isis addons' <a href="http://github.com/isisaddons/isis-metamodel-paraname8">paraname8</a> metamodel extension allows the parameter name to be used in the UI, rather than the type.</p>
+</div>
</td>
</tr>
</table>
</div>
-<div class="admonitionblock note">
+</div>
+<div class="sect4">
+<h5 id="_ugfun_how-tos_class-structure_actions_reference-parameter-types">(Reference) Parameter types</h5>
+<div class="paragraph">
+<p>Parameter types can be value types or reference types.
+In the case of primitive types, the end-user can just enter the value directly through the parameter field.
+In the case of reference types however (such as <code>Product</code>), a drop-down must be provided from which the end-user to select.
+This is done using either a supporting <a href="rgcms.html#_rgcms_methods_prefixes_choices"><code>choices</code></a> or <a href="rgcms.html#_rgcms_methods_prefixes_autoComplete"><code>autoComplete</code></a> method.
+The "choices" is used when there is a limited set of options, while "autoComplete" is used when there are large set of options such that the end-user must provide some characters to use for a search.</p>
+</div>
+<div class="paragraph">
+<p>For example, the <code>addToBasket(…​)</code> action shown above might well have a :</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
+<span class="directive">public</span> ShoppingBasket addToBasket(
+ Product product,
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>)
+ <span class="type">int</span> quantity
+ ) {
+ ...
+ return <span class="local-variable">this</span>;
+}
+<span class="directive">public</span> <span class="predefined-type">List</span><Product> autoComplete0AddToBasket( <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="annotation">@MinLength</span>(<span class="integer">3</span>) <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="predefined-type">String</span> searchTerm) {
+ <span class="keyword">return</span> productRepository.find(searchTerm); <i class="conum" data-value="3"></i><b>(3)</b>
+}
+<span class="annotation">@javax</span>.inject.Inject
+ProductRepository productRepository;</code></pre>
+</div>
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Supporting <code>autoComplete</code> method.
+The "0" in the name means that this corresponds to parameter 0 of the "addToBasket" action (ie <code>Product</code>).
+It is also required to return a Collection of that type.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>The <a href="rgant.html#_rgant_MinLength"><code>@MinLength</code></a> annotation defines how many characters the end-user must enter before performing a search.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>The implementation delegates to an injected repository service. This is typical.</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
-<p>While Apache Isis support actions whose parameters' types are scalar (values such as <code>String</code>, <code>int</code>, or references such as <code>Customer</code>), the framework (currently) does not support parameter types that are collections or maps.</p>
+<p>Note that it is also valid to define "choices" and "autoComplete" for value types (such as <code>quantity</code>, above); it just isn’t as common to do so.</p>
</div>
+<div class="sect5">
+<h6 id="_ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate">Removing boilerplate</h6>
<div class="paragraph">
-<p>The workaround is to mark the collection as <code>@Programmatic</code>, as described in <a href="#_ugfun_how-tos_class-structure_ignoring-methods">Ignoring Methods</a>. This ensures that the collection is ignored by Apache Isis.</p>
+<p>To save having to define an <code>autoCompleteNXxx(…​)</code> method everywhere that a reference to a particular type (such as <code>Product</code>) appears as an action parameter, it is also possible to use the <code>@DomainObject</code> annotation on <code>Product</code> itself:</p>
</div>
-</td>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(
+ autoCompleteRepository=ProductRepository.class <i class="conum" data-value="1"></i><b>(1)</b>
+ autoCompleteAction=<span class="string"><span class="delimiter">"</span><span class="content">find</span><span class="delimiter">"</span></span> <i class="conum" data-value="2"></i><b>(2)</b>
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Product</span> ... {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Whenever an action parameter requiring a <code>Product</code> is defined, provide an autoComplete drop-down automatically</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Use the "find" method of <code>ProductRepository</code> (rather than the default name of "autoComplete")</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>(As noted above), if the number of available instances of the reference type is a small number (in other words, all of which could comfortably be shown in a drop-down) then instead the <code>choicesNXxx()</code> supporting method can be used.
+This too can be avoided by annotating the referenced class.</p>
</div>
-<div class="sect3">
-<h4 id="_ugfun_how-tos_class-structure_action-parameters">4.1.5. Action Parameters</h4>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>For example, support we have an action to specify the <code>PaymentMethodType</code>, where there only 10 or so such (Visa, Mastercard, Amex, Paypal etc).
+We could define this as:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> Order payUsing(PaymentMethodType type) {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>where <code>PaymentMethodType</code> would be annotated using:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(
+ bounded=<span class="predefined-constant">true</span> <i class="conum" data-value="1"></i><b>(1)</b>
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">PaymentMethodType</span> ... {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>only a small (ie "bounded") number of instances available, meaning that the framework should render all in a drop-down.</td>
</tr>
</table>
</div>
+</div>
+</div>
<div class="sect4">
-<h5 id="__code_string_code_s_length"><code>String</code>s (Length)</h5>
-<div class="admonitionblock note">
+<h5 id="_ugfun_how-tos_class-structure_actions_collection-parameter-types">Collection Parameter types (<code>1.14.0-SNAPSHOT</code>)</h5>
+<div class="paragraph">
+<p>As of <code>1.14.0-SNAPSHOT</code> Apache Isis action parameters can be collections of types scalar (values such as <code>String</code>, <code>int</code>, or references such as <code>Customer</code>).</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
+<span class="directive">public</span> ShoppingBasket addToBasket(
+ <span class="predefined-type">List</span><Product> products,
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Quantity</span><span class="delimiter">"</span></span>) <span class="type">int</span> quantity
+ ) {
+ ...
+ return <span class="local-variable">this</span>;
+}
+<span class="directive">public</span> <span class="predefined-type">List</span><Product> autoComplete0AddToBasket(<span class="annotation">@MinLength</span>(<span class="integer">3</span>) <span class="predefined-type">String</span> searchTerm) {
+ <span class="keyword">return</span> ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>As the example suggests, any collection parameter type must provide a way to select items, either by way of a "choices" or "autoComplete" supporting method or alternatively defined globally using <a href="rgant.html#_rgant_DomainObject"><code>@DomainObject</code></a> on the referenced type (described <a href="#_ugfun_how-tos_class-structure_actions_reference-parameter-types_removing-boilerplate">above</a>).</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_ugfun_how-tos_class-structure_actions_optional-parameters">Optional Parameters</h5>
+<div class="paragraph">
+<p>Whereas the <a href="#_ugfun_how-tos_class-structure_properties_optional-properties">optionality of properties</a> is defined using <a href="rgant.html#_rgant_Column_allowsNull"><code>@javax.jdo.annotations.Column#allowsNull()</code></a>, that JDO annotation cannot be applied to parameter types.
+Instead, either the <a href="rgant.html#_rgant_Nullable"><code>@Nullable</code></a> annotation or the <a href="rgant.html#_rgant_Parameter_optionality"><code>@Parameter#optionality()</code></a> annotation/attribute is used.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>) <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> LocalDate shipBy;
+
+<span class="directive">public</span> Order invoice(
+ PaymentMethodType paymentMethodType,
+ <span class="annotation">@Nullable</span> <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Ship no later than</span><span class="delimiter">"</span></span>)
+ LocalDate shipBy) {
+ ...
+ setShipBy(shipBy)
+ <span class="keyword">return</span> <span class="local-variable">this</span>;
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Specifies the property is optional.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Specifies the corresponding parameter is optional.</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>See also <a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">properties vs parameters</a>.</p>
+</div>
</div>
<div class="sect4">
-<h5 id="__code_bigdecimal_code_s_precision"><code>BigDecimal</code>s (Precision)</h5>
-<div class="admonitionblock note">
+<h5 id="_ugfun_how-tos_class-structure_actions_string-parameters"><code>String</code> Parameters (Length)</h5>
+<div class="paragraph">
+<p>Whereas the <a href="#_ugfun_how-tos_class-structure_properties_mapping-strings">length of string properties</a> is defined using <a href="rgant.html#_rgant_Column_length"><code>@javax.jdo.annotations.Column#length()</code></a>, that JDO annotation cannot be applied to parameter types.
+Instead, the <a href="rgant.html#_rgant_Parameter_maxLength"><code>@Parameter#maxLength()</code></a> annotation/attribute is used.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(length=<span class="integer">50</span>) <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> <span class="predefined-type">String</span> firstName;
+
+<span class="annotation">@javax</span>.jdo.annotations.Column(length=<span class="integer">50</span>)
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> <span class="predefined-type">String</span> lastName;
+
+<span class="directive">public</span> Customer updateName(
+ <span class="annotation">@Parameter</span>(maxLength=<span class="integer">50</span>) <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">First name</span><span class="delimiter">"</span></span>)
+ <span class="predefined-type">String</span> firstName,
+ <span class="annotation">@Parameter</span>(maxLength=<span class="integer">50</span>)
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Last name</span><span class="delimiter">"</span></span>)
+ <span class="predefined-type">String</span> lastName) {
+ setFirstName(firstName);
+ setLastName(lastName);
+ <span class="keyword">return</span> <span class="local-variable">this</span>;
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Specifies the property length using the JDO <a href="rgant.html#_rgant_Column_length"><code>@Column#length()</code></a> annotation</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Specifies the parameter length using the (Apache Isis) <a href="rgant.html#_rgant_Parameter_maxLength"><code>@Parameter#maxLength()</code></a> annotation</td>
+</tr>
+</table>
+</div>
+<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<p>Incidentally, note in the above example that the new value is assigned to the properties using the setter methods; the action does not simply use set the instance field directly.
+This is important, because it allows JDO/DataNucleus to keep track that this instance variable is "dirty" and so needs flushing to the database table before the transaction completes.</p>
+</div>
</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>See also <a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">properties vs parameters</a>.</p>
+</div>
</div>
<div class="sect4">
-<h5 id="_optional">Optional</h5>
-<div class="admonitionblock note">
+<h5 id="_ugfun_how-tos_class-structure_actions_bigdecimal-parameters"><code>BigDecimal</code>s (Precision)</h5>
+<div class="paragraph">
+<p>Whereas the <a href="#_ugfun_how-tos_class-structure_properties_mapping-bigdecimals">precision of BigDecimal properties</a> is defined using <a href="rgant.html#_rgant_Column_scale"><code>@javax.jdo.annotations.Column#scale()</code></a>, that JDO annotation cannot be applied to parameter types.
+Instead, the <a href="rgant.html#_rgant_Digits_fraction"><code>@javax.validation.constraints.Digits#fraction()</code></a> annotation/attribute is used.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(scale=<span class="integer">2</span>) <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@lombok</span>.Getter <span class="annotation">@lombok</span>.Setter
+<span class="directive">private</span> <span class="predefined-type">BigDecimal</span> discountRate;
+
+<span class="directive">public</span> Order updateDiscount(
+ <span class="annotation">@javax</span>.validation.constraints.Digits(fraction=<span class="integer">2</span>) <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="annotation">@ParameterLayout</span>(named=<span class="string"><span class="delimiter">"</span><span class="content">Discount rate</span><span class="delimiter">"</span></span>)
+ <span class="predefined-type">String</span> discountRate) {
+ setDiscountRate(discountRate);
+ <span class="keyword">return</span> <span class="local-variable">this</span>;
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>Specifies the property precision using <a href="rgant.html#_rgant_Column_scale"><code>@Column#scale()</code></a></td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>Specifies the corresponding parameter precision using <a href="rgant.html#_rgant_Digits_fraction"><code>@Digits#fraction()</code></a>.</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>See also <a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">properties vs parameters</a>.</p>
+</div>
</div>
</div>
<div class="sect3">
-<h4 id="_ugfun_how-tos_class-structure_inject-services">4.1.6. Injecting services</h4>
+<h4 id="_ugfun_how-tos_class-structure_inject-services">4.1.5. Injecting services</h4>
<div class="paragraph">
-<p>Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib <code>DomainObjectContainer</code> is also a service, so can be injected in exactly the same manner.</p>
+<p>Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection.
+The framework defines many additional services (such as <a href="rgsvc.html#_rgsvc_api_RepositoryService"><code>RepositoryService</code></a>); these are injected in exactly the same manner.</p>
+</div>
+<div class="paragraph">
+<p>Sometimes there may be multiple services that implement a single type.
+This is common for example for SPI service, whereby one module defines an SPI service, and other module(s) in the application implement that service.
+To support this, the framework also allows lists of services to be injected.</p>
+</div>
+<div class="paragraph">
+<p>When there are multiple service implementations of a given type, the framework will inject the service with highest priority, as defined through <a href="rgant.html#_rgant_DomainService_menuOrder"><code>@DomainService#menuOrder()</code></a> (even for domain services that are not menus), lowest first.
+If a list of services are injected, then that list will be ordered according to <code>menuOrder</code>, again lowest first.</p>
</div>
<div class="admonitionblock note">
<table>
@@ -3811,14 +4152,27 @@ TODO
<div class="sect4">
<h5 id="_field_injection">Field Injection</h5>
<div class="paragraph">
-<p>Field injection is recommended, using the <code>@javax.inject.Inject</code> annotation. For example:</p>
+<p>Field injection is recommended, using the <code>@javax.inject.Inject</code> annotation.
+For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> {
+ ...
<span class="annotation">@javax</span>.inject.Inject
OrderRepository orderRepository;
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>To inject a list of services, use:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentService</span> {
...
+ <span class="annotation">@javax</span>.inject.Inject
+ <span class="predefined-type">List</span><PaperclipFactory> paperclipFactories;
}</code></pre>
</div>
</div>
@@ -3829,9 +4183,9 @@ TODO
<div class="sect4">
<h5 id="_method_injection">Method Injection</h5>
<div class="paragraph">
-<p>Isis also supports two forms of method injection. All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
-of the method does not matter, only that it is prefixed either <code>set</code> or <code>inject</code>, is
-public, and has a single parameter of the correct type.</p>
+<p>The framework also supports two forms of method injection.
+All that is required to inject a service into a entity/service is to provide an appropriate method or field.
+The name of the method does not matter, only that it is prefixed either <code>set</code> or <code>inject</code>, is public, and has a single parameter of the correct type.</p>
</div>
<div class="paragraph">
<p>For example:</p>
@@ -3862,6 +4216,9 @@ public, and has a single parameter of the correct type.</p>
</div>
</div>
<div class="paragraph">
+<p>Lists of services can be injected in a similar manner.</p>
+</div>
+<div class="paragraph">
<p>Note that the method name can be anything; it doesn’t need to be related to the type being injected.</p>
</div>
</div>
@@ -3873,27 +4230,16 @@ public, and has a single parameter of the correct type.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_ugfun_how-tos_class-structure_properties-vs-parameters">4.1.7. Properties vs Parameters</h4>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
-</div>
+<h4 id="_ugfun_how-tos_class-structure_properties-vs-parameters">4.1.6. Properties vs Parameters</h4>
<div class="paragraph">
-<p>In many cases the value types of properties and of action parameters align. For example, a <code>Customer</code> entity might have a <code>surname</code> property, and there might also be corresponding <code>changeSurname</code>. Ideally we want the surname property and surname action parameter to use the same value type.</p>
+<p>In many cases the value types of properties and of action parameters align.
+For example, a <code>Customer</code> entity might have a <code>surname</code> property, and there might also be corresponding <code>changeSurname</code>.
+Ideally we want the surname property and surname action parameter to use the same value type.</p>
</div>
<div class="paragraph">
-<p>Having first-class support for this is a goal of Apache Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal. However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as <code>java.lang.String</code>.</p>
-</div>
-<div class="paragraph">
-<p>However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters. It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.</p>
+<p>Since JDO/DataNucleus handles persistence, its annotations are requiredto specify semantics such as optionality or maximum length on properties.
+However, they cannot be applied to action parameters.
+It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.</p>
</div>
<div class="paragraph">
<p>The table below summarises the equivalence of some of the most common cases.</p>
@@ -3908,30 +4254,25 @@ TODO
<thead>
<tr>
<th class="tableblock halign-left valign-top">value type/semantic</th>
-<th class="tableblock halign-left valign-top">property</th>
+<th class="tableblock halign-left valign-top">(JDO) property</th>
<th class="tableblock halign-left valign-top">action parameter</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">string (length)</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@javax.jdo.annotations.Column(length=50)</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@javax.jdo.annotations.Parameter(maxLength=50)</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">big decimal (precision)</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Isis blob</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@javax.jdo.annotations.Column(scale=2)</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@javax.validation.constraints.Digits(fraction=2)</code></p></td>
</tr>
<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">optional</p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">optionality</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@Column(allowsNull="true")</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ParameterLayout(optionality=Optionality.OPTIONAL</code>) or <code>@Optional</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@Nullable</code> or <code>ParameterLayout(optionality=Optionality.OPTIONAL</code>) (also <code>@Optional</code>, now deprecated)</p></td>
</tr>
</tbody>
</table>
@@ -7852,39 +8193,42 @@ example the <a href="ug.html#_ug_getting-started_simpleapp-archetype">SimpleApp
</li>
<li><a href="#_ugfun_how-tos_class-structure_properties">4.1.2. Property</a>
<ul class="sectlevel4">
-<li><a href="#_value_vs_reference_types">Value vs Reference Types</a></li>
-<li><a href="#_optional_properties">Optional Properties</a></li>
-<li><a href="#_editable_properties">Editable Properties</a></li>
-<li><a href="#_ignoring_properties">Ignoring Properties</a></li>
-<li><a href="#_derived_properties">Derived Properties</a></li>
-<li><a href="#_mapping_code_string_code_s_length">Mapping <code>String</code>s (Length)</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_value-vs-reference-types">Value vs Reference Types</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_optional-properties">Optional Properties</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_editable-properties">Editable Properties</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_ignoring-properties">Ignoring Properties</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_derived-properties">Derived Properties</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_mapping-strings">Mapping <code>String</code>s (Length)</a></li>
<li><a href="#_ugfun_how-tos_class-structure_properties_mapping-joda-dates">Mapping JODA Date</a></li>
-<li><a href="#_mapping_code_bigdecimal_code_s_precision">Mapping <code>BigDecimal</code>s (Precision)</a></li>
-<li><a href="#_mapping_code_blob_code_s_and_code_clob_code_s">Mapping <code>Blob</code>s and <code>Clob</code>s</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_mapping-bigdecimals">Mapping <code>BigDecimal</code>s (Precision)</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_mapping-blobs-and-clobs">Mapping <code>Blob</code>s and <code>Clob</code>s</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties_handling-mandatory-properties-in-subtypes">Handling Mandatory Properties in Subtypes</a></li>
</ul>
</li>
<li><a href="#_ugfun_how-tos_class-structure_collections">4.1.3. Collections</a>
<ul class="sectlevel4">
-<li><a href="#_value_vs_reference_types_2">Value vs Reference Types</a></li>
-<li><a href="#_one_to_many_collections">One-to-many collections</a></li>
+<li><a href="#_mapping_bidir_1_m">Mapping bidir 1:m</a></li>
+<li><a href="#_value_vs_reference_types">Value vs Reference Types</a></li>
</ul>
</li>
-<li><a href="#_ugfun_how-tos_class-structure_actions">4.1.4. Actions</a></li>
-<li><a href="#_ugfun_how-tos_class-structure_action-parameters">4.1.5. Action Parameters</a>
+<li><a href="#_ugfun_how-tos_class-structure_actions">4.1.4. Actions</a>
<ul class="sectlevel4">
-<li><a href="#__code_string_code_s_length"><code>String</code>s (Length)</a></li>
-<li><a href="#__code_bigdecimal_code_s_precision"><code>BigDecimal</code>s (Precision)</a></li>
-<li><a href="#_optional">Optional</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_defining-actions">Defining actions</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_reference-parameter-types">(Reference) Parameter types</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_collection-parameter-types">Collection Parameter types (<code>1.14.0-SNAPSHOT</code>)</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_optional-parameters">Optional Parameters</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_string-parameters"><code>String</code> Parameters (Length)</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_actions_bigdecimal-parameters"><code>BigDecimal</code>s (Precision)</a></li>
</ul>
</li>
-<li><a href="#_ugfun_how-tos_class-structure_inject-services">4.1.6. Injecting services</a>
+<li><a href="#_ugfun_how-tos_class-structure_inject-services">4.1.5. Injecting services</a>
<ul class="sectlevel4">
<li><a href="#_field_injection">Field Injection</a></li>
<li><a href="#_method_injection">Method Injection</a></li>
<li><a href="#_constructor_injection">Constructor injection</a></li>
</ul>
</li>
-<li><a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">4.1.7. Properties vs Parameters</a></li>
+<li><a href="#_ugfun_how-tos_class-structure_properties-vs-parameters">4.1.6. Properties vs Parameters</a></li>
</ul>
</li>
<li><a href="#_ugfun_how-tos_ui-hints">4.2. UI Hints</a>