You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/08 00:00:29 UTC
[31/44] isis-site git commit: ISIS-1594: provide an 'edit' button
http://git-wip-us.apache.org/repos/asf/isis-site/blob/83a3755a/content/guides/rgfis.html
----------------------------------------------------------------------
diff --git a/content/guides/rgfis.html b/content/guides/rgfis.html
index c363240..8e42879 100644
--- a/content/guides/rgfis.html
+++ b/content/guides/rgfis.html
@@ -1,12 +1,10 @@
<!doctype html>
<html class="no-js" lang="en">
-<head>
- <meta charset="utf-8"/>
- <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
-
- <title>Framework Internal Services</title>
-
- <!--
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Framework Internal Services</title>
+ <!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
@@ -23,31 +21,21 @@
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
- -->
-
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache" />
- <meta http-equiv="pragma" content="no-cache" />
- <meta http-equiv="expires" content="-1" />
-
-
- <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
- <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" />
- <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
- <link href="../css/asciidoctor/colony.css" rel="stylesheet">
- <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
- <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />
- <!--[if lt IE 9]>
+ -->
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache">
+ <meta http-equiv="pragma" content="no-cache">
+ <meta http-equiv="expires" content="-1">
+ <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
+ <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet">
+ <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
+ <link href="../css/asciidoctor/colony.css" rel="stylesheet">
+ <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet">
+ <!--[if lt IE 9]>
<link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.ie.css" rel="stylesheet" />
- <![endif]-->
-
-
-
- <style type="text/css">
+ <![endif]-->
+ <style type="text/css">
pre code {
background-color: inherit;
border-style: none;
@@ -192,9 +180,8 @@ table.CodeRay td.code>pre{padding:0}
color:#fff;
font-size: 1.1em;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 40.063em) {
.top-bar {
.contain-to-grid .top-bar {
@@ -205,9 +192,8 @@ table.CodeRay td.code>pre{padding:0}
.row {
max-width: 80rem;
}
- </style>
-
- <style>
+ </style>
+ <style>
.extended-quote,
.extended-quote-first {
margin-left: 40px;
@@ -231,9 +217,8 @@ table.CodeRay td.code>pre{padding:0}
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
}
- </style>
-
- <style>
+ </style>
+ <style>
body {
position: relative;
}
@@ -255,6 +240,7 @@ table.CodeRay td.code>pre{padding:0}
div#doc-content {
margin-top: 30px;
+ padding-top: 30px;
}
div.documentation-page table.frame-all {
@@ -286,9 +272,8 @@ table.CodeRay td.code>pre{padding:0}
min-height: 2000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 768px) {
#toc.toc2 ul ul { margin-left: -10px; }
@@ -316,15 +301,13 @@ table.CodeRay td.code>pre{padding:0}
body div#toc2 li.tocify-item.active a {
color: red;
}
- </style>
-
- <style>
+ </style>
+ <style>
footer {
margin-top: 1000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* overriding colony.css stylesheet */
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
/*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
@@ -372,9 +355,8 @@ table.CodeRay td.code>pre{padding:0}
.imageblock img {
margin-bottom: 10px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
.header-link {
position: absolute;
@@ -395,9 +377,8 @@ table.CodeRay td.code>pre{padding:0}
h6:hover .header-link {
opacity: 1;
}
- </style>
-
- <style>
+ </style>
+ <style>
.top-bar
{
-webkit-transition-duration: .5s;
@@ -425,314 +406,234 @@ table.CodeRay td.code>pre{padding:0}
-webkit-transition-property: -webkit-transform;
transition-property: transform;
}
- </style>
-
- <style>
+ </style>
+ <style>
#doc-content a.guide {
color: white;
}
- </style>
-
- <style>
+ </style>
+ <style>
+ .tocify {
+ margin-top: 80px;
+ }
+ </style>
+ <style>
.tocify {
margin-top: 80px;
}
- </style>
-
-
-</script>
-
-</head>
-<body>
-
-<<div class="github-fork-ribbon-wrapper right" style="position: fixed;">
- <div class="github-fork-ribbon">
- <a href="https://github.com/apache/isis#fork-destination-box">Fork me on GitHub</a>
- </div>
-</div>
-
-
-<div class="row">
-
- <div class="fixed contain-to-grid header">
- <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
- <ul class="title-area">
- <li class="name">
- <h1>
- <a href="/index.html">Apache Isis™</a>
- </h1>
- </li>
- <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
- <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
- </ul>
-
- <section class="top-bar-section">
- <ul class="right">
-
- <li class="has-form">
- <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
- <div class="row collapse">
- <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
- <INPUT type="hidden" name="cof" value="FORID:0">
- <INPUT class="form-control" name="q" type="text" placeholder="Search">
- </div>
- </FORM>
- </li>
-
- </ul>
-
- <!-- Left Nav Section -->
- <ul class="left">
-
- <li><a href="/documentation.html">Documentation</a></li>
- <li><a href="/downloads.html">Downloads</a></li>
- <li><a href="/help.html">Help</a></li>
- <li><a href="/asf.html">@ASF</a></li>
-
- </ul>
-
- </section>
- </nav>
- </div>
-</div>
-
-<div class="row">
-
- <div id="doc-content-left" class="large-9 medium-9 columns">
-
-
- <div id="doc-content">
- <div class="sect1">
-<h2 id="_rgfis">1. Framework Internal Services</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This guide documents a number of domain services that are not part of the framework’s formal API, they use classes that are outside of the applib. They should be
-thought of as part of the internal design of the framework, and are liable to change from release to release.</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 services.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="sect2">
-<h3 id="_other_guides">1.1. Other Guides</h3>
-<div class="paragraph">
-<p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
-</div>
-<div class="paragraph">
-<p>The user guides available are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="ugfun.html">Fundamentals</a></p>
-</li>
-<li>
-<p><a href="ugvw.html">Wicket viewer</a></p>
-</li>
-<li>
-<p><a href="ugvro.html">Restful Objects viewer</a></p>
-</li>
-<li>
-<p><a href="ugdno.html">DataNucleus object store</a></p>
-</li>
-<li>
-<p><a href="ugsec.html">Security</a></p>
-</li>
-<li>
-<p><a href="ugtst.html">Testing</a></p>
-</li>
-<li>
-<p><a href="ugbtb.html">Beyond the Basics</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The reference guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="rgant.html">Annotations</a></p>
-</li>
-<li>
-<p><a href="rgsvc.html">Domain Services</a></p>
-</li>
-<li>
-<p><a href="rgcfg.html">Configuration Properties</a></p>
-</li>
-<li>
-<p><a href="rgcms.html">Classes, Methods and Schema</a></p>
-</li>
-<li>
-<p><a href="rgmvn.html">Apache Isis Maven plugin</a></p>
-</li>
-<li>
-<p><a href="#">Framework Internal Services</a> (this guide)</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The remaining guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p>
-</li>
-<li>
-<p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rgfis_presentation-layer">2. Presentation Layer</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="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 1. Internal 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="#_rgfis_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.html#_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="#_rgfis_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="#_rgfis_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="_rgfis_spi_ContentNegotiationService">2.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 three implementations of <code>ContentNegotiationService</code> which inspects different elements of the HTTP <code>Accept</code> header. One of these implementations, <code>ContentNegotiationServiceXRoDomainType</code> will further delegate down to the companion <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> service (if configured/available), based on the value of the "x-ro-domain-type" parameter of the header.<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">2.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> {
+ </style>
+ </head>
+ <body>
+ <div class="row">
+ <div class="fixed contain-to-grid header">
+ <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
+ <ul class="title-area">
+ <li class="name"> <h1> <a href="/index.html">Apache Isis\u2122</a> </h1> </li>
+ <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
+ <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
+ </ul>
+ <section class="top-bar-section">
+ <ul class="right">
+ <li class="has-form">
+ <form class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="row collapse">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <input type="hidden" name="cof" value="FORID:0">
+ <input class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </form> </li>
+ </ul>
+ <!-- Left Nav Section -->
+ <ul class="left">
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/downloads.html">Downloads</a></li>
+ <li><a href="/help.html">Help</a></li>
+ <li><a href="/asf.html">@ASF</a></li>
+ </ul>
+ </section>
+ </nav>
+ </div>
+ </div>
+ <div class="row">
+ <div id="doc-content-left" class="large-9 medium-9 columns">
+ <div id="doc-content">
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgfis.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_rgfis">1. Framework Internal Services</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_rgfis.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This guide documents a number of domain services that are not part of the framework\u2019s formal API, they use classes that are outside of the applib. They should be thought of as part of the internal design of the framework, and are liable to change from release to release.</p>
+ </div>
+ <div class="admonitionblock warning">
+ <table>
+ <tbody>
+ <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 services.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="ugfun.html">Fundamentals</a></p> </li>
+ <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li>
+ <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="ugsec.html">Security</a></p> </li>
+ <li> <p><a href="ugtst.html">Testing</a></p> </li>
+ <li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The reference guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="rgant.html">Annotations</a></p> </li>
+ <li> <p><a href="rgsvc.html">Domain Services</a></p> </li>
+ <li> <p><a href="rgcfg.html">Configuration Properties</a></p> </li>
+ <li> <p><a href="rgcms.html">Classes, Methods and Schema</a></p> </li>
+ <li> <p><a href="rgmvn.html">Apache Isis Maven plugin</a></p> </li>
+ <li> <p><a href="#">Framework Internal Services</a> (this guide)</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The remaining guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li>
+ <li> <p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_rgfis_presentation-layer">2. Presentation Layer</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <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="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 1. Internal 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\u2019n (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="#_rgfis_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.html#_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="#_rgfis_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="#_rgfis_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="_rgfis_spi_ContentNegotiationService">2.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 three implementations of <code>ContentNegotiationService</code> which inspects different elements of the HTTP <code>Accept</code> header. One of these implementations, <code>ContentNegotiationServiceXRoDomainType</code> will further delegate down to the companion <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> service (if configured/available), based on the value of the "x-ro-domain-type" parameter of the header.<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">2.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> {
Response.ResponseBuilder buildResponse( <i class="conum" data-value="1"></i><b>(1)</b>
RepresentationService.Context2 renderContext2,
ObjectAdapter objectAdapter);
@@ -748,61 +649,59 @@ Impl’n (g: a:)</th>
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>
-<div class="sect3">
-<h4 id="_implementation">2.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 {
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <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>
+ </tbody>
+ </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>
+ <div class="sect3">
+ <h4 id="_implementation">2.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) { ... }
@@ -812,185 +711,164 @@ Impl’n (g: a:)</th>
<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 three implementation of this service, one of which is <code>o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType</code>. This implementation 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.html#_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 class="paragraph">
-<p>The other two implementations of <code>ContentNegotiationService</code> are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>ContentNegotiationServiceForRestfulObjectsV1_0</code><br></p>
-<div class="paragraph">
-<p>which returns representations according to the <a href="http://restfulobjects.org">Restful Objects</a> spec</p>
-</div>
-</li>
-<li>
-<p><code>ContentNegotiationServiceOrgApacheIsisV1</code><br></p>
-<div class="paragraph">
-<p>which returns <a href="ugvro.html#_ugvro_simplified-representations">simplified representations</a></p>
-</div>
-</li>
-</ul>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_usage">2.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">2.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">2.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
-implementations of <code>ContentNegotiationService</code> service are 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.html#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_related_services">2.1.6. Related Services</h4>
-<div class="paragraph">
-<p>The default implementation of <code>ContentNegotiationService</code> delegates to <a href="rgsvc.html#_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="#_rgfis_spi_RepresentationService"><code>RepresentationService</code></a>.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgfis_spi_RepresentationService">2.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="#_rgfis_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="#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>and the <a href="rgsvc.html#_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_2">2.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> {
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>As discussed in the introduction, the framework also provides three implementation of this service, one of which is <code>o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType</code>. This implementation 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=\u2026\u200b</code></p> </li>
+ <li> <p><code>application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=\u2026\u200b</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=\u2026\u200b</code><br></p> </li>
+ <li> <p><code>application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=\u2026\u200b</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.html#_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 class="paragraph">
+ <p>The other two implementations of <code>ContentNegotiationService</code> are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>ContentNegotiationServiceForRestfulObjectsV1_0</code><br></p>
+ <div class="paragraph">
+ <p>which returns representations according to the <a href="http://restfulobjects.org">Restful Objects</a> spec</p>
+ </div> </li>
+ <li> <p><code>ContentNegotiationServiceOrgApacheIsisV1</code><br></p>
+ <div class="paragraph">
+ <p>which returns <a href="ugvro.html#_ugvro_simplified-representations">simplified representations</a></p>
+ </div> </li>
+ </ul>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_usage">2.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">2.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">2.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 implementations of <code>ContentNegotiationService</code> service are 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.html#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_related_services">2.1.6. Related Services</h4>
+ <div class="paragraph">
+ <p>The default implementation of <code>ContentNegotiationService</code> delegates to <a href="rgsvc.html#_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="#_rgfis_spi_RepresentationService"><code>RepresentationService</code></a>.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgfis_spi_RepresentationService">2.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="#_rgfis_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="#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>and the <a href="rgsvc.html#_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\u2019ll see that the default implementation of this service\u2019s 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\u2019ll notice that their SPIs are very similar).</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_spi_2">2.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> {
Response objectRepresentation( <i class="conum" data-value="1"></i><b>(1)</b>
<span class="predefined-type">Context</span> rendererContext,
ObjectAdapter objectAdapter);
@@ -1012,225 +890,197 @@ in the <a href="rgsvc.html#_rgsvc_intro_overriding-the-services">introduction</a
<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>
-<div class="sect3">
-<h4 id="_implementation_2">2.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.RepresentationServiceContentNegotiator</code>. This delegates to <a href="#_rgfis_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.html#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_registering_the_services_2">2.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_2">2.2.4. Related Services</h4>
-<div class="paragraph">
-<p>The default implementation delegates to <a href="#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>, whose default implementation may delegate in turn to <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> (if present).</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rgfis_application-layer">3. Application Layer</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="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 2. Internal 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="#_rgfis_spi_AuthenticationSessionProvider"><code>o.a.i.core.commons.</code><br>
-<code>authentication.</code><br>
-<code>AuthenticationSessionProvider</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Simply responsible for obtaining the current <code>AuthenticationSession</code> (the framework’s internal representation of the currently logged-in user).</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>AuthenticationSession-</code><br>
-<code>ProviderDefault</code><br>
-<code>isis-core-runtime</code></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Default implementation looks up from <code>IsisSessionFactory</code> singleton’s thread-local</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgfis_spi_CommandDtoServiceInternal"><code>o.a.i.c.m.s.command</code><br>
-<code>CommandDtoServiceInternal</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">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>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="#_rgfis_spi_MessageBrokerServiceInternal"><code>o.a.i.c.m.s.msgbroker</code><br>
-<code>MessageBrokerServiceInternal</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A wrapper around <a href="rgsvc.html#_rgsvc_api_MessageService"><code>MessageService</code></a>.</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">MessageBrokerService-`<br>
-<code>InternalDefault</code><br>
-<code>isis-core-runtime</code></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>This service does not provide any additional capabilities over <code>MessageService</code>, and will (most likely) be conflated with that service in the future.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgfis_spi_InteractionDtoServiceInternal"><code>o.a.i.c.m.s.ixn</code><br>
-<code>InteractionDtoServiceInternal</code></a></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">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.html#_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>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="_rgfis_spi_AuthenticationSessionProvider">3.1. <code>AuthenticationSessionProvider</code></h3>
-<div class="paragraph">
-<p>The (internal) <code>AuthenticationSessionProvider</code> domain service is simply responsible for obtaining the <code>AuthenticationSession</code> (being the framework’s internal representation of the currently logged in user).</p>
-</div>
-<div class="sect3">
-<h4 id="_spi_and_implementation">3.1.1. SPI and 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">AuthenticationSessionProvider</span> {
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <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>
+ </tbody>
+ </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>
+ <div class="sect3">
+ <h4 id="_implementation_2">2.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.RepresentationServiceContentNegotiator</code>. This delegates to <a href="#_rgfis_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.html#_rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_registering_the_services_2">2.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_2">2.2.4. Related Services</h4>
+ <div class="paragraph">
+ <p>The default implementation delegates to <a href="#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>, whose default implementation may delegate in turn to <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> (if present).</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_rgfis_application-layer">3. Application Layer</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <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="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 2. Internal 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\u2019n (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="#_rgfis_spi_AuthenticationSessionProvider"><code>o.a.i.core.commons.</code><br> <code>authentication.</code><br> <code>AuthenticationSessionProvider</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Simply responsible for obtaining the current <code>AuthenticationSession</code> (the framework\u2019s internal representation of the currently logged-in user).</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AuthenticationSession-</code><br> <code>ProviderDefault</code><br> <code>isis-core-runtime</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Default implementation looks up from <code>IsisSessionFactory</code> singleton\u2019s thread-local</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgfis_spi_CommandDtoServiceInternal"><code>o.a.i.c.m.s.command</code><br> <code>CommandDtoServiceInternal</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">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>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="#_rgfis_spi_MessageBrokerServiceInternal"><code>o.a.i.c.m.s.msgbroker</code><br> <code>MessageBrokerServiceInternal</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">A wrapper around <a href="rgsvc.html#_rgsvc_api_MessageService"><code>MessageService</code></a>.</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">MessageBrokerService-`<br> <code>InternalDefault</code><br> <code>isis-core-runtime</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>This service does not provide any additional capabilities over <code>MessageService</code>, and will (most likely) be conflated with that service in the future.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgfis_spi_InteractionDtoServiceInternal"><code>o.a.i.c.m.s.ixn</code><br> <code>InteractionDtoServiceInternal</code></a></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">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.html#_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>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="_rgfis_spi_AuthenticationSessionProvider">3.1. <code>AuthenticationSessionProvider</code></h3>
+ <div class="paragraph">
+ <p>The (internal) <code>AuthenticationSessionProvider</code> domain service is simply responsible for obtaining the <code>AuthenticationSession</code> (being the framework\u2019s internal representation of the currently logged in user).</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_spi_and_implementation">3.1.1. SPI and 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">AuthenticationSessionProvider</span> {
AuthenticationSession getAuthenticationSession();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The framework provides a default implementation of the service, <code>AuthenticationSessionProviderDefault</code>, which looks up
-the current <code>AuthenticationSession</code> from <code>IsisSessionFactory</code> singleton service:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">isisSessionFactory.getCurrentSession().getAuthenticationSession();</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>If <a href="rgsvc.html#_rgsvc_api_SudoService"><code>SudoService</code></a> has been used to temporarily override the user and/or roles, then this service will report the overridden values.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgfis_spi_CommandDtoServiceInternal">3.2. <code>CommandDtoServiceInternal</code></h3>
-<div class="paragraph">
-<p>The <code>CommandDtoServiceInternal</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.html#_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.html#_rgsvc_spi_BackgroundCommandService">background command</a>.</p>
-</div>
-<div class="sect3">
-<h4 id="_spi_implementation">3.2.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> {
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The framework provides a default implementation of the service, <code>AuthenticationSessionProviderDefault</code>, which looks up the current <code>AuthenticationSession</code> from <code>IsisSessionFactory</code> singleton service:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java">isisSessionFactory.getCurrentSession().getAuthenticationSession();</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>If <a href="rgsvc.html#_rgsvc_api_SudoService"><code>SudoService</code></a> has been used to temporarily override the user and/or roles, then this service will report the overridden values.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgfis_spi_CommandDtoServiceInternal">3.2. <code>CommandDtoServiceInternal</code></h3>
+ <div class="paragraph">
+ <p>The <code>CommandDtoServiceInternal</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.html#_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.html#_rgsvc_spi_BackgroundCommandService">background command</a>.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_spi_implementation">3.2.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,
@@ -1251,118 +1101,108 @@ as a <a href="rgsvc.html#_rgsvc_spi_BackgroundCommandService">background command
<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.html#_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.html#_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_3">3.2.2. Related Services</h4>
-<div class="paragraph">
-<p>The design of this service is similar to that of
-<a href="#_rgfis_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="
<TRUNCATED>