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 2019/01/06 17:22:58 UTC
[31/51] [partial] isis-site git commit: ISIS-1899: updates site for
1.17.0
http://git-wip-us.apache.org/repos/asf/isis-site/blob/1685fcc5/content/guides/rgsvc/rgsvc.html
----------------------------------------------------------------------
diff --git a/content/guides/rgsvc/rgsvc.html b/content/guides/rgsvc/rgsvc.html
index cd7cf80..c1c4e33 100644
--- a/content/guides/rgsvc/rgsvc.html
+++ b/content/guides/rgsvc/rgsvc.html
@@ -244,7 +244,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</form>
</div>
- <p class="nav navbar-text navbar-right small">v1.16.2</p>
+ <p class="nav navbar-text navbar-right small">v1.17.0</p>
</div>
</div>
</nav>
@@ -569,7 +569,7 @@ table.CodeRay td.code>pre{padding:0}
<p>Likewise, the <code>PublishedObjects</code> class passed to the <code>PublisherService</code> at the end of the interaction provides the <code>PublishedObjects#getDto()</code> method which returns a <code>ChangesDto</code> instance. This can be converted into XML using the <code>ChangesDtoUtils</code> utility class.</p>
</div>
<div class="paragraph">
- <p>One final point: multiple <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a> implementations are supported because different implementations may have different responsibilities. For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module is responsible for publishing messages onto an ActiveMQ event bus, for inter-system communication. However, the SPI can also be used for profiling; each execution within the call-graph contains metrics of the number of objects loaded or modified as a result of that execution, and thus could be used for application profiling. The framework provides a default <code>PublisherServiceLogging</code> implementation that logs this using SLF4J.</p>
+ <p>One final point: multiple <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublisherService"><code>PublisherService</code></a> implementations are supported because different implementations may have different responsibilities. For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s publishmq module is responsible for publishing messages onto an ActiveMQ event bus, for inter-system communication. However, the SPI can also be used for profiling; each execution within the call-graph contains metrics of the number of objects loaded or modified as a result of that execution, and thus could be used for application profiling. The framework provides a default <code>PublisherServiceLogging</code> implementation that logs this using SLF4J.</p>
</div>
</div>
</div>
@@ -969,7 +969,7 @@ table.CodeRay td.code>pre{padding:0}
<p>Domain service SPIs for the presentation layer influence how the Apache Isis viewers behave.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the presentation layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the presentation layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -1243,7 +1243,7 @@ table.CodeRay td.code>pre{padding:0}
<p>The framework provides two implementations of this service, both in support of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> SPI.</p>
</div>
<div class="paragraph">
- <p>By way of background: implementations of the SPI <code>CommandService</code> work with custom implementations of the <code>Command</code> interface, typically being persisted to a datastore. The <code>CommandWithDto</code> interface is a subtype of <code>Command</code> for implementations that can be reified into <a href="../rgcms/rgcms.html#_rgcms_schema-cmd"><code>CommandDto</code></a> XML instances. One implementation that does this is the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module.</p>
+ <p>By way of background: implementations of the SPI <code>CommandService</code> work with custom implementations of the <code>Command</code> interface, typically being persisted to a datastore. The <code>CommandWithDto</code> interface is a subtype of <code>Command</code> for implementations that can be reified into <a href="../rgcms/rgcms.html#_rgcms_schema-cmd"><code>CommandDto</code></a> XML instances. One implementation that does this is the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module.</p>
</div>
<div class="paragraph">
<p>For framework implementations of <code>ContentMappingService</code> allow domain service actions that return <code>CommandDto</code>s (either singularly or in a list) to be converted into XML documents:</p>
@@ -2455,7 +2455,7 @@ table.CodeRay td.code>pre{padding:0}
<p>The framework provides an implementation, <code>SessionLoggingService.Stderr</code> that just prints out to standard error. This is not registered by default, but can be easily registered manually using <code>AppManifestAbstract.Builder#withAdditionalServices(…)</code>.</p>
</div>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s sessionlogger module provides an implementation that logs each session as a JDO entity.</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s sessionlogger module provides an implementation that logs each session as a JDO entity.</p>
</div>
</div>
</div>
@@ -2902,7 +2902,7 @@ table.CodeRay td.code>pre{padding:0}
<p>Domain service APIs for the application layer allow the domain objects to control aspects of the application layer, such as sending info messages back to the end-user.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the application layer APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the application layer APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -2954,7 +2954,7 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CommandContext</code><br> <code>o.a.i.core</code><br> <code>isis-core-applib</code></p></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">API is also a concrete class.<br> depends on:<br> <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> for persistent <code>Command</code>, else in-memory impl. used. </p><p class="tableblock">The <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> manages the actual execution of the command.</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">API is also a concrete class.<br> depends on:<br> <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> for persistent <code>Command</code>, else in-memory impl. used.</p> <p class="tableblock">The <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> manages the actual execution of the command.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandExecutorService"><code>o.a.i.applib.</code><br> <code>services.command</code><br> <code>CommandExecutorService</code></a></p></td>
@@ -3317,7 +3317,7 @@ table.CodeRay td.code>pre{padding:0}
<p>One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the <code>submitInvoice()</code> method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.</p>
</div>
<div class="paragraph">
- <p>However, an alternative is to rely on the fact that the <code>BackgroundService</code> will automatically hint that the <code>Command</code> representing the original interaction (to <code>submitCustomerInvoices()</code> in the example above) should be persisted. This will be available if the related <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> and <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> domain services are configured, and the <code>CommandService</code> supports persistent commands. Note that (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module does indeed provide such an implementation of <code>CommandService</code> (as well as of the required <code>BackgroundCommandService</code>).</p>
+ <p>However, an alternative is to rely on the fact that the <code>BackgroundService</code> will automatically hint that the <code>Command</code> representing the original interaction (to <code>submitCustomerInvoices()</code> in the example above) should be persisted. This will be available if the related <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> and <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> domain services are configured, and the <code>CommandService</code> supports persistent commands. Note that (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module does indeed provide such an implementation of <code>CommandService</code> (as well as of the required <code>BackgroundCommandService</code>).</p>
</div>
<div class="paragraph">
<p>Thus, the original action can run a query to obtain it corresponding <code>Command</code>, and return this to the user. The upshot is that the child <code>Command</code>s created by the <code>BackgroundService</code> will then be associated with <code>Command</code> for the original action.</p>
@@ -3360,7 +3360,7 @@ CommandContext commandContext; <i class="conum" data-value="1"></i><b>(1)</b></
<p>The <code>CommandContext</code> service is responsible for providing a parent <code>Command</code> with which the background <code>Command</code>s can then be associated as children, while the <code>CommandService</code> is responsible for persisting those parent <code>Command`s. The latter is analogous to the way in which the `BackgroundCommandService</code> persists the child background `Command`s.</p>
</div>
<div class="paragraph">
- <p>The implementations of <code>CommandService</code> and <code>BackgroundCommandService</code> go together; typically both parent <code>Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module provides implementations of both (see <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService">`CommandService</a></code> and <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>).</p>
+ <p>The implementations of <code>CommandService</code> and <code>BackgroundCommandService</code> go together; typically both parent <code>Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module provides implementations of both (see <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService">`CommandService</a></code> and <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>).</p>
</div>
<div class="paragraph">
<p>The <a href="../rgfis/rgfis.html#_rgfis_application-layer_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a> is used to obtain a memento of the command such that it can be persisted. (In earlier versions, <a href="../rgsvc/rgsvc.html#_rgsvc_integration-api_MementoService"><code>MementoService</code></a> was used for this purpose).</p>
@@ -3411,7 +3411,7 @@ CommandContext commandContext; <i class="conum" data-value="1"></i><b>(1)</b></
<p>The last part of the puzzle is to actually run the (appropriate implementation of) <code>BackgroundCommandExecution</code>). This could be run in a batch job overnight, or run continually by, say, the <a href="http://quartz-scheduler.org">Quartz</a> scheduler or by <a href="http://camel.apache.org">Apache Camel</a>. This section looks at configuring Quartz.</p>
</div>
<div class="paragraph">
- <p>If using (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module, then note that this already provides a suitable concrete implementation, namely <code>org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo</code>. We therefore just need to schedule this to run as a Quartz job.</p>
+ <p>If using (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module, then note that this already provides a suitable concrete implementation, namely <code>org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo</code>. We therefore just need to schedule this to run as a Quartz job.</p>
</div>
<div class="paragraph">
<p>First, we need to define a Quartz job, for example:</p>
@@ -3578,7 +3578,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>The <code>CommandContext</code> service is a <a href="../rgant/rgant.html#_rgant-RequestScoped">request-scoped</a> service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the <code>Command</code> object.</p>
</div>
<div class="paragraph">
- <p>By default, the <code>Command</code> is held in-memory only; once the action invocation has completed, the <code>Command</code> object is gone. The optional supporting <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> enables the implementation of <code>Command</code> to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module’s <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a>) the <code>Command</code> may then be persisted.</p>
+ <p>By default, the <code>Command</code> is held in-memory only; once the action invocation has completed, the <code>Command</code> object is gone. The optional supporting <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> enables the implementation of <code>Command</code> to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module’s <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a>) the <code>Command</code> may then be persisted.</p>
</div>
<div class="paragraph">
<p>The primary use case for persistent <code>Command</code>s is in support of background commands; they act as a parent to any background commands that can be persisted either explicitly using the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_BackgroundService"><code>BackgroundService</code></a>, or implicitly by way of the <a href="../rgant/rgant.html#_rgant-Action_command"><code>@Action#command()</code></a> annotation.</p>
@@ -3594,7 +3594,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</ul>
</div>
<div class="paragraph">
- <p>However, while persistent <code>Command</code>s <em>can</em> be used for these use cases, it is recommended instead to use the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> service and persistent implementations of the <code>Interaction</code> object, eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module.</p>
+ <p>However, while persistent <code>Command</code>s <em>can</em> be used for these use cases, it is recommended instead to use the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> service and persistent implementations of the <code>Interaction</code> object, eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s publishmq module.</p>
</div>
</div>
<div class="sect3">
@@ -3799,7 +3799,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).</p>
</div>
<div class="paragraph">
- <p>This requires that an implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> that persists the commands (such as the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module’s <code>CommandService</code>) is configured. It also requires that a scheduler is configured to execute the background commands, see <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>).</p>
+ <p>This requires that an implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> that persists the commands (such as the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module’s <code>CommandService</code>) is configured. It also requires that a scheduler is configured to execute the background commands, see <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>).</p>
</div>
</div>
<div class="sect3">
@@ -3931,7 +3931,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>If a bulk action is performed (as per an action annotated using <a href="../rgant/rgant.html#_rgant-Action_invokeOn"><code>@Action#invokeOn()</code></a>), then this will result in multiple <code>Interaction</code>s, one per selected object (not one <code>Interaction</code> with multiple top-level <code>Execution</code>s).</p>
</div>
<div class="paragraph">
- <p>It is possible for <code>Interaction.Execution</code>s to be persisted; this is supported by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module, for example. Persistent <code>Interaction</code>s support several use cases:</p>
+ <p>It is possible for <code>Interaction.Execution</code>s to be persisted; this is supported by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s publishmq module, for example. Persistent <code>Interaction</code>s support several use cases:</p>
</div>
<div class="ulist">
<ul>
@@ -3955,7 +3955,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>The <code>Execution</code> class itself is abstract; there are two subclasses, <code>ActionInvocation</code> and <code>PropertyEdit</code>.</p>
</div>
<div class="sect4">
- <h5 id="__code_interactioncontext_code"><code>InteractionContext</code></h5>
+ <h5 id="_code_interactioncontext_code"><code>InteractionContext</code></h5>
<div class="paragraph">
<p>The public API of the <code>InteractionContext</code> domain service itself consists of simply:</p>
</div>
@@ -3982,7 +3982,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="__code_interaction_code"><code>Interaction</code></h5>
+ <h5 id="_code_interaction_code"><code>Interaction</code></h5>
<div class="paragraph">
<p>The public API of the <code>Interaction</code> class consists of:</p>
</div>
@@ -4028,7 +4028,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="__code_interaction_execution_code"><code>Interaction.Execution</code></h5>
+ <h5 id="_code_interaction_execution_code"><code>Interaction.Execution</code></h5>
<div class="paragraph">
<p>The <code>Interaction.Execution</code> (static nested) class represents an action invocation/property edit as a node in a call-stack execution graph. Sub-executions can be performed using the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_WrapperFactory"><code>WrapperFactory</code></a>.</p>
</div>
@@ -4681,24 +4681,31 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<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">WrapperFactory</span> {
+
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">enum</span> ExecutionMode { <i class="conum" data-value="1"></i><b>(1)</b>
+ EXECUTE,
+ SKIP_RULES,
+ NO_EXECUTE,
+ TRY,
+ }
+
<span class="annotation">@Programmatic</span>
- <T> T wrap(T domainObject); <i class="conum" data-value="1"></i><b>(1)</b>
+ <T> T wrap(T domainObject, ExecutionMode mode); <i class="conum" data-value="2"></i><b>(2)</b>
+
<span class="annotation">@Programmatic</span>
- <T> T unwrap(T possibleWrappedDomainObject); <i class="conum" data-value="2"></i><b>(2)</b>
+ <T> T wrap(T domainObject); <i class="conum" data-value="3"></i><b>(3)</b>
<span class="annotation">@Programmatic</span>
- <T> <span class="type">boolean</span> isWrapper(T possibleWrappedDomainObject); <i class="conum" data-value="3"></i><b>(3)</b>
-
- <span class="directive">public</span> <span class="directive">static</span> <span class="type">enum</span> ExecutionMode { <i class="conum" data-value="4"></i><b>(4)</b>
- EXECUTE(<span class="predefined-constant">true</span>,<span class="predefined-constant">true</span>),
- SKIP_RULES(<span class="predefined-constant">false</span>, <span class="predefined-constant">true</span>), <i class="conum" data-value="5"></i><b>(5)</b>
- NO_EXECUTE(<span class="predefined-constant">true</span>, <span class="predefined-constant">false</span>); <i class="conum" data-value="6"></i><b>(6)</b>
- }
+ <T> T wrapSkipRules(T domainObject); <i class="conum" data-value="4"></i><b>(4)</b>
<span class="annotation">@Programmatic</span>
- <T> T wrap(T domainObject, ExecutionMode mode); <i class="conum" data-value="7"></i><b>(7)</b>
+ <T> T wrapNoExecute(T domainObject); <i class="conum" data-value="5"></i><b>(5)</b>
<span class="annotation">@Programmatic</span>
- <T> T wrapNoExecute(T domainObject); <i class="conum" data-value="8"></i><b>(8)</b>
+ <T> T wrapTry(T domainObject); <i class="conum" data-value="6"></i><b>(6)</b>
<span class="annotation">@Programmatic</span>
- <T> T wrapSkipRules(T domainObject); <i class="conum" data-value="9"></i><b>(9)</b>
+
+ <span class="annotation">@Programmatic</span>
+ <T> T unwrap(T possibleWrappedDomainObject); <i class="conum" data-value="7"></i><b>(7)</b>
+ <span class="annotation">@Programmatic</span>
+ <T> <span class="type">boolean</span> isWrapper(T possibleWrappedDomainObject); <i class="conum" data-value="8"></i><b>(8)</b>
...
}</code></pre>
</div>
@@ -4708,45 +4715,62 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<tbody>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
- <td>wraps the underlying domain object. If it is already wrapped, returns the object back unchanged.</td>
+ <td>enumerates how the wrapper returned by <code>wrap(…)</code> interacts with the underlying domain object.</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
- <td>Obtains the underlying domain object, if wrapped. If the object is not wrapped, returns back unchanged.</td>
+ <td>wraps the underlying domain object with a wrapper as specified by the execution mode.
+ <div class="paragraph">
+ <p>If the domain object is already wrapped, then wrapping it again does nothing; the wrapper is returned unchanged.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
- <td>whether the supplied object has been wrapped.</td>
+ <td>wraps the underlying domain object with a wrapper that will validate all business rules and then execute if they pass.
+ <div class="paragraph">
+ <p>This is the same as invoke <code>wrap(…)</code> with <code>ExecuteMode#EXECUTE</code>.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
- <td>enumerates how the wrapper interacts with the underlying domain object.</td>
+ <td>wraps the underlying domain object with a wrapper that will validate all business rules but will not actually perform the interaction.
+ <div class="paragraph">
+ <p>This is the same as invoke <code>wrap(…)</code> with <code>ExecuteMode#NO_EXECUTE</code>.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="5"></i><b>5</b></td>
- <td>validate all business rules and then execute.</td>
+ <td>wraps the underlying domain object with a wrapper that will NOT check any business rules and instead will just perform the interaction.
+ <div class="paragraph">
+ <p>This is the same as invoke <code>wrap(…)</code> with <code>ExecuteMode#SKIP_RULES</code>.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="6"></i><b>6</b></td>
- <td>skip all business rules and then execute (including creating <a href="../rgant/rgant.html#_rgant-Action_command">command</a>s and firing pre- and post-execute <a href="../rgant/rgant.html#_rgant-Action_domainEvent">domain event</a>s).</td>
+ <td>wraps the underlying domain object with a wrapper that will validate the business rules, and just return <code>null</code> if any fail. If all business rules pass, then will just perform the interaction.
+ <div class="paragraph">
+ <p>This is the same as invoke <code>wrap(…)</code> with <code>ExecuteMode#TRY</code>.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="7"></i><b>7</b></td>
- <td>validate all business rules (including those from <a href="../rgant/rgant.html#_rgant-Action_domainEvent">domain event</a>s) but do not execute.</td>
+ <td>Obtains the underlying domain object, if wrapped.
+ <div class="paragraph">
+ <p>If the object is not wrapped, returns back unchanged.</p>
+ </div></td>
</tr>
<tr>
<td><i class="conum" data-value="8"></i><b>8</b></td>
- <td>convenience method to invoke <code>wrap(…)</code> with <code>ExecuteMode#NO_EXECUTE</code> (make this feature more discoverable)</td>
- </tr>
- <tr>
- <td><i class="conum" data-value="9"></i><b>9</b></td>
- <td>convenience method to invoke <code>wrap(…)</code> with <code>ExecuteMode#SKIP_RULES</code> (make this feature more discoverable)</td>
+ <td>whether the supplied object has been wrapped.</td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph">
- <p>The service works by returning a "wrapper" around a supplied domain object (a <a href="http://www.javassist.org">javassist</a> proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Apache Isis programming model are enforced. The wrapper can be interacted with as follows:</p>
+ <p>If the interface is performed (action invoked or property set), then - irrespective of whether the business rules were checked or skipped - a <a href="../rgant/rgant.html#_rgant-Action_command">command</a>s will be created and pre- and post-execute <a href="../rgant/rgant.html#_rgant-Action_domainEvent">domain event</a>s) will be fired</p>
+ </div>
+ <div class="paragraph">
+ <p>The service works by returning a "wrapper" around a supplied domain object (using a byte manipulation library such as <a href="http://www.javassist.org">javassist</a> or <a href="https://bytebuddy.net/">byte buddy</a>), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Apache Isis programming model are enforced. The wrapper can be interacted with as follows:</p>
</div>
<div class="ulist">
<ul>
@@ -4898,7 +4922,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>Domain service SPIs influence how the framework handles application layer concerns, for example which home page to render to the end-user.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the application layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the application layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -4942,6 +4966,17 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<td class="tableblock halign-left valign-top"><p class="tableblock">related services:<br> <code>CommandService-</code> `JdoContributions`, `CommandService-` <code>JdoRepository</code></p></td>
</tr>
<tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_HealthCheckService"><code>o.a.i.applib.</code><br> <code>services.health</code><br> <code>HealthCheckService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Performs a health check so that the runtime infrastructure can determine if the application is still healthy (and perform remedial action, such as restarting the app, if not).</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">No default implementation.</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Exposed via REST API, typically on <code>/restful/health</code>.</p></td>
+ </tr>
+ <tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_HomePageProviderService"><code>o.a.i.applib.</code><br> <code>services.homepage</code><br> <code>HomePageProviderService</code></a></p></td>
<td class="tableblock halign-left valign-top">
<div>
@@ -5048,7 +5083,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="__internal_spi">6.1.2. "Internal" SPI</h4>
+ <h4 id="_internal_spi">6.1.2. "Internal" SPI</h4>
<div class="paragraph">
<p>The <code>BackgroundCommandExecution</code> (in isis-core) is an abstract template class for <a href="../ugbtb/ugbtb.html#_ugbtb_headless-access_AbstractIsisSessionTemplate">headless access</a>, that defines an abstract hook method to obtain background `Command`s to be executed:</p>
</div>
@@ -5069,7 +5104,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<div class="sect3">
<h4 id="_implementation_19">6.1.3. Implementation</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module provides an implementation (<code>org.isisaddons.module.command.dom.BackgroundCommandServiceJdo</code>) that persists <code>Command</code>s using the JDO/DataNucleus object store. It further provides a number of supporting services:</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module provides an implementation (<code>org.isisaddons.module.command.dom.BackgroundCommandServiceJdo</code>) that persists <code>Command</code>s using the JDO/DataNucleus object store. It further provides a number of supporting services:</p>
</div>
<div class="ulist">
<ul>
@@ -5109,7 +5144,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<div class="sect3">
<h4 id="_alternative_implementations_2">6.1.5. Alternative Implementations</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module provides an implementation of this service (<code>BackgroundCommandService</code>), and also provides a number of related domain services (<code>BackgroundCommandServiceJdo</code>, <code>BackgroundCommandJdoRepository</code> and <code>BackgroundCommandServiceJdoContributions</code>). This module also provides service implementations of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a>.</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module provides an implementation of this service (<code>BackgroundCommandService</code>), and also provides a number of related domain services (<code>BackgroundCommandServiceJdo</code>, <code>BackgroundCommandJdoRepository</code> and <code>BackgroundCommandServiceJdoContributions</code>). This module also provides service implementations of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a>.</p>
</div>
<div class="paragraph">
<p>If contributions are not required in the UI, these can be suppressed either using security or by implementing a <a href="../ugbtb/ugbtb.html#_ugbtb_hints-and-tips_vetoing-visibility">vetoing subscriber</a>.</p>
@@ -5124,7 +5159,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>There is also a tie-up with the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_CommandContext"><code>CommandContext</code></a> and its supporting <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>CommandService</code></a> domain service. The <code>CommandContext</code> service is responsible for providing a parent <code>Command</code> with which the background <code>Command`s can then be associated as children, while the `CommandService</code> is responsible for persisting those parent <code>Command`s (analogous to the way in which the `BackgroundCommandService</code> persists the child background <code>Command`s). The `BackgroundCommandService</code> ensures that these background <code>Command`s are associated with the parent "foreground" `Command</code>.</p>
</div>
<div class="paragraph">
- <p>What that means is that the implementations of <code>CommandService</code> and <code>BackgroundCommandService</code> go together, hence both implemented in the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module.).</p>
+ <p>What that means is that the implementations of <code>CommandService</code> and <code>BackgroundCommandService</code> go together, hence both implemented in the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module.).</p>
</div>
</div>
</div>
@@ -5160,7 +5195,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</ul>
</div>
<div class="paragraph">
- <p>However, while persistent <code>Command</code>s <em>can</em> be used for these use cases, it is recommended instead to use the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> service and persistent implementations of the <code>Interaction</code> object, eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module.</p>
+ <p>However, while persistent <code>Command</code>s <em>can</em> be used for these use cases, it is recommended instead to use the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-api_InteractionContext"><code>InteractionContext</code></a> service and persistent implementations of the <code>Interaction</code> object, eg as provided by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s publishmq module.</p>
</div>
<div class="sect3">
<h4 id="_screencast">6.2.1. Screencast</h4>
@@ -5214,7 +5249,10 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
- <td>"Complete" the command, typically meaning that the command should be persisted it if its <code>Command#getPersistence()</code> flag and persistence hint (<code>Command#isPersistHint()</code>) indicate that it should be. <br></td>
+ <td>"Complete" the command, typically meaning that the command should be persisted it if its <code>Command#getPersistence()</code> flag and persistence hint (<code>Command#isPersistHint()</code>) indicate that it should be. <br>
+ <div class="paragraph">
+ <p>The framework will automatically have set the <code>completedAt</code> property of the <code>Command</code>.</p>
+ </div></td>
</tr>
</tbody>
</table>
@@ -5223,7 +5261,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<div class="sect3">
<h4 id="_implementation_20">6.2.3. Implementation</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module provides an implementation (<code>org.isisaddons.module.command.dom.CommandServiceJdo</code>) that persists <code>Command</code>s using the JDO/DataNucleus object store. It further provides a number of supporting services:</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module provides an implementation (<code>org.isisaddons.module.command.dom.CommandServiceJdo</code>) that persists <code>Command</code>s using the JDO/DataNucleus object store. It further provides a number of supporting services:</p>
</div>
<div class="ulist">
<ul>
@@ -5241,7 +5279,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<div class="sect3">
<h4 id="_alternative_implementations_3">6.2.5. Alternative Implementations</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module provides an implementation of this service (<code>CommandService</code>), and also provides a number of related domain services (<code>CommandJdoRepository</code> and <code>CommandServiceJdoContributions</code>). This module also provides service implementations of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>BackgroundCommandService</code></a>.</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module provides an implementation of this service (<code>CommandService</code>), and also provides a number of related domain services (<code>CommandJdoRepository</code> and <code>CommandServiceJdoContributions</code>). This module also provides service implementations of the <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_CommandService"><code>BackgroundCommandService</code></a>.</p>
</div>
<div class="paragraph">
<p>If contributions are not required in the UI, these can be suppressed either using security or by implementing a <a href="../ugbtb/ugbtb.html#_ugbtb_hints-and-tips_vetoing-visibility">vetoing subscriber</a>.</p>
@@ -5291,8 +5329,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</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">interface</span> <span class="class">HomePageProviderService</span> {
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">HomePageProviderService</span> {
<span class="annotation">@Programmatic</span>
<span class="predefined-type">Object</span> homePage();
}</code></pre>
@@ -5301,6 +5338,74 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<div class="paragraph">
<p>The default implementation is provided by <code>o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault</code>.</p>
</div>
+ <div class="paragraph">
+ <p>Any custom implementations should be annotated using <code>@DomainService(nature = NatureOfService.DOMAIN)</code>.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgsvc_application-layer-spi_HealthCheckService">6.4. <code>HealthCheckService</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/rgsvc/_rgsvc_application-layer-spi_HealthCheckService.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/rgsvc/_rgsvc_application-layer-spi_HealthCheckService.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/rgsvc/_rgsvc_application-layer-spi_HealthCheckService.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/rgsvc/_rgsvc_application-layer-spi_HealthCheckService.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/rgsvc/_rgsvc_application-layer-spi_HealthCheckService.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>This service, if implemented, is used to performs a health check to determine if the application is still available. The results of this service are made available through a REST resource, typically mounted at <code>/restful/health</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>The service, when called, will be within the context of a special internal user <code><em>health</em></code><em> with the internal role <code></code></em><code>health-role</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>This service was introduced to allow deployment infrastructure to monitor the app and (potentially) restart it if required. For example, if deploying to Docker then both Docker Swarm and Kubernetes are orchestrators that can perform this task.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_spi_implementation_2">6.4.1. SPI & Implementation</h4>
+ <div class="paragraph">
+ <p>The SPI defined by <code>HealthCheckService</code> is:</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">HealthCheckService</span> {
+ <span class="annotation">@Programmatic</span>
+ <span class="directive">public</span> Health check();
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>There is no default implementation. Any custom implementations should be annotated using <code>@DomainService(nature = NatureOfService.DOMAIN)</code>.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_rest_api_mapping">6.4.2. REST API Mapping</h4>
+ <div class="paragraph">
+ <p>The <code>/restful/health</code> path must be specified as a "passThru" so that no authentication challenge is issued.</p>
+ </div>
+ <div class="listingblock">
+ <div class="title">
+ web.xml
+ </div>
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><filter></span>
+ <span class="tag"><filter-name></span>IsisSessionFilterForRestfulObjects<span class="tag"></filter-name></span>
+ <span class="tag"><filter-class></span>org.apache.isis.core.webapp.IsisSessionFilter<span class="tag"></filter-class></span>
+ ...
+ <span class="tag"><init-param></span>
+ <span class="tag"><param-name></span>passThru<span class="tag"></param-name></span>
+ <span class="tag"><param-value></span>/restful/swagger,/restful/health<span class="tag"></param-value></span>
+ <span class="tag"></init-param></span>
+ ...
+<span class="tag"></filter></span></code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>This is a comma separated list, so there may be other values also (for example <code>/restful/swagger</code>, as shown above).</p>
+ </div>
</div>
</div>
</div>
@@ -5322,7 +5427,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>The core/domain APIs provide general-purpose services to the domain objects, for example obtaining the current time or user, or instantiating domain objects.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the core/domain APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the core/domain APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -6516,7 +6621,7 @@ container.persist(cust);</code></pre>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
- <td>It’s important that subscribers register before any domain services that might emit events on the event bus service. For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s security module provides a domain service that automatically seeds certain domain entities; these will generate <a href="../rgcms/rgcms.html#_rgcms_classes_lifecycleevent">lifecycle events</a> and so any subscribers must be registered before such seed services. The easiest way to do this is to use the <a href="../rgant/rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> attribute.</td>
+ <td>It’s important that subscribers register before any domain services that might emit events on the event bus service. For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s security module provides a domain service that automatically seeds certain domain entities; these will generate <a href="../rgcms/rgcms.html#_rgcms_classes_lifecycleevent">lifecycle events</a> and so any subscribers must be registered before such seed services. The easiest way to do this is to use the <a href="../rgant/rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> attribute.</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
@@ -7291,7 +7396,7 @@ Scratchpad scratchpad;</code></pre>
<p>The integration APIs provide functionality to the domain objects to integrate with other bounded contexts, for example sending an email or serializing an object out to XML.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the integration APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the integration APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -7424,7 +7529,7 @@ Scratchpad scratchpad;</code></pre>
</table>
</div>
<div class="paragraph">
- <p><code>Bookmark</code>s are used by several other domain services as a means of storing a reference to an arbitrary object (a polymorphic relationship). For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s auditing module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_AuditerService"><code>AuditerService</code></a> uses bookmarks to capture the object that is being audited.</p>
+ <p><code>Bookmark</code>s are used by several other domain services as a means of storing a reference to an arbitrary object (a polymorphic relationship). For example, the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s auditing module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_AuditerService"><code>AuditerService</code></a> uses bookmarks to capture the object that is being audited.</p>
</div>
<div class="admonitionblock tip">
<table>
@@ -7433,7 +7538,7 @@ Scratchpad scratchpad;</code></pre>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
- <p>One downside of using <code>Bookmark</code>s is that there is no way for the JDO/DataNucleus objectstore to enforce any kind of referental integrity. However, the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s poly module describes and supports a design pattern to address this requirement.</p>
+ <p>One downside of using <code>Bookmark</code>s is that there is no way for the JDO/DataNucleus objectstore to enforce any kind of referental integrity. However, the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s poly module describes and supports a design pattern to address this requirement.</p>
</div> </td>
</tr>
</tbody>
@@ -7481,7 +7586,7 @@ Scratchpad scratchpad;</code></pre>
</div>
</div>
<div class="sect3">
- <h4 id="__code_bookmarkholder_code">8.1.2. <code>BookmarkHolder</code></h4>
+ <h4 id="_code_bookmarkholder_code">8.1.2. <code>BookmarkHolder</code></h4>
<div class="paragraph">
<p>The <code>BookmarkHolder</code> interface is intended to be implemented by domain objects that use a <code>Bookmark</code> to reference a (single) domain object; an example might be a class such as the audit entry, mentioned above. The interface is simply:</p>
</div>
@@ -7523,10 +7628,10 @@ Scratchpad scratchpad;</code></pre>
<div class="sect3">
<h4 id="_usage_by_other_services">8.1.3. Usage by other services</h4>
<div class="paragraph">
- <p>Bookmarks are used by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>, which uses a bookmark to capture the target object on which an action will be invoked subsequently.</p>
+ <p>Bookmarks are used by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s command module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_application-layer-spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>, which uses a bookmark to capture the target object on which an action will be invoked subsequently.</p>
</div>
<div class="paragraph">
- <p>Bookmarks are also used by the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s auditing module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_AuditerService"><code>AuditerService</code></a>.</p>
+ <p>Bookmarks are also used by the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s auditing module’s implementation of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_AuditerService"><code>AuditerService</code></a>.</p>
</div>
</div>
</div>
@@ -8413,7 +8518,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
<p>The metadata APIs provide access to the framework’s internal metamodel. These are generally of use to support development-time activities, for example creating custom UIs through Swagger.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the metadata APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the metadata APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -8524,7 +8629,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
<td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
<td class="content">
<div class="paragraph">
- <p>This functionality was originally implemented as part of (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> security module, where the string representations of the various features are used to represent permissions.</p>
+ <p>This functionality was originally implemented as part of (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> security module, where the string representations of the various features are used to represent permissions.</p>
</div> </td>
</tr>
</tbody>
@@ -8746,7 +8851,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
</div>
</div>
<div class="sect2">
- <h3 id="_rgsvc_metadata-api_MetamodelService">9.3. <code>MetaModelService5</code></h3>
+ <h3 id="_rgsvc_metadata-api_MetamodelService">9.3. <code>MetaModelService6</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/rgsvc/_rgsvc_metadata-api_MetamodelService.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>
@@ -8758,7 +8863,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
</ul>
</div>
<div class="paragraph">
- <p>The <code>MetaModelService5</code> service (and its various supertypes) provides access to a number of aspects of Apache Isis' internal metamodel.</p>
+ <p>The <code>MetaModelService6</code> service (and its various supertypes) provides access to a number of aspects of Apache Isis' internal metamodel.</p>
</div>
<div class="sect3">
<h4 id="_rgsvc_metadata-api_MetamodelService_api">9.3.1. API</h4>
@@ -8777,7 +8882,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
</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">MetaModelService5</span> {
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">MetaModelService6</span> {
<span class="predefined-type">Class</span><?> fromObjectType(<span class="predefined-type">String</span> objectType); <i class="conum" data-value="1"></i><b>(1)</b>
<span class="predefined-type">String</span> toObjectType(<span class="predefined-type">Class</span><?> domainType); <i class="conum" data-value="2"></i><b>(2)</b>
<span class="type">void</span> rebuild(<span class="predefined-type">Class</span><?> domainType); <i class="conum" data-value="3"></i><b>(3)</b>
@@ -8807,6 +8912,18 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
CommandDtoProcessor commandDtoProcessorFor( <i class="conum" data-value="8"></i><b>(8)</b>
<span class="predefined-type">String</span> memberIdentifier);
+ <span class="comment">// introduced in MetaModelService6</span>
+ MetamodelDto pexportMetaModel(<span class="directive">final</span> Config config);
+
+
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">Config</span> {
+ <span class="directive">public</span> Config withIgnoreNoop() { ... }
+ <span class="directive">public</span> Config withIgnoreInterfaces() { ... }
+ <span class="directive">public</span> Config withIgnoreAbstractClasses() { ... }
+ <span class="directive">public</span> Config withIgnoreBuiltInValueTypes() { ... }
+ <span class="directive">public</span> Config withIgnoreMixins() { ... }
+ <span class="directive">public</span> Config withPackagePrefix(<span class="directive">final</span> <span class="predefined-type">String</span> packagePrefix) { ... }
+ }
}</code></pre>
</div>
</div>
@@ -8843,7 +8960,17 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
</tr>
<tr>
<td><i class="conum" data-value="8"></i><b>8</b></td>
- <td>obtain an implementation of <code>CommandDtoProcessor</code> (if any) as per an <a href="../rgant/rgant.html#_rgant-Action_command"><code>@Action#commandDtoProcessor()</code></a> or <a href="../rgant/rgant.html#_rgant-Property_command"><code>@Property#commandDtoProcessor()</code></a>.</td>
+ <td>obtain an implementation of <code>CommandDtoProcessor</code> (if any) as per an <a href="../rgant/rgant.html#_rgant-Action_command"><code>@Action#commandDtoProcessor()</code></a> or <a href="../rgant/rgant.html#_rgant-Property_command"><code>@Property#commandDtoProcessor()</code></a>.
+ <div class="paragraph">
+ <p>This is used by the <a href="#_rgsvc_presentation-layer-spi_ContentMappingService_implementations">framework-provided implementations</a> of <code>ContentMappingService</code>.</p>
+ </div></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="9"></i><b>9</b></td>
+ <td>Exports the entire metamodel as a DTO, serializable into XML using JAXB.
+ <div class="paragraph">
+ <p>The <code>Config</code> property specifies which package(s) to include and can be used to ignore certain elements.</p>
+ </div></td>
</tr>
</tbody>
</table>
@@ -8878,7 +9005,7 @@ Element customerXsd = snapshot.getXsdElement();</code></pre>
</ul>
</div>
<div class="paragraph">
- <p>The <code>MetaModelServiceMenu</code> provides a method to download all domain members as a CSV. Internally this calls <code>MetaModelService#export()</code>. Under the covers this uses the API provided by the <a href="../rgsvc/rgsvc.html#_rgsvc_metadata-api_ApplicationFeatureRepository"><code>ApplicationFeatureRepository</code></a> domain service.</p>
+ <p>The <code>MetaModelServiceMenu</code> provides a method to download all domain members as a CSV (by calling <code>MetaModelService#export()</code>) or as an XML (by calling <code>MetaModelService6#exportMetaModel(…)</code>.</p>
</div>
</div>
</div>
@@ -9097,7 +9224,7 @@ repositoryService.persist(cust);</code></pre>
<p>The testing SPIs allow the framework to provide supporting functionality for use when testing or demoing an application.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the testing APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the testing APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -9176,7 +9303,7 @@ repositoryService.persist(cust);</code></pre>
</tbody>
</table>
<div class="paragraph">
- <p>The table below summarizes the testing SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the testing SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -9640,7 +9767,7 @@ repositoryService.persist(cust);</code></pre>
<p>The persistence layer APIs provide domain objects with tools to manage the interactions with the persistence layer, for example adding on-the-fly caching to queries that are called many times within a loop.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the persistence layer APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the persistence layer APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -10444,7 +10571,7 @@ repositoryService.persist(cust);</code></pre>
</div>
</div>
<div class="sect4">
- <h5 id="__code_persistandflush_code_code_removeandflush_code"><code>persistAndFlush(…)</code>, <code>removeAndFlush(…)</code></h5>
+ <h5 id="_code_persistandflush_code_code_removeandflush_code"><code>persistAndFlush(…)</code>, <code>removeAndFlush(…)</code></h5>
<div class="paragraph">
<p>In some cases, such as when using managed properties and collections for implementing 1-1, 1-n, or m-n relationships, the developer needs to invoke <code>flush()</code> to send the changes to the DataNucleus persistence mechanism. These managed properties and collections and then updated.</p>
</div>
@@ -10715,7 +10842,7 @@ repositoryService.persist(cust);</code></pre>
<p>The persistence layer SPIs influence how the framework persists domain objects, for example controlling how to create an audit log of changes to domain objects.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the persistence layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the persistence layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">
@@ -10930,10 +11057,10 @@ log4j.additivity.org.apache.isis.applib.services.audit.AuditerServiceLogging=fal
<div class="sect3">
<h4 id="_alternative_implementations_6">12.1.4. Alternative Implementations</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit module provides an implementation of this service (<code>AuditerService</code>), and also provides a number of related domain services (<code>AuditingServiceMenu</code>, <code>AuditingServiceRepository</code> and <code>AuditingServiceContributions</code>).</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s audit module provides an implementation of this service (<code>AuditerService</code>), and also provides a number of related domain services (<code>AuditingServiceMenu</code>, <code>AuditingServiceRepository</code> and <code>AuditingServiceContributions</code>).</p>
</div>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit module also provides an implementation, <code>org.isisaddons.module.audit.dom.AuditerServiceUsingJdo</code>. This creates an audit record for each changed property (ie every time that <code>AuditerService#audit(…)</code> is called.</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s audit module also provides an implementation, <code>org.isisaddons.module.audit.dom.AuditerServiceUsingJdo</code>. This creates an audit record for each changed property (ie every time that <code>AuditerService#audit(…)</code> is called.</p>
</div>
<div class="paragraph">
<p>The module also provides:</p>
@@ -11018,7 +11145,7 @@ log4j.additivity.org.apache.isis.applib.services.audit.AuditerServiceLogging=fal
<div class="sect3">
<h4 id="_implementation_35">12.2.2. Implementation</h4>
<div class="paragraph">
- <p>The most full-featured available implementation is the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit module. This creates an audit records for each changed property (ie every time that <code>AuditingService3#audit(…)</code> is called. The implementation is <code>org.isisaddons.module.audit.dom.AuditingService</code>.</p>
+ <p>The most full-featured available implementation is the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s audit module. This creates an audit records for each changed property (ie every time that <code>AuditingService3#audit(…)</code> is called. The implementation is <code>org.isisaddons.module.audit.dom.AuditingService</code>.</p>
</div>
<div class="paragraph">
<p>The module also provides:</p>
@@ -11161,7 +11288,7 @@ log4j.additivity.org.apache.isis.applib.services.audit.AuditerServiceLogging=fal
<div class="sect3">
<h4 id="_related_services_28">12.3.3. Related Services</h4>
<div class="paragraph">
- <p>This service is intended (though not mandated) to be used by implementations of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>. The (non-ASF) <a href="http://github.com/isisaddons-legacy/isis-module-publishing">Isis addons' publishing</a> module does use it (though the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> publishmq module does not).</p>
+ <p>This service is intended (though not mandated) to be used by implementations of <a href="../rgsvc/rgsvc.html#_rgsvc_persistence-layer-spi_PublishingService"><code>PublishingService</code></a>. The (non-ASF) <a href="http://github.com/isisaddons-legacy/isis-module-publishing">Isis addons' publishing</a> module does use it (though the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> publishmq module does not).</p>
</div>
</div>
</div>
@@ -11298,7 +11425,7 @@ log4j.additivity.org.apache.isis.applib.services.publish.PublisherServiceLogging
<div class="sect3">
<h4 id="_alternative_implementations_8">12.4.4. Alternative Implementations</h4>
<div class="paragraph">
- <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s publishmq module also provides an implementation (<code>o.ia.m.publishmq.dom.servicespi.PublisherServiceUsingActiveMq</code>). This implementation:</p>
+ <p>The (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a>'s publishmq module also provides an implementation (<code>o.ia.m.publishmq.dom.servicespi.PublisherServiceUsingActiveMq</code>). This implementation:</p>
</div>
<div class="ulist">
<ul>
@@ -11731,7 +11858,7 @@ log4j.additivity.org.apache.isis.applib.services.publish.PublisherServiceLogging
<p>Bootstrapping SPIs influence how the framework locates the components that make up the running application.</p>
</div>
<div class="paragraph">
- <p>The table below summarizes the bootstrapping SPI defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules.</p>
+ <p>The table below summarizes the bootstrapping SPI defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org" target="_blank" rel="noopener">Incode Platform</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
<caption class="title">