http://git-wip-us.apache.org/repos/asf/isis-site/blob/97af7e5f/content/guides/rgant/rgant.html ---------------------------------------------------------------------- diff --git a/content/guides/rgant/rgant.html b/content/guides/rgant/rgant.html index 939bfcb..023b7d7 100644 --- a/content/guides/rgant/rgant.html +++ b/content/guides/rgant/rgant.html @@ -243,6 +243,7 @@ table.CodeRay td.code>pre{padding:0} </div> </form> </div> + <p class="nav navbar-text navbar-right small">v1.16.1</p> </div> </div> </nav> @@ -2084,6 +2085,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 +2135,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 +2170,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 +2196,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,77 +2282,44 @@ 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_command.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <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_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-Action_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-Action_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-Action_command.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + <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>@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> - </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 action invocation 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 action, the parameter arguments, 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> + <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>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> + <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="paragraph"> - <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 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>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> - </div> - <div class="ulist"> - <ul> - <li> <p><code>all</code><br></p> - <div class="paragraph"> - <p>all actions 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> - </div> </li> - <li> <p><code>none</code><br></p> - <div class="paragraph"> - <p>no actions are reified.</p> - </div> </li> - </ul> + <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>If there is no configuration property in <code>isis.properties</code> then all actions are reified into <code>Command</code>s.</p> + <p>In the user interface associated actions are rendered close to the member to which they relate.</p> </div> <div class="admonitionblock note"> <table> @@ -2324,417 +2328,1444 @@ table.CodeRay td.code>pre{padding:0} <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> + <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="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> - </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">@Action</span>(command=CommandReification.ENABLED) - <span class="directive">public</span> Invoice generateInvoice(...) { ... } -}</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">3.1.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> - </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">@Action</span>( - command=CommandReification.ENABLED, - commandPersistence=CommandPersistence.IF_HINTED - ) - <span class="directive">public</span> Invoice generateInvoice(...) { ... } -}</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 action by way of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_BackgroundService"><code>BackgroundService</code></a>.</p> - </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">@Action</span>( - command=CommandReification.ENABLED, - commandExecuteIn=CommandExecuteIn.FOREGROUND, - commandPersistence=CommandPersistence.NOT_PERSISTED - ) - <span class="directive">public</span> Invoice generateInvoice(...) { ... } -}</code></pre> - </div> - </div> + <h4 id="_inferred_defaults_and_choices">3.1.1. Inferred Defaults and Choices</h4> <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> + <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> - <div class="sect3"> - <h4 id="__code_commandexecutein_code">3.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> + <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>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> + <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:</p> + <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">@Action</span>( - command=CommandReification.ENABLED, - commandExecuteIn=CommandExecuteIn.BACKGROUND) - <span class="directive">public</span> Invoice generateInvoice(...) { ... } + + <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>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>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_domainEvent">3.2. domainEvent()</h3> + <h3 id="_rgant-Action_command">3.2. Command Persistence and Processing</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" 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> <ul class="dropdown-menu"> - <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_domainEvent.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_domainEvent.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_domainEvent.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_domainEvent.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Action_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-Action_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-Action_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-Action_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>Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain objectâs actions, the events that are fired are:</p> - </div> - <div class="ulist"> - <ul> - <li> <p>hide phase: to check that the action is visible (has not been hidden)</p> </li> - <li> <p>disable phase: to check that the action is usable (has not been disabled)</p> </li> - <li> <p>validate phase: to check that the actionâs arguments are valid</p> </li> - <li> <p>pre-execute phase: before the invocation of the action</p> </li> - <li> <p>post-execute: after the invocation of the action</p> </li> - </ul> - </div> - <div class="paragraph"> - <p>Subscribers subscribe through the <a href="../rgsvc/rgsvc.html#_rgsvc_core-domain-api_EventBusService"><code>EventBusService</code></a> using either <a href="https://github.com/google/guava";>Guava</a> or <a href="http://www.axonframework.org/";>Axon Framework</a> annotations and can influence each of these phases.</p> - </div> - <div class="paragraph"> - <p>By default the event raised is <code>ActionDomainEvent.Default</code>. 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">ToDoItem</span> { - <span class="annotation">@Action</span>() - <span class="directive">public</span> ToDoItem completed() { ... } - ... -}</code></pre> - </div> - </div> - <div class="paragraph"> - <p>The <code>domainEvent()</code> attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those subclasses) to be defined instead. This attribute is also supported for <a href="../rgant/rgant.html#_rgant-Collection_domainEvent">collections</a> and <a href="../rgant/rgant.html#_rgant-Property_domainEvent">properties</a>.</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">ToDoItem</span> { - <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">CompletedEvent</span> <span class="directive">extends</span> ActionDomainEvent<ToDoItem> { } <i class="conum" data-value="1"></i><b>(1)</b> - <span class="annotation">@Action</span>(domainEvent=CompletedEvent.class) - <span class="directive">public</span> ToDoItem completed() { ... } -}</code></pre> - </div> + <p>Every action invocation (and property edit for that matter) is automatically reified into a concrete <code>Command</code> object. The <code>@Action(command=â¦â, commandXxx=â¦â)</code> attributes provide hints for the persistence of that <code>Command</code> object, and the subsequent processing of that persisted command. The primary use cases 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 benefit is that subscribers can be more targeted as to the events that they subscribe to.</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 framework provides no-arg constructor and will initialize the domain event using (non-API) setters rather than through the constructor. This substantially reduces the boilerplate required in subclasses because no explicit constructor is required.</p> - </div> </td> - </tr> - </tbody> - </table> + <p>Note that for a <code>Command</code> to actually be persisted requires an appropriate implementation of <code>CommandService</code> SPI. The framework does <em>not</em> provide an implementation of this SPI "out-of-the-box". However, the (non-ASF) Incode Platformâs <a href="http://platform.incode.org/modules/spi/command/spi-command.html";> command module</a>) <em>does</em> provide such an implementation.</p> </div> <div class="sect3"> - <h4 id="_subscribers">3.2.1. Subscribers</h4> + <h4 id="_design">3.2.1. Design</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> + <p>The annotation works with (and is influenced by the behaviour of) a number of domain services:</p> </div> - <div class="paragraph"> - <p>Subscribers can be either coarse-grained (if they subscribe to the top-level event type):</p> + <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="listingblock"> - <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN) -<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber { - <span class="annotation">@com</span>.google.common.eventbus.Subscribe - <span class="directive">public</span> <span class="type">void</span> on(ActionDomainEvent ev) { - ... - } -}</code></pre> - </div> + <div class="paragraph"> + <p>Each action invocation is automatically 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 action, the parameter arguments, the user, a timestamp and so on.</p> </div> <div class="paragraph"> - <p>or can be fine-grained (by subscribing to specific event subtypes):</p> + <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="listingblock"> - <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN) -<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber { - <span class="annotation">@com</span>.google.common.eventbus.Subscribe - <span class="directive">public</span> <span class="type">void</span> on(ToDoItem.CompletedEvent ev) { - ... - } -}</code></pre> - </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 tip"> + <div class="admonitionblock note"> <table> <tbody> <tr> - <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> + <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> <td class="content"> <div class="paragraph"> - <p>If the AxonFramework is being used, replace <code>@com.google.common.eventbus.Subscribe</code> with <code>@org.axonframework.eventhandling.annotation.EventHandler</code>.</p> + <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 subscriberâs method is called (up to) 5 times:</p> - </div> - <div class="ulist"> - <ul> - <li> <p>whether to veto visibility (hide)</p> </li> - <li> <p>whether to veto usability (disable)</p> </li> - <li> <p>whether to veto execution (validate)</p> </li> - <li> <p>steps to perform prior to the action being invoked.</p> </li> - <li> <p>steps to perform after the action has been invoked.</p> </li> - </ul> - </div> - <div class="paragraph"> - <p>The subscriber can distinguish these by calling <code>ev.getEventPhase()</code>. Thus the general form is:</p> - </div> - <div class="listingblock"> - <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Programmatic</span> -<span class="annotation">@com</span>.google.common.eventbus.Subscribe -<span class="directive">public</span> <span class="type">void</span> on(ActionDomainEvent ev) { - <span class="keyword">switch</span>(ev.getEventPhase()) { - <span class="keyword">case</span> HIDE: - <span class="comment">// call ev.hide() or ev.veto("") to hide the action</span> - <span class="keyword">break</span>; - <span class="keyword">case</span> DISABLE: - <span class="comment">// call ev.disable("...") or ev.veto("...") to disable the action</span> - <span class="keyword">break</span>; - <span class="keyword">case</span> VALIDATE: - <span class="comment">// call ev.invalidate("...") or ev.veto("...")</span> - <span class="comment">// if action arguments are invalid</span> - <span class="keyword">break</span>; - <span class="keyword">case</span> EXECUTING: - <span class="keyword">break</span>; - <span class="keyword">case</span> EXECUTED: - <span class="keyword">break</span>; - } + </div> + <div class="sect3"> + <h4 id="_rgant-Action_commandPersistence">3.2.2. <code>command()</code> and <code>commandPersistence()</code></h4> + <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_commandPersistence.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_commandPersistence.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_commandPersistence.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_commandPersistence.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_commandPersistence.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>command()</code> and `commandPersistence() attributes work together to determine whether a command will actually be persisted. There inter-relationship is somewhat complex, so is probably best explained by way of examples:</p> + </div> + <table class="tableblock frame-all grid-all spread"> + <colgroup> + <col style="width: 14.2857%;"> + <col style="width: 14.2857%;"> + <col style="width: 14.2857%;"> + <col style="width: 14.2857%;"> + <col style="width: 14.2857%;"> + <col style="width: 28.5715%;"> + </colgroup> + <thead> + <tr> + <th class="tableblock halign-left valign-top"><code>command()</code></th> + <th class="tableblock halign-left valign-top"><code>isis.services. command.actions</code> config property</th> + <th class="tableblock halign-left valign-top">actionâs declared <code>semantics()</code></th> + <th class="tableblock halign-left valign-top"><code>command Persistence()</code></th> + <th class="tableblock halign-left valign-top">action dirties objects?</th> + <th class="tableblock halign-left valign-top">is command persisted?</th> + </tr> + </thead> + <tbody> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ENABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(either)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ENABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ENABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ENABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>all</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>all</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>all</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>all</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>SAFE</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no (!)</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>SAFE</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code> or <code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>SAFE</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code> or <code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>SAFE</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes (!)</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IDEMPOTENT</code> or <code>NON_IDEMPOTENT</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IDEMPOTENT</code> or <code>NON_IDEMPOTENT</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IDEMPOTENT</code> or <code>NON_IDEMPOTENT</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>ignoreSafe</code> or <code>ignoreQueryOnly</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IDEMPOTENT</code> or <code>NON_IDEMPOTENT</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no (!)</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>AS_CONFIGURED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>none</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes (!)</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no (!)</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>IF_HINTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>no</p> + </div> + </div></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>DISABLED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>(any)</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p><code>NOT_PERSISTED</code></p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes</p> + </div> + </div></td> + <td class="tableblock halign-left valign-top"> + <div> + <div class="paragraph"> + <p>yes (!)</p> + </div> + </div></td> + </tr> + </tbody> + </table> + <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">@Action</span>( + command=CommandReification.ENABLED, + commandPersistence=CommandPersistence.PERSISTED + ) + <span class="directive">public</span> Invoice generateInvoice(...) { ... } }</code></pre> </div> </div> <div class="paragraph"> - <p>It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of <code>RecoverableException</code> then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.</p> + <p>As can be seen, whether a command is actually persisted does not always follow the value of the <code>commandPersistence()</code> attribute. This is because the <code>command()</code> attribute actually determines whether any command metadata for the action is captured within the frameworkâs internal metamodel. If <code>command</code> is <code>DISABLED</code> or does not otherwise apply due to the actionâs declared semantics, then the framework decides to persist a command based solely on whether the action dirtied any objects (as if <code>commandPersistence()</code> was set to <code>IF_HINTED</code>).</p> </div> </div> <div class="sect3"> - <h4 id="_default_doop_and_noop_events">3.2.2. Default, Doop and Noop events</h4> + <h4 id="__code_commandexecutein_code">3.2.3. <code>commandExecuteIn()</code></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> - <div class="paragraph"> - <p>If this is not required, then the <code>isis.reflector.facet.actionAnnotation.domainEvent.postForDefault</code> configuration property can be set to "false"; this will disable posting.</p> + <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>On the other hand, if the <code>domainEvent</code> has been explicitly specified to some subclass, then an event will be posted. The framework provides <code>ActionDomainEvent.Doop</code> as such a subclass, so setting the <code>domainEvent</code> attribute to this class will ensure that the event to be posted, irrespective of the configuration property setting.</p> + <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>And, conversely, the framework also provides <code>ActionDomainEvent.Noop</code>; if <code>domainEvent</code> attribute is set to this class, then no event will be posted.</p> + <p>For example:</p> </div> - </div> - <div class="sect3"> - <h4 id="_raising_events_programmatically">3.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 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 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">@Action</span>( + command=CommandReification.ENABLED, + 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 invocation is the persisted <code>Command</code> itself.</p> + </div> + </div> + <div class="sect3"> + <h4 id="__code_commanddtoprocessor_code">3.2.4. <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>) { +
<TRUNCATED>
