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 2016/05/15 17:12:19 UTC
[15/27] isis-site git commit: ISIS-1291: moved internal framework
services into its own guide
http://git-wip-us.apache.org/repos/asf/isis-site/blob/cb86cd1e/content/guides/rgsvc.html
----------------------------------------------------------------------
diff --git a/content/guides/rgsvc.html b/content/guides/rgsvc.html
index 5734871..98e887d 100644
--- a/content/guides/rgsvc.html
+++ b/content/guides/rgsvc.html
@@ -560,6 +560,9 @@ which are called by the framework).</p>
<li>
<p><a href="rgmvn.html">Apache Isis Maven plugin</a></p>
</li>
+<li>
+<p><a href="rgfis.html">Framework Internal Services</a></p>
+</li>
</ul>
</div>
<div class="paragraph">
@@ -620,8 +623,9 @@ allowing you to easily mock out these services in your unit tests.</p>
</div>
<div class="paragraph">
<p>The framework also defines a number of "internal" services. These are not part of the framework’s formal API, in that
-they use classes that are outside of the applib. These are documented here, but should be thought of as part of the
-internal design of the framework, and are liable to change from release to release.</p>
+they use classes that are outside of the applib. These internal framework services should be thought of as part of the
+internal design of the framework, and are liable to change from release to release. The internal framework services
+are documented in the <a href="rgfis.html">Framework Internal Services</a> guide.</p>
</div>
</div>
<div class="sect2">
@@ -833,13 +837,13 @@ may be broadcast to all subscribers. Whether this occurs depends on whether the
</li>
<li>
<p>As each execution progresses, and objects that are modified are "enlisted" into the (internal)
-<a href="#_rgsvc_spi_ChangedObjectsServiceInternal"><code>ChangedObjectsServiceInternal</code></a> domain service. Metrics as
+<a href="rgfis.html#_rgfis_spi_ChangedObjectsServiceInternal"><code>ChangedObjectsServiceInternal</code></a> domain service. Metrics as
to which objects are merely loaded into memory are also captured using the
<a href="#_rgsvc_api_MetricsService"><code>MetricsService</code></a> (not shown on the diagram).</p>
</li>
<li>
<p>At the end of each execution, details of that execution are published through the (internal)
-<a href="#_rgsvc_spi_PublisherServiceInternal"><code>PublisherServiceInternal</code></a> domain service. This is only done for
+<a href="rgfis.html#_rgfis_spi_PublisherServiceInternal"><code>PublisherServiceInternal</code></a> domain service. This is only done for
actions/properties annotated appropriate (with <a href="rgant.html#_rgant-Action_publishing"><code>@Action#publishing()</code></a> or
<a href="rgant.html#_rgant-Property_publishing"><code>@Property#publishing()</code></a>). <br></p>
<div class="paragraph">
@@ -850,14 +854,14 @@ registered <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code><
</li>
<li>
<p>At the end of all executions, details of all changed objects are published, again through the (internal)
-<a href="#_rgsvc_spi_PublisherServiceInternal"><code>PublisherServiceInternal</code></a> to any registered <code>PublishingService</code>
+<a href="rgfis.html#_rgfis_spi_PublisherServiceInternal"><code>PublisherServiceInternal</code></a> to any registered <code>PublishingService</code>
or <code>PublisherService</code> implementations. Only domain objects specified to be published with
<a href="rgant.html#_rgant-DomainObject_publishing"><code>@DomainObject#publishing()</code></a> are published.</p>
</li>
<li>
<p>Also at the end of all executions, details of all changed properties are passed to any registered
<a href="#_rgsvc_spi_AuditingService"><code>AuditingService</code></a> by way of the (internal)
-<a href="#_rgsvc_spi_AuditingServiceInternal"><code>AuditingServiceInternal</code></a> domain service.</p>
+<a href="rgfis.html#_rgfis_spi_AuditingServiceInternal"><code>AuditingServiceInternal</code></a> domain service.</p>
</li>
</ul>
</div>
@@ -1111,19 +1115,16 @@ depends on:<br>
</li>
</ul>
</div>
-<div class="paragraph">
-<p>There are also a number of presentation layer SPIs that use internal classes. These can be found in the <a href="#_rgsvc_presentation-layer-internal-spi">next chapter</a>.</p>
-</div>
<div class="sect2">
<h3 id="_rgsvc_spi_ContentMappingService">3.1. <code>ContentMappingService</code></h3>
<div class="paragraph">
<p>The <code>ContentMappingService</code> supports the (default implementation of the)
-<a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> allowing the
+<a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> allowing the
<a href="ugvro.html">RestfulObjects viewer</a> to allow domain objects to be transformed into some other format as specified
by the HTTP <code>Accept</code> header.</p>
</div>
<div class="paragraph">
-<p>See <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> for further discussion.</p>
+<p>See <a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> for further discussion.</p>
</div>
<div class="admonitionblock note">
<table>
@@ -1233,7 +1234,7 @@ The mapped object used will be the first non-<code>null</code> result returned b
<div class="sect3">
<h4 id="_related_services">3.1.3. Related Services</h4>
<div class="paragraph">
-<p>This service is a companion to the default implementation of the <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>.</p>
+<p>This service is a companion to the default implementation of the <a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>.</p>
</div>
</div>
</div>
@@ -2552,532 +2553,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect1">
-<h2 id="_rgsvc_presentation-layer-internal-spi">4. Presentation Layer internal SPI</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>These domain services are internal to the framework, controlling various aspects of the presentation layer.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>We do not guarantee that <a href="http://semver.org">semantic versioning</a> will be honoured for these SPIs.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The table below summarizes the presentation layer internal 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://www.isisaddons.org">Isis Addons</a> modules.</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 2. "Internal" SPI Services</caption>
-<colgroup>
-<col style="width: 30%;">
-<col style="width: 30%;">
-<col style="width: 20%;">
-<col style="width: 20%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">SPI</th>
-<th class="tableblock halign-left valign-top">Maven Module<br>
-Impl’n (g: a:)</th>
-<th class="tableblock halign-left valign-top">Implementation</th>
-<th class="tableblock halign-left valign-top">Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_ContentNegotiationService"><code>o.a.i.v.ro.</code><br>
-<code>rendering.service.conneg.</code><br>
-<code>ContentNegotiationService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Encodes the algorithm that delegates to any registered <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>s.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ContentNegotiationService-</code><br>
-<code>XRoDomainType</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-viewer-restfulobjects-rendering</code></p></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_RepresentationService"><code>o.a.i.v.ro.</code><br>
-<code>rendering.service.</code><br>
-<code>RepresentationService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Generates the representations, delegating to any registered <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>s.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>RepresentationService-</code><br>
-<code>ForRestfulObjects</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-viewer-restfulobjects-rendering</code></p></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
-<p>Key:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>o.a.i</code> is an abbreviation for <code>org.apache.isis</code></p>
-</li>
-<li>
-<p><code>o.ia.m</code> is an abbreviation for <code>org.isisaddons.module</code></p>
-</li>
-<li>
-<p><code>o.a.i.c.m.s</code> is an abbreviation for <code>org.apache.isis.core.metamodel.services</code></p>
-</li>
-<li>
-<p><code>o.a.i.c.r.s</code> is an abbreviation for <code>org.apache.isis.core.runtime.services</code></p>
-</li>
-<li>
-<p><code>o.a.i.v.ro</code> is an abbreviation for <code>org.apache.isis.viewer.restfulobjects</code></p>
-</li>
-</ul>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_spi_ContentNegotiationService">4.1. <code>ContentNegotiationService</code></h3>
-<div class="paragraph">
-<p>The <code>ContentNegotiationService</code> is a plug-in point for the <a href="ugvro.html">RestfulObjects viewer</a> so that it can generate representations according to HTTP <code>Accept</code> header of the request. This idea is discussed in section 34.1 of the <a href="http://restfulobjects.org">Restful Objects spec</a> v1.0.</p>
-</div>
-<div class="paragraph">
-<p>The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.</p>
-</div>
-<div class="paragraph">
-<p>Another use case is to support "third party" REST clients over which you have no control. In this scenario you <em>must not</em> naively expose entities through the RO viewer, because over time those entities will inevitably evolve and change their structure. If the entities were exposed directly then those REST clients will break.</p>
-</div>
-<div class="paragraph">
-<p>Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>first is to solve the problem at the domain layer by defining a regular Apache Isis <a href="ugbtb.html#_ugbtb_view-models">view model</a>. This is then surfaced over the RO viewer. <br></p>
-<div class="paragraph">
-<p>If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.</p>
-</div>
-</li>
-<li>
-<p>a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then <a href="ugbtb.html#_ugbtb_other-techniques_mapping-rdbms-views">mapping this</a> to a (read-only) entity. Again this is surfaced by the RO viewer. <br></p>
-<div class="paragraph">
-<p>If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.</p>
-</div>
-</li>
-<li>
-<p>our third option is to solve the problem at the presentation layer, using the <code>ContentNegotiationService</code> described in this section.<br></p>
-<div class="paragraph">
-<p>The <code>ContentNegotiationService</code> is responsible for inspecting the HTTP <code>Accept</code> header, and use this to select the correct representation to render. <br></p>
-</div>
-<div class="paragraph">
-<p>The Apache Isis framework provides a default implementation of <code>ContentNegotiationService</code> which inspects the "x-ro-domaintype" component of the HTTP <code>Accept</code> header. If present, this implementation will delegate to the companion <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> service, if configured. <br></p>
-</div>
-<div class="paragraph">
-<p>A typical implementation of <code>ContentMappingService</code> will convert the domain object into some sort of DTO (data transfer object) as specified by the "x-ro-domaintype". If this DTO is annotated with JAXB or Jackson mappings, then the RO viewer (courtesy of the underlying <a href="http://resteasy.jboss.org/">RestEasy</a> framework) can serialize these directly <br></p>
-</div>
-<div class="paragraph">
-<p>What all that means is that, if the underlying entities change, we are required to update the mappings in the <code>ContentMappingService</code> to map to the same DTOs.</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>This diagram illustrates the three options available:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services-spi/ContentNegotiationService/facade-choices.png"><img src="images/reference-services-spi/ContentNegotiationService/facade-choices.png" alt="facade choices" width="700px"></a>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_spi_15">4.1.1. SPI</h4>
-<div class="paragraph">
-<p>The SPI defined by this service 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">ContentNegotiationService</span> {
- <span class="annotation">@Programmatic</span>
- Response.ResponseBuilder buildResponse( <i class="conum" data-value="1"></i><b>(1)</b>
- RepresentationService.Context2 renderContext2,
- ObjectAdapter objectAdapter);
- <span class="annotation">@Programmatic</span>
- Response.ResponseBuilder buildResponse( <i class="conum" data-value="2"></i><b>(2)</b>
- RepresentationService.Context2 renderContext2,
- ObjectAndProperty objectAndProperty);
- <span class="annotation">@Programmatic</span>
- Response.ResponseBuilder buildResponse( <i class="conum" data-value="3"></i><b>(3)</b>
- RepresentationService.Context2 renderContext2,
- ObjectAndCollection objectAndCollection);
- <span class="annotation">@Programmatic</span>
- Response.ResponseBuilder buildResponse( <i class="conum" data-value="4"></i><b>(4)</b>
- RepresentationService.Context2 renderContext2,
- ObjectAndAction objectAndAction);
- <span class="annotation">@Programmatic</span>
- Response.ResponseBuilder buildResponse( <i class="conum" data-value="5"></i><b>(5)</b>
- RepresentationService.Context2 renderContext2,
- ObjectAndActionInvocation objectAndActionInvocation);
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>representation of a single object, as per section 14.4 of the RO spec, v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>representation of a single property of an object, as per section 16.4 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>representation of a single collection of an object, as per section 17.5 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>These methods provide:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>a <code>RepresentationService.Context2</code> which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)</p>
-</li>
-<li>
-<p>an object representing the information to be rendered<br></p>
-<div class="paragraph">
-<p>eg <code>ObjectAdapter</code>, <code>ObjectAndProperty</code>, <code>ObjectAndCollection</code> etc</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>In all cases, returning <code>null</code> will result in the regular RO spec representation being returned.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that <a href="http://semver.org">semantic versioning</a> will be honoured for these APIs.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_implementation_14">4.1.2. Implementation</h4>
-<div class="paragraph">
-<p><code>ContentNegotiationServiceAbstract</code> (in <code>o.a.i.v.ro.rendering.service.conneg</code>) provides a no-op implementation of the SPI, along with supporting methods:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="directive">abstract</span> <span class="type">class</span> <span class="class">ContentNegotiationServiceAbstract</span> <span class="directive">implements</span> ContentNegotiationService {
- ...
- protected <span class="predefined-type">Object</span> objectOf(<span class="directive">final</span> ObjectAdapter objectAdapter) { ... }
- <span class="directive">protected</span> <span class="predefined-type">Object</span> returnedObjectOf(ObjectAndActionInvocation objectAndActionInvocation) { ... }
-
- <span class="directive">protected</span> <span class="predefined-type">Class</span><?> loadClass(<span class="predefined-type">String</span> cls) { ... }
-
- <span class="directive">protected</span> <span class="type">void</span> ensureJaxbAnnotated(<span class="predefined-type">Class</span><?> domainType) { ... }
- <span class="directive">protected</span> <span class="type">void</span> ensureDomainObjectAssignable(
- <span class="predefined-type">String</span> xRoDomainType, <span class="predefined-type">Class</span><?> domainType, <span class="predefined-type">Object</span> domainObject) { ... }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>As discussed in the introduction, the framework also provides a default implementation, <code>o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType</code>. This handles content negotiation for two of the possible representations, object representations and for action result representations:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>For object representations it will handle requests with HTTP <code>Accept</code> headers of the form:</p>
-<div class="ulist">
-<ul>
-<li>
-<p><code>application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=…​</code></p>
-</li>
-<li>
-<p><code>application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=…​</code></p>
-</li>
-</ul>
-</div>
-</li>
-<li>
-<p>for action result representations it will similarly handle requests with HTTP <code>Accept</code> headers of the form:</p>
-<div class="ulist">
-<ul>
-<li>
-<p><code>application/json;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=…​</code><br></p>
-</li>
-<li>
-<p><code>application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=…​</code></p>
-</li>
-</ul>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The value of the <code>x-ro-domain-type</code> parameter corresponds to the DTO to be mapped into by the <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>.</p>
-</div>
-<div class="paragraph">
-<p>If the DTO is annotated with JAXB, then also note that the runtime type must be annotated with the JAXB <code>javax.xml.bind.annotation.XmlRootElement</code> so that RestEasy is able to unambiguously serialize it.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_usage">4.1.3. Usage</h4>
-<div class="paragraph">
-<p>You can find an example of all these services in the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>. This defines a <code>ToDoItemDto</code> class that is JAXB annotated (it is in fact generated from an XSD).</p>
-</div>
-<div class="paragraph">
-<p>The example app also includes an implementation of <code>ContentMappingService</code> that maps <code>todoapp.dom.module.todoitem.ToDoItem</code> entities to <code>todoapp.dto.module.todoitem.ToDoItemDto</code> classes.</p>
-</div>
-<div class="paragraph">
-<p>A REST client can therefore request a DTO representation of an entity by invoking</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/0</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with an <code>Accept</code> header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>will result in an XML serialization of that class:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services-spi/ContentNegotiationService/accept-xml.png"><img src="images/reference-services-spi/ContentNegotiationService/accept-xml.png" alt="accept xml" width="700px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>while similarly hitting the same URL with an <code>Accept</code> header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>will result in the JSON serialization of that class:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services-spi/ContentNegotiationService/accept-json.png"><img src="images/reference-services-spi/ContentNegotiationService/accept-json.png" alt="accept json" width="700px"></a>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_configuration">4.1.4. Configuration</h4>
-<div class="paragraph">
-<p>The default <code>ContentNegotiationServiceXRoDomainType</code> implementation provides a <a href="rgcfg.html#_rgcfg_configuring-core">configuration property</a> which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services.ContentNegotiationServiceXRoDomainType.prettyPrint=true</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>If the property is not set, then the default depends on the <a href="rgcfg.html#_rgcfg_deployment-types">deployment type</a>; production mode will disable pretty printing, while prototyping mode will enable it.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_registering_the_services_9">4.1.5. Registering the Services</h4>
-<div class="paragraph">
-<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default
-implementation of <code>ContentNegotiationService</code> service is automatically registered and injected (it is annotated with
-<code>@DomainService</code>) so no further configuration is required.</p>
-</div>
-<div class="paragraph">
-<p>To use an alternative implementation, use
-<a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
-in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_related_services_11">4.1.6. Related Services</h4>
-<div class="paragraph">
-<p>The default implementation of <code>ContentNegotiationService</code> delegates to <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> (if present) to convert domain entities into a stable form (eg DTO).</p>
-</div>
-<div class="paragraph">
-<p>The <code>ContentNegotiationService</code> is itself called by the (default implementation of) <a href="#_rgsvc_spi_RepresentationService"><code>RepresentationService</code></a>.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_spi_RepresentationService">4.2. <code>RepresentationService</code></h3>
-<div class="paragraph">
-<p>The <code>RepresentationService</code> is the main plug-in point for the <a href="ugvro.html">RestfulObjects viewer</a> to generate representations.</p>
-</div>
-<div class="paragraph">
-<p>The default implementation generates representations according to the <a href="http://restfulobjects.org">Restful Objects spec</a> v1.0. However, it also delegates to the <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> which provides a mechanism for altering representations according to the HTTP <code>Accept</code> header.</p>
-</div>
-<div class="paragraph">
-<p>The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.</p>
-</div>
-<div class="paragraph">
-<p>In all there are three domain services that can influence the representations generated: this service, <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>and the <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>. The diagram below shows how these collaborate:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services-spi/RepresentationService/service-collaborations.png"><img src="images/reference-services-spi/RepresentationService/service-collaborations.png" alt="service collaborations" width="700px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>The <code>RepresentationServiceForRestfulObjects</code> is the default implementation of this service; likewise <code>ContentNegotiationServiceXRoDomainType</code> is the default implementation of the <code>ContentNegotiationService</code>. If you inspect the source code you’ll see that the default implementation of this service’s primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a <em>different _representation then in many cases replacing either this service _or</em> the <code>ContentNegotiationService</code> will be equivalent (you’ll notice that their SPIs are very similar).</p>
-</div>
-<div class="sect3">
-<h4 id="_spi_16">4.2.1. SPI</h4>
-<div class="paragraph">
-<p>The SPI defined by this service 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">RepresentationService</span> {
- <span class="annotation">@Programmatic</span>
- Response objectRepresentation( <i class="conum" data-value="1"></i><b>(1)</b>
- <span class="predefined-type">Context</span> rendererContext,
- ObjectAdapter objectAdapter);
- <span class="annotation">@Programmatic</span>
- Response propertyDetails( <i class="conum" data-value="2"></i><b>(2)</b>
- <span class="predefined-type">Context</span> rendererContext,
- ObjectAndProperty objectAndProperty,
- MemberReprMode memberReprMode);
- <span class="annotation">@Programmatic</span>
- Response collectionDetails( <i class="conum" data-value="3"></i><b>(3)</b>
- <span class="predefined-type">Context</span> rendererContext,
- ObjectAndCollection objectAndCollection,
- MemberReprMode memberReprMode);
- <span class="annotation">@Programmatic</span>
- Response actionPrompt( <i class="conum" data-value="4"></i><b>(4)</b>
- <span class="predefined-type">Context</span> rendererContext,
- ObjectAndAction objectAndAction);
- <span class="annotation">@Programmatic</span>
- Response actionResult( <i class="conum" data-value="5"></i><b>(5)</b>
- <span class="predefined-type">Context</span> rendererContext,
- ObjectAndActionInvocation objectAndActionInvocation,
- ActionResultReprRenderer.SelfLink selfLink);
- <span class="directive">public</span> <span class="directive">static</span> <span class="type">interface</span> <span class="class">Context</span> <span class="directive">extends</span> RendererContext {
- ObjectAdapterLinkTo getAdapterLinkTo();
- }
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>representation of a single object, as per section 14.4 of the RO spec, v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>representation of a single property of an object, as per section 16.4 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>representation of a single collection of an object, as per section 17.5 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>These methods provide:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>a <code>RendererContext</code> which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)</p>
-</li>
-<li>
-<p>an object representing the information to be rendered<br></p>
-<div class="paragraph">
-<p>eg <code>ObjectAdapter</code>, <code>ObjectAndProperty</code>, <code>ObjectAndCollection</code> etc</p>
-</div>
-</li>
-<li>
-<p>for members, whether the representation is in read/write mode<br></p>
-<div class="paragraph">
-<p>ie <code>MemberReprMode</code></p>
-</div>
-</li>
-</ul>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that <a href="http://semver.org">semantic versioning</a> will be honoured for these APIs.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_implementation_15">4.2.2. Implementation</h4>
-<div class="paragraph">
-<p>As discussed in the introduction, the framework provides a default implementation, <code>o.a.i.v.ro.rendering.service.RepresentationServiceForRestfulObjects</code>. This delegates to <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the <a href="http://restfulobjects.org">Restful Objects spec</a> v1.0.</p>
-</div>
-<div class="paragraph">
-<p>To use an alternative implementation, use
-<a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
-in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_registering_the_services_10">4.2.3. Registering the Services</h4>
-<div class="paragraph">
-<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default implementation of <code>RepresentationService</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_related_services_12">4.2.4. Related Services</h4>
-<div class="paragraph">
-<p>The default implementation delegates to <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>, whose default implementation may delegate in turn to <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> (if present).</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rgsvc_application-layer-api">5. Application Layer API</h2>
+<h2 id="_rgsvc_application-layer-api">4. Application Layer API</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
@@ -3086,7 +2562,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<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 in (non-ASF) <a href="http://www.isisaddons.org">Isis Addons</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 3. Application Layer API</caption>
+<caption class="title">Table 2. Application Layer API</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 50%;">
@@ -3254,7 +2730,7 @@ represented as the <code>Interaction</code> context.</p>
</ul>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_AcceptHeaderService">5.1. <code>AcceptHeaderService</code></h3>
+<h3 id="_rgsvc_api_AcceptHeaderService">4.1. <code>AcceptHeaderService</code></h3>
<div class="paragraph">
<p>The <code>AcceptHeaderService</code> domain service is a <a href="rgant.html#_rgant-RequestScoped"><code>@RequestScoped</code></a> service that
simply exposes the HTTP <code>Accept</code> header to the domain. Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.</p>
@@ -3267,7 +2743,7 @@ simply exposes the HTTP <code>Accept</code> header to the domain. Its intended
</td>
<td class="content">
<div class="paragraph">
-<p>As an alternative to performing content negotiation within the domain classes, the <a href="#_rgsvc_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> and
+<p>As an alternative to performing content negotiation within the domain classes, the <a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> and
<a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> SPI domain services allow the framework to perform the content negotiation responsibility.</p>
</div>
</td>
@@ -3275,7 +2751,7 @@ simply exposes the HTTP <code>Accept</code> header to the domain. Its intended
</table>
</div>
<div class="sect3">
-<h4 id="_api_implementation">5.1.1. API & Implementation</h4>
+<h4 id="_api_implementation">4.1.1. API & Implementation</h4>
<div class="paragraph">
<p>The API defined by the service is:</p>
</div>
@@ -3320,7 +2796,7 @@ simply exposes the HTTP <code>Accept</code> header to the domain. Its intended
</div>
</div>
<div class="sect3">
-<h4 id="_usage_2">5.1.2. Usage</h4>
+<h4 id="_usage">4.1.2. Usage</h4>
<div class="paragraph">
<p>The intended use of this service is where there are multiple concurrent versions of a REST API, for backward
compatibility of existing clients. The <code>AcceptHeaderService</code> allows the responsibility for content negotiation
@@ -3362,7 +2838,7 @@ map domain objects to view models/DTOs.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_4">5.1.3. Registering the Service</h4>
+<h4 id="_registering_the_service_4">4.1.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default
@@ -3377,7 +2853,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_ActionInvocationContext">5.2. <code>ActionInvocationContext</code></h3>
+<h3 id="_rgsvc_api_ActionInvocationContext">4.2. <code>ActionInvocationContext</code></h3>
<div class="paragraph">
<p>The <code>ActionInvocationContext</code> domain service is a <a href="rgant.html#_rgant-RequestScoped"><code>@RequestScoped</code></a> service intended to support the implementation of "bulk" actions annotated with <a href="rgant.html#_rgant-Action_invokeOn"><code>@Action#invokeOn()</code></a>. This allows the user to select multiple objects in a table and then invoke the same action against all of them.</p>
</div>
@@ -3385,7 +2861,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<p>When an action is invoked in this way, this service allows each object instance to "know where it is" in the collection; it acts a little like an iterator. In particular, an object can determine if it is the last object to be called, and so can perform special processing, eg to return a summary calculated result.</p>
</div>
<div class="sect3">
-<h4 id="_api_implementation_2">5.2.1. API & Implementation</h4>
+<h4 id="_api_implementation_2">4.2.1. API & Implementation</h4>
<div class="paragraph">
<p>The API defined by the service is:</p>
</div>
@@ -3425,7 +2901,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_usage_3">5.2.2. Usage</h4>
+<h4 id="_usage_2">4.2.2. Usage</h4>
<div class="paragraph">
<p>For actions that are void or that return null, Apache Isis will return to the list once executed. But for bulk actions that are non-void, Apache Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).</p>
</div>
@@ -3465,7 +2941,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_5">5.2.3. Registering the Service</h4>
+<h4 id="_registering_the_service_5">4.2.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default
@@ -3479,7 +2955,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_unit_testing_support">5.2.4. Unit testing support</h4>
+<h4 id="_unit_testing_support">4.2.4. Unit testing support</h4>
<div class="paragraph">
<p>The <code>ActionInvocationContext</code> class also has a couple of static factory methods intended to support unit testing:</p>
</div>
@@ -3504,7 +2980,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_BackgroundService">5.3. <code>BackgroundService2</code></h3>
+<h3 id="_rgsvc_api_BackgroundService">4.3. <code>BackgroundService2</code></h3>
<div class="paragraph">
<p>The <code>BackgroundService2</code> domain service, and also the companion
<a href="#_rgsvc_spi_BackgroundCommandService"><code>BackgroundCommandService2</code></a> SPI service, enable commands
@@ -3517,7 +2993,7 @@ and persisting it rather than executing it directly.</p>
</div>
<div class="paragraph">
<p>The default <code>BackgroundServiceDefault</code> implementation works by using a proxy wrapper around the target so that it can
-capture the action to invoke and its arguments. (As of <code>1.13.0-SNAPSHOT</code>), this is done using <a href="#_rgsvc_spi_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a> (in previous releases it used (a private copy of) <a href="#_rgsvc_api_MementoService"><code>MementoService</code></a>).</p>
+capture the action to invoke and its arguments. (As of <code>1.13.0-SNAPSHOT</code>), this is done using <a href="rgfis.html#_rgfis_spi_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a> (in previous releases it used (a private copy of) <a href="#_rgsvc_api_MementoService"><code>MementoService</code></a>).</p>
</div>
<div class="paragraph">
<p>The persistence delegates the persistence of the memento to an appropriate implementation of the companion
@@ -3532,7 +3008,7 @@ the concrete implementation of this class depends on the configured <code>Backgr
the persisted (background) <code>Command</code>s.</p>
</div>
<div class="sect3">
-<h4 id="_api_implementation_3">5.3.1. API & Implementation</h4>
+<h4 id="_api_implementation_3">4.3.1. API & Implementation</h4>
<div class="paragraph">
<p>The API is:</p>
</div>
@@ -3561,7 +3037,7 @@ the persisted (background) <code>Command</code>s.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_usage_4">5.3.2. Usage</h4>
+<h4 id="_usage_3">4.3.2. Usage</h4>
<div class="paragraph">
<p>Using the service is very straight-forward; wrap the target domain object using <code>BackgroundService#execute(…​)</code> and invoke the method on the object returned by that method.</p>
</div>
@@ -3603,7 +3079,7 @@ the persisted (background) <code>Command</code>s.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_end_user_experience">5.3.3. End-user experience</h4>
+<h4 id="_end_user_experience">4.3.3. End-user experience</h4>
<div class="paragraph">
<p>For the end-user, executing an action that delegates work off to the <code>BackgroundService</code> raises the problem of how does the user know the work is complete?</p>
</div>
@@ -3644,7 +3120,7 @@ CommandContext commandContext; <i class="conum" data-value="1"></i><b>(1)</b></
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_services_11">5.3.4. Registering the Services</h4>
+<h4 id="_registering_the_services_9">4.3.4. Registering the Services</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -3658,7 +3134,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_related_services_13">5.3.5. Related Services</h4>
+<h4 id="_related_services_11">4.3.5. Related Services</h4>
<div class="paragraph">
<p>This service is closely related to the <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a> and also that service’s supporting <a href="#_rgsvc_spi_CommandService"><code>CommandService</code></a> service.</p>
</div>
@@ -3669,12 +3145,12 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<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://github.com/isisaddons/isis-module-command">Isis addons' command</a> module provides implementations of both (see <a href="#_rgsvc_spi_CommandService">`CommandService</code></a> and <a href="#_rgsvc_spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>).</p>
</div>
<div class="paragraph">
-<p>The <a href="#_rgsvc_spi_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a> (<code>1.13.0-SNAPSHOT</code>) is used to obtain
+<p>The <a href="rgfis.html#_rgfis_spi_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a> (<code>1.13.0-SNAPSHOT</code>) is used to obtain
a memento of the command such that it can be persisted. (In earlier versions, <a href="#_rgsvc_api_MementoService"><code>MementoService</code></a> was used for this purpose).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_rgsvc_api_BackgroundService_BackgroundCommandExecution">5.3.6. <code>BackgroundCommandExec’n</code> abstract class</h4>
+<h4 id="_rgsvc_api_BackgroundService_BackgroundCommandExecution">4.3.6. <code>BackgroundCommandExec’n</code> abstract class</h4>
<div class="paragraph">
<p>The <code>BackgroundCommandExecution</code> (in isis-core) is an abstract template class provided by isis-core that defines an abstract hook method to obtain background `Command`s to be executed:</p>
</div>
@@ -3693,7 +3169,7 @@ a memento of the command such that it can be persisted. (In earlier versions, <
</div>
</div>
<div class="sect3">
-<h4 id="_rgsvc_api_BackgroundService_Quartz">5.3.7. Quartz Scheduler Configuration</h4>
+<h4 id="_rgsvc_api_BackgroundService_Quartz">4.3.7. Quartz Scheduler Configuration</h4>
<div class="paragraph">
<p>The last part of the puzzle is to actually run the (appropriate implementation of) `BackgroundCommandExecution). 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" class="bare">http://camel.apache.org</a>]Apache Camel]. This section looks at configuring Quartz.</p>
</div>
@@ -3856,7 +3332,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_CommandContext">5.4. <code>CommandContext</code></h3>
+<h3 id="_rgsvc_api_CommandContext">4.4. <code>CommandContext</code></h3>
<div class="paragraph">
<p>The <code>CommandContext</code> service is a <a href="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>
@@ -3887,7 +3363,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<p>Assuming that the <code>CommandService</code> supports persistent <code>Command`s, the associated <a href="rgant.html#_rgant-Action_command"></code>@Action#command()<code></a> annotation also allows action invocations to be performed in the background. In this case the act of invoking the action on an object instead returns the `Command</code> to the user.</p>
</div>
<div class="sect3">
-<h4 id="_rgsvc_api_CommandContext_screencast">5.4.1. Screencast</h4>
+<h4 id="_rgsvc_api_CommandContext_screencast">4.4.1. Screencast</h4>
<div class="paragraph">
<p>The <a href="https://www.youtube.com/watch?v=tqXUZkPB3EI">screencast</a> provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.</p>
</div>
@@ -3907,7 +3383,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_api_implementation_4">5.4.2. API & Implementation</h4>
+<h4 id="_api_implementation_4">4.4.2. API & Implementation</h4>
<div class="paragraph">
<p>The <code>CommandContext</code> request-scoped service defines the following very simple API:</p>
</div>
@@ -4036,7 +3512,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_usage_5">5.4.3. Usage</h4>
+<h4 id="_usage_4">4.4.3. Usage</h4>
<div class="paragraph">
<p>The typical way to indicate that an action should be treated as a command is to annotate it with the <a href="rgant.html#_rgant-Action_command"><code>@Action#command()</code></a> annotation.</p>
</div>
@@ -4090,7 +3566,7 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
</div>
</div>
<div class="sect3">
-<h4 id="_interacting_with_the_services">5.4.4. Interacting with the services</h4>
+<h4 id="_interacting_with_the_services">4.4.4. Interacting with the services</h4>
<div class="paragraph">
<p>Typically domain objects will have little need to interact with the <code>CommandContext</code> and <code>Command</code> directly; what is
more useful is that these are persisted in support of the various use cases identified above.</p>
@@ -4143,7 +3619,7 @@ more useful is that these are persisted in support of the various use cases iden
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_services_12">5.4.5. Registering the Services</h4>
+<h4 id="_registering_the_services_10">4.4.5. Registering the Services</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -4157,7 +3633,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_related_services_14">5.4.6. Related Services</h4>
+<h4 id="_related_services_12">4.4.6. Related Services</h4>
<div class="paragraph">
<p>The <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a> service is very similar in nature to the <a href="#_rgsvc_api_InteactionContext"><code>InteactionContext</code></a>, in that the
<code>Command</code> object accessed through it is very similar to the <code>Interaction</code> object obtained from the <code>InteractionContext</code>.
@@ -4183,7 +3659,7 @@ created explicitly through the <a href="#_rgsvc_api_BackgroundService"><code>Bac
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_InteractionContext">5.5. <code>InteractionContext</code> (<code>1.13.0-SNAPSHOT</code>)</h3>
+<h3 id="_rgsvc_api_InteractionContext">4.5. <code>InteractionContext</code> (<code>1.13.0-SNAPSHOT</code>)</h3>
<div class="paragraph">
<p>The <code>InteractionContext</code> (<code>1.13.0-SNAPSHOT</code>) is a request-scoped domain service that is used to obtain the current <code>Interaction</code>.</p>
</div>
@@ -4194,7 +3670,7 @@ created explicitly through the <a href="#_rgsvc_api_BackgroundService"><code>Bac
<p>If a bulk action is performed (as per an action annotated using <a href="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="sect3">
-<h4 id="_api_implementatin">5.5.1. API & Implementatin</h4>
+<h4 id="_api_implementatin">4.5.1. API & Implementatin</h4>
<div class="paragraph">
<p>The public API of the service consists of several related classes:</p>
</div>
@@ -4408,7 +3884,7 @@ execution of this action invocation/property edit.</td>
</div>
</div>
<div class="sect3">
-<h4 id="_interacting_with_the_services_2">5.5.2. Interacting with the services</h4>
+<h4 id="_interacting_with_the_services_2">4.5.2. Interacting with the services</h4>
<div class="paragraph">
<p>Typically domain objects will have little need to interact with the <code>InteractionContext</code> and <code>Interaction</code> directly.
The services are used within the framework however, primarily to support the
@@ -4417,7 +3893,7 @@ The services are used within the framework however, primarily to support the
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_6">5.5.3. Registering the Service</h4>
+<h4 id="_registering_the_service_6">4.5.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default
@@ -4447,7 +3923,7 @@ implementations of <code>Interaction</code> to be used. If this were to be need
</div>
</div>
<div class="sect3">
-<h4 id="_rgsvc_api_InteractionContext_Related-Classes">5.5.4. Related Classes</h4>
+<h4 id="_rgsvc_api_InteractionContext_Related-Classes">4.5.4. Related Classes</h4>
<div class="paragraph">
<p>This service is very similar in nature to <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a>, in that the
<code>Interaction</code> object accessed through it is very similar to the <code>Command</code> object obtained from the <code>CommandContext</code>.
@@ -4464,7 +3940,7 @@ interaction/execution is deferred until some other mechanism invokes the command
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_MessageService">5.6. <code>MessageService</code></h3>
+<h3 id="_rgsvc_api_MessageService">4.6. <code>MessageService</code></h3>
<div class="paragraph">
<p>The <code>MessageService</code> allows domain objects to raise information, warning or error messages. These messages can either be simple strings, or can be translated.</p>
</div>
@@ -4483,7 +3959,7 @@ interaction/execution is deferred until some other mechanism invokes the command
</table>
</div>
<div class="sect3">
-<h4 id="_api_and_usage">5.6.1. API and Usage</h4>
+<h4 id="_api_and_usage">4.6.1. API and Usage</h4>
<div class="paragraph">
<p>The API of <code>MessageService</code> is:</p>
</div>
@@ -4547,13 +4023,13 @@ interaction/execution is deferred until some other mechanism invokes the command
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_16">5.6.2. Implementation</h4>
+<h4 id="_implementation_14">4.6.2. Implementation</h4>
<div class="paragraph">
<p>The core framework provides a default implementation of this service (<code>o.a.i.core.runtime.services.message.MessageServiceDefault</code>).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_7">5.6.3. Registering the Service</h4>
+<h4 id="_registering_the_service_7">4.6.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -4568,14 +4044,14 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_SessionManagementService">5.7. <code>SessionManagementService</code></h3>
+<h3 id="_rgsvc_api_SessionManagementService">4.7. <code>SessionManagementService</code></h3>
<div class="paragraph">
<p>The <code>SessionManagementService</code> provides the ability to programmatically manage sessions. The primary use case is
for fixture scripts or other routines that are invoked from the UI and which create or modify large amounts of data.
A classic example is migrating data from one system to another.</p>
</div>
<div class="sect3">
-<h4 id="_api">5.7.1. API</h4>
+<h4 id="_api">4.7.1. API</h4>
<div class="paragraph">
<p>The API of <code>SessionManagementService</code> is:</p>
</div>
@@ -4611,13 +4087,13 @@ session and start a new transaction.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_17">5.7.2. Implementation</h4>
+<h4 id="_implementation_15">4.7.2. Implementation</h4>
<div class="paragraph">
<p>The core framework provides a default implementation of this service (<code>o.a.i.core.runtime.services.xactn.SessionManagementServiceDefault</code>).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_8">5.7.3. Registering the Service</h4>
+<h4 id="_registering_the_service_8">4.7.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -4632,7 +4108,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_TitleService">5.8. <code>TitleService</code></h3>
+<h3 id="_rgsvc_api_TitleService">4.8. <code>TitleService</code></h3>
<div class="paragraph">
<p>The <code>TitleService</code> provides methods to programmatically obtain the title and icon of a domain object.</p>
</div>
@@ -4651,7 +4127,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</table>
</div>
<div class="sect3">
-<h4 id="_api_2">5.8.1. API</h4>
+<h4 id="_api_2">4.8.1. API</h4>
<div class="paragraph">
<p>The API of <code>TitleService</code> is:</p>
</div>
@@ -4677,7 +4153,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_usage_6">5.8.2. Usage</h4>
+<h4 id="_usage_5">4.8.2. Usage</h4>
<div class="paragraph">
<p>By way of example, here’s some code based on a system for managing government benefits:</p>
</div>
@@ -4702,13 +4178,13 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_18">5.8.3. Implementation</h4>
+<h4 id="_implementation_16">4.8.3. Implementation</h4>
<div class="paragraph">
<p>The core framework provides a default implementation of this service (<code>o.a.i.core.metamodel.services.title.TitleServiceDefault</code>).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_9">5.8.4. Registering the Service</h4>
+<h4 id="_registering_the_service_9">4.8.4. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -4723,7 +4199,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_TransactionService">5.9. <code>TransactionService</code></h3>
+<h3 id="_rgsvc_api_TransactionService">4.9. <code>TransactionService</code></h3>
<div class="paragraph">
<p>The <code>TransactionService</code> provides a small number of methods to allow domain objects to influence user transactions.</p>
</div>
@@ -4742,7 +4218,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</table>
</div>
<div class="sect3">
-<h4 id="_api_3">5.9.1. API</h4>
+<h4 id="_api_3">4.9.1. API</h4>
<div class="paragraph">
<p>The API of <code>TransactionService</code> is:</p>
</div>
@@ -4781,13 +4257,13 @@ end of the transaction, or immediately prior to the next query.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_19">5.9.2. Implementation</h4>
+<h4 id="_implementation_17">4.9.2. Implementation</h4>
<div class="paragraph">
<p>The core framework provides a default implementation of this service (<code>o.a.i.core.metamodel.services.xactn.TransactionServiceDefault</code>).</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_10">5.9.3. Registering the Service</h4>
+<h4 id="_registering_the_service_10">4.9.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -4802,7 +4278,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_WrapperFactory">5.10. <code>WrapperFactory</code></h3>
+<h3 id="_rgsvc_api_WrapperFactory">4.10. <code>WrapperFactory</code></h3>
<div class="paragraph">
<p>The <code>WrapperFactory</code> provides the ability to enforce business rules for programmatic interactions between domain objects. If there is a (lack-of-) trust boundary between the caller and callee — eg if they reside in different modules — then the wrapper factory is a useful mechanism to ensure that any business constraints defined by te callee are honoured.</p>
</div>
@@ -4830,7 +4306,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<p>This capability is frequently used within <a href="ugtst.html#_ugtst_integ-test-support">integration tests</a>, but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).</p>
</div>
<div class="sect3">
-<h4 id="_api_4">5.10.1. API</h4>
+<h4 id="_api_4">4.10.1. API</h4>
<div class="paragraph">
<p>The API provided by the service is:</p>
</div>
@@ -4939,7 +4415,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_usage_7">5.10.2. Usage</h4>
+<h4 id="_usage_6">4.10.2. Usage</h4>
<div class="paragraph">
<p>The caller will typically obtain the target object (eg from some repository) and then use the injected <code>WrapperFactory</code> to wrap it before interacting with it.</p>
</div>
@@ -4998,7 +4474,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_listener_api">5.10.3. Listener API</h4>
+<h4 id="_listener_api">4.10.3. Listener API</h4>
<div class="paragraph">
<p>The <code>WrapperFactory</code> also provides a listener API to allow other services to listen in on interactions.</p>
</div>
@@ -5042,7 +4518,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_service_11">5.10.4. Registering the Service</h4>
+<h4 id="_registering_the_service_11">4.10.4. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
@@ -5059,7 +4535,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect1">
-<h2 id="_rgsvc_application-layer-spi">6. Application Layer SPI</h2>
+<h2 id="_rgsvc_application-layer-spi">5. Application Layer SPI</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Domain service SPIs influence how the framework handles application layer concerns, for example which home page to render to the end-user.</p>
@@ -5068,7 +4544,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<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 in (non-ASF) <a href="http://www.isisaddons.org">Isis Addons</a> modules.</p>
</div>
<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 4. Application Layer SPI</caption>
+<caption class="title">Table 3. Application Layer SPI</caption>
<colgroup>
<col style="width: 25%;">
<col style="width: 50%;">
@@ -5151,7 +4627,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</ul>
</div>
<div class="sect2">
-<h3 id="_rgsvc_spi_BackgroundCommandService">6.1. <code>BackgroundCommandService</code></h3>
+<h3 id="_rgsvc_spi_BackgroundCommandService">5.1. <code>BackgroundCommandService</code></h3>
<div class="paragraph">
<p>The <code>BackgroundCommandService</code> (SPI) service supports the <a href="#_rgsvc_api_BackgroundService"><code>BackgroundService</code></a> (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.</p>
</div>
@@ -5162,7 +4638,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
<p>The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The abstract <a href="#_rgsvc_api_BackgroundService_BackgroundCommandExecution"><code>BackgroundCommandExecution</code></a> provides a mechanism to execute such commands. This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.</p>
</div>
<div class="sect3">
-<h4 id="_spi_17">6.1.1. SPI</h4>
+<h4 id="_spi_15">5.1.1. SPI</h4>
<div class="paragraph">
<p>The SPI of the <code>BackgroundCommandService</code> is:</p>
</div>
@@ -5219,7 +4695,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="__internal_spi">6.1.2. "Internal" SPI</h4>
+<h4 id="__internal_spi">5.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.html#_ugbtb_headless-access_AbstractIsisSessionTemplate">headless access</a>, that defines an abstract hook method to obtain background `Command`s to be executed:</p>
</div>
@@ -5238,7 +4714,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_20">6.1.3. Implementation</h4>
+<h4 id="_implementation_18">5.1.3. Implementation</h4>
<div class="paragraph">
<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> 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>
@@ -5271,7 +4747,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_usage_8">6.1.4. Usage</h4>
+<h4 id="_usage_7">5.1.4. Usage</h4>
<div class="paragraph">
<p>Background commands can be created either declaratively or imperatively.</p>
</div>
@@ -5283,7 +4759,7 @@ in the <a href="#_rgsvc_intro_overriding-the-services">introduction</a> to this
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_services_13">6.1.5. Registering the Services</h4>
+<h4 id="_registering_the_services_11">5.1.5. Registering the Services</h4>
<div class="paragraph">
<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> module provides an implementation
of this service (<code>BackgroundCommandService</code>), and also provides a number of related domain services
@@ -5301,7 +4777,7 @@ then this can be activated by updating the <code>pom.xml</code> and updating the
</div>
</div>
<div class="sect3">
-<h4 id="_related_services_15">6.1.6. Related Services</h4>
+<h4 id="_related_services_13">5.1.6. Related Services</h4>
<div class="paragraph">
<p>As discussed above, this service supports the <a href="#_rgsvc_api_BackgroundService"><code>BackgroundService</code></a> , persisting `Command`s such that they can be executed in the background.</p>
</div>
@@ -5314,7 +4790,7 @@ then this can be activated by updating the <code>pom.xml</code> and updating the
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_spi_CommandService">6.2. <code>CommandService</code></h3>
+<h3 id="_rgsvc_spi_CommandService">5.2. <code>CommandService</code></h3>
<div class="paragraph">
<p>The <code>CommandService</code> service supports the <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a> service such
that <code>Command</code> objects (that reify the invocation of an action/edit of a property on a domain object) can be persisted.</p>
@@ -5348,7 +4824,7 @@ time) ++</p>
</ul>
</div>
<div class="sect3">
-<h4 id="_screencast">6.2.1. Screencast</h4>
+<h4 id="_screencast">5.2.1. Screencast</h4>
<div class="paragraph">
<p>The <a href="https://www.youtube.com/watch?v=tqXUZkPB3EI">screencast</a> below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.</p>
</div>
@@ -5368,7 +4844,7 @@ time) ++</p>
</div>
</div>
<div class="sect3">
-<h4 id="_spi_18">6.2.2. SPI</h4>
+<h4 id="_spi_16">5.2.2. SPI</h4>
<div class="paragraph">
<p>The <code>CommandService</code> service defines the following very simple API:</p>
</div>
@@ -5410,7 +4886,7 @@ flag and persistence hint (<code>Command#isPersistHint()</code>) indicate that i
</div>
</div>
<div class="sect3">
-<h4 id="_implementation_21">6.2.3. Implementation</h4>
+<h4 id="_implementation_19">5.2.3. Implementation</h4>
<div class="paragraph">
<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> 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>
@@ -5426,13 +4902,13 @@ flag and persistence hint (<code>Command#isPersistHint()</code>) indicate that i
</div>
</div>
<div class="sect3">
-<h4 id="_usage_9">6.2.4. Usage</h4>
+<h4 id="_usage_8">5.2.4. Usage</h4>
<div class="paragraph">
<p>The typical way to indicate that an action should be reified into a <code>Command</code> is by annotating the action using <a href="rgant.html#_rgant-Action_command"><code>@Action#command()</code></a>.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_registering_the_services_14">6.2.5. Registering the Services</h4>
+<h4 id="_registering_the_services_12">5.2.5. Registering the Services</h4>
<div class="paragraph">
<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-command">Isis addons' command</a> module provides an implementation
of this service (<code>CommandService</code>), and also provides a number of related domain services
@@ -5450,7 +4926,7 @@ then this can be activated by updating the <code>pom.xml</code> and updating the
</div>
</div>
<div class="sect3">
-<h4 id="_related_services_16">6.2.6. Related Services</h4>
+<h4 id="_related_services_14">5.2.6. Related Services</h4>
<div class="paragraph">
<p>As discussed above, this service supports the <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a>, providing the ability for <code>Command</code> objects to be
persisted. This is closely related to the <a href="#_rgsvc_spi_BackgroundCommandService"><code>BackgroundCommandService</code></a>that allows the <a href="#_rgsvc_api_BackgroundService"><code>BackgroundService</code></a> to schedule commands for background/asynchronous execution.</p>
@@ -5470,7 +4946,7 @@ persisted. This is closely related to the <a href="#_rgsvc_spi_BackgroundCommand
</div>
</div>
<div class="sect2">
-<h3 id="_rgsvc_api_HomePageProviderService">6.3. <code>HomePageProviderService</code></h3>
+<h3 id="_rgsvc_api_HomePageProviderService">5.3. <code>HomePageProviderService</code></h3>
<div class="paragraph">
<p>This service simply provides access to the home page object (if any) that is returned from the domain service
action annotated with <a href="rgant.html#_rgant-HomePage"><code>@HomePage</code></a>.</p>
@@ -5478,264 +4954,40 @@ action annotated with <a href="rgant.html#_rgant-HomePage"><code>@HomePage</code
<div class="paragraph">
<p>It is originally introduced to support the default implementation of
<a href="#_rgsvc_spi_RoutingService"><code>RoutingService</code></a>, but was factored out to support alternative implementations
-of that service (and may be useful for other use cases).</p>
-</div>
-<div class="sect3">
-<h4 id="_api_implementation_5">6.3.1. API & Implementation</h4>
-<div class="paragraph">
-<p>The API defined by <code>HomePageProviderService</code> is:</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">interface</span> <span class="class">HomePageProviderService</span> {
- <span class="annotation">@Programmatic</span>
- <span class="predefined-type">Object</span> homePage();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The default implementation is provided by <code>o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault</code>.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_registering_the_service_12">6.3.2. Registering the Service</h4>
-<div class="paragraph">
-<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
-implementation of <code>HomePageProviderService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further
-configuration is required.</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rgsvc_application-layer-internal-spi">7. Application Layer internal SPI</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>These domain services are internal to the framework, controlling various aspects of the application layer.</p>
-</div>
-<div class="admonitionblock warning">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>We do not guarantee that <a href="http://semver.org">semantic versioning</a> will be honoured for these SPIs.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The table below summarizes the application layer internal 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://www.isisaddons.org">Isis Addons</a> modules.</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 5. "Internal" SPI Services</caption>
-<colgroup>
-<col style="width: 30%;">
-<col style="width: 30%;">
-<col style="width: 20%;">
-<col style="width: 20%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">SPI</th>
-<th class="tableblock halign-left valign-top">Maven Module<br>
-Impl’n (g: a:)</th>
-<th class="tableblock halign-left valign-top">Implementation</th>
-<th class="tableblock halign-left valign-top">Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_api_CommandDtoServiceInternal"><code>o.a.i.c.</code><br>
-<code>m.s.command</code><br>
-<code>CommandDtoServiceInternal</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">(<code>1.13.0-SNAPSHOT</code>) Creates memento of current action invocation, for use as a serializable XML reified command. The
-most notable usage of this is to allow the execution of the <code>Command</code> to be deferred to run in the background (via
-<a href="rgant.html#_rgant-Action_command"><code>@Action#commandExecuteIn()</code></a> or
-<a href="rgant.html#_rgant-Property_command"><code>@Property#commandExecuteIn()</code></a>.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CommandDtoService-</code><br>
-<code>InternalServiceDefault</code><br>
-<code>o.a.i.c.r.s.command</code><br>
-<code>isis-core-runtime</code></p></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_api_InteractionDtoServiceInternal"><code>o.a.i.c.</code><br>
-<code>m.s.ixn</code><br>
-<code>InteractionDtoServiceInternal</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">(<code>1.13.0-SNAPSHOT</code>) Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the <a href="#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CommandDtoService-</code><br>
-<code>InternalServiceDefault</code><br>
-<code>o.a.i.c.m.s.command</code><br>
-<code>isis-core-metamodel</code></p></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
-<p>Key:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>o.a.i</code> is an abbreviation for <code>org.apache.isis</code></p>
-</li>
-<li>
-<p><code>o.ia.m</code> is an abbreviation for <code>org.isisaddons.module</code></p>
-</li>
-<li>
-<p><code>o.a.i.c.m.s</code> is an abbreviation for <code>org.apache.isis.core.metamodel.services</code></p>
-</li>
-<li>
-<p><code>o.a.i.c.r.s</code> is an abbreviation for <code>org.apache.isis.core.runtime.services</code></p>
-</li>
-</ul>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_spi_CommandDtoServiceInternal">7.1. <code>CommandDtoServiceInternal</code> (<code>1.13.0-SNAPSHOT</code>)</h3>
-<div class="paragraph">
-<p>The <code>CommandDtoServiceInternal</code> (<code>1.13.0-SNAPSHOT</code>) is responsible for creating an memento of the current action
-invocation or property edit, to store in the <code>Command</code> object (from
-<a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a>). This memento is a JAXB DTO being an instance of the
-<a href="rgcms.html#_rgcms_schema-cmd">"cmd" schema</a>, so can be reified so that its execution can be deferred until later,
-as a <a href="#_rgsvc_spi_BackgroundCommandService">background command</a>.</p>
-</div>
-<div class="sect3">
-<h4 id="_spi_implementation">7.1.1. SPI & Implementation</h4>
-<div class="paragraph">
-<p>The SPI of the service 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">CommandDtoServiceInternal</span> {
- <span class="annotation">@Deprecated</span>
- ActionInvocationMemento asActionInvocationMemento( <i class="conum" data-value="1"></i><b>(1)</b>
- <span class="predefined-type">Method</span> m,
- <span class="predefined-type">Object</span> domainObject, <span class="predefined-type">Object</span><span class="type">[]</span> args);
- CommandDto asCommandDto( <i class="conum" data-value="2"></i><b>(2)</b>
- <span class="predefined-type">List</span><ObjectAdapter> targetAdapters,
- ObjectAction objectAction,
- ObjectAdapter<span class="type">[]</span> argAdapters);
- CommandDto asCommandDto( <i class="conum" data-value="3"></i><b>(3)</b>
- <span class="directive">final</span> <span class="predefined-type">List</span><ObjectAdapter> targetAdapters,
- <span class="directive">final</span> OneToOneAssociation association,
- <span class="directive">final</span> ObjectAdapter valueAdapterOrNull);
- <span class="type">void</span> addActionArgs( <i class="conum" data-value="4"></i><b>(4)</b>
- <span class="directive">final</span> ObjectAction objectAction,
- <span class="directive">final</span> ActionDto actionDto,
- <span class="directive">final</span> ObjectAdapter<span class="type">[]</span> argAdapters);
- <span class="type">void</span> addPropertyValue( <i class="conum" data-value="5"></i><b>(5)</b>
- <span class="directive">final</span> OneToOneAssociation property,
- <span class="directive">final</span> PropertyDto propertyDto,
- <span class="directive">final</span> ObjectAdapter valueAdapter);
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>Note that this method (more precisely, <code>ActionInvocationMemento</code>) does <em>not</em> support mixins.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>Returns a JAXB DTO being an instance of the <a href="rgcms.html#_rgcms_schema-cmd">"cmd" schema</a> (hence convertible to
-XML) that represents the <em>intention</em> to invoke an action on a target object (or possibly many targets, for
-bulk actions). If an action, it can also be either mixin action or a contributed action.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>Returns a JAXB DTO that represents the intention to edit (set or clear) a property on a target (or possibly many
-targets, for symmetry with actions).</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>add the arguments of an action to an <code>ActionDto</code>. This is used when the command is actually executed (per <a href="#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a>) to populate the parameters of the equivalent <code>ActionInvocationDto</code>.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>add the new value argument of a property to a <code>PropertyDto</code>. This is used when the command is actually executed (per <a href="#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a>) to set the the new value of the equivalent <code>PropertyEditDto</code>.</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The SPI is implemented by <code>o.a.i.c.r.s.command.CommandDtoServiceInternalServiceDefault</code>.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_related_services_17">7.1.2. Related Services</h4>
-<div class="paragraph">
-<p>The design of this service is similar to that of <a href="#_rgsvc_spi_InteractionDtoServiceInternal"><code>InteractionDtoServiceInternal</code></a>, used to create the <code>MemberExecutionDto</code> (from the <a href="rgcms.html#_rgcms_schema-ixn">"ixn" schema</a>).</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_spi_InteractionDtoServiceInternal">7.2. <code>InteractionDtoServiceInternal</code> (<code>1.13.0-SNAPSHOT</code>)</h3>
-<div class="paragraph">
-<p>The <code>InteractionDtoServiceInternal</code> internal domain service (<code>1.13.0-SNAPSHOT</code>) is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property. The DTO is in all cases a subclass of <code>MemberExecutionDto</code>, from the <a href="rgcms.html#_rgcms_schema-ixn">"ixn" schema</a>, and subsequently accessible from the <code>Interaction</code> object (per the <a href="#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a> service).</p>
+of that service (and may be useful for other use cases).</p>
</div>
<div class="sect3">
-<h4 id="_spi_implementation_2">7.2.1. SPI & Implementation</h4>
+<h4 id="_api_implementation_5">5.3.1. API & Implementation</h4>
<div class="paragraph">
-<p>The SPI of the service is:</p>
+<p>The API defined by <code>HomePageProviderService</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">InteractionDtoServiceInternal</span> {
- ActionInvocationDto asActionInvocationDto( <i class="conum" data-value="1"></i><b>(1)</b>
- ObjectAction objectAction,
- ObjectAdapter targetAdapter,
- <span class="predefined-type">List</span><ObjectAdapter> argumentAdapters);
- PropertyEditDto asPropertyEditDto( <i class="conum" data-value="2"></i><b>(2)</b>
- OneToOneAssociation property,
- ObjectAdapter targetAdapter,
- ObjectAdapter newValueAdapterIfAny);
- ActionInvocationDto updateResult( <i class="conum" data-value="3"></i><b>(3)</b>
- ActionInvocationDto actionInvocationDto,
- ObjectAction objectAction,
- <span class="predefined-type">Object</span> resultPojo);
+<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> {
+ <span class="annotation">@Programmatic</span>
+ <span class="predefined-type">Object</span> homePage();
}</code></pre>
</div>
</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>called by the framework when invoking an action, to create a DTO capturing the details of the action invocation (target, arguments etc).</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>called by the framework when editing a property, to create a DTO (for the <a href="rgcms.html#_rgcms_schema-ixn">"ixn" schema</a>) capturing the details of the property edit (target, new value etc).</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>called by the framework to attach the result of an action invocation to the aforementioned DTO.</td>
-</tr>
-</table>
-</div>
<div class="paragraph">
-<p>The service is implemented by <code>o.a.i.core.runtime.services.ixn.InteractionDtoServiceInternalDefault</code>.</p>
+<p>The default implementation is provided by <code>o.a.i.core.runtime.services.homepage.HomePageProviderServiceDefault</code>.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_related_services_18">7.2.2. Related Services</h4>
+<h4 id="_registering_the_service_12">5.3.2. Registering the Service</h4>
<div class="paragraph">
-<p>The design of this service is similar to that of <a href="#_rgsvc_spi_CommandDtoServiceInternal"><code>CommandDtoServiceInternal</code></a>, used to create the <code>CommandDto</code> (from the <a href="rgcms.html#_rgcms_schema-cmd">"cmd" schema</a>).</p>
+<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
+<code>AppManifest</code> to <a href="rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>HomePageProviderService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further
+configuration is required.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
-<h2 id="_rgsvc_core-domain-api">8. Core/Domain API</h2>
+<h2 id="_rgsvc_core-domain-api">6. Core/Domain API</h2>
<div class="sectionbody">
<div class="paragraph">
<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>
@@ -5744,7 +4996,7 @@ targets, for symmetry with actions).</td>
<p>The table below summarizes the core/domain APIs defined by
<TRUNCATED>