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 2015/11/19 23:45:57 UTC
[4/5] isis-site git commit: ISIS-1250, ISIS-915, ISIS-1251, ISIS-1252,
ISIS-1254, ISIS-1255
http://git-wip-us.apache.org/repos/asf/isis-site/blob/3970c476/content/guides/rg.html
----------------------------------------------------------------------
diff --git a/content/guides/rg.html b/content/guides/rg.html
index e3050d6..7e254c4 100644
--- a/content/guides/rg.html
+++ b/content/guides/rg.html
@@ -46,6 +46,20 @@
<![endif]-->
+
+ <style type="text/css">
+ pre code {
+ background-color: inherit;
+ border-style: none;
+ }
+
+ pre code > span:first-child {
+ margin-left: -5px;
+ }
+
+ <style>
+
+ <!--
<style type="text/css">
/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
/*pre.CodeRay {background-color:#f7f7f8;}*/
@@ -164,6 +178,7 @@ table.CodeRay td.code>pre{padding:0}
}
<style>
+ -->
<style>
.github-fork-ribbon-wrapper.right {
@@ -242,6 +257,22 @@ table.CodeRay td.code>pre{padding:0}
margin-top: 30px;
}
+ div#doc-content a.header-link {
+ margin-left: -75px;
+ }
+
+ div#doc-content div.sect1 h2 {
+ margin-left: -60px;
+ }
+
+ div#doc-content div.sect3 h4 {
+ margin-left: -60px;
+ }
+
+ div#doc-content div.sect2 h3 {
+ margin-left: -60px;
+ }
+
div.documentation-page table.frame-all {
border-left: none;
border-right: none;
@@ -1004,6 +1035,26 @@ For use with <code>@ViewModel</code>. If specifying view models using <code>@Dom
<td class="tableblock halign-left valign-top"><p class="tableblock">Domain</p></td>
<td class="tableblock halign-left valign-top"></td>
</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-XmlRootElement"><code>javax.xml.bind</code><br>
+<code>.annotation</code><br>
+<code>XmlRootElement</code></a></p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>JAXB annotation indicating the XML root element when serialized to XML; also used by the framework for view models (whose memento is the XML), often also acting as a DTO.</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Application</p></td>
+<td class="tableblock halign-left valign-top"></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-XmlJavaTypeAdapter"><code>javax.xml.bind</code><br>
+<code>.annotation</code><br>
+<code>XmlJavaTypeAdapter</code></a></p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>JAXB annotation defining how to serialize an entity. Used in conjunction with the (framework provided) <code>PersistentEntityAdapter</code> class to serialize persistent entities into a canonical OID (equivalent to the <code>Bookmark</code> provided by the <a href="#_rg_services-api_manpage-BookmarkService"><code>BookmarkService</code></a>).</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Domain</p></td>
+<td class="tableblock halign-left valign-top"></td>
+</tr>
</tbody>
</table>
</div>
@@ -1796,7 +1847,9 @@ This annotation indicates that transient instances of this class may be created
<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>ActionDomainEvent</code><br>
(<code>ActionDomainEvent.Default</code>)</p></td>
<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>the event type to be posted to the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> to broadcast the action’s business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).</p>
+<p>the event type to be posted to the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> to
+broadcast the action’s business rule checking (hide, disable, validate) and its invocation (pre-execute and
+post-execute).</p>
</div></div></td>
</tr>
<tr>
@@ -2123,7 +2176,10 @@ returned object from this action is the persisted <code>Command</code> itself.</
</div>
</div>
<div class="paragraph">
-<p>The purpose of the <code>domainEvent()</code> attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for <a href="#_rg_annotations_manpage-Collection_domainEvent">collections</a> and <a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
+<p>The <code>domainEvent()</code> attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+<a href="#_rg_annotations_manpage-Collection_domainEvent">collections</a> and
+<a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
@@ -2165,11 +2221,10 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
- <span class="directive">public</span> <span class="type">void</span> on(ActionInteractionEvent ev) {
+ <span class="directive">public</span> <span class="type">void</span> on(ActionDomainEvent ev) {
...
}
}</code></pre>
@@ -2180,9 +2235,8 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
<span class="directive">public</span> <span class="type">void</span> on(ToDoItem.CompletedEvent ev) {
...
@@ -2258,6 +2312,26 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
</div>
<div class="sect4">
+<h5 id="_default_doop_and_noop_events_code_1_11_0_snapshot_code">Default, Doop and Noop events (<code>1.11.0-SNAPSHOT</code>)</h5>
+<div class="paragraph">
+<p>If the <code>domainEvent</code> attribute is not explicitly specified (is left as its default value, <code>ActionDomainEvent.Default</code>),
+then the framework will, by default, post an event.</p>
+</div>
+<div class="paragraph">
+<p>If this is not required, then the <code>isis.reflector.facet.actionAnnotation.domainEvent.postForDefault</code>
+configuration property can be set to "false"; this will disable posting.</p>
+</div>
+<div class="paragraph">
+<p>On the other hand, if the <code>domainEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>ActionDomainEvent.Doop</code> as such a subclass, so setting the <code>domainEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.</p>
+</div>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>ActionDomainEvent.Noop</code>; if <code>domainEvent</code> attribute is set to this class,
+then no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
<h5 id="_raising_events_programmatically">Raising events programmatically</h5>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> API directly, or by emulating the UI by
@@ -3533,7 +3607,10 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="paragraph">
-<p>The purpose of the <code>domainEvent()</code> attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for <a href="#_rg_annotations_manpage-Action_domainEvent">actions</a> and <a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
+<p>The <code>domainEvent()</code> attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+<a href="#_rg_annotations_manpage-Action_domainEvent">actions</a> and
+<a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
@@ -3587,11 +3664,10 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
- <span class="directive">public</span> <span class="type">void</span> on(CollectionInteractionEvent ev) {
+ <span class="directive">public</span> <span class="type">void</span> on(CollectionDomainEvent ev) {
...
}
}</code></pre>
@@ -3602,9 +3678,8 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
<span class="directive">public</span> <span class="type">void</span> on(ToDoItem.DependenciesChangedEvent ev) {
...
@@ -3680,6 +3755,26 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
</div>
<div class="sect4">
+<h5 id="_default_doop_and_noop_events_code_1_11_0_snapshot_code_2">Default, Doop and Noop events (<code>1.11.0-SNAPSHOT</code>)</h5>
+<div class="paragraph">
+<p>If the <code>domainEvent</code> attribute is not explicitly specified (is left as its default value, <code>CollectionDomainEvent.Default</code>),
+then the framework will, by default, post an event.</p>
+</div>
+<div class="paragraph">
+<p>If this is not required, then the <code>isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault</code>
+configuration collection can be set to "false"; this will disable posting.</p>
+</div>
+<div class="paragraph">
+<p>On the other hand, if the <code>domainEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>CollectionDomainEvent.Doop</code> as such a subclass, so setting the <code>domainEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration collection setting.</p>
+</div>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>CollectionDomainEvent.Noop</code>; if <code>domainEvent</code> attribute is set to this class,
+then no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
<h5 id="_raising_events_programmatically_2">Raising events programmatically</h5>
<div class="paragraph">
<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> API directly, or by emulating the UI by
@@ -5580,6 +5675,14 @@ can be used instead, eg:</p>
</div></div></td>
</tr>
<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent"><code>cssClassUiEvent()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>CssClassUiEvent</code><br>
+(<code>CssClassUiEvent.Default</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>the event type to be posted (<code>1.11.0-SNAPSHOT</code>) to the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> to obtain a CSS class for the domain object.</p>
+</div></div></td>
+</tr>
+<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-DomainObjectLayout_describedAs"><code>describedAs()</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String.</p></td>
<td class="tableblock halign-left valign-top"><div><div class="paragraph">
@@ -5587,6 +5690,14 @@ can be used instead, eg:</p>
</div></div></td>
</tr>
<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-DomainObjectLayout_iconUiEvent"><code>iconUiEvent()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>IconUiEvent</code><br>
+(<code>IconUiEvent.Default</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>the event type to be posted (<code>1.11.0-SNAPSHOT</code>) to the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> to obtain the icon (name) for the domain object.</p>
+</div></div></td>
+</tr>
+<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-DomainObjectLayout_named"><code>named()</code></a></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">String.</p></td>
<td class="tableblock halign-left valign-top"><div><div class="paragraph">
@@ -5610,6 +5721,14 @@ can be used instead, eg:</p>
<p>the plural name of the class</p>
</div></div></td>
</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent"><code>titleUiEvent()</code></a></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">subtype of <code>TitleUiEvent</code><br>
+(<code>TitleUiEvent.Default</code>)</p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>the event type to be posted (<code>1.11.0-SNAPSHOT</code>) to the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> to obtain the title for the domain object.</p>
+</div></div></td>
+</tr>
</tbody>
</table>
<div class="paragraph">
@@ -5813,57 +5932,103 @@ member so that it can be styled in an application-specific way.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_rg_annotations_manpage-DomainObjectLayout_describedAs">2.10.4. <code>describedAs()</code></h4>
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent">2.10.4. cssClassUiEvent() (<code>1.11.0-SNAPSHOT</code>)</h4>
<div class="paragraph">
-<p>The <code>describedAs()</code> attribute is used to provide a short description of the domain object to the user. In the <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> it is displayed as a 'tool tip'. The attribute can also be specified for <a href="#_rg_annotations_manpage-CollectionLayout_describedAs">collections</a>, <a href="#_rg_annotations_manpage-PropertyLayout_describedAs">properties</a>, <a href="#_rg_annotations_manpage-ActionLayout_describedAs">actions</a>, <a href="#_rg_annotations_manpage-ParameterLayout_describedAs">parameters</a> and <a href="#_rg_annotations_manpage-ViewModelLayout_describedAs">view models</a>.</p>
-</div>
-<div class="paragraph">
-<p>For example:</p>
+<p>Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
+in any wrapping <code><div></code>s and <code><span></code>s that render the domain object. This is as an alternative to implementing
+<a href="#_rg_methods_reserved_manpage-cssClass"><code>cssClass()</code></a> reserved method. (If <code>cssClass()</code> is present, then
+it will take precedence).</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DescribedAs</span>(<span class="string"><span class="delimiter">"</span><span class="content">A customer who may have originally become known to us via </span><span class="delimiter">"</span></span> +
- <span class="string"><span class="delimiter">"</span><span class="content">the marketing system or who may have contacted us directly.</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">ProspectiveSale</span> {
- ...
-}</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_rg_annotations_manpage-DomainObjectLayout_named">2.10.5. <code>named()</code></h4>
<div class="paragraph">
-<p>The <code>named()</code> attribute explicitly specifies the domain object’s name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for <a href="#_rg_annotations_manpage-ActionLayout_named">actions</a>, <a href="#_rg_annotations_manpage-CollectionLayout_named">collections</a>, <a href="#_rg_annotations_manpage-PropertyLayout_named">properties</a>, <a href="#_rg_annotations_manpage-ParameterLayout_named">parameters</a>, <a href="#_rg_annotations_manpage-ViewModelLayout_named">view models</a> and <a href="#_rg_annotations_manpage-DomainServiceLayout_named">domain services</a>.</p>
+<p>Subscribers subscribe through the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> using either <a href="https://github.com/google/guava">Guava</a> or <a href="http://www.axonframework.org/">Axon Framework</a> annotations and can
+optionally specify a title.</p>
</div>
-<div class="admonitionblock tip">
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>Following the <a href="http://en.wikipedia.org/wiki/Don%27t_repeat_yourself">don’t repeat yourself</a> principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.</p>
+<p>The feature was originally introduced so that <a href="#_rg_annotations_manpage-XmlRootElement"><code>@XmlRootElement</code></a>-annotated
+<a href="ug.html#_ug_more-advanced_view-models">view model</a>s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while <a href="ug.html#_ug_more-advanced_decoupling_mixins">mixin</a>s can be used to provide the behaviour.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
+<p>By default the event raised is <code>CssClassUiEvent.Default</code>. For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The purpose of the <code>cssClassUiEvent()</code> attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for titles and icons.</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="annotation">@DomainObjectLayout</span>(
- named=<span class="string"><span class="delimiter">"</span><span class="content">Customer</span><span class="delimiter">"</span></span>
+ iconUiEvent=ToDoItemDto.CssClassUiEvent.class
)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerImpl</span> <span class="directive">implements</span> Customer{
- ...
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">CssClassUiEvent</span>
+ <span class="directive">extends</span> org.apache.isis.applib.services.eventbus.CssClassUiEvent<ToDoItemDto> { }
+ ...
}</code></pre>
</div>
</div>
<div class="paragraph">
-<p>It’s also possible to specify a <a href="#_rg_annotations_manpage-DomainObjectLayout_plural">plural form</a> of the name, used by the framework when rendering a standalone collection of the domain object.</p>
+<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
+</div>
+<div class="sect4">
+<h5 id="_subscribers_3">Subscribers</h5>
+<div class="paragraph">
+<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
+or (if the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> has been appropriately configured)
+using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
+</div>
+<div class="paragraph">
+<p>Subscribers can be either coarse-grained (if they subscribe to the top-level event type):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(CssClassUiEvent ev) {
+ <span class="keyword">if</span>(ev.getSource() <span class="keyword">instanceof</span> ToDoItemDto) { ... }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>or can be fine-grained (by subscribing to specific event subtypes):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(ToDoItemDto.CssClassUiEvent ev) {
+ ...
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The subscriber should then use <code>CssClassUiEvent#setCssClass(…​)</code> to actually specify the CSS class to be used.</p>
</div>
<div class="admonitionblock tip">
<table>
@@ -5873,94 +6038,481 @@ member so that it can be styled in an application-specific way.</p>
</td>
<td class="content">
<div class="paragraph">
-<p>The framework also provides a separate, powerful mechanism for <a href="ug.html#_ug_more-advanced_i18n">internationalization</a>.</p>
+<p>If the AxonFramework is being used, replace <code>@com.google.common.eventbus.Subscribe</code> with <code>@org.axonframework.eventhandling.annotation.EventHandler</code>.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
+<div class="sect4">
+<h5 id="_default_doop_and_noop_events">Default, Doop and Noop events</h5>
+<div class="paragraph">
+<p>If the <code>cssClassUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>CssClassUiEvent.Default</code>),
+then the framework will, by default, post an event.</p>
+</div>
+<div class="paragraph">
+<p>If this is not required, then the <code>isis.reflector.facet.domainObjectLayoutAnnotation.cssClassUiEvent.postForDefault</code>
+configuration property can be set to "false"; this will disable posting.</p>
+</div>
+<div class="paragraph">
+<p>On the other hand, if the <code>cssClassUiEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>CssClassUiEvent.Doop</code> as such a subclass, so setting the <code>cssClassUiEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.</p>
+</div>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>CssClassUiEvent.Noop</code>; if <code>cssClassUiEvent</code> attribute is set to this class,
+thn no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_raising_events_programmatically_3">Raising events programmatically</h5>
+<div class="paragraph">
+<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> API directly, or as a result
+of calling the <a href="#_rg_services-api_manpage-DomainObjectContainer"><code>DomainObjectContainer</code></a>'s
+<code>cssClassOf(…​)</code> method.</p>
+</div>
+</div>
+</div>
<div class="sect3">
-<h4 id="_rg_annotations_manpage-DomainObjectLayout_paged">2.10.6. <code>paged()</code></h4>
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_describedAs">2.10.5. <code>describedAs()</code></h4>
<div class="paragraph">
-<p>The <code>paged()</code> attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to <a href="#_rg_annotations_manpage-CollectionLayout_paged">collections</a> and <a href="#_rg_annotations_manpage-ViewModelLayout_paged">view models</a>.</p>
+<p>The <code>describedAs()</code> attribute is used to provide a short description of the domain object to the user. In the <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> it is displayed as a 'tool tip'. The attribute can also be specified for <a href="#_rg_annotations_manpage-CollectionLayout_describedAs">collections</a>, <a href="#_rg_annotations_manpage-PropertyLayout_describedAs">properties</a>, <a href="#_rg_annotations_manpage-ActionLayout_describedAs">actions</a>, <a href="#_rg_annotations_manpage-ParameterLayout_describedAs">parameters</a> and <a href="#_rg_annotations_manpage-ViewModelLayout_describedAs">view models</a>.</p>
</div>
-<div class="admonitionblock warning">
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DescribedAs</span>(<span class="string"><span class="delimiter">"</span><span class="content">A customer who may have originally become known to us via </span><span class="delimiter">"</span></span> +
+ <span class="string"><span class="delimiter">"</span><span class="content">the marketing system or who may have contacted us directly.</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ProspectiveSale</span> {
+ ...
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_iconUiEvent">2.10.6. iconUiEvent() (<code>1.11.0-SNAPSHOT</code>)</h4>
+<div class="paragraph">
+<p>Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
+object (if possible). This is as an alternative to implementing
+<a href="#_rg_methods_reserved_manpage-iconName"><code>iconName()</code></a> reserved method. (If <code>iconName()</code> is present, then
+it will take precedence).</p>
+</div>
+<div class="paragraph">
+<p>Subscribers subscribe through the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> using either <a href="https://github.com/google/guava">Guava</a> or <a href="http://www.axonframework.org/">Axon Framework</a> annotations and can
+optionally specify a title.</p>
+</div>
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-warning" title="Warning"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>The <a href="ug.html#<em>ug_restfulobjects-viewer">RestfulObjects viewer</a> currently does not support paging. The <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> _does</em> support paging, but note that the paging is performed client-side rather than server-side.</p>
-</div>
-<div class="paragraph">
-<p>We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).</p>
+<p>The feature was originally introduced so that <a href="#_rg_annotations_manpage-XmlRootElement"><code>@XmlRootElement</code></a>-annotated
+<a href="ug.html#_ug_more-advanced_view-models">view model</a>s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while <a href="ug.html#_ug_more-advanced_decoupling_mixins">mixin</a>s can be used to provide the behaviour.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>By default the event raised is <code>IconUiEvent.Default</code>. For example:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>(paged=<span class="integer">15</span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
...
}</code></pre>
</div>
</div>
<div class="paragraph">
-<p>It is also possible to specify a global default for the page size of standalone collections, using the <a href="#_rg_runtime_configuring-core">configuration property</a> <code>isis.viewer.paged.standalone</code>.</p>
+<p>The purpose of the <code>iconUiEvent()</code> attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for titles and CSS classes.</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="annotation">@DomainObjectLayout</span>(
+ iconUiEvent=ToDoItemDto.IconUiEvent.class
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">IconUiEvent</span>
+ <span class="directive">extends</span> org.apache.isis.applib.services.eventbus.IconUiEvent<ToDoItemDto> { }
+ ...
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_rg_annotations_manpage-DomainObjectLayout_plural">2.10.7. <code>plural()</code></h4>
<div class="paragraph">
-<p>When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.</p>
+<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
</div>
+<div class="sect4">
+<h5 id="_subscribers_4">Subscribers</h5>
<div class="paragraph">
-<p>By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").</p>
+<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
+or (if the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> has been appropriately configured)
+using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
</div>
<div class="paragraph">
-<p>The <code>plural()</code> attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for <a href="#_rg_annotations_manpage-ViewModelLayout_plural">view models</a>.</p>
+<p>Subscribers can be either coarse-grained (if they subscribe to the top-level event type):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(IconUiEvent ev) {
+ <span class="keyword">if</span>(ev.getSource() <span class="keyword">instanceof</span> ToDoItemDto) { ... }
+ }
+}</code></pre>
+</div>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>or can be fine-grained (by subscribing to specific event subtypes):</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>(plural=<span class="string"><span class="delimiter">"</span><span class="content">Children</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Child</span> {
- ...
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(ToDoItemDto.IconUiEvent ev) {
+ ...
+ }
}</code></pre>
</div>
</div>
+<div class="paragraph">
+<p>The subscriber should then use <code>IconUiEvent#setIconName(…​)</code> to actually specify the icon name to be used.</p>
</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>If the AxonFramework is being used, replace <code>@com.google.common.eventbus.Subscribe</code> with <code>@org.axonframework.eventhandling.annotation.EventHandler</code>.</p>
</div>
-<div class="sect2">
-<h3 id="_rg_annotations_manpage-DomainService">2.11. <code>@DomainService</code></h3>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_default_doop_and_noop_events_2">Default, Doop and Noop events</h5>
<div class="paragraph">
-<p>The <code>@DomainService</code> annotation indicates that the (concrete) class should be automatically instantiated as a domain service.</p>
+<p>If the <code>iconUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>IconUiEvent.Default</code>),
+then the framework will, by default, post an event.</p>
</div>
<div class="paragraph">
-<p>Domain services with this annotation do NOT need to be registered explicitly in <code>isis.properties</code>; they will be
-discovered automatically on the CLASSPATH.</p>
+<p>If this is not required, then the <code>isis.reflector.facet.domainObjectLayoutAnnotation.iconUiEvent.postForDefault</code>
+configuration property can be set to "false"; this will disable posting.</p>
</div>
<div class="paragraph">
-<p>The table below summarizes the annotation’s attributes.</p>
+<p>On the other hand, if the <code>iconUiEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>IconUiEvent.Doop</code> as such a subclass, so setting the <code>iconUiEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.</p>
</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 14. <code>@DomainService</code> attributes</caption>
-<colgroup>
-<col style="width: 25%;">
-<col style="width: 25%;">
-<col style="width: 50%;">
-</colgroup>
-<thead>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>IconUiEvent.Noop</code>; if <code>iconUiEvent</code> attribute is set to this class,
+then no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_raising_events_programmatically_4">Raising events programmatically</h5>
+<div class="paragraph">
+<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> API directly, or as a result
+of calling the <a href="#_rg_services-api_manpage-DomainObjectContainer"><code>DomainObjectContainer</code></a>'s
+<code>iconNameOf(…​)</code> method.</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_named">2.10.7. <code>named()</code></h4>
+<div class="paragraph">
+<p>The <code>named()</code> attribute explicitly specifies the domain object’s name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for <a href="#_rg_annotations_manpage-ActionLayout_named">actions</a>, <a href="#_rg_annotations_manpage-CollectionLayout_named">collections</a>, <a href="#_rg_annotations_manpage-PropertyLayout_named">properties</a>, <a href="#_rg_annotations_manpage-ParameterLayout_named">parameters</a>, <a href="#_rg_annotations_manpage-ViewModelLayout_named">view models</a> and <a href="#_rg_annotations_manpage-DomainServiceLayout_named">domain services</a>.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>Following the <a href="http://en.wikipedia.org/wiki/Don%27t_repeat_yourself">don’t repeat yourself</a> principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.</p>
+</div>
+</td>
+</tr>
+</table>
+</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="annotation">@DomainObjectLayout</span>(
+ named=<span class="string"><span class="delimiter">"</span><span class="content">Customer</span><span class="delimiter">"</span></span>
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerImpl</span> <span class="directive">implements</span> Customer{
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>It’s also possible to specify a <a href="#_rg_annotations_manpage-DomainObjectLayout_plural">plural form</a> of the name, used by the framework when rendering a standalone collection of the domain object.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The framework also provides a separate, powerful mechanism for <a href="ug.html#_ug_more-advanced_i18n">internationalization</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_paged">2.10.8. <code>paged()</code></h4>
+<div class="paragraph">
+<p>The <code>paged()</code> attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to <a href="#_rg_annotations_manpage-CollectionLayout_paged">collections</a> and <a href="#_rg_annotations_manpage-ViewModelLayout_paged">view models</a>.</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>The <a href="ug.html#<em>ug_restfulobjects-viewer">RestfulObjects viewer</a> currently does not support paging. The <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> _does</em> support paging, but note that the paging is performed client-side rather than server-side.</p>
+</div>
+<div class="paragraph">
+<p>We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).</p>
+</div>
+</td>
+</tr>
+</table>
+</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="annotation">@DomainObjectLayout</span>(paged=<span class="integer">15</span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span> {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>It is also possible to specify a global default for the page size of standalone collections, using the <a href="#_rg_runtime_configuring-core">configuration property</a> <code>isis.viewer.paged.standalone</code>.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_plural">2.10.9. <code>plural()</code></h4>
+<div class="paragraph">
+<p>When Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.</p>
+</div>
+<div class="paragraph">
+<p>By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").</p>
+</div>
+<div class="paragraph">
+<p>The <code>plural()</code> attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for <a href="#_rg_annotations_manpage-ViewModelLayout_plural">view models</a>.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>(plural=<span class="string"><span class="delimiter">"</span><span class="content">Children</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Child</span> {
+ ...
+}</code></pre>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-DomainObjectLayout_titleUiEvent">2.10.10. titleUiEvent() (<code>1.11.0-SNAPSHOT</code>)</h4>
+<div class="paragraph">
+<p>Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
+This is as an alternative to implementing <a href="#_rg_methods_reserved_manpage-title"><code>title()</code></a> reserved method, or
+using the <a href="#_rg_annotations_manpage-Title"><code>@Title</code></a> annotation, within the class itself. (If either
+<code>title()</code> or <code>@Title</code> are present, then they will take precedence).</p>
+</div>
+<div class="paragraph">
+<p>Subscribers subscribe through the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> using either <a href="https://github.com/google/guava">Guava</a> or <a href="http://www.axonframework.org/">Axon Framework</a> annotations and can
+optionally specify a title.</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>The feature was originally introduced so that <a href="#_rg_annotations_manpage-XmlRootElement"><code>@XmlRootElement</code></a>-annotated
+<a href="ug.html#_ug_more-advanced_view-models">view model</a>s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while <a href="ug.html#_ug_more-advanced_decoupling_mixins">mixin</a>s can be used to provide the behaviour.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<p>By default the event raised is <code>TitleUiEvent.Default</code>. For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObjectLayout</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The purpose of the <code>titleUiEvent()</code> attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for icon names and CSS classes.</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="annotation">@DomainObjectLayout</span>(
+ titleUiEvent=ToDoItemDto.TitleUiEvent.class
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> {
+ <span class="directive">public</span> <span class="directive">static</span> <span class="type">class</span> <span class="class">TitleUiEvent</span>
+ <span class="directive">extends</span> org.apache.isis.applib.services.eventbus.TitleUiEvent<ToDoItemDto> { }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The benefit is that subscribers can be more targeted as to the events that they subscribe to.</p>
+</div>
+<div class="sect4">
+<h5 id="_subscribers_5">Subscribers</h5>
+<div class="paragraph">
+<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API
+or (if the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> has been appropriately configured)
+using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
+</div>
+<div class="paragraph">
+<p>Subscribers can be either coarse-grained (if they subscribe to the top-level event type):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(TitleUiEvent ev) {
+ <span class="keyword">if</span>(ev.getSource() <span class="keyword">instanceof</span> ToDoItemDto) { ... }
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>or can be fine-grained (by subscribing to specific event subtypes):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
+ <span class="annotation">@com</span>.google.common.eventbus.Subscribe
+ <span class="directive">public</span> <span class="type">void</span> on(ToDoItemDto.TitleUiEvent ev) {
+ ...
+ }
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The subscriber should then use either <code>TitleUiEvent#setTranslatableTitle(…​)</code> or <code>TitleUiEvent#setTitle(…​)</code> to
+actually specify the title to be used.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>If the AxonFramework is being used, replace <code>@com.google.common.eventbus.Subscribe</code> with <code>@org.axonframework.eventhandling.annotation.EventHandler</code>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_default_doop_and_noop_events_3">Default, Doop and Noop events</h5>
+<div class="paragraph">
+<p>If the <code>titleUiEvent</code> attribute is not explicitly specified (is left as its default value, <code>TitleUiEvent.Default</code>),
+then the framework will, by default, post an event.</p>
+</div>
+<div class="paragraph">
+<p>If this is not required, then the <code>isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault</code>
+configuration property can be set to "false"; this will disable posting.</p>
+</div>
+<div class="paragraph">
+<p>On the other hand, if the <code>titleUiEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>TitleUiEvent.Doop</code> as such a subclass, so setting the <code>titleUiEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.</p>
+</div>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>TitleUiEvent.Noop</code>; if <code>titleUiEvent</code> attribute is set to this class,
+thn no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_raising_events_programmatically_5">Raising events programmatically</h5>
+<div class="paragraph">
+<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> API directly, or as a result
+of calling the <a href="#_rg_services-api_manpage-DomainObjectContainer"><code>DomainObjectContainer</code></a>'s
+<code>titleOf(…​)</code> method.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rg_annotations_manpage-DomainService">2.11. <code>@DomainService</code></h3>
+<div class="paragraph">
+<p>The <code>@DomainService</code> annotation indicates that the (concrete) class should be automatically instantiated as a domain service.</p>
+</div>
+<div class="paragraph">
+<p>Domain services with this annotation do NOT need to be registered explicitly in <code>isis.properties</code>; they will be
+discovered automatically on the CLASSPATH.</p>
+</div>
+<div class="paragraph">
+<p>The table below summarizes the annotation’s attributes.</p>
+</div>
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 14. <code>@DomainService</code> attributes</caption>
+<colgroup>
+<col style="width: 25%;">
+<col style="width: 25%;">
+<col style="width: 50%;">
+</colgroup>
+<thead>
<tr>
<th class="tableblock halign-left valign-top">Attribute</th>
<th class="tableblock halign-left valign-top">Values (default)</th>
@@ -8132,7 +8684,10 @@ so that boilerplate-busting tools such as <a href="https://projectlombok.org/">P
</div>
</div>
<div class="paragraph">
-<p>The purpose of the <code>domainEvent()</code> attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for <a href="#_rg_annotations_manpage-Action_domainEvent">actions</a> and <a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
+<p>The <code>domainEvent()</code> attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+ <a href="#_rg_annotations_manpage-Action_domainEvent">actions</a> and
+ <a href="#_rg_annotations_manpage-Property_domainEvent">properties</a>.</p>
</div>
<div class="paragraph">
<p>For example:</p>
@@ -8174,7 +8729,7 @@ rather than through the constructor. This substantially reduces the boilerplate
</table>
</div>
<div class="sect4">
-<h5 id="_subscribers_3">Subscribers</h5>
+<h5 id="_subscribers_6">Subscribers</h5>
<div class="paragraph">
<p>Subscribers (which must be domain services) subscribe using either the <a href="https://github.com/google/guava">Guava</a> API or (if the <a href="#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> has been appropriately configured) using the <a href="http://www.axonframework.org/">Axon Framework</a> API. The examples below use the Guava API.</p>
</div>
@@ -8183,16 +8738,12 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
-
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
- <span class="directive">public</span> <span class="type">void</span> on(PropertyInteractionEvent ev) {
-
+ <span class="directive">public</span> <span class="type">void</span> on(PropertyDomainEvent ev) {
...
}
-
}</code></pre>
</div>
</div>
@@ -8201,16 +8752,12 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> {
-
- <span class="annotation">@Programmatic</span>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature=NatureOfService.DOMAIN)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubscriber</span> <span class="directive">extends</span> AbstractSubscriber {
<span class="annotation">@com</span>.google.common.eventbus.Subscribe
<span class="directive">public</span> <span class="type">void</span> on(ToDoItem.DueByChangedEvent ev) {
-
...
}
-
}</code></pre>
</div>
</div>
@@ -8282,15 +8829,35 @@ rather than through the constructor. This substantially reduces the boilerplate
</div>
</div>
<div class="sect4">
-<h5 id="_raising_events_programmatically_3">Raising events programmatically</h5>
+<h5 id="_default_doop_and_noop_events_code_1_11_0_snapshot_code_3">Default, Doop and Noop events (<code>1.11.0-SNAPSHOT</code>)</h5>
<div class="paragraph">
-<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
-wrapping the target object using the <a href="#_rg_services-api_manpage-WrapperFactory"><code>WrapperFactory</code></a> service.</p>
+<p>If the <code>domainEvent</code> attribute is not explicitly specified (is left as its default value, <code>PropertyDomainEvent.Default</code>),
+then the framework will, by default, post an event.</p>
</div>
+<div class="paragraph">
+<p>If this is not required, then the <code>isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault</code>
+configuration property can be set to "false"; this will disable posting.</p>
</div>
+<div class="paragraph">
+<p>On the other hand, if the <code>domainEvent</code> has been explicitly specified to some subclass, then an event will be posted.
+The framework provides <code>PropertyDomainEvent.Doop</code> as such a subclass, so setting the <code>domainEvent</code> attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.</p>
</div>
-<div class="sect3">
-<h4 id="_rg_annotations_manpage-Property_editing">2.27.2. <code>editing()</code></h4>
+<div class="paragraph">
+<p>And, conversely, the framework also provides <code>PropertyDomainEvent.Noop</code>; if <code>domainEvent</code> attribute is set to this class,
+then no event will be posted.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_raising_events_programmatically_6">Raising events programmatically</h5>
+<div class="paragraph">
+<p>Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
+wrapping the target object using the <a href="#_rg_services-api_manpage-WrapperFactory"><code>WrapperFactory</code></a> service.</p>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_rg_annotations_manpage-Property_editing">2.27.2. <code>editing()</code></h4>
<div class="paragraph">
<p>The <code>editing()</code> attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for <a href="#_rg_annotations_manpage-Collection_editing">collections</a>, and can also be specified for the <a href="#_rg_annotations_manpage-DomainObject_editing">domain object</a>.</p>
</div>
@@ -9853,6 +10420,146 @@ for symmetry with domain objects that have been annotated using <a href="#_rg_an
</div>
</div>
</div>
+<div class="sect2">
+<h3 id="_rg_annotations_manpage-XmlJavaTypeAdapter">2.33. <code>@XmlJavaTypeAdapter</code> (<code>jaxb</code>) (<code>1.11.0-SNAPSHOT</code>)</h3>
+<div class="paragraph">
+<p>The JAXB <code>@XmlJavaTypeAdapter</code> annotation (<code>1.11.0-SNAPSHOT</code>) is used with the framework-provided
+<code>PersistentEntityAdapter</code> to instruct JAXB to serialize references to persistent entities using the canonical
+<code>OidDto</code> complex type: the object’s type and its identifier. This is the formal XML equivalent to the <code>Bookmark</code>
+provided by the <a href="#_rg_services-api_manpage-BookmarkService"><code>BookmarkService</code></a>.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlJavaTypeAdapter</span>(PersistentEntityAdapter.class)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> ... {
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom.</p>
+</div>
+<div class="paragraph">
+<p>For a more complete discussion of writing JAXB view models/DTOs, see <a href="ug.html#_ug_more-advanced_view-models">this topic</a>
+in the user guide.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rg_annotations_manpage-XmlRootElement">2.34. <code>@XmlRootElement</code> (<code>jaxb</code>) (<code>1.11.0-SNAPSHOT</code>)</h3>
+<div class="paragraph">
+<p>The <code>@XmlRootElement</code> annotation (<code>1.11.0-SNAPSHOT</code>) provides an alternative way to define a
+<a href="#_ug_more-advanced_view-models">view model</a>, in particular one intended to act as a DTO for use within
+<a href="ug.html#_ug_restfulobjects-viewer">RestfulObjects viewer</a>, or which contains arbitrarily complex state.</p>
+</div>
+<div class="paragraph">
+<p>A view model is a non-persisted domain object whose state is converted to/from a string memento. In the case of a
+JAXB-annotated object this memento is its XML representation. JAXB generally requires that the root element of the
+XML representation is annotated with <code>@XmlRootElement</code>. Apache Isis makes this a mandatory requirement.</p>
+</div>
+<div class="paragraph">
+<p>In comparison to using either the <a href="#_rg_classes_super_manpage-ViewModel"><code>ViewModel</code></a> interface or the
+<a href="#_rg_annotations_manpage-ViewModel"><code>@ViewModel</code></a> annotation, using <code>@XmlRootElement</code> has a couple of
+significant advantages:</p>
+</div>
+<div class="ulist">
+<ul>
+<li>
+<p>the view model can be used as a "canonical" DTO, for example when accessing data using the
+<a href="ug.html#_ug_restfulobjects-viewer">RestfulObjects viewer</a> in combination with the
+<a href="#_rg_services-spi_manpage-ContentMappingService"><code>ContentMappingService</code></a>.<br></p>
+<div class="paragraph">
+<p>This provides a stable and
+versioned API to access data in XML format using whatever client-side technology may be appropriate.</p>
+</div>
+</li>
+<li>
+<p>the XML graph can be as deep as required; in particular it can contain collections of other objects.<br></p>
+<div class="paragraph">
+<p>In contrast, if the <code>@ViewModel</code> annotation is used then only the state of the properties (not collections) is captured.
+If using <code>ViewModel</code> interface then arbitrary state (including that of collections), however the programmer must write
+all the code by hand</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="paragraph">
+<p>The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
+with the <a href="#_rg_annotations_manpage-XmlJavaTypeAdapter"><code>@XmlJavaTypeAdapter</code></a>, using the
+framework-provided <code>PersistentEntityAdapter</code>. This adapter converts any references to such domain entities using the
+<code>oidDto</code> complex type (as defined by the Apache Isis <a href="#_rg_schema-common">common schema</a>):
+the object’s type and its identifier.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The memento string for view models is converted into a form compatible with use within a URL. This is performed by the
+<a href="#_rg_services-spi_manpage-UrlEncodingService"><code>UrlEncodingService</code></a>, the default implementation of which
+simply encodes to base 64. If the view model XML graph is too large to be serialized to a string, then an alternative
+implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in
+<a href="#_ug_how-tos_replacing-default-service-implementations">here</a> in the user guide.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+<div class="sect3">
+<h4 id="_example">2.34.1. Example</h4>
+<div class="paragraph">
+<p>This example is taken from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</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">ToDoItemDto</span> <span class="directive">implements</span> Dto {
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span> <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> description;
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> category;
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> subcategory;
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">BigDecimal</span> cost;
+}</code></pre>
+</div>
+</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>identifies this class as a view model and defines the root element for JAXB serialization</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>using Project Lombok for getters and setters</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_see_also">2.34.2. See also</h4>
+<div class="paragraph">
+<p>Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep
+the DTO "clean", just focused on specifying the data contract.</p>
+</div>
+<div class="paragraph">
+<p>Behaviour can therefore be provided using <a href="ug.html#_ug_more-advanced_decoupling_mixins">mixins</a> (annotated with
+<a href="#_rg_annotations_manpage-Mixin"><code>@Mixin</code></a>), while <a href="#_rg_classes_uievent">UI events</a> can be used
+to obtain title, icons and so on.</p>
+</div>
+<div class="paragraph">
+<p>For a more complete discussion of writing JAXB view models/DTOs, see <a href="ug.html#_ug_more-advanced_view-models">this topic</a>
+in the user guide.</p>
+</div>
+</div>
+</div>
</div>
</div>
<div class="sect1">
@@ -12328,6 +13035,22 @@ SpecificationProvider</code></a>.</p>
<td class="tableblock halign-left valign-top"><div></div></td>
</tr>
<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_services-api_manpage-JaxbService"><code>o.a.i.applib.</code><br>
+<code>services.jaxb</code><br>
+<code>JaxbService</code></a></p></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p>Marshal and unmarshal JAXB-annotated view models to/from XML.</p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><code>JaxbServiceDefault</code><br>
+<code>o.a.i.core</code><br>
+<code>isis-core-schema</code></p>
+</div></div></td>
+<td class="tableblock halign-left valign-top"><div><div class="paragraph">
+<p><code>1.11.0-SNAPSHOT</code>.</p>
+</div></div></td>
+</tr>
+<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><a href="#_rg_services-api_manpage-MementoService"><code>o.a.i.applib.</code><br>
<code>services.memento</code><br>
<code>MementoService</code></a></p></td>
@@ -12590,15 +13313,14 @@ SpecificationProvider</code></a>.</p>
<h4 id="_registering_the_service">4.1.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default
+implementation of <code>ActionInvocationContext</code> class is automatically registered (it is annotated with <code>@DomainService</code>)
+so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Isis' default implementation of <code>ActionInvocationContext</code> class is automatically registered (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
<div class="sect3">
@@ -12745,15 +13467,14 @@ CommandContext commandContext; <i class="conum" data-value="1"></i><b>(1)</b></
<h4 id="_registering_the_services">4.2.4. Registering the Services</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>BackgroundService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no
+further configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>BackgroundService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
<div class="sect3">
@@ -13095,15 +13816,14 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<h4 id="_registering_the_service_2">4.3.4. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>BookmarkService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further
+configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>BookmarkService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
</div>
@@ -13225,18 +13945,13 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<h4 id="_registering_the_service_3">4.4.3. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>ClockService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further
+configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>ClockService</code> is automatically registered (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
-</div>
-<div class="paragraph">
-<p>If you want to use a different implementation of <code>Clock</code>, eg delegating to NNTP, then do <em>not</em> register directly, but instead subclass from <code>o.a.i.applib.clock.Clock</code> singleton (as described in the section above).</p>
+<p>If you want to use a different implementation of <code>Clock</code>, eg delegating to NNTP, then do <em>not</em> register directly, but
+instead subclass from <code>o.a.i.applib.clock.Clock</code> singleton (as described in the section above).</p>
</div>
</div>
</div>
@@ -13526,15 +14241,14 @@ org.quartz.plugin.jobInitializer.failOnFileNotFound = true</code></pre>
<h4 id="_registering_the_services_2">4.5.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="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>CommandContext</code> service is automatically registered and injected (it is annotated with
+<code>@DomainService</code>) so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>CommandContext</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
<div class="sect3">
@@ -13603,15 +14317,14 @@ view model.</p>
<h4 id="_registering_the_services_3">4.6.4. Registering the Services</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#<em>rg_classes_AppManifest-bootstrapping">bootstrap the app</a>), _and</em> that the
+<a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> is being used, then an implementation of <code>DeepLinkService</code> is
+automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>and that the <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> is being used then an implementation of <code>DeepLinkService</code> is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
</div>
@@ -14263,15 +14976,9 @@ container.persist(cust);</code></pre>
<h4 id="_registering_the_service_4">4.7.10. Registering the Service</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>DomainObjectContainer</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>DomainObjectContainer</code> service is automatically registered and injected (it is annotated with
+<code>@DomainService</code>) so no further configuration is required.</p>
</div>
</div>
</div>
@@ -14398,18 +15105,14 @@ container.persist(cust);</code></pre>
<h4 id="_registering_the_services_4">4.8.4. Registering the Services</h4>
<div class="paragraph">
<p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the
-<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>EmailService</code> service is automatically registered and injected (it is annotated with
+<code>@DomainService</code>) so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>EmailService</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
-</div>
-<div class="paragraph">
-<p>If you have written an alternative implementation, then register your implementation in <code>isis.properties</code> under the "isis.services" key and it will be used instead.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
<div class="sect3">
@@ -14925,15 +15628,14 @@ public <span class="directive">static</span> <span class="type">class</span> <sp
<h4 id="_registering_the_services_5">4.9.9. 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="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>EventBusService</code> service is automatically registered and injected (it is annotated with
+<code>@DomainService</code>) so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>EventBusService</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
<div class="sect3">
@@ -15102,15 +15804,14 @@ public <span class="directive">static</span> <span class="type">class</span> <sp
<h4 id="_registering_the_services_6">4.11.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="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
-</div>
+<code>AppManifest</code> to <a href="#<em>rg_classes_AppManifest-bootstrapping">bootstrap the app</a>), _and</em> that the
+<a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> is being used, then an implementation of <code>GuiceBeanProvider</code> is
+automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
</div>
<div class="paragraph">
-<p>and that the <a href="ug.html#_ug_wicket-viewer">Wicket viewer</a> is being used then an implementation of <code>GuiceBeanProvider</code> is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
</div>
</div>
</div>
@@ -15431,20 +16132,98 @@ refresh the parent.</p>
<h4 id="_registering_the_services_7">4.12.6. 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="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>):</p>
+<code>AppManifest</code> to <a href="#_rg_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' core
+implementation of <code>IsisJdoSupport</code> service is automatically registered and injected (it is annotated with
+<code>@DomainService</code>) so no further configuration is required.</p>
+</div>
+<div class="paragraph">
+<p>To use an alternative implementation, use
+<a href="#_rg_annotations_manpage-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained
+further in this <a href="ug.html#_ug_how-tos_replacing-default-service-implementations">"how to"</a> tip).</p>
+</div>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_rg_services-api_manpage-JaxbService">4.13. <code>JaxbService</code> (<code>1.11.0-SNAPSHOT</code>)</h3>
+<div class="paragraph">
+<p>The <code>JaxbService</code> (<code>1.11.0-SNAPSHOT</code>) allows instances of JAXB-annotated classes to be marshalled to XML and
+unmarshalled from XML back into domain objects.</p>
+</div>
+<div class="sect3">
+<h4 id="_rg_services-api_manpage-JaxbService_api-and-implementation">4.13.1. API & Implementation</h4>
+<div class="paragraph">
+<p>The API defined by <code>JaxbService</code> is:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.services-installer=configuration-and-annotation</code></pre>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">JaxbService</span> {
+ <span class="annotation">@Programmatic</span>
+ <T> T fromXml(<span class="predefined-type">Class</span><T> domainClass, <span class="predefined-type">String</span> xml); <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="annotation">@Programmatic</span>
+ <span class="directive">public</span> <span class="predefined-type">String</span> toXml(<span class="directive">final</span> <span class="predefined-type">Object</span> domainObject); <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="directive">public</span> <span class="type">enum</span> IsisSchemas { <i class="conum" data-value="3"></i><b>(3)</b>
+ INCLUDE, IGNORE
+ }
+ <span class="annotation">@Programmatic</span>
+ <span class="directive">public</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> toXsd(<span class="directive">final</span> <span class="predefined-type">Object</span> domainObject, <span class="directive">final</span> IsisSchemas isSchemas);} <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>unmarshalls the XML into an instance of the class.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>marshalls the domain object into XML</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="3"></i><b>3</b></td>
+<td>whether to include or exclude the Isis schemas in the generated map of XSDs. Discussed further below.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="4"></i><b>4</b></td>
+<td>generates a map of each of the schemas referenced; the key is the schema namespace, the value is the XML of the schema itself.</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
-<p>then Apache Isis' core implementation of <code>IsisJdoSupport</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p>
+<p>With respect to the <code>IsisSchemas</code> enum: a JAXB-annotated domain object will live in its own XSD namespace and may
+reference multiple other XSD schemas. In particular, many JAXB domain objects will reference the
+<a href="#_rg_schema">common Isis schemas</a> (for example the <code>OidDto</code> class that represents a reference to
+a persistent entity). The enum indicates whether these schemas should be included or excluded from the map.</p>
+</div>
+<div class="paragraph">
+<p>Isis provides a default implementation of the service, <code>o.a.i.schema.services.jaxb.JaxbServiceDefault</code>.</p>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_usage_within_the_framework_2">4.13.2. Usage within the framework</h4>
+<div class="paragraph">
+<p>This service is provided as a convenience for applications, but is also used internally by the framework to
+<a href="#_rg_annotations_manpage-XmlRootElement"><code>@XmlRootElement</code></a>-annotated
+<a href="ug.html#_ug_more-advanced_view-models">view models</a>. The functionality to download XML and XSD schemas is also
+exposed in the UI through mixins to <
<TRUNCATED>