http://git-wip-us.apache.org/repos/asf/isis-site/blob/9d921a51/content/guides/rgsvc/rgsvc.html ---------------------------------------------------------------------- diff --git a/content/guides/rgsvc/rgsvc.html b/content/guides/rgsvc/rgsvc.html index 383fd70..c679a2e 100644 --- a/content/guides/rgsvc/rgsvc.html +++ b/content/guides/rgsvc/rgsvc.html @@ -179,6 +179,7 @@ table.CodeRay td.code>pre{padding:0} <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li> <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li> <li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li> + <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object Store</a></li> <li><a href="../../guides/ugsec/ugsec.html">Security</a></li> <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li> <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li> @@ -196,25 +197,32 @@ table.CodeRay td.code>pre{padding:0} </ul> </li> <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a> <ul class="dropdown-menu"> - <li><a href="../../downloads.html">Downloads</a></li> - <li><a href="../../release-notes/release-notes.html">Release Notes</a></li> - <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li> - <li role="separator" class="divider"></li> <li class="dropdown-header">Maven archetypes</li> <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li> <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li> <li role="separator" class="divider"></li> - <li><a href="https://issues.apache.org/jira/browse/ISIS";>ASF JIRA</a></li> + <li><a href="../../downloads.html">Downloads</a></li> + <li><a href="../../release-notes/release-notes.html">Release Notes</a></li> + <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li> + <li role="separator" class="divider"></li> <li><a href="https://github.com/apache/isis";>Github mirror</a></li> </ul> </li> <li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a> <ul class="dropdown-menu"> - <li><a href="../../support.html">Mailing lists</a></li> + <li class="dropdown-header">Guides</li> + <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li> + <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li> + <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Mailing Lists</li> + <li><a href="../../support.html">How to subscribe</a></li> <li><a href="https://lists.apache.org/[email protected]";>Archives (ASF Pony mail)</a></li> <li><a href="http://isis.markmail.org/search/?q=";>Archives (Markmail)</a></li> + <li role="separator" class="divider"></li> + <li class="dropdown-header">Other Resources</li> + <li><a href="https://issues.apache.org/jira/browse/ISIS";>ASF JIRA</a></li> <li><a href="http://stackoverflow.com/questions/tagged/isis";>Stack Overflow</a></li> - <li><a href="../../guides/dg/dg.html">How to contribute</a></li> - <li><a href="../../help.html">Other resources</a></li> + <li><a href="../../help.html">Wiki, Fisheye etc.</a></li> </ul> </li> <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a> <ul class="dropdown-menu"> @@ -565,27 +573,27 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect1"> - <h2 id="_rgsvc_presentation-layer-spi">3. Presentation Layer SPI</h2> + <h2 id="_rgsvc_presentation-layer-api">3. Presentation Layer API</h2> <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> - <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> <ul class="dropdown-menu"> - <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> - <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> - <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> - <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> </ul> </div> <div class="sectionbody"> <div class="paragraph"> - <p>Domain service SPIs for the presentation layer influence how the Apache Isis viewers behave.</p> + <p>Domain service APIs for the presentation layer allow the domain objects to control aspects of the user interface. The implementations are specific to the particular viewer (<a href="../ugvw/ugvw.html">Wicket viewer</a> or <a href="../ugvro/ugvro.html">Restful Objects viewer</a>) so the domain code must guard against them being unavailable in some cases.</p> </div> <div class="paragraph"> - <p>The table below summarizes the presentation layer SPIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the (non-ASF) <a href="http://platform.incode.org"; target="_blank">Incode Platform</a> modules.</p> + <p>The table below summarizes the presentation layer APIs defined by Apache Isis. It also lists their corresponding implementation.</p> </div> <table class="tableblock frame-all grid-all spread"> <caption class="title"> - Table 1. Presentation Layer SPI + Table 1. Presentation Layer API </caption> <colgroup> <col style="width: 25%;"> @@ -595,7 +603,7 @@ table.CodeRay td.code>pre{padding:0} </colgroup> <thead> <tr> - <th class="tableblock halign-left valign-top">SPI</th> + <th class="tableblock halign-left valign-top">API</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> @@ -603,169 +611,48 @@ table.CodeRay td.code>pre{padding:0} </thead> <tbody> <tr> - <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_persistence-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-spi_GridLoaderService"><code>GridLoaderService</code></a> and <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_application-layer-spi_HomePageProviderService"><code>HomePageProviderService</code></a>) if a void or null is returned.<br> Used by the <a href="../ugvw/ugvw.html">Wicket viewer</a> only.</p></td> - </tr> - <tr> - <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-api_AcceptHeaderService"><code>o.a.i.applib.</code><br> <code>services.acceptheader</code><br> <code>AcceptHeaderService</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/rgsvc.html#_rgsvc_presentation-layer-spi_LocaleProvider"><code>LocalProvider</code></a>.</p> + <p>Request-scoped access to HTTP Accept headers.</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> + <td class="tableblock halign-left valign-top"><p class="tableblock"><code>AcceptHeaderServiceDefault</code><br> <code>o.a.i.core</code><br> <code>isis-core-viewer-restfulobjects-rendering</code></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation only usable within the <a href="../ugvro/ugvro.html">Restful Objects viewer</a>.</p></td> </tr> <tr> - <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-api_BookmarkUiService"><code>o.a.i.applib.</code><br> <code>services.bookmarkui</code><br> <code>BookmarkUiService</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/rgsvc.html#_rgsvc_presentation-layer-spi_TranslationService"><code>TranslationService</code></a></p> + <p>Manage bookmarks and breadcrumbs in the (Wicket) UI.</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> + <td class="tableblock halign-left valign-top"><p class="tableblock"><code>BookmarkUiServiceWicket</code><br> <code>o.a.i.core</code><br> <code>isis-core-viewer-wicket-impl</code></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">(Implementation only usable within the <a href="../ugvw/ugvw.html">Wicket viewer</a>.</p></td> </tr> <tr> - <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-api_DeepLinkService"><code>o.a.i.applib</code><br> <code>services.deeplink</code><br> <code>DeepLinkService</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> + <p>Obtain a URL to a domain object (eg for use within an email or report)</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> + <td class="tableblock halign-left valign-top"><p class="tableblock"><code>DeepLinkServiceWicket</code><br> <code>o.a.i.viewer</code><br> <code>isis-core-viewer-wicket-impl</code></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation only usable within the <a href="../ugvw/ugvw.html">Wicket viewer</a>.</p></td> </tr> <tr> - <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-api_GuiceBeanProvider"><code>o.a.i.applib.</code><br> <code>services.guice</code><br> <code>GuiceBeanProvider</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> + <p>Access to internal framework services initialized using Guice DI.</p> </div> </div></td> - <td class="tableblock halign-left valign-top"></td> - <td class="tableblock halign-left valign-top"></td> + <td class="tableblock halign-left valign-top"><p class="tableblock"><code>GuiceBeanProviderWicket</code><br> <code>o.a.i.core</code><br> <code>isis-core-viewer-wicket-impl</code></p></td> + <td class="tableblock halign-left valign-top"><p class="tableblock">Implementation only usable within the <a href="../ugvw/ugvw.html">Wicket viewer</a>.</p></td> </tr> </tbody> </table> @@ -781,22 +668,19 @@ table.CodeRay td.code>pre{padding:0} </ul> </div> <div class="sect2"> - <h3 id="_rgsvc_presentation-layer-spi_ContentMappingService">3.1. <code>ContentMappingService</code></h3> + <h3 id="_rgsvc_presentation-layer-api_AcceptHeaderService">3.1. <code>AcceptHeaderService</code></h3> <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> - <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api_AcceptHeaderService.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> <ul class="dropdown-menu"> - <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> - <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> - <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> - <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api_AcceptHeaderService.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api_AcceptHeaderService.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api_AcceptHeaderService.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-api_AcceptHeaderService.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> </ul> </div> <div class="paragraph"> - <p>The <code>ContentMappingService</code> supports the (default implementation of the) <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a> enabling the <a href="../ugvro/ugvro.html">RestfulObjects viewer</a> to represent domain objects in some other format as specified by the HTTP <code>Accept</code> header.</p> - </div> - <div class="paragraph"> - <p>See <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a> for further discussion.</p> + <p>The <code>AcceptHeaderService</code> domain service is a <a href="../rgant/rgant.html#_rgant-RequestScoped"><code>@RequestScoped</code></a> service that simply exposes the HTTP <code>Accept</code> header to the domain. Its intended use is to support multiple versions of a REST API, where the responsibility for content negotiation (determining which version of the REST API is to be used) is managed by logic in the domain objects themselves.</p> </div> <div class="admonitionblock note"> <table> @@ -805,22 +689,24 @@ table.CodeRay td.code>pre{padding:0} <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/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> + <p>As an alternative to performing content negotiation within the domain classes, the <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a> and <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_ContentMappingService"><code>ContentMappingService</code></a> SPI domain services allow the framework to perform the content negotiation responsibility.</p> </div> </td> </tr> </tbody> </table> </div> <div class="sect3"> - <h4 id="_spi">3.1.1. SPI</h4> + <h4 id="_api_implementation">3.1.1. API & Implementation</h4> <div class="paragraph"> - <p>The SPI defined by this service is:</p> + <p>The API defined by the service is:</p> </div> <div class="listingblock"> <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">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> + <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainService</span>(nature = NatureOfService.DOMAIN) +<span class="annotation">@RequestScoped</span> <i class="conum" data-value="1"></i><b>(1)</b> +<span class="directive">public</span> <span class="type">interface</span> <span class="class">AcceptHeaderService</span> { + <span class="annotation">@Programmatic</span> + <span class="predefined-type">List</span><MediaType> getAcceptableMediaTypes(); <i class="conum" data-value="2"></i><b>(2)</b> }</code></pre> </div> </div> @@ -829,87 +715,558 @@ table.CodeRay td.code>pre{padding:0} <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> + <td>is <a href="../rgant/rgant.html#_rgant-RequestScoped"><code>@RequestScoped</code></a>, so this domain service instance is scoped to a particular request and is then destroyed</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> + <td>returns the list of media types found in the HTTP Accept 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/ugvro.html">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> + <p>The default implementation is provided by <code>o.a.i.v.ro.rendering.service.acceptheader.AcceptHeaderServiceForRest</code>.</p> </div> - <div class="colist arabic"> + <div class="admonitionblock note"> <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> + <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> + <td class="content"> + <div class="paragraph"> + <p>Note that the service will only return a list when the request is initiated through the <a href="../ugvro/ugvro.html">Restful Objects viewer</a>. Otherwise the service will return <code>null</code>.</p> + </div> </td> </tr> </tbody> </table> </div> </div> <div class="sect3"> - <h4 id="_implementations">3.1.2. Implementations</h4> + <h4 id="_usage">3.1.2. Usage</h4> <div class="paragraph"> - <p>No default implementations are provided by Apache Isis framework itself.</p> + <p>The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients. The <code>AcceptHeaderService</code> allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.</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> + <p>The diagram below illustrated this:</p> </div> - <div class="listingblock"> + <div class="imageblock"> <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">ContentMappingServiceForToDoItem</span> <span class="directive">implements</span> ContentMappingService { - <span class="annotation">@Override</span> - <span class="directive">public</span> <span class="predefined-type">Object</span> map( - <span class="directive">final</span> <span class="predefined-type">Object</span> object, - <span class="directive">final</span> <span class="predefined-type">List</span><MediaType> acceptableMediaTypes) { - <span class="keyword">if</span>(object <span class="keyword">instanceof</span> ToDoItem) { - <span class="keyword">for</span> (MediaType acceptableMediaType : acceptableMediaTypes) { - <span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> parameters = acceptableMediaType.getParameters(); - <span class="directive">final</span> <span class="predefined-type">String</span> className = parameters.get(<span class="string"><span class="delimiter">"</span><span class="content">x-ro-domain-type</span><span class="delimiter">"</span></span>); - <span class="keyword">if</span>(className.eqausl(ToDoItemV1_1.class.getName())) { - <span class="keyword">return</span> newToDoItemV1_1((ToDoItem) object); - } - } - } - <span class="keyword">return</span> <span class="predefined-constant">null</span>; - } - <span class="directive">private</span> ToDoItemV1_1 newToDoItemV1_1(<span class="directive">final</span> ToDoItem toDoItem) { - <span class="directive">final</span> ToDoItemV1_1 dto = <span class="keyword">new</span> ToDoItemV1_1(); - dto.setToDoItem(toDoItem); - dto.setDescription(toDoItem.getDescription()); - ... - return dto; - } - ... -}</code></pre> + <a class="image" href="images/reference-services-api/acceptheaderservice.png"><img src="images/reference-services-api/acceptheaderservice.png" alt="acceptheaderservice" width="700px"></a> </div> </div> - </div> - <div class="sect3"> - <h4 id="_related_services">3.1.3. Related Services</h4> <div class="paragraph"> - <p>This service is a companion to the default implementation of the <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a>.</p> + <p>The REST request is submitted to a domain service with a <a href="../rgant/rgant.html#_rgant-DomainService_nature">nature</a> of <code>VIEW_REST_ONLY</code> (<code>MyRestApi</code> in the diagram). This uses the <code>AcceptHeaderService</code> to obtain the values of the HTTP <code>Accept</code> header. Based on this it delegates to the appropriate underlying domain service (with a nature of <code>DOMAIN</code> so that they are not exposed in the REST API at all).</p> + </div> + <div class="admonitionblock tip"> + <table> + <tbody> + <tr> + <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> + <td class="content"> + <div class="paragraph"> + <p>The service does not define any conventions as to the format of the media types. The option is to use the media typeâs type/subtype, eg <code>application/vnd.myrestapi-v1+json</code>; an alternative is to use a media type parameter as a hint, eg <code>application/json;x-my-rest-api-version=1</code> (where <code>x-my-rest-api-version</code> is the media type parameter).</p> + </div> + <div class="paragraph"> + <p>The Restful Objects specification does this something similar with its own <code>x-ro-domain-type</code> media type parameter; this is used by the <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_ContentMappingService"><code>ContentMappingService</code></a> to determine how to map domain objects to view models/DTOs.</p> + </div> </td> + </tr> + </tbody> + </table> </div> </div> </div> <div class="sect2"> - <h3 id="_rgsvc_presentation-layer-spi_EmailNotificationService">3.2. <code>EmailNotificationService</code></h3> + <h3 id="_rgsvc_presentation-api_BookmarkUiService">3.2. <code>BookmarkUiService</code></h3> + <div class="paragraph"> + <p>The <code>BookmarkUiService</code> provides the ability to programmatically interact with bookmarked pages and breadcrumbs, as rendered by the Wicket viewer.</p> + </div> + <div class="paragraph"> + <p>One possible use case is programmatically to support multiple "contexts" and allow the end-user to switch from one context to another.</p> + </div> + <div class="sect3"> + <h4 id="_api_implementation_2">3.2.1. API & Implementation</h4> + <div class="paragraph"> + <p>The API defined by <code>BookmarkUiService</code> is:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">BookmarkUiService</span> { + <span class="type">void</span> clear(); <i class="conum" data-value="1"></i><b>(1)</b> +}</code></pre> + </div> + </div> + <div class="colist arabic"> + <table> + <tbody> + <tr> + <td><i class="conum" data-value="1"></i><b>1</b></td> + <td>Simply clears the current list of breadcrumbs and bookmarks.</td> + </tr> + </tbody> + </table> + </div> + <div class="paragraph"> + <p>The <a href="../ugvw/ugvw.html">Wicket viewer</a> provides an implementation of this service, <code>o.a.i.viewer.wicket.viewer.services.BookmarkUiServiceWicket</code>.</p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_rgsvc_presentation-api_DeepLinkService">3.3. <code>DeepLinkService</code></h3> + <div class="paragraph"> + <p>The <code>DeepLinkService</code> provides the ability to obtain a <code>java.net.URI</code> that links to a representation of any (persisted) domain entity or view model.</p> + </div> + <div class="paragraph"> + <p>A typical use case is to generate a clickable link for rendering in an email, PDF, tweet or other communication.</p> + </div> + <div class="sect3"> + <h4 id="_api_implementation_3">3.3.1. API & Implementation</h4> + <div class="paragraph"> + <p>The API defined by <code>DeepLinkService</code> is:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">DeepLinkService</span> { + <span class="predefined-type">URI</span> deepLinkFor(<span class="predefined-type">Object</span> domainObject); <i class="conum" data-value="1"></i><b>(1)</b> +}</code></pre> + </div> + </div> + <div class="colist arabic"> + <table> + <tbody> + <tr> + <td><i class="conum" data-value="1"></i><b>1</b></td> + <td>Creates a URI that can be used to obtain a representation of the provided domain object in one of the Apache Isis viewers.</td> + </tr> + </tbody> + </table> + </div> + <div class="paragraph"> + <p>The <a href="../ugvw/ugvw.html">Wicket viewer</a> provides an implementation of this service <code>o.a.i.viewer.wicket.viewer.services.DeepLinkServiceWicket</code>.</p> + </div> + <div class="paragraph"> + <p>For the <a href="../ugvro/ugvro.html">RestfulObjects viewer</a>, a URL can be constructed according to the <a href="http://www.restfulobjects.org";>Restful Objects spec</a> in conjunction with a <code>Bookmark</code> obtained via the <a href="../rgsvc/rgsvc.html#_rgsvc_integration-api_BookmarkService"><code>BookmarkService</code></a>.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_usage_within_the_framework">3.3.2. Usage within the framework</h4> + <div class="paragraph"> + <p>The <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-spi_EmailNotificationService"><code>EmailNotificationService</code></a> uses this service in order to generate emails as part of <a href="../ugvw/ugvw.html#_ugvw_features_user-registration">user registration</a>.</p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_rgsvc_presentation-api_GuiceBeanProvider">3.4. <code>GuiceBeanProvider</code></h3> + <div class="paragraph"> + <p>The <code>GuiceBeanProvider</code> domain service acts as a bridge between Apache Isis' <a href="../ugvw/ugvw.html">Wicket viewer</a> internal bootstrapping using <a href="https://github.com/google/guice";>Google Guice</a>.</p> + </div> + <div class="paragraph"> + <p>This service operates at a very low-level, and you are unlikely to have a need for it. It is used internally by the framework, in the default implementation of the <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-api_DeepLinkService"><code>DeepLinkService</code></a>.</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>Currently Apache Isis uses a combination of Guice (within the Wicket viewer only) and a home-grown dependency injection framework. In future versions we intended to refactor the framework to use CDI throughout. At that time this service is likely to become redundant because we will allow any of the internal components of Apache Isis to be injected into your domain object code.</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + <div class="sect3"> + <h4 id="_api_implementation_4">3.4.1. API & Implementation</h4> + <div class="paragraph"> + <p>The API 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">GuiceBeanProvider</span> { + <span class="annotation">@Programmatic</span> + <T> T lookup(<span class="predefined-type">Class</span><T> beanType); + <span class="annotation">@Programmatic</span> + <T> T lookup(<span class="predefined-type">Class</span><T> beanType, <span class="directive">final</span> <span class="predefined-type">Annotation</span> qualifier); +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>The <a href="../ugvw/ugvw.html">Wicket viewer</a> this provides an implementation of this service.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_usage_2">3.4.2. Usage</h4> + <div class="paragraph"> + <p>Using the <a href="../ugvw/ugvw.html">Wicket viewer</a> requires subclassing of <code>IsisWicketApplication</code>. In the subclass it is commonplace to override <code>newIsisWicketModule()</code>, for example:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Override</span> +<span class="directive">protected</span> Module newIsisWicketModule() { + <span class="directive">final</span> Module isisDefaults = <span class="local-variable">super</span>.newIsisWicketModule(); + <span class="directive">final</span> Module overrides = <span class="keyword">new</span> AbstractModule() { + <span class="annotation">@Override</span> + <span class="directive">protected</span> <span class="type">void</span> configure() { + bind(<span class="predefined-type">String</span>.class).annotatedWith(Names.named(<span class="string"><span class="delimiter">"</span><span class="content">applicationName</span><span class="delimiter">"</span></span>)) + .toInstance(<span class="string"><span class="delimiter">"</span><span class="content">ToDo App</span><span class="delimiter">"</span></span>); + bind(<span class="predefined-type">String</span>.class).annotatedWith(Names.named(<span class="string"><span class="delimiter">"</span><span class="content">applicationCss</span><span class="delimiter">"</span></span>)) + .toInstance(<span class="string"><span class="delimiter">"</span><span class="content">css/application.css</span><span class="delimiter">"</span></span>); + bind(<span class="predefined-type">String</span>.class).annotatedWith(Names.named(<span class="string"><span class="delimiter">"</span><span class="content">applicationJs</span><span class="delimiter">"</span></span>)) + .toInstance(<span class="string"><span class="delimiter">"</span><span class="content">scripts/application.js</span><span class="delimiter">"</span></span>); + ... + } + }; + <span class="keyword">return</span> Modules.override(isisDefaults).with(overrides); +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>This "module" is in fact a Guice module, and so the <code>GuiceBeanProvider</code> service can be used to lookup any of the components bound into it.</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">SomeDomainObject</span> { + <span class="directive">private</span> <span class="predefined-type">String</span> lookupApplicationName() { + <span class="keyword">return</span> guiceBeanProvider.lookup(<span class="predefined-type">String</span>.class, Names.named(<span class="string"><span class="delimiter">"</span><span class="content">applicationName</span><span class="delimiter">"</span></span>)); + } + <span class="annotation">@Inject</span> + GuiceBeanProvider guiceBeanProvider; +}</code></pre> + </div> + </div> + <div class="paragraph"> + <p>should return "ToDo App".</p> + </div> + </div> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_rgsvc_presentation-layer-spi">4. Presentation Layer SPI</h2> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <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 (non-ASF) <a href="http://platform.incode.org"; target="_blank">Incode Platform</a> modules.</p> + </div> + <table class="tableblock frame-all grid-all spread"> + <caption class="title"> + Table 2. 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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_persistence-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-spi_GridLoaderService"><code>GridLoaderService</code></a> and <a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_application-layer-spi_HomePageProviderService"><code>HomePageProviderService</code></a>) if a void or null is returned.<br> Used by the <a href="../ugvw/ugvw.html">Wicket viewer</a> only.</p></td> + </tr> + <tr> + <td class="tableblock halign-left valign-top"><p class="tableblock"><a href="../rgsvc/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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/rgsvc.html#_rgsvc_presentation-layer-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_presentation-layer-spi_ContentMappingService">4.1. <code>ContentMappingService</code></h3> + <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> + <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> + <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> + <ul class="dropdown-menu"> + <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li> + <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li> + <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li> + <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ContentMappingService.adoc"; target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li> + </ul> + </div> + <div class="paragraph"> + <p>The <code>ContentMappingService</code> supports the (default implementation of the) <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a> enabling the <a href="../ugvro/ugvro.html">RestfulObjects viewer</a> to represent domain objects in some other format as specified by the HTTP <code>Accept</code> header.</p> + </div> + <div class="paragraph"> + <p>See <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_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/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">4.1.1. SPI</h4> + <div class="paragraph"> + <p>The SPI defined by this service is:</p> + </div> + <div class="listingblock"> + <div class="content"> + <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">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> + <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âs HTTP <code>Accept</code> header</td> + </tr> + </tbody> + </table> + </div> + </div> + <div class="sect3"> + <h4 id="_implementations">4.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) +<span class="directive">public</span> <span class="type">class</span> <span class="class">ContentMappingServiceForToDoItem</span> <span class="directive">implements</span> ContentMappingService { + <span class="annotation">@Override</span> + <span class="directive">public</span> <span class="predefined-type">Object</span> map( + <span class="directive">final</span> <span class="predefined-type">Object</span> object, + <span class="directive">final</span> <span class="predefined-type">List</span><MediaType> acceptableMediaTypes) { + <span class="keyword">if</span>(object <span class="keyword">instanceof</span> ToDoItem) { + <span class="keyword">for</span> (MediaType acceptableMediaType : acceptableMediaTypes) { + <span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> parameters = acceptableMediaType.getParameters(); + <span class="directive">final</span> <span class="predefined-type">String</span> className = parameters.get(<span class="string"><span class="delimiter">"</span><span class="content">x-ro-domain-type</span><span class="delimiter">"</span></span>); + <span class="keyword">if</span>(className.eqausl(ToDoItemV1_1.class.getName())) { + <span class="keyword">return</span> newToDoItemV1_1((ToDoItem) object); + } + } + } + <span class="keyword">return</span> <span class="predefined-constant">null</span>; + } + <span class="directive">private</span> ToDoItemV1_1 newToDoItemV1_1(<span class="directive">final</span> ToDoItem toDoItem) { + <span class="directive">final</span> ToDoItemV1_1 dto = <span class="keyword">new</span> ToDoItemV1_1(); + dto.setToDoItem(toDoItem); + dto.setDescription(toDoItem.getDescription()); + ... + return dto; + } + ... +}</code></pre> + </div> + </div> + </div> + <div class="sect3"> + <h4 id="_related_services">4.1.3. Related Services</h4> + <div class="paragraph"> + <p>This service is a companion to the default implementation of the <a href="../rgfis/rgfis.html#_rgfis_presentation-layer_ContentNegotiationService"><code>ContentNegotiationService</code></a>.</p> + </div> + </div> + </div> + <div class="sect2"> + <h3 id="_rgsvc_presentation-layer-spi_EmailNotificationService">4.2. <code>EmailNotificationService</code></h3> <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_EmailNotificationService.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> @@ -933,7 +1290,7 @@ table.CodeRay td.code>pre{padding:0} <p>The default implementation of this service uses the <a href="../rgsvc/rgsvc.html#_rgsvc_integration-api_EmailService"><code>EmailService</code></a>, which must be configured in order for user registration to be enabled.</p> </div> <div class="sect3"> - <h4 id="_spi_2">3.2.1. SPI</h4> + <h4 id="_spi_2">4.2.1. SPI</h4> <div class="paragraph"> <p>The SPI defined by this service is:</p> </div> @@ -972,7 +1329,7 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect3"> - <h4 id="_implementation">3.2.2. Implementation</h4> + <h4 id="_implementation">4.2.2. Implementation</h4> <div class="paragraph"> <p>The framework provides a default implementation, <code>o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault</code> that constructs the emails to send.</p> </div> @@ -1002,16 +1359,7 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect3"> - <h4 id="_registering_the_service">3.2.3. Registering the Service</h4> - <div class="paragraph"> - <p>Assuming that the <code>configuration-and-annotation</code> services installer is configured (implicit if using the <code>AppManifest</code> to <a href="../rgcms/rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>) then Apache Isis' default implementation of <code>EmailNotificationService</code> service is automatically registered and injected (it is annotated with <code>@DomainService</code>) so no further configuration is required.</p> - </div> - <div class="paragraph"> - <p>To use an alternative implementation, use <a href="../rgant/rgant.html#_rgant-DomainServiceLayout_menuOrder"><code>@DomainServiceLayout#menuOrder()</code></a> (as explained in the <a href="../rgsvc/rgsvc.html#__rgsvc_intro_overriding-the-services">introduction</a> to this guide).</p> - </div> - </div> - <div class="sect3"> - <h4 id="_related_services_2">3.2.4. Related Services</h4> + <h4 id="_related_services_2">4.2.3. Related Services</h4> <div class="paragraph"> <p>As noted elsewhere, the default implementation of this service uses <a href="../rgsvc/rgsvc.html#_rgsvc_integration-api_EmailService"><code>EmailService</code></a>. This service has no specific configuration properties but does require that the <code>EmailService</code> has been configured.</p> </div> @@ -1021,7 +1369,7 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect2"> - <h3 id="_rgsvc_presentation-layer-spi_ErrorReportingService">3.3. <code>ErrorReportingService</code></h3> + <h3 id="_rgsvc_presentation-layer-spi_ErrorReportingService">4.3. <code>ErrorReportingService</code></h3> <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ErrorReportingService.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> @@ -1036,7 +1384,7 @@ table.CodeRay td.code>pre{padding:0} <p>The <code>ErrorReportingService</code> service is an optional SPI that provides the ability to record any errors/exceptions that might occur in the application into an external incident recording system (such as JIRA). The service also allows a user-friendly (jargon-free) error message to be returned and rendered to the end-user, along with an optional incident reference (eg a JIRA issue <code>XXX-1234</code>).</p> </div> <div class="sect3"> - <h4 id="_spi_3">3.3.1. SPI</h4> + <h4 id="_spi_3">4.3.1. SPI</h4> <div class="paragraph"> <p>The SPI defined by this service is:</p> </div> @@ -1115,7 +1463,10 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect3"> - <h4 id="_implementation_2">3.3.2. Implementation</h4> + <h4 id="_implementation_2">4.3.2. Implementation</h4> + <div class="paragraph"> + <p>There is no default implementation of this service.</p> + </div> <div class="paragraph"> <p>The (non-ASF) <a href="http://github.com/isisaddons/isis-app-kitchensink";>Isis addons' kitchensink</a> app provides an example implementation:</p> </div> @@ -1151,15 +1502,9 @@ table.CodeRay td.code>pre{padding:0} </div> </div> </div> - <div class="sect3"> - <h4 id="_registering_the_services">3.3.3. Registering the Services</h4> - <div class="paragraph"> - <p>There is no default implementation of this service. To register your own implementation (and assuming that an <code>AppManifest</code> is being used to <a href="../rgcms/rgcms.html#_rgcms_classes_AppManifest-bootstrapping">bootstrap the app</a>), then just ensure that the implementation is on the classpath and the module containing the implementation is returned in <code>AppManifest#getModules()</code>.</p> - </div> - </div> </div> <div class="sect2"> - <h3 id="_rgsvc_presentation-layer-spi_ExceptionRecognizer">3.4. <code>ExceptionRecognizer</code></h3> + <h3 id="_rgsvc_presentation-layer-spi_ExceptionRecognizer">4.4. <code>ExceptionRecognizer</code></h3> <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "> <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_presentation-layer-spi_ExceptionRecognizer.adoc"";><i class="fa fa-pencil-square-o"></i> Edit</button> <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button> @@ -1180,7 +1525,7 @@ table.CodeRay td.code>pre{padding:0} <p>It is also possible to provide additional implementations, registered in <code>isis.properties</code>. Unlike other services, where any service registered in <code>isis.properties</code> replaces any default implementations, in the case of this service all implementations registered are "consulted" to see if they recognize an exception (the chain-of-responsibility pattern).</p> </div> <div class="sect3"> - <h4 id="_spi_4">3.4.1. SPI</h4> + <h4 id="_spi_4">4.4.1. SPI</h4> <div class="paragraph"> <p>The SPI defined by this service is:</p> </div> @@ -1283,7 +1628,7 @@ table.CodeRay td.code>pre{padding:0} </div> </div> <div class="sect3"> - <h4 id="_implementation_3">3.4.2. Implementation</h4> + <h4 id="_implementation
<TRUNCATED>
