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:25 UTC
[27/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/rgsvc.html
----------------------------------------------------------------------
diff --git a/content/guides/rgsvc.html b/content/guides/rgsvc.html
index b4ba83e..5ab2ef1 100644
--- a/content/guides/rgsvc.html
+++ b/content/guides/rgsvc.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>Domain Services</title>
-
- <!--
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Domain 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,224 +406,153 @@ 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="_rgsvc">1. Domain Services</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This guide documents Apache Isis' domain services, both those that act as an API (implemented by the framework for
-your domain objects to call), and those domain services that act as an SPI (implemented by your domain application and
-which are called by the framework).</p>
-</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="#">Domain Services</a> (this guide)</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="rgfis.html">Framework Internal Services</a></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="_rgsvc_intro">2. Introduction</h2>
-<div class="sectionbody">
-<div class="sect2">
-<h3 id="_rgsvc_intro_types-of-domain-services">2.1. Types of Domain Service</h3>
-<div class="paragraph">
-<p>The domain services also group into various broad categories. Many support functionality of the various layers of the
-system (presentation layer, application layer, core domain, persistence layer); others exist to allow the domain objects
-to integrate with other bounded contexts, or provide various metadata (eg for development-time tooling). The diagram
-below shows these categories:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services/categories.png"><img src="images/reference-services/categories.png" alt="categories" width="600px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>A small number of domain services can be considered both API and SPI; a good example is the <a href="#_rgsvc_api_EmailService"><code>EmailService</code></a> that is of direct use for domain objects wishing to send out emails,
-but is also used by the framework to support the <a href="ugvw.html#_ugvw_features_user-registration">user registration</a>
-functionality supported by the <a href="ugvw.html">Wicket viewer</a>. The same is true of the <a href="#_rgsvc_api_EventBusService"><code>EventBusService</code></a>; this can be used by domain objects to broadcast arbitrary events,
-but is also used by the framework to automatically emit events for
-<a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a> etc.</p>
-</div>
-<div class="paragraph">
-<p>For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only
-the strictly SPI services.</p>
-</div>
-<div class="paragraph">
-<p>This rest of this guide is broken out into several chapters, one for each of the various types/categories of domain
-service.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_intro_public-api">2.2. Public API vs Internal Services</h3>
-<div class="paragraph">
-<p>The vast majority of Apache Isis' domain services are defined in Apache Isis' applib (<code>o.a.i.core:isis-core-applib</code>
-module) as stable, public classes. Importantly, this also minimizes the coupling between your code and Apache Isis,
-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 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">
-<h3 id="_rgsvc_intro_using-the-services">2.3. Using the services</h3>
-<div class="paragraph">
-<p>Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service
-as an annotated field and Apache Isis will inject the service into your object.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</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/rgsvc.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_rgsvc">1. Domain 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/_rgsvc.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 Apache Isis' domain services, both those that act as an API (implemented by the framework for your domain objects to call), and those domain services that act as an SPI (implemented by your domain application and which are called by the framework).</p>
+ </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="#">Domain Services</a> (this guide)</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="rgfis.html">Framework Internal Services</a></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="_rgsvc_intro">2. Introduction</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.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="sect2">
+ <h3 id="_rgsvc_intro_types-of-domain-services">2.1. Types of Domain Service</h3>
+ <div class="paragraph">
+ <p>The domain services also group into various broad categories. Many support functionality of the various layers of the system (presentation layer, application layer, core domain, persistence layer); others exist to allow the domain objects to integrate with other bounded contexts, or provide various metadata (eg for development-time tooling). The diagram below shows these categories:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/reference-services/categories.png"><img src="images/reference-services/categories.png" alt="categories" width="600px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>A small number of domain services can be considered both API and SPI; a good example is the <a href="#_rgsvc_api_EmailService"><code>EmailService</code></a> that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the <a href="ugvw.html#_ugvw_features_user-registration">user registration</a> functionality supported by the <a href="ugvw.html">Wicket viewer</a>. The same is true of the <a href="#_rgsvc_api_EventBusService"><code>EventBusService</code></a>; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events for <a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a> etc.</p>
+ </div>
+ <div class="paragraph">
+ <p>For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.</p>
+ </div>
+ <div class="paragraph">
+ <p>This rest of this guide is broken out into several chapters, one for each of the various types/categories of domain service.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgsvc_intro_public-api">2.2. Public API vs Internal Services</h3>
+ <div class="paragraph">
+ <p>The vast majority of Apache Isis' domain services are defined in Apache Isis' applib (<code>o.a.i.core:isis-core-applib</code> module) as stable, public classes. Importantly, this also minimizes the coupling between your code and Apache Isis, 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\u2019s formal API, in that 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">
+ <h3 id="_rgsvc_intro_using-the-services">2.3. Using the services</h3>
+ <div class="paragraph">
+ <p>Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service as an annotated field and Apache Isis will inject the service into your object.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> {
<span class="directive">public</span> <span class="type">void</span> sendEmail( <span class="predefined-type">String</span> subject, <span class="predefined-type">String</span> body) {
<span class="predefined-type">List</span><<span class="predefined-type">String</span>> cc = <span class="predefined-type">Collections</span>.emptyList;
@@ -655,98 +565,87 @@ as an annotated field and Apache Isis will inject the service into your object.<
<span class="annotation">@Inject</span> <i class="conum" data-value="1"></i><b>(1)</b>
EmailService emailService;
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>Service automatically injected by the framework.</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>For objects that are already persisted, the service is automatically injected just after the object is rehydrated by
-JDO/DataNucleus.</p>
-</div>
-<div class="paragraph">
-<p>For transient objects (instantiated programmatically), the <a href="#_rgsvc_api_FactoryService"><code>FactoryService</code></a>'s
-<code>instantiate()</code> method (or the deprecated <a href="#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>'s
-<code>newTransientInstance()</code> method) will automatically inject the services.</p>
-</div>
-<div class="paragraph">
-<p>Alternatively the object can be instantiated simply using <code>new</code>, then services injected using
-<a href="#_rgsvc_api_ServiceRegistry"><code>ServiceRegistry</code></a>'s <code>injectServicesInto(…​)</code> method (or the deprecated
-<a href="#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>'s <code>injectServicesInto(…​)</code> method).</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_intro_overriding-the-services">2.4. Overriding the services</h3>
-<div class="paragraph">
-<p>The framework provides default implementations for many of the domain services. This is convenient, but sometimes you
-will want to replace the default implementation with your own service implementation.</p>
-</div>
-<div class="paragraph">
-<p>The trick is to use the <a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a>
-attribute, specifying a low number (typically <code>"1"</code>).</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>For a small number of domain services, all implementations are used (following the chain-of-responsibility pattern),
-not just the first one. The services in question are:
-<a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>,
-<a href="#_rgsvc_spi_GridSystemService"><code>GridSystemService</code></a>, and
-<a href="#_rgsvc_spi_RoutingService"><code>RoutingService</code></a>.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>For example, suppose you wanted to provide your own implementation of
-<a href="#_rgsvc_api_LocaleProvider"><code>LocaleProvider</code></a>. Here’s how:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</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>Service automatically injected by the framework.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>For objects that are already persisted, the service is automatically injected just after the object is rehydrated by JDO/DataNucleus.</p>
+ </div>
+ <div class="paragraph">
+ <p>For transient objects (instantiated programmatically), the <a href="#_rgsvc_api_FactoryService"><code>FactoryService</code></a>'s <code>instantiate()</code> method (or the deprecated <a href="#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>'s <code>newTransientInstance()</code> method) will automatically inject the services.</p>
+ </div>
+ <div class="paragraph">
+ <p>Alternatively the object can be instantiated simply using <code>new</code>, then services injected using <a href="#_rgsvc_api_ServiceRegistry"><code>ServiceRegistry</code></a>'s <code>injectServicesInto(\u2026\u200b)</code> method (or the deprecated <a href="#_rgsvc_api_DomainObjectContainer"><code>DomainObjectContainer</code></a>'s <code>injectServicesInto(\u2026\u200b)</code> method).</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgsvc_intro_overriding-the-services">2.4. Overriding the services</h3>
+ <div class="paragraph">
+ <p>The framework provides default implementations for many of the domain services. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.</p>
+ </div>
+ <div class="paragraph">
+ <p>The trick is to use the <a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> attribute, specifying a low number (typically <code>"1"</code>).</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>For a small number of domain services, all implementations are used (following the chain-of-responsibility pattern), not just the first one. The services in question are: <a href="#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>, <a href="#_rgsvc_spi_GridSystemService"><code>GridSystemService</code></a>, and <a href="#_rgsvc_spi_RoutingService"><code>RoutingService</code></a>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>For example, suppose you wanted to provide your own implementation of <a href="#_rgsvc_api_LocaleProvider"><code>LocaleProvider</code></a>. Here\u2019s how:</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="annotation">@DomainServiceLayout</span>(
- menuOrder = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ menuOrder = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b>
)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyLocaleProvider</span> <span class="directive">implements</span> LocaleProvider {
<span class="annotation">@Override</span>
<span class="directive">public</span> <span class="predefined-type">Locale</span> getLocale() {
<span class="keyword">return</span> ...
}
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>takes precedence over the default implementation.</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>It’s also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the
-default); this is also possible and quite easy (if using <code>1.10.0</code> or later). The idea is to have the framework
-inject all implementations of the service, and then to delegate to the first one that isn’t "this" one:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>takes precedence over the default implementation.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>It\u2019s also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the default); this is also possible and quite easy (if using <code>1.10.0</code> or later). The idea is to have the framework inject all implementations of the service, and then to delegate to the first one that isn\u2019t "this" one:</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="annotation">@DomainServiceLayout</span>(
- menuOrder = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ menuOrder = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span> <i class="conum" data-value="1"></i><b>(1)</b>
)
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyLocaleProvider</span> <span class="directive">implements</span> LocaleProvider {
<span class="annotation">@Override</span>
@@ -758,484 +657,390 @@ inject all implementations of the service, and then to delegate to the first one
}
<span class="annotation">@Inject</span>
<span class="predefined-type">List</span><LocaleProvider> localeProviders; <i class="conum" data-value="4"></i><b>(4)</b>
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>takes precedence over the default implementation when injected elsewhere.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>this implementation merely delegates to the default implementation</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>find the first implementation that isn’t <em>this</em> implementation (else infinite loop!)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>injects all implementations, including this implemenation</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The above code could be improved by caching the delegateLocaleProvider once located (rather than searching each time).</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_rgsvc_intro_commands-and-events">2.5. Command and Events</h3>
-<div class="paragraph">
-<p>A good number of the domain services manage the execution of action invocations/property edits, along with the state
-of domain objects that are modified as a result of these. These services capture information which can then be used
-for various purposes, most notably for auditing or for publishing events, or for deferring execution such that the
-execution be performed in the background at some later date.</p>
-</div>
-<div class="paragraph">
-<p>The diagram below shows how these services fit together. The outline boxes are services while the coloured boxes
-represent data structures - defined in the applib and therefore accessible to domain applications - which hold various
-information about the executions.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services/commands-and-events.png"><img src="images/reference-services/commands-and-events.png" alt="commands and events" width="960px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>To explain:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>the (request-scoped) <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a> captures the user’s intention to
-invoke an action or edit a property; this is held by the <code>Command</code> object.</p>
-</li>
-<li>
-<p>if a <a href="#_rgsvc_spi_CommandService"><code>CommandService</code></a> has been configured, then this will be used to
-create the <code>Command</code> object implementation, generally so that it can then also be persisted.<br></p>
-<div class="paragraph">
-<p>If the action or property is annotated to be invoked in the background (using
-<a href="rgant.html#_rgant-Action_command"><code>@Action#command…​()</code></a> or
-<a href="rgant.html#_rgant-Property_command"><code>@Property#command…​()</code></a>) then no further work is done. But,
-if the action/property is to be executed in the foreground, then the interaction continues.</p>
-</div>
-</li>
-<li>
-<p>the (request-scoped) <a href="#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a> domain service acts as a
-factory for the <code>Interaction</code> object, which keeps track of the call-graph of executions (<code>Interaction.Execution</code>)
-of either action invocations or property edits. In the majority of cases there is likely to be just a single top-level
-node of this graph, but for applications that use the <a href="#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a>
-extensively each successive call results in a new child execution.</p>
-</li>
-<li>
-<p>before and after each action invocation/property edit, a <a href="rgcms.html#_rgcms_classes_domainevent">domain event</a> is
-may be broadcast to all subscribers. Whether this occurs depends on whether the action/property has been annotated
-(using <a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a> or
-<a href="rgant.html#_rgant-Property_domainEvent"><code>@Property#domainEvent()</code></a>).<br></p>
-<div class="paragraph">
-<p>(Note that susbcribers will also receive events for vetoing the action/property; this is not shown on the diagram).</p>
-</div>
-</li>
-<li>
-<p>As each execution progresses, and objects that are modified are "enlisted" into the (internal)
-<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="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">
-<p>The internal service delegates in turn to any registered
-<a href="#_rgsvc_spi_PublishingService"><code>PublishingService</code></a> (deprecated) and also to any
-registered <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a>s (there may be more than one).</p>
-</div>
-</li>
-<li>
-<p>At the end of each transaction, details of all changed objects are published, again through the (internal)
-<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.<br></p>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>Note that it’s possible for there to be more than one transaction per top-level interaction, by virtue of the
-<a href="#_rgsvc_api_TransactionService"><code>TransactionService</code></a>.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</li>
-<li>
-<p>Also at the end of each transaction, details of all changed properties are passed to any registered
-<a href="#_rgsvc_spi_AuditerService"><code>AuditerService</code></a> or
-<a href="#_rgsvc_spi_AuditingService"><code>AuditingService</code></a> (the latter deprecated) by way of the (internal)
-<a href="rgfis.html#_rgfis_spi_AuditingServiceInternal"><code>AuditingServiceInternal</code></a> domain service.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Implementations of <a href="#_rgsvc_spi_CommandService"><code>CommandService</code></a> can use the <code>Command#getMemento()</code>
-method to obtain a XML equivalent of that <code>Command</code>, reified using the <a href="rgcms.html#_rgcms_schema-cmd"><code>cmd.xsd</code></a>
-schema. This can be converted back into a <code>CommandDto</code> using the <code>CommandDtoUtils</code> utility class (part of the applib).</p>
-</div>
-<div class="paragraph">
-<p>Similarly, implementations of <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> can use the
-<code>InteractionDtoUtils</code> utility class to obtain a <code>InteractionDto</code> representing the interaction, either just for a single
-execution or for the entire call-graph. This can be converted into XML in a similar fashion.</p>
-</div>
-<div class="paragraph">
-<p>Likewise, the <code>PublishedObjects</code> class passed to the <code>PublisherService</code> at the end of the interaction provides the
-<code>PublishedObjects#getDto()</code> method which returns a <code>ChangesDto</code> instance. This can be converted into XML using the
-<code>ChangesDtoUtils</code> utility class.</p>
-</div>
-<div class="paragraph">
-<p>One final point: multiple <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> implementations are supported
-because different implementations may have different responsibilities. For example, the (non-ASF)
-<a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module is responsible for publishing
-messages onto an ActiveMQ event bus, for inter-system communication. However, the SPI can also be used for profiling;
-each execution within the call-graph contains metrics of the number of objects loaded or modified as a result of that
-execution, and thus could be used for application profiling. The framework provides a default
-<code>PublisherServiceLogging</code> implementation that logs this using SLF4J.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rgsvc_presentation-layer-spi">3. Presentation Layer SPI</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Domain service SPIs for the presentation layer influence how the Apache Isis viewers behave.</p>
-</div>
-<div class="paragraph">
-<p>The table below summarizes the presentation layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the 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 1. Presentation Layer SPI</caption>
-<colgroup>
-<col style="width: 25%;">
-<col style="width: 50%;">
-<col style="width: 12.5%;">
-<col style="width: 12.5%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">SPI</th>
-<th class="tableblock halign-left valign-top">Description</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_ContentMappingService"><code>o.a.i.applb.</code><br>
-<code>services.conmap</code><br>
-<code>ContentMappingService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>(Attempt to) map the returned data into the representation required by the client’s HTTP <code>Accept</code> header.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Replaces (and simplifies) the earlier <code>ContentMappingService</code> that defined an SPI using classes internal to the
-framework.<br>
-+
-No default implementation.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_EmailNotificationService"><code>o.a.i.applib.</code><br>
-<code>services.userreg</code><br>
-<code>EmailNotificationService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Notify a user during <a href="#_rgsvc_spi_UserRegistrationService">self-registration</a> of users.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>EmailNotificationService-</code><br>
-<code>Default</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-runtime</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">depends on:<br>
-a configured <code>EmailService</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_ErrorReportingService"><code>o.a.i.applib.</code><br>
-<code>services.error</code><br>
-<code>ErrorReportingService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Record details of an error occurring in the system (eg in an external incident recording system such as JIRA), and return a more friendly (jargon-free) message to display to the end user, with optional reference (eg <code>XXX-1234</code>).</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">(none)</p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_ExceptionRecognizer"><code>o.a.i.applib.</code><br>
-<code>services.exceprecog</code><br>
-<code>ExceptionRecognizer2</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ExceptionRecognizer-</code><br>
-<code>CompositeFor-</code><br>
-<code>JdoObjectStore</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-applib</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Extensible using composite pattern if required</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridSystemService"><code>o.a.i.applib.</code><br>
-<code>services.grid</code><br>
-<code>GridSystemService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Validates and normalizes the grid layout for a domain class (with respect to a particular grid
-system such as Bootstrap3), also providing a default grid (for those domain classes where there is no grid layout).</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridSystemServiceBS3</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-metamodel</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridLoaderService"><code>o.a.i.applib.</code><br>
-<code>services.grid</code><br>
-<code>GridLoaderService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Responsible for loading a grid layout for a domain class, eg from a <code>layout.xml</code> file.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridLoaderServiceDefault</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-metamodel</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridService"><code>o.a.i.applib.</code><br>
-<code>services.grid</code><br>
-<code>GridService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>A facade on top of both <a href="#_rgsvc_spi_GridLoaderService"><code>GridLoaderService</code></a> and
-<a href="#_rgsvc_spi_GridSystemService"><code>GridSystemService</code></a>, thus being able to return normalized
-grids for any domain class.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridServiceDefault</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-metamodel</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_HintStore"><code>o.a.i.applib.</code><br>
-<code>services.hint</code><br>
-<code>HintStore</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Stores UI hints on a per-object basis. For example, the viewer remembers which tabs are selected, and for collections which view is selected (eg table or hidden), which page of a table to render, or whether "show all" (rows) is toggled.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>HintStoreUsingWicketSession</code><br>
-<code>o.a.i.viewer</code><br>
-<code>isis-viewer-wicket-impl</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_LocaleProvider"><code>o.a.i.applib.</code><br>
-<code>services.i18n</code><br>
-<code>LocaleProvider</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app’s UI, messages and exceptions can be translated to the required locale by the <a href="#_rgsvc_spi_TranslationService"><code>TranslationService</code></a>.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>LocaleProviderWicket</code><br>
-<code>o.a.i.viewer</code><br>
-<code>isis-viewer-wicket-impl</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_RoutingService"><code>o.a.i.applib.</code><br>
-<code>services.routing</code><br>
-<code>RoutingService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Return an alternative object than that returned by an action.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>RoutingServiceDefault</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-applib</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The default implementation will return the home page (per <a href="#_rgsvc_api_HomePageProviderService"><code>HomePageProviderService</code></a>) if a void or null is returned.<br>
-Used by the <a href="ugvw.html">Wicket viewer</a> only.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TableColumnOrderService"><code>o.a.i.applib.</code><br>
-<code>services.tablecol</code><br>
-<code>TableColumn-</code><br>
-<code>OrderService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Allows the columns of a parented or standalone table to be reordered, based upon the parent object, collection id and type of object in the collection..</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TableColumn-</code><br>
-<code>OrderService.Default</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-applib</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TranslationService"><code>o.a.i.applib.</code><br>
-<code>services.i18n</code><br>
-<code>TranslationService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Translate an app’s UI, messages and exceptions for the current user (as per the locale provided by <a href="#_rgsvc_spi_LocaleProvider"><code>LocalProvider</code></a>.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TranslationServicePo</code><br>
-<code>o.a.i.core</code><br>
-<code>isis-core-runtime</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">related services: <code>TranslationServicePoMenu</code><br>
-depends on:<br>
-<code>TranslationsResolver</code>, <code>LocaleProvider</code></p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TranslationsResolver"><code>o.a.i.applib.</code><br>
-<code>services.i18n</code><br>
-<code>TranslationsResolver</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app’s UI, messages and exceptions can be translated to the required locale by the <a href="#_rgsvc_spi_TranslationService"><code>TranslationService</code></a></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>TranslationsResolverWicket</code><br>
-<code>o.a.i.viewer</code><br>
-<code>isis-viewer-wicket-impl</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_UrlEncodingService"><code>o.a.i.applib.</code><br>
-<code>services.urlencoding</code><br>
-<code>UrlEncodingService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Converts strings into a form safe for use within a URL. Used to convert view models mementos into usable URL form.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>UrlEncodingService</code><br>
-<code>UsingBaseEncoding</code><br>
-<code>o.a.i.applib</code><br>
-<code>isis-core-applib</code></p></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_UserProfileService"><code>o.a.i.applib.</code><br>
-<code>services.userprof</code><br>
-<code>UserProfileService</code></a></p></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></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_ContentMappingService">3.1. <code>ContentMappingService</code></h3>
-<div class="paragraph">
-<p>The <code>ContentMappingService</code> supports the (default implementation of 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="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> for further discussion.</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>Unlike most other domain services, the framework (that is, <code>ContentNegotiationService</code>) will check <em>all</em> available
-implementations of <code>ContentMappingService</code> to convert the domain object to the requested media type, rather than merely
-the first implementation found; in other words it uses the chain-of-responsibility pattern. Services are checked
-in the ordering defined by <a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a>).
-The mapped object used will be the first non-<code>null</code> result returned by an implementation.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="sect3">
-<h4 id="_spi">3.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">ContentMappingService</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>takes precedence over the default implementation when injected elsewhere.</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>this implementation merely delegates to the default implementation</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>find the first implementation that isn\u2019t <em>this</em> implementation (else infinite loop!)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="4"></i><b>4</b></td>
+ <td>injects all implementations, including this implemenation</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>The above code could be improved by caching the delegateLocaleProvider once located (rather than searching each time).</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_rgsvc_intro_commands-and-events">2.5. Command and Events</h3>
+ <div class="paragraph">
+ <p>A good number of the domain services manage the execution of action invocations/property edits, along with the state of domain objects that are modified as a result of these. These services capture information which can then be used for various purposes, most notably for auditing or for publishing events, or for deferring execution such that the execution be performed in the background at some later date.</p>
+ </div>
+ <div class="paragraph">
+ <p>The diagram below shows how these services fit together. The outline boxes are services while the coloured boxes represent data structures - defined in the applib and therefore accessible to domain applications - which hold various information about the executions.</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/reference-services/commands-and-events.png"><img src="images/reference-services/commands-and-events.png" alt="commands and events" width="960px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>To explain:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>the (request-scoped) <a href="#_rgsvc_api_CommandContext"><code>CommandContext</code></a> captures the user\u2019s intention to invoke an action or edit a property; this is held by the <code>Command</code> object.</p> </li>
+ <li> <p>if a <a href="#_rgsvc_spi_CommandService"><code>CommandService</code></a> has been configured, then this will be used to create the <code>Command</code> object implementation, generally so that it can then also be persisted.<br></p>
+ <div class="paragraph">
+ <p>If the action or property is annotated to be invoked in the background (using <a href="rgant.html#_rgant-Action_command"><code>@Action#command\u2026\u200b()</code></a> or <a href="rgant.html#_rgant-Property_command"><code>@Property#command\u2026\u200b()</code></a>) then no further work is done. But, if the action/property is to be executed in the foreground, then the interaction continues.</p>
+ </div> </li>
+ <li> <p>the (request-scoped) <a href="#_rgsvc_api_InteractionContext"><code>InteractionContext</code></a> domain service acts as a factory for the <code>Interaction</code> object, which keeps track of the call-graph of executions (<code>Interaction.Execution</code>) of either action invocations or property edits. In the majority of cases there is likely to be just a single top-level node of this graph, but for applications that use the <a href="#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a> extensively each successive call results in a new child execution.</p> </li>
+ <li> <p>before and after each action invocation/property edit, a <a href="rgcms.html#_rgcms_classes_domainevent">domain event</a> is may be broadcast to all subscribers. Whether this occurs depends on whether the action/property has been annotated (using <a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a> or <a href="rgant.html#_rgant-Property_domainEvent"><code>@Property#domainEvent()</code></a>).<br></p>
+ <div class="paragraph">
+ <p>(Note that susbcribers will also receive events for vetoing the action/property; this is not shown on the diagram).</p>
+ </div> </li>
+ <li> <p>As each execution progresses, and objects that are modified are "enlisted" into the (internal) <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="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">
+ <p>The internal service delegates in turn to any registered <a href="#_rgsvc_spi_PublishingService"><code>PublishingService</code></a> (deprecated) and also to any registered <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a>s (there may be more than one).</p>
+ </div> </li>
+ <li> <p>At the end of each transaction, details of all changed objects are published, again through the (internal) <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.<br></p>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Note that it\u2019s possible for there to be more than one transaction per top-level interaction, by virtue of the <a href="#_rgsvc_api_TransactionService"><code>TransactionService</code></a>.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div> </li>
+ <li> <p>Also at the end of each transaction, details of all changed properties are passed to any registered <a href="#_rgsvc_spi_AuditerService"><code>AuditerService</code></a> or <a href="#_rgsvc_spi_AuditingService"><code>AuditingService</code></a> (the latter deprecated) by way of the (internal) <a href="rgfis.html#_rgfis_spi_AuditingServiceInternal"><code>AuditingServiceInternal</code></a> domain service.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Implementations of <a href="#_rgsvc_spi_CommandService"><code>CommandService</code></a> can use the <code>Command#getMemento()</code> method to obtain a XML equivalent of that <code>Command</code>, reified using the <a href="rgcms.html#_rgcms_schema-cmd"><code>cmd.xsd</code></a> schema. This can be converted back into a <code>CommandDto</code> using the <code>CommandDtoUtils</code> utility class (part of the applib).</p>
+ </div>
+ <div class="paragraph">
+ <p>Similarly, implementations of <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> can use the <code>InteractionDtoUtils</code> utility class to obtain a <code>InteractionDto</code> representing the interaction, either just for a single execution or for the entire call-graph. This can be converted into XML in a similar fashion.</p>
+ </div>
+ <div class="paragraph">
+ <p>Likewise, the <code>PublishedObjects</code> class passed to the <code>PublisherService</code> at the end of the interaction provides the <code>PublishedObjects#getDto()</code> method which returns a <code>ChangesDto</code> instance. This can be converted into XML using the <code>ChangesDtoUtils</code> utility class.</p>
+ </div>
+ <div class="paragraph">
+ <p>One final point: multiple <a href="#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> implementations are supported because different implementations may have different responsibilities. For example, the (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module is responsible for publishing messages onto an ActiveMQ event bus, for inter-system communication. However, the SPI can also be used for profiling; each execution within the call-graph contains metrics of the number of objects loaded or modified as a result of that execution, and thus could be used for application profiling. The framework provides a default <code>PublisherServiceLogging</code> implementation that logs this using SLF4J.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_rgsvc_presentation-layer-spi">3. Presentation Layer SPI</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.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>Domain service SPIs for the presentation layer influence how the Apache Isis viewers behave.</p>
+ </div>
+ <div class="paragraph">
+ <p>The table below summarizes the presentation layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the 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 1. Presentation Layer SPI
+ </caption>
+ <colgroup>
+ <col style="width: 25%;">
+ <col style="width: 50%;">
+ <col style="width: 12.5%;">
+ <col style="width: 12.5%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">SPI</th>
+ <th class="tableblock halign-left valign-top">Description</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_ContentMappingService"><code>o.a.i.applb.</code><br> <code>services.conmap</code><br> <code>ContentMappingService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>(Attempt to) map the returned data into the representation required by the client\u2019s HTTP <code>Accept</code> header.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Replaces (and simplifies) the earlier <code>ContentMappingService</code> that defined an SPI using classes internal to the framework.<br> + No default implementation.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_EmailNotificationService"><code>o.a.i.applib.</code><br> <code>services.userreg</code><br> <code>EmailNotificationService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Notify a user during <a href="#_rgsvc_spi_UserRegistrationService">self-registration</a> of users.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>EmailNotificationService-</code><br> <code>Default</code><br> <code>o.a.i.core</code><br> <code>isis-core-runtime</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">depends on:<br> a configured <code>EmailService</code></p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_ErrorReportingService"><code>o.a.i.applib.</code><br> <code>services.error</code><br> <code>ErrorReportingService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Record details of an error occurring in the system (eg in an external incident recording system such as JIRA), and return a more friendly (jargon-free) message to display to the end user, with optional reference (eg <code>XXX-1234</code>).</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">(none)</p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_ExceptionRecognizer"><code>o.a.i.applib.</code><br> <code>services.exceprecog</code><br> <code>ExceptionRecognizer2</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>ExceptionRecognizer-</code><br> <code>CompositeFor-</code><br> <code>JdoObjectStore</code><br> <code>o.a.i.core</code><br> <code>isis-core-applib</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">Extensible using composite pattern if required</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridSystemService"><code>o.a.i.applib.</code><br> <code>services.grid</code><br> <code>GridSystemService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Validates and normalizes the grid layout for a domain class (with respect to a particular grid system such as Bootstrap3), also providing a default grid (for those domain classes where there is no grid layout).</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridSystemServiceBS3</code><br> <code>o.a.i.core</code><br> <code>isis-core-metamodel</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridLoaderService"><code>o.a.i.applib.</code><br> <code>services.grid</code><br> <code>GridLoaderService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Responsible for loading a grid layout for a domain class, eg from a <code>layout.xml</code> file.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridLoaderServiceDefault</code><br> <code>o.a.i.core</code><br> <code>isis-core-metamodel</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_GridService"><code>o.a.i.applib.</code><br> <code>services.grid</code><br> <code>GridService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>A facade on top of both <a href="#_rgsvc_spi_GridLoaderService"><code>GridLoaderService</code></a> and <a href="#_rgsvc_spi_GridSystemService"><code>GridSystemService</code></a>, thus being able to return normalized grids for any domain class.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GridServiceDefault</code><br> <code>o.a.i.core</code><br> <code>isis-core-metamodel</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_HintStore"><code>o.a.i.applib.</code><br> <code>services.hint</code><br> <code>HintStore</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Stores UI hints on a per-object basis. For example, the viewer remembers which tabs are selected, and for collections which view is selected (eg table or hidden), which page of a table to render, or whether "show all" (rows) is toggled.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>HintStoreUsingWicketSession</code><br> <code>o.a.i.viewer</code><br> <code>isis-viewer-wicket-impl</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_LocaleProvider"><code>o.a.i.applib.</code><br> <code>services.i18n</code><br> <code>LocaleProvider</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app\u2019s UI, messages and exceptions can be translated to the required locale by the <a href="#_rgsvc_spi_TranslationService"><code>TranslationService</code></a>.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>LocaleProviderWicket</code><br> <code>o.a.i.viewer</code><br> <code>isis-viewer-wicket-impl</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_RoutingService"><code>o.a.i.applib.</code><br> <code>services.routing</code><br> <code>RoutingService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Return an alternative object than that returned by an action.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>RoutingServiceDefault</code><br> <code>o.a.i.core</code><br> <code>isis-core-applib</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">The default implementation will return the home page (per <a href="#_rgsvc_api_HomePageProviderService"><code>HomePageProviderService</code></a>) if a void or null is returned.<br> Used by the <a href="ugvw.html">Wicket viewer</a> only.</p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TableColumnOrderService"><code>o.a.i.applib.</code><br> <code>services.tablecol</code><br> <code>TableColumn-</code><br> <code>OrderService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Allows the columns of a parented or standalone table to be reordered, based upon the parent object, collection id and type of object in the collection..</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>TableColumn-</code><br> <code>OrderService.Default</code><br> <code>o.a.i.core</code><br> <code>isis-core-applib</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TranslationService"><code>o.a.i.applib.</code><br> <code>services.i18n</code><br> <code>TranslationService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Translate an app\u2019s UI, messages and exceptions for the current user (as per the locale provided by <a href="#_rgsvc_spi_LocaleProvider"><code>LocalProvider</code></a>.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>TranslationServicePo</code><br> <code>o.a.i.core</code><br> <code>isis-core-runtime</code></p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">related services: <code>TranslationServicePoMenu</code><br> depends on:<br> <code>TranslationsResolver</code>, <code>LocaleProvider</code></p></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_TranslationsResolver"><code>o.a.i.applib.</code><br> <code>services.i18n</code><br> <code>TranslationsResolver</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app\u2019s UI, messages and exceptions can be translated to the required locale by the <a href="#_rgsvc_spi_TranslationService"><code>TranslationService</code></a></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>TranslationsResolverWicket</code><br> <code>o.a.i.viewer</code><br> <code>isis-viewer-wicket-impl</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_UrlEncodingService"><code>o.a.i.applib.</code><br> <code>services.urlencoding</code><br> <code>UrlEncodingService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Converts strings into a form safe for use within a URL. Used to convert view models mementos into usable URL form.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>UrlEncodingService</code><br> <code>UsingBaseEncoding</code><br> <code>o.a.i.applib</code><br> <code>isis-core-applib</code></p></td>
+ <td class="tableblock halign-left valign-top"></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rgsvc_spi_UserProfileService"><code>o.a.i.applib.</code><br> <code>services.userprof</code><br> <code>UserProfileService</code></a></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"></td>
+ <td class="tableblock halign-left valign-top"></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_ContentMappingService">3.1. <code>ContentMappingService</code></h3>
+ <div class="paragraph">
+ <p>The <code>ContentMappingService</code> supports the (default implementation of 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="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a> for further discussion.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>Unlike most other domain services, the framework (that is, <code>ContentNegotiationService</code>) will check <em>all</em> available implementations of <code>ContentMappingService</code> to convert the domain object to the requested media type, rather than merely the first implementation found; in other words it uses the chain-of-responsibility pattern. Services are checked in the ordering defined by <a href="rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a>). The mapped object used will be the first non-<code>null</code> result returned by an implementation.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="_spi">3.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">ContentMappingService</span> {
<span class="predefined-type">Object</span> map(<span class="predefined-type">Object</span> object, <i class="conum" data-value="1"></i><b>(1)</b>
<span class="predefined-type">List</span><MediaType> acceptableMediaTypes); <i class="conum" data-value="2"></i><b>(2)</b>
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>typically the input is a domain object (whose structure might change over time), and the output is a DTO (whose structure is guaranteed to be preserved over time)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>as per the caller’s HTTP <code>Accept</code> header</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>In versions prior to <code>v1.12.0</code>, this interface resided in a different package, internal to the
-<a href="#ugvro.adoc">Restful Objects</a> viewer, and defined a slightly different signature that used an internal enum:</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">ContentMappingService</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>typically the input is a domain object (whose structure might change over time), and the output is a DTO (whose structure is guaranteed to be preserved over time)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>as per the caller\u2019s HTTP <code>Accept</code> header</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>In versions prior to <code>v1.12.0</code>, this interface resided in a different package, internal to the <a href="#ugvro.adoc">Restful Objects</a> viewer, and defined a slightly different signature that used an internal enum:</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">ContentMappingService</span> {
<span class="predefined-type">Object</span> map(<span class="predefined-type">Object</span> object,
<span class="predefined-type">List</span><MediaType> acceptableMediaTypes,
RepresentationType representationType); <i class="conum" data-value="1"></i><b>(1)</b>
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>enum representing the requested representation; only ever take a value of <code>DOMAIN_OBJECT</code> or <code>ACTION_RESULT</code>.</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_implementations">3.1.2. Implementations</h4>
-<div class="paragraph">
-<p>No default implementations are provided by Apache Isis framework itself.</p>
-</div>
-<div class="paragraph">
-<p>However, the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> includes a sample implementation to convert its <code>ToDoItem</code> entity into a (JAXB annotated) <code>ToDoItemDto</code>. The source 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)
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>enum representing the requested representation; only ever take a value of <code>DOMAIN_OBJECT</code> or <code>ACTION_RESULT</code>.</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_implementations">3.1.2. Implementations</h4>
+ <div class="paragraph">
+ <p>No default implementations are provided by Apache Isis framework itself.</p>
+ </div>
+
<TRUNCATED>