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 2018/02/13 13:48:41 UTC
[14/19] isis-site git commit: publishes 1.16.1-SNAPSHOT
http://git-wip-us.apache.org/repos/asf/isis-site/blob/f27adae8/content/versions/SNAPSHOT/guides/rgant/rgant.html
----------------------------------------------------------------------
diff --git a/content/versions/SNAPSHOT/guides/rgant/rgant.html b/content/versions/SNAPSHOT/guides/rgant/rgant.html
index 939bfcb..d9575e8 100644
--- a/content/versions/SNAPSHOT/guides/rgant/rgant.html
+++ b/content/versions/SNAPSHOT/guides/rgant/rgant.html
@@ -2084,6 +2084,26 @@ table.CodeRay td.code>pre{padding:0}
</thead>
<tbody>
<tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Action_associateWith"><code>associateWith()</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><em>memberId</em><br> ("")</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>associates an action with another property or collection of the action.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Action_associateWith"><code>associateWith-Sequence()</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><em>memberId</em><br> ("")</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>associates an action with another property or collection of the action.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Action_command"><code>command()</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>AS_CONFIGURED</code>, <code>ENABLED</code>, <code>DISABLED</code><br> (<code>AS_CONFIGURED</code>)</p></td>
<td class="tableblock halign-left valign-top">
@@ -2114,6 +2134,16 @@ table.CodeRay td.code>pre{padding:0}
</div></td>
</tr>
<tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commandDtoProcessor()</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation of <code>CommandDtoProcessor</code> interface<br> (null)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>If the <code>Command</code> also implements <code>CommandWithDto</code> (meaning that it can return a <code>CommandDto</code>, in other words be converted into an XML memento), then optionally specifies a processor that can refine this XML.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Action_domainEvent"><code>domainEvent()</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>ActionDomainEvent</code><br> (<code>ActionDomainEvent.Default</code>)</p></td>
<td class="tableblock halign-left valign-top">
@@ -2139,6 +2169,9 @@ table.CodeRay td.code>pre{padding:0}
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
+ <p>(deprecated - use view models and associated actions instead).</p>
+ </div>
+ <div class="paragraph">
<p>whether an action can be invoked on a single object and/or on many objects in a collection.</p>
</div>
<div class="paragraph">
@@ -2162,6 +2195,9 @@ table.CodeRay td.code>pre{padding:0}
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
+ <p>(deprecated).</p>
+ </div>
+ <div class="paragraph">
<p>specifies that a custom implementation of <code>PublishingPayloadFactoryForAction</code> be used to create the (payload of the) published event representing the action invocation</p>
</div>
</div></td>
@@ -2245,7 +2281,93 @@ table.CodeRay td.code>pre{padding:0}
</table>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_command">3.1. <code>command()</code></h3>
+ <h3 id="_rgant-Action_associateWith">3.1. <code>associateWith()</code></h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_associateWith.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_associateWith.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_associateWith.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_associateWith.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_associateWith.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The <code>associateWith</code> attribute allows an action to be associated with other properties or collections of the same domain object. The optional <code>associateWithSequence</code> attribute specifies the order of the action in the UI.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, an <code>Order</code> could have a collection of <code>OrderItem</code>s, and might provide actions to add and remove items:</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">Order</span> {
+
+ <span class="annotation">@Collection</span>
+ <span class="predefined-type">SortedSet</span><OrderItem> getItems() { ... }
+
+ <span class="annotation">@Action</span>(associateWith=<span class="string"><span class="delimiter">"</span><span class="content">items</span><span class="delimiter">"</span></span>, associateWithSequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>)
+ <span class="directive">public</span> Order addItem(Product p, <span class="type">int</span> quantity) { ... }
+
+ <span class="annotation">@Action</span>(associateWith=<span class="string"><span class="delimiter">"</span><span class="content">items</span><span class="delimiter">"</span></span>, associateWithSequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>)
+ <span class="directive">public</span> Order removeItem(OrderItem item) { ... }
+ ...
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>These actions - <code>addItem()</code> and <code>removeItem()</code> can be thought of as associated with with the <code>items</code> collection because that is the state that they primarily affect.</p>
+ </div>
+ <div class="paragraph">
+ <p>In the user interface associated actions are rendered close to the member to which they relate.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>The same effect can be accomplished using <code>@MemberOrder</code> or with the <code>.layout.xml</code> file.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="_inferred_defaults_and_choices">3.1.1. Inferred Defaults and Choices</h4>
+ <div class="paragraph">
+ <p>If an action is associated with a collection, then any scalar or collection parameter of the action that is the same type as that collection will automatically have a list of choices provided for it, being the items of the associated collection.</p>
+ </div>
+ <div class="paragraph">
+ <p>This is only done provided that there isn’t already an explicit <code>choicesNXxx()</code> or <code>autoCompleteNXxx()</code> supporting method. However, this list of choices <em>does</em> take priority over any choices that are inferred from the parameter type itself (as per either an <code>@DomainObject(autoCompleteRepository=…)</code> or <code>@DomainObject(bounded=…)</code>).</p>
+ </div>
+ <div class="paragraph">
+ <p>In addition, if the action has a collection parameter of the same type as the associated collection, then the Wicket viewer will render the collection with checkboxes. The user can use these checkboxes can be used to select the items of the action parameter.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, suppose we have a "removeItems(…)" action:</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">Order</span> {
+
+ <span class="annotation">@Collection</span>
+ <span class="predefined-type">SortedSet</span><OrderItem> getItems() { ... }
+
+ ...
+
+ <span class="annotation">@Action</span>(associateWith=<span class="string"><span class="delimiter">"</span><span class="content">items</span><span class="delimiter">"</span></span>, associateWithSequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>)
+ <span class="directive">public</span> Order removeItems(<span class="predefined-type">SortedSet</span><OrderItem> items) { ... }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The Wicket viewer will then render the "items" collection with checkboxes, and any selected items will be used as the pre-selected set of items if the action is invoked.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgant-Action_command">3.2. <code>command()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_command.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2257,7 +2379,7 @@ table.CodeRay td.code>pre{padding:0}
</ul>
</div>
<div class="paragraph">
- <p>The <code>@Action(command=…)</code> attribute (and the related <code>@Action(commandPersistence=…)</code> and <code>@Action(commandExecuteIn=…)</code> attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this is enhanced profiling/auditing, and it also supports the deferring the execution of the action such that it can be invoked in the background.</p>
+ <p>The <code>@Action(command=…)</code> attribute (and the related <code>@Action(commandXxx=…)</code> attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this are to support the deferring the execution of the action such that it can be invoked in the background, and to replay commands in a master/slave configuration.</p>
</div>
<div class="paragraph">
<p>The annotation works with (and is influenced by the behaviour of) a number of domain services:</p>
@@ -2296,26 +2418,26 @@ table.CodeRay td.code>pre{padding:0}
<p>The <code>command()</code> attribute determines whether the action invocation should be reified into a <code>Command</code> object (by the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> service).</p>
</div>
<div class="paragraph">
- <p>The default is <code>AS_CONFIGURED</code>, meaning that the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-core">configuration property</a> <code>isis.services.command.actions</code> is used to determine the whether the action is reified:</p>
+ <p>The default is <code>AS_CONFIGURED</code>, meaning that the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-core">configuration property</a> <code>isis.services.command.actions</code> is used to determine whether the action invocation is reified:</p>
</div>
<div class="ulist">
<ul>
<li> <p><code>all</code><br></p>
<div class="paragraph">
- <p>all actions are reified</p>
+ <p>all action invocations are reified</p>
</div> </li>
<li> <p><code>ignoreSafe</code> (or <code>ignoreQueryOnly</code>)<br></p>
<div class="paragraph">
- <p>actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored</p>
+ <p>invocations of actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored</p>
</div> </li>
<li> <p><code>none</code><br></p>
<div class="paragraph">
- <p>no actions are reified.</p>
+ <p>no action invocations are reified.</p>
</div> </li>
</ul>
</div>
<div class="paragraph">
- <p>If there is no configuration property in <code>isis.properties</code> then all actions are reified into <code>Command</code>s.</p>
+ <p>If there is no configuration property in <code>isis.properties</code> then all action invocations are reified into <code>Command</code>s.</p>
</div>
<div class="admonitionblock note">
<table>
@@ -2331,7 +2453,7 @@ table.CodeRay td.code>pre{padding:0}
</table>
</div>
<div class="paragraph">
- <p>This default can be overridden on an action-by-action basis; if <code>command()</code> is set to <code>ENABLED</code> then the action is reified irrespective of the configured value; if set to <code>DISABLED</code> then the action is NOT reified irrespective of the configured value.</p>
+ <p>This default can be overridden on an action-by-action basis; if <code>command()</code> is set to <code>ENABLED</code> then the action is reified irrespective of the configured value; if set to <code>DISABLED</code> then the action invocation is NOT reified irrespective of the configured value.</p>
</div>
<div class="paragraph">
<p>For example:</p>
@@ -2348,9 +2470,9 @@ table.CodeRay td.code>pre{padding:0}
<p>corresponds to the behaviour described above; the <code>Command</code> object is persisted (assuming an appropriate <code>CommandService</code> is defined, and executed immediately in the foreground).</p>
</div>
<div class="sect3">
- <h4 id="__code_commandpersistence_code">3.1.1. <code>commandPersistence()</code></h4>
+ <h4 id="__code_commandpersistence_code">3.2.1. <code>commandPersistence()</code></h4>
<div class="paragraph">
- <p>If the action has been reified, then the <code>commandPersistence()</code> attribute determines whether that <code>Command</code> object should then also be persisted (the default), or not persisted, or only if hinted.</p>
+ <p>If the action invocation has been reified, then the <code>commandPersistence()</code> attribute determines whether that <code>Command</code> object should then also be persisted (the default), or not persisted, or only if hinted.</p>
</div>
<div class="paragraph">
<p>To explain this last alternative:</p>
@@ -2377,7 +2499,6 @@ table.CodeRay td.code>pre{padding:0}
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
<span class="annotation">@Action</span>(
command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.FOREGROUND,
commandPersistence=CommandPersistence.NOT_PERSISTED
)
<span class="directive">public</span> Invoice generateInvoice(...) { ... }
@@ -2389,7 +2510,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect3">
- <h4 id="__code_commandexecutein_code">3.1.2. <code>commandExecuteIn()</code></h4>
+ <h4 id="__code_commandexecutein_code">3.2.2. <code>commandExecuteIn()</code></h4>
<div class="paragraph">
<p>For persisted commands, the <code>commandExecuteIn()</code> attribute determines whether the <code>Command</code> should be executed in the foreground (the default) or executed in the background.</p>
</div>
@@ -2404,18 +2525,162 @@ table.CodeRay td.code>pre{padding:0}
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
<span class="annotation">@Action</span>(
command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.BACKGROUND)
+ commandExecuteIn=CommandExecuteIn.BACKGROUND
+ )
<span class="directive">public</span> Invoice generateInvoice(...) { ... }
}</code></pre>
</div>
</div>
<div class="paragraph">
- <p>will result in the <code>Command</code> being persisted but its execution deferred to a background execution mechanism. The returned object from this action is the persisted <code>Command</code> itself.</p>
+ <p>will result in the <code>Command</code> being persisted but its execution deferred to a background execution mechanism. The returned object from this action invocation is the persisted <code>Command</code> itself.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_commanddtoprocessor_code">3.2.3. <code>commandDtoProcessor()</code></h4>
+ <div class="paragraph">
+ <p>The <code>commandDtoProcessor()</code> attribute allows an implementation of <code>CommandDtoProcessor</code> to be specified. This interface has the following API:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">CommandDtoProcessor</span> {
+ CommandDto process( <i class="conum" data-value="1"></i><b>(1)</b>
+ Command command, <i class="conum" data-value="2"></i><b>(2)</b>
+ CommandDto dto); <i class="conum" data-value="3"></i><b>(3)</b>
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>The returned <code>CommandDto</code>. This will typically be the <code>CommandDto</code> passed in, but supplemented in some way.</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>The <code>Command</code> being processed</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>The <code>CommandDto</code> (XML) obtained already from the <code>Command</code> (by virtue of it also implementing <code>CommandWithDto</code>, see discussion below).</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>This interface is used by the framework-provided implementations of <code>ContentMappingService</code> for the REST API, allowing <code>Command</code>s implementations that also implement <code>CommandWithDto</code> to be further customised as they are serialized out. The primary use case for this capability is in support of master/slave replication.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>on the master, <code>Command</code>s are serialized to XML. This includes the identity of the target object and the argument values of all parameters.</p>
+ <div class="admonitionblock important">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>However, any <code>Blob</code>s and <code>Clob</code>s are deliberately excluded from this XML (they are instead stored as references). This is to prevent the storage requirements for <code>Command</code> from becoming excessive. A <code>CommandDtoProcessor</code> can be provided to re-attach blob information if required.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div> </li>
+ <li> <p>replaying <code>Command</code>s requires this missing parameter information to be reinstated. The <code>CommandDtoProcessor</code> therefore offers a hook to dynamically re-attach the missing <code>Blob</code> or <code>Clob</code> argument.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>As a special case, returning <code>null</code> means that the command’s DTO is effectively excluded when retrieving the list of commands. If replicating from master to slave, this effectively allows certain commands to be ignored. The <code>CommandDtoProcessor.Null</code> class provides a convenience implementation for this requirement.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>If <code>commandDtoProcessor()</code> is specified, then <code>command()</code> is assumed to be ENABLED.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect4">
+ <h5 id="_example_implementation">Example implementation</h5>
+ <div class="paragraph">
+ <p>Consider the following method:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Action</span>(
+ domainEvent = IncomingDocumentRepository.UploadDomainEvent.class,
+ commandDtoProcessor = DeriveBlobArg0FromReturnedDocument.class
+)
+<span class="directive">public</span> <span class="predefined-type">Document</span> upload(<span class="directive">final</span> <span class="predefined-type">Blob</span> blob) {
+ <span class="directive">final</span> <span class="predefined-type">String</span> name = blob.getName();
+ <span class="directive">final</span> DocumentType type = DocumentTypeData.INCOMING.findUsing(documentTypeRepository);
+ <span class="directive">final</span> ApplicationUser me = meService.me();
+ <span class="predefined-type">String</span> atPath = me != <span class="predefined-constant">null</span> ? me.getAtPath() : <span class="predefined-constant">null</span>;
+ <span class="keyword">if</span> (atPath == <span class="predefined-constant">null</span>) {
+ atPath = <span class="string"><span class="delimiter">"</span><span class="content">/</span><span class="delimiter">"</span></span>;
+ }
+ <span class="keyword">return</span> incomingDocumentRepository.upsertAndArchive(type, atPath, name, blob);
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The <code>Blob</code> argument will not be persisted in the memento of the <code>Command</code>, but the information is implicitly available in the <code>Document</code> that is returned by the action. The <code>DeriveBlobArg0FromReturnedDocument</code> processor retrieves this information and dynamically adds:</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">DeriveBlobArg0FromReturnedDocument</span>
+ <span class="directive">extends</span> CommandDtoProcessorForActionAbstract {
+
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> CommandDto process(Command command, CommandDto commandDto) {
+ <span class="directive">final</span> Bookmark result = commandWithDto.getResult();
+ <span class="keyword">if</span>(result == <span class="predefined-constant">null</span>) {
+ <span class="keyword">return</span> commandDto;
+ }
+ <span class="keyword">try</span> {
+ <span class="directive">final</span> <span class="predefined-type">Document</span> document = bookmarkService.lookup(result, <span class="predefined-type">Document</span>.class);
+ <span class="keyword">if</span> (document != <span class="predefined-constant">null</span>) {
+ ParamDto paramDto = getParamDto(commandDto, <span class="integer">0</span>);
+ CommonDtoUtils.setValueOn(paramDto, ValueType.BLOB, document.getBlob(), bookmarkService);
+ }
+ } <span class="keyword">catch</span>(<span class="exception">Exception</span> ex) {
+ <span class="keyword">return</span> commandDto;
+ }
+ <span class="keyword">return</span> commandDto;
+ }
+ <span class="annotation">@Inject</span>
+ BookmarkService bookmarkService;
+}</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_null_implementation">Null implementation</h5>
+ <div class="paragraph">
+ <p>The null implementation can be used to simply indicate that no DTO should be returned for a <code>Command</code>. The effect is to ignore it for replay purposes:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="xml">pubc interface CommandDtoProcessor {
+ ...
+ class Null implements CommandDtoProcessor {
+ public CommandDto process(Command command, CommandDto commandDto) {
+ return null;
+ }
+ }
+}</code></pre>
+ </div>
+ </div>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_domainEvent">3.2. domainEvent()</h3>
+ <h3 id="_rgant-Action_domainEvent">3.3. domainEvent()</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2485,7 +2750,7 @@ table.CodeRay td.code>pre{padding:0}
</table>
</div>
<div class="sect3">
- <h4 id="_subscribers">3.2.1. Subscribers</h4>
+ <h4 id="_subscribers">3.3.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API or (if the <a href="../rgsvc/rgsvc.html#_rgsvc_core-domain-api_EventBusService"><code>EventBusService</code></a> has been appropriately configured) using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
</div>
@@ -2574,7 +2839,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect3">
- <h4 id="_default_doop_and_noop_events">3.2.2. Default, Doop and Noop events</h4>
+ <h4 id="_default_doop_and_noop_events">3.3.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>domainEvent</code> attribute is not explicitly specified (is left as its default value, <code>ActionDomainEvent.Default</code>), then the framework will, by default, post an event.</p>
</div>
@@ -2589,14 +2854,14 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect3">
- <h4 id="_raising_events_programmatically">3.2.3. Raising events programmatically</h4>
+ <h4 id="_raising_events_programmatically">3.3.3. Raising events programmatically</h4>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the <a href="../rgsvc/rgsvc.html#_rgsvc_core-domain-api_EventBusService"><code>EventBusService</code></a> API directly, or by emulating the UI by wrapping the target object using the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_WrapperFactory"><code>WrapperFactory</code></a> domain service.</p>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_hidden">3.3. <code>hidden()</code></h3>
+ <h3 id="_rgant-Action_hidden">3.4. <code>hidden()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_hidden.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2668,7 +2933,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_invokeOn">3.4. <code>invokeOn()</code></h3>
+ <h3 id="_rgant-Action_invokeOn">3.5. <code>invokeOn()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_invokeOn.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2751,7 +3016,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_publishing">3.5. <code>publishing()</code></h3>
+ <h3 id="_rgant-Action_publishing">3.6. <code>publishing()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_publishing.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2763,7 +3028,7 @@ table.CodeRay td.code>pre{padding:0}
</ul>
</div>
<div class="paragraph">
- <p>The <code>publishing()</code> attribute determines whether and how an action invocation is published via the registered implementation of a <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>) or <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a>. This attribute is also supported for <a href="../rgant/rgant.html#_rgant-DomainObject_publishing">domain objects</a>, where it controls whether changed objects are published as events, and for <a href="../rgant/rgant.html#_rgant_Property_publishing"><code>@Property#publishing()</code></a>, where it controls whether property edits are published as events.</p>
+ <p>The <code>publishing()</code> attribute determines whether and how an action invocation is published via the registered implementation of a <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>) or <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a>. This attribute is also supported for <a href="../rgant/rgant.html#_rgant-DomainObject_publishing">domain objects</a>, where it controls whether changed objects are published as events, and for <a href="../rgant/rgant.html#_rgant-Property_publishing"><code>@Property#publishing()</code></a>, where it controls whether property edits are published as events.</p>
</div>
<div class="paragraph">
<p>A common use case is to notify external "downstream" systems of changes in the state of the Isis application. The default value for the attribute is <code>AS_CONFIGURED</code>, meaning that the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-core">configuration property</a> <code>isis.services.publish.actions</code> is used to determine the whether the action is published:</p>
@@ -2812,7 +3077,7 @@ table.CodeRay td.code>pre{padding:0}
</table>
</div>
<div class="sect3">
- <h4 id="__code_publishingpayloadfactory_code">3.5.1. <code>publishingPayloadFactory()</code></h4>
+ <h4 id="__code_publishingpayloadfactory_code">3.6.1. <code>publishingPayloadFactory()</code></h4>
<div class="paragraph">
<p>The (optional) related <code>publishingPayloadFactory()</code> specifies the class to use to create the (payload of the) event to be published by the publishing factory.</p>
</div>
@@ -2835,7 +3100,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_restrictTo">3.6. <code>restrictTo()</code></h3>
+ <h3 id="_rgant-Action_restrictTo">3.7. <code>restrictTo()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_restrictTo.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2869,7 +3134,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_semantics">3.7. <code>semantics()</code></h3>
+ <h3 id="_rgant-Action_semantics">3.8. <code>semantics()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_semantics.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -2988,7 +3253,7 @@ WrapperFactory wrapperFactory;</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Action_typeOf">3.8. <code>typeOf()</code></h3>
+ <h3 id="_rgant-Action_typeOf">3.9. <code>typeOf()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_typeOf.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -5631,9 +5896,9 @@ WrapperFactory wrapperFactory;</code></pre>
</div>
<div class="olist arabic">
<ol class="arabic">
- <li> <p><a href="../rgant/rgant.html#_rgant_Discriminator"><code>@Discriminator</code></a></p> </li>
+ <li> <p><a href="../rgant/rgant.html#_rgant-Discriminator"><code>@Discriminator</code></a></p> </li>
<li> <p><code>@DomainObject#objectType</code></p> </li>
- <li> <p><a href="../rgant/rgant.html#_rgant_PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
+ <li> <p><a href="../rgant/rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
<div class="paragraph">
<p>If both <code>schema</code> and <code>table</code> are defined, then the value is “schema.table�?. If only <code>schema</code> is defined, then the value is “schema.className�?.</p>
</div> </li>
@@ -6070,7 +6335,7 @@ WrapperFactory wrapperFactory;</code></pre>
</table>
</div>
<div class="paragraph">
- <p>The autocomplete action can also be a regular method, annotated using <a href="../rgant/rgant.html#_rgant_Programmatic"><code>@Programmatic</code></a>:</p>
+ <p>The autocomplete action can also be a regular method, annotated using <a href="../rgant/rgant.html#_rgant-Programmatic"><code>@Programmatic</code></a>:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -6930,9 +7195,9 @@ WrapperFactory wrapperFactory;</code></pre>
</div>
<div class="olist arabic">
<ol class="arabic">
- <li> <p><a href="../rgant/rgant.html#_rgant_Discriminator"><code>@Discriminator</code></a></p> </li>
+ <li> <p><a href="../rgant/rgant.html#_rgant-Discriminator"><code>@Discriminator</code></a></p> </li>
<li> <p><code>@DomainObject#objectType</code>, or <a href="../rgant/rgant.html#_rgant_aaa_deprecated"><code>@ObjectType</code></a> (deprecated)</p> </li>
- <li> <p><a href="../rgant/rgant.html#_rgant_PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
+ <li> <p><a href="../rgant/rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
<div class="paragraph">
<p>If both <code>schema</code> and <code>table</code> are defined, then the value is “schema.table�?. If only <code>schema</code> is defined, then the value is “schema.className�?.</p>
</div> </li>
@@ -6983,7 +7248,7 @@ WrapperFactory wrapperFactory;</code></pre>
</ul>
</div>
<div class="paragraph">
- <p>The <code>publishing()</code> attribute determines whether and how a modified object instance is published via the registered implementation of a <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>) or <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a>. This attribute is also supported for <a href="../rgant/rgant.html#_rgant-Action_publishing">actions</a>, where it controls whether action invocations are published as events, and for <a href="../rgant/rgant.html#_rgant_Property_publishing"><code>@Property#publishing()</code></a>, where it controls whether property edits are published as events.</p>
+ <p>The <code>publishing()</code> attribute determines whether and how a modified object instance is published via the registered implementation of a <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>) or <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a>. This attribute is also supported for <a href="../rgant/rgant.html#_rgant-Action_publishing">actions</a>, where it controls whether action invocations are published as events, and for <a href="../rgant/rgant.html#_rgant-Property_publishing"><code>@Property#publishing()</code></a>, where it controls whether property edits are published as events.</p>
</div>
<div class="paragraph">
<p>A common use case is to notify external "downstream" systems of changes in the state of the Isis application.</p>
@@ -8450,7 +8715,7 @@ WrapperFactory wrapperFactory;</code></pre>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p>equivalent to <a href="../rgant/rgant.html#_rgant_DomainObject_objectType"><code>@DomainObject#objectType()</code></a>, specifies the objectType of the service.</p>
+ <p>equivalent to <a href="../rgant/rgant.html#_rgant-DomainObject_objectType"><code>@DomainObject#objectType()</code></a>, specifies the objectType of the service.</p>
</div>
<div class="paragraph">
<p>The instanceId for services is always "1".</p>
@@ -9656,7 +9921,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Apache Isis does provide several other ways to specify optionality: using the <a href="../rgant/rgant.html#_rgant_Property_optionality"><code>@Property#optionality()</code></a> / <a href="../rgant/rgant.html#_rgant_Parameter_optionality"><code>@Parameter#optionality()</code></a> annotation. For properties, the optionality can also be inferred from the <a href="../rgant/rgant.html#_rgant_Column_allowsNull"><code>@Column#allowsNull()</code></a> attribute.</p>
+ <p>Apache Isis does provide several other ways to specify optionality: using the <a href="../rgant/rgant.html#_rgant-Property_optionality"><code>@Property#optionality()</code></a> / <a href="../rgant/rgant.html#_rgant-Parameter_optionality"><code>@Parameter#optionality()</code></a> annotation. For properties, the optionality can also be inferred from the <a href="../rgant/rgant.html#_rgant-Column_allowsNull"><code>@Column#allowsNull()</code></a> attribute.</p>
</div>
<div class="admonitionblock tip">
<table>
@@ -9665,7 +9930,7 @@ container.persist(cust);</code></pre>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
- <p>See the <a href="../rgant/rgant.html#_rgant_Property_optionality"><code>@Property#optionality()</code></a> documentation for a much fuller discussion on the relationship between using the Apache Isis annotations vs <a href="../rgant/rgant.html#_rgant_Column_allowsNull"><code>@Column#allowsNull()</code></a>.</p>
+ <p>See the <a href="../rgant/rgant.html#_rgant-Property_optionality"><code>@Property#optionality()</code></a> documentation for a much fuller discussion on the relationship between using the Apache Isis annotations vs <a href="../rgant/rgant.html#_rgant-Column_allowsNull"><code>@Column#allowsNull()</code></a>.</p>
</div> </td>
</tr>
</tbody>
@@ -9818,7 +10083,7 @@ container.persist(cust);</code></pre>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p>Deprecated; use <a href="../rgant/rgant.html#_rgant_minLength"><code>@MinLength</code></a> instead.<br></p>
+ <p>Deprecated; use <a href="../rgant/rgant.html#_rgant-MinLength"><code>@MinLength</code></a> instead.<br></p>
</div>
<div class="paragraph">
<p>Can be used to specify the minimum length for <a href="../rgcms/rgcms.html#<em>rgcms_methods_prefixes_autoComplete"><code>autoComplete…()</code></a> supporting method; but because this _is a supporting method rather than the action method itself, we now feel it is misleading to use the <code>@Parameter</code> annotation in this situation.</p>
@@ -10158,7 +10423,7 @@ container.persist(cust);</code></pre>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content">
<div class="paragraph">
- <p>It is also possible to specify optionality using <a href="../rgant/rgant.html#_rgant_Nullable"><code>@Nullable</code></a> annotation.</p>
+ <p>It is also possible to specify optionality using <a href="../rgant/rgant.html#_rgant-Nullable"><code>@Nullable</code></a> annotation.</p>
</div> </td>
</tr>
</tbody>
@@ -10811,9 +11076,9 @@ container.persist(cust);</code></pre>
</div>
<div class="olist arabic">
<ol class="arabic">
- <li> <p><a href="../rgant/rgant.html#_rgant_Discriminator"><code>@Discriminator</code></a></p> </li>
+ <li> <p><a href="../rgant/rgant.html#_rgant-Discriminator"><code>@Discriminator</code></a></p> </li>
<li> <p><code>@DomainObject#objectType</code></p> </li>
- <li> <p><a href="../rgant/rgant.html#_rgant_PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
+ <li> <p><a href="../rgant/rgant.html#_rgant-PersistenceCapable"><code>@PersistenceCapable</code></a>, if at least the <code>schema</code> attribute is defined. <br></p>
<div class="paragraph">
<p>If both <code>schema</code> and <code>table</code> are defined, then the value is “schema.table�?. If only <code>schema</code> is defined, then the value is “schema.className�?.</p>
</div> </li>
@@ -11160,6 +11425,46 @@ container.persist(cust);</code></pre>
</thead>
<tbody>
<tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Property_command"><code>command()</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AS_CONFIGURED</code>, <code>ENABLED</code>, <code>DISABLED</code><br> (<code>AS_CONFIGURED</code>)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>whether the property edit should be reified into a <code>o.a.i.applib.</code><br> <code>services.command.Command</code> object through the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> service.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commandExecuteIn()</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>FOREGROUND</code>,<code>BACKGROUND</code><br> (<code>FOREGROUND</code>)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> has been configured) such that a background scheduler can execute the command asynchronously</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commandPersistence()</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>PERSISTED</code>, <code>NOT_PERSISTED</code>, <code>IF_HINTED</code><br> (<code>PERSISTED</code>)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>whether the reified <code>Command</code> (as provided by the <code>CommandContext</code> domain service) should actually be persisted (assuming an appropriate implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> has been configured).</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>commandDtoProcessor()</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation of <code>CommandDtoProcessor</code> interface<br> (null)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>If the <code>Command</code> also implements <code>CommandWithDto</code> (meaning that it can return a <code>CommandDto</code>, in other words be converted into an XML memento), then optionally specifies a processor that can refine this XML.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgant/rgant.html#_rgant-Property_domainEvent"><code>domainEvent()</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>PropertyDomainEvent</code><br> (<code>PropertyDomainEvent.Default</code>)</p></td>
<td class="tableblock halign-left valign-top">
@@ -11334,7 +11639,264 @@ container.persist(cust);</code></pre>
</table>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_domainEvent">30.1. <code>domainEvent()</code></h3>
+ <h3 id="_rgant-Property_command">30.1. <code>command()</code></h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_command.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_command.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_command.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_command.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_command.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The <code>@Property(command=…)</code> attribute (and the related <code>@Property(commandXxx=…)</code> attributes) allows a property edit to be made into a concrete object such that it can be inspected and persisted. The primary use case for this are to support the deferring the execution of the action such that it can be invoked in the background, and to replay commands in a master/slave configuration.</p>
+ </div>
+ <div class="paragraph">
+ <p>The annotation works with (and is influenced by the behaviour of) a number of domain services:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a></p> </li>
+ <li> <p><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a></p> </li>
+ <li> <p><a href="../rgsvc/rgsvc.html#_rgsvc_spi_BackgroundService"><code>BackgroundService</code></a> and</p> </li>
+ <li> <p><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Each property edit is reified by the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> service into a <code>Command</code> object, capturing details of the target object, the property, the proposed new value fo the property, the user, a timestamp and so on.</p>
+ </div>
+ <div class="paragraph">
+ <p>If an appropriate <code>CommandService</code> is configured (for example using (non-ASF) <a href="http://platform.incode.org/modules/spi/command/spi-command.html">Incode Platform’s command</a> module), then the <code>Command</code> itself is persisted.</p>
+ </div>
+ <div class="paragraph">
+ <p>By default, actions are invoked in directly in the thread of the invocation. If there is an implementation of <code>BackgroundCommandService</code> (as the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module does provide), then this means in turn that the <code>BackgroundService</code> can be used by the domain object code to programmatically create background <code>Command</code>s.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>If background <code>Command</code>s are used, then an external scheduler, using <a href="../ugbtb/ugbtb.html#_ugbtb_headless-access_BackgroundCommandExecution">headless access</a>, must also be configured.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>The <code>command()</code> attribute determines whether the property edit should be reified into a <code>Command</code> object (by the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> service).</p>
+ </div>
+ <div class="paragraph">
+ <p>The default is <code>AS_CONFIGURED</code>, meaning that the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-core">configuration property</a> <code>isis.services.command.properties</code> is used to determine whether the property edit is reified:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>all</code><br></p>
+ <div class="paragraph">
+ <p>all property edits are reified</p>
+ </div> </li>
+ <li> <p><code>none</code><br></p>
+ <div class="paragraph">
+ <p>no property edits are reified.</p>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>If there is no configuration property in <code>isis.properties</code> then all property edits are reified into <code>Command</code>s.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Note: <code>Command</code> reification does not necessarily imply that <code>Command</code> objects will be persisted; that depends on whether there is a <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> configured that will persist said <code>Command</code>s.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>This default can be overridden on an property-by-property basis; if <code>command()</code> is set to <code>ENABLED</code> then the action is reified irrespective of the configured value; if set to <code>DISABLED</code> then the property edit is NOT reified irrespective of the configured value.</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="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+ <span class="annotation">@Property</span>(command=CommandReification.ENABLED)
+ <span class="directive">public</span> Product getProduct() { ... }
+ <span class="directive">public</span> <span class="type">void</span> setProduct(Product p) { ... }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>corresponds to the behaviour described above; the <code>Command</code> object is persisted (assuming an appropriate <code>CommandService</code> is defined, and executed immediately in the foreground).</p>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_commandpersistence_code_2">30.1.1. <code>commandPersistence()</code></h4>
+ <div class="paragraph">
+ <p>If the property edit has been reified, then the <code>commandPersistence()</code> attribute determines whether that <code>Command</code> object should then also be persisted (the default), or not persisted, or only if hinted.</p>
+ </div>
+ <div class="paragraph">
+ <p>To explain this last alternative:</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">Order</span> {
+ <span class="annotation">@Property</span>(
+ command=CommandReification.ENABLED,
+ commandPersistence=CommandPersistence.IF_HINTED
+ )
+ <span class="directive">public</span> Product getProduct() { ... }
+ <span class="directive">public</span> <span class="type">void</span> setProduct(Product p) { ... }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will suppress the persistence of the <code>Command</code> object <em>unless</em> a child background <code>Command</code> has been created in the body of the property by way of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_BackgroundService"><code>BackgroundService</code></a>.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Unlike actions, where this is quite feasible, it is rather unlikely to occur as a side-effect of editing a property.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>On the other hand:</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">Order</span> {
+ <span class="annotation">@Property</span>(
+ command=CommandReification.ENABLED,
+ commandPersistence=CommandPersistence.NOT_PERSISTED
+ )
+ <span class="directive">public</span> Product getProduct() { ... }
+ <span class="directive">public</span> <span class="type">void</span> setProduct(Product p) { ... }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will prevent the parent <code>Command</code> object from being persisted, <em>even if</em> a child background <code>Command</code> is created.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_commandexecutein_code_2">30.1.2. <code>commandExecuteIn()</code></h4>
+ <div class="paragraph">
+ <p>For persisted commands, the <code>commandExecuteIn()</code> attribute determines whether the <code>Command</code> should be executed in the foreground (the default) or executed in the background.</p>
+ </div>
+ <div class="paragraph">
+ <p>Background execution means that the command is not executed immediately, but is available for a configured <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a> to execute, eg by way of an in-memory scheduler such as Quartz. See <a href="../ugbtb/ugbtb.html#_ugbtb_headless-access_BackgroundCommandExecution">here</a> for further information on this topic.</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="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+ <span class="annotation">@Property</span>(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.BACKGROUND
+ )
+ <span class="directive">public</span> Product getProduct() { ... }
+ <span class="directive">public</span> <span class="type">void</span> setProduct(Product p) { ... }
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>will result in the <code>Command</code> being persisted but its execution deferred to a background execution mechanism. The returned object from this property edit is the persisted <code>Command</code> itself.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="__code_commanddtoprocessor_code_2">30.1.3. <code>commandDtoProcessor()</code></h4>
+ <div class="paragraph">
+ <p>The <code>commandDtoProcessor()</code> attribute allows an implementation of <code>CommandDtoProcessor</code> to be specified. This interface has the following API:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">CommandDtoProcessor</span> {
+ CommandDto process( <i class="conum" data-value="1"></i><b>(1)</b>
+ Command command, <i class="conum" data-value="2"></i><b>(2)</b>
+ CommandDto dto); <i class="conum" data-value="3"></i><b>(3)</b>
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>The returned <code>CommandDto</code>. This will typically be the <code>CommandDto</code> passed in, but supplemented in some way.</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>The <code>Command</code> being processed</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>The <code>CommandDto</code> (XML) obtained already from the <code>Command</code> (by virtue of it also implementing <code>CommandWithDto</code>, see discussion below).</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>This interface is used by the framework-provided implementations of <code>ContentMappingService</code> for the REST API, allowing <code>Command</code>s implementations that also implement <code>CommandWithDto</code> to be further customised as they are serialized out. The primary use case for this capability is in support of master/slave replication.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>on the master, <code>Command</code>s are serialized to XML. This includes the identity of the target object and the intended new value of the property.</p>
+ <div class="admonitionblock important">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-important" title="Important"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>However, any <code>Blob</code>s and <code>Clob</code>s are deliberately excluded from this XML (they are instead stored as references). This is to prevent the storage requirements for <code>Command</code> from becoming excessive. A <code>CommandDtoProcessor</code> can be provided to re-attach blob information if required.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div> </li>
+ <li> <p>replaying <code>Command</code>s requires this missing parameter information to be reinstated. The <code>CommandDtoProcessor</code> therefore offers a hook to dynamically re-attach the missing <code>Blob</code> or <code>Clob</code> argument.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>As a special case, returning <code>null</code> means that the command’s DTO is effectively excluded when retrieving the list of commands. If replicating from master to slave, this effectively allows certain commands to be ignored. The <code>CommandDtoProcessor.Null</code> class provides a convenience implementation for this requirement.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>If <code>commandDtoProcessor()</code> is specified, then <code>command()</code> is assumed to be ENABLED.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>For an example application, see <a href="#_rgant-Action_command"><code>Action#command()</code></a>.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgant-Property_domainEvent">30.2. <code>domainEvent()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_domainEvent.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11415,7 +11977,7 @@ container.persist(cust);</code></pre>
</table>
</div>
<div class="sect3">
- <h4 id="_subscribers_13">30.1.1. Subscribers</h4>
+ <h4 id="_subscribers_13">30.2.1. Subscribers</h4>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API or (if the <a href="../rgsvc/rgsvc.html#_rgsvc_core-domain-api_EventBusService"><code>EventBusService</code></a> has been appropriately configured) using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
</div>
@@ -11504,7 +12066,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="_default_doop_and_noop_events_13">30.1.2. Default, Doop and Noop events</h4>
+ <h4 id="_default_doop_and_noop_events_13">30.2.2. Default, Doop and Noop events</h4>
<div class="paragraph">
<p>If the <code>domainEvent</code> attribute is not explicitly specified (is left as its default value, <code>PropertyDomainEvent.Default</code>), then the framework will, by default, post an event.</p>
</div>
@@ -11519,14 +12081,14 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="_raising_events_programmatically_6">30.1.3. Raising events programmatically</h4>
+ <h4 id="_raising_events_programmatically_6">30.2.3. Raising events programmatically</h4>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically by wrapping the target object using the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_WrapperFactory"><code>WrapperFactory</code></a> service.</p>
</div>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_editing">30.2. <code>editing()</code></h3>
+ <h3 id="_rgant-Property_editing">30.3. <code>editing()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_editing.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11584,7 +12146,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_fileAccept">30.3. <code>fileAccept()</code></h3>
+ <h3 id="_rgant-Property_fileAccept">30.4. <code>fileAccept()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_fileAccept.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11624,7 +12186,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_hidden">30.4. <code>hidden()</code></h3>
+ <h3 id="_rgant-Property_hidden">30.5. <code>hidden()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_hidden.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11718,7 +12280,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_maxLength">30.5. <code>maxLength()</code></h3>
+ <h3 id="_rgant-Property_maxLength">30.6. <code>maxLength()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_maxLength.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11752,7 +12314,7 @@ container.persist(cust);</code></pre>
<p>In this case there is therefore no need for the <code>@Property#maxLength()</code> attribute.</p>
</div>
<div class="sect3">
- <h4 id="_non_persistent_properties">30.5.1. Non-persistent properties</h4>
+ <h4 id="_non_persistent_properties">30.6.1. Non-persistent properties</h4>
<div class="paragraph">
<p>Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the <code>maxLength()</code> attribute is still required.</p>
</div>
@@ -11791,7 +12353,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_mustSatisfy">30.6. <code>mustSatisfy()</code></h3>
+ <h3 id="_rgant-Property_mustSatisfy">30.7. <code>mustSatisfy()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_mustSatisfy.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11878,7 +12440,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_notPersisted">30.7. <code>notPersisted()</code></h3>
+ <h3 id="_rgant-Property_notPersisted">30.8. <code>notPersisted()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_notPersisted.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11962,7 +12524,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_optionality">30.8. <code>optionality()</code></h3>
+ <h3 id="_rgant-Property_optionality">30.9. <code>optionality()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_optionality.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -11999,7 +12561,7 @@ container.persist(cust);</code></pre>
<p>In this case there is no need for the <code>@Property#optionality()</code> attribute.</p>
</div>
<div class="sect3">
- <h4 id="_mismatched_defaults">30.8.1. Mismatched defaults</h4>
+ <h4 id="_mismatched_defaults">30.9.1. Mismatched defaults</h4>
<div class="paragraph">
<p>If the <code>@Column#allowsNull()</code> attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Isis' defaults and JDO’s defaults differ. Specifically, Isis always assumes properties are mandatory, whereas JDO specifies that primitives are mandatory, but all reference types are optional.</p>
</div>
@@ -12008,7 +12570,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="_superclass_inheritance_type">30.8.2. Superclass inheritance type</h4>
+ <h4 id="_superclass_inheritance_type">30.9.2. Superclass inheritance type</h4>
<div class="paragraph">
<p>There is one case (at least) it may be necessary to annotate the property with both <code>@Column#allowsNull</code> and also <code>@Property#optionality()</code>. If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using <code>javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE</code>), then JDO requires that the property is annotated as <code>@Column#allowsNull="true"</code>: its value will be not defined for other subclasses.</p>
</div>
@@ -12055,7 +12617,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="_non_persistent_properties_2">30.8.3. Non-persistent properties</h4>
+ <h4 id="_non_persistent_properties_2">30.9.3. Non-persistent properties</h4>
<div class="paragraph">
<p>Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the <code>optionality()</code> attribute is still required.</p>
</div>
@@ -12133,7 +12695,7 @@ container.persist(cust);</code></pre>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content">
<div class="paragraph">
- <p>It is also possible to specify optionality using <a href="../rgant/rgant.html#_rgant_Nullable"><code>@Nullable</code></a> annotation.</p>
+ <p>It is also possible to specify optionality using <a href="../rgant/rgant.html#_rgant-Nullable"><code>@Nullable</code></a> annotation.</p>
</div> </td>
</tr>
</tbody>
@@ -12142,7 +12704,7 @@ container.persist(cust);</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgant-Property_regexPattern">30.9. <code>regexPattern()</code></h3>
+ <h3 id="_rgant-Property_regexPattern">30.10. <code>regexPattern()</code></h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
<button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Property_regexPattern.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
<button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
@@ -12989,7 +13551,7 @@ container.persist(cust);</code></pre>
<td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
<td class="content">
<div class="paragraph">
- <p>Design note: we considered implementing this an "immutable" flag on the <a href="#_rgant_Property"><code>@Property</code></a> annotation (because this flag is typically appropriate for immutable/unchanging properties of a domain object). However, we decided not to do that, on the basis that it might be interpreted as having a deeper impact within the framework than simply a hint for rendering.</p>
+ <p>Design note: we considered implementing this an "immutable" flag on the <a href="#_rgant-Property"><code>@Property</code></a> annotation (because this flag is typically appropriate for immutable/unchanging properties of a domain object). However, we decided not to do that, on the basis that it might be interpreted as having a deeper impact within the framework than simply a hint for rendering.</p>
</div> </td>
</tr>
</tbody>
@@ -13268,7 +13830,7 @@ serviceRegistry.injectServicesInto(vm);</code></pre>
<p>The <code>@ViewModel</code> does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the <a href="../rgcfg/rgcfg.html#__rgcfg_configuring-core_metamodel-validation"><code>explicitObjectType</code></a> configuration property.</p>
</div>
<div class="paragraph">
- <p>Instead, use <a href="../rgant/rgant.html#_rgant_DomainObject_nature"><code>@DomainObject#nature()</code></a> with <code>Nature.VIEW_MODEL</code>, and specify <a href="../rgant/rgant.html#_rgant_DomainObject_objectType"><code>@DomainObject#objectType()</code></a>.</p>
+ <p>Instead, use <a href="../rgant/rgant.html#_rgant-DomainObject_nature"><code>@DomainObject#nature()</code></a> with <code>Nature.VIEW_MODEL</code>, and specify <a href="../rgant/rgant.html#_rgant-DomainObject_objectType"><code>@DomainObject#objectType()</code></a>.</p>
</div> </td>
</tr>
</tbody>