You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/08 00:00:11 UTC
[13/44] isis-site git commit: ISIS-1594: provide an 'edit' button
http://git-wip-us.apache.org/repos/asf/isis-site/blob/83a3755a/content/guides/ugvro.html
----------------------------------------------------------------------
diff --git a/content/guides/ugvro.html b/content/guides/ugvro.html
index a807b2f..990664d 100644
--- a/content/guides/ugvro.html
+++ b/content/guides/ugvro.html
@@ -1,12 +1,10 @@
<!doctype html>
<html class="no-js" lang="en">
-<head>
- <meta charset="utf-8"/>
- <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
-
- <title>Restful Objects Viewer</title>
-
- <!--
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Restful Objects Viewer</title>
+ <!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
@@ -23,31 +21,21 @@
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
- -->
-
- <!-- No caching headers -->
- <meta http-equiv="cache-control" content="no-cache" />
- <meta http-equiv="pragma" content="no-cache" />
- <meta http-equiv="expires" content="-1" />
-
-
- <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
- <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet" />
- <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
- <link href="../css/asciidoctor/colony.css" rel="stylesheet">
- <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
-
-
-
-
- <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet" />
- <!--[if lt IE 9]>
+ -->
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache">
+ <meta http-equiv="pragma" content="no-cache">
+ <meta http-equiv="expires" content="-1">
+ <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
+ <link href="../css/foundation/5.5.1/foundation.css" rel="stylesheet">
+ <script src="../js/foundation/5.5.1/vendor/modernizr.js"></script>
+ <link href="../css/asciidoctor/colony.css" rel="stylesheet">
+ <link href="../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.css" rel="stylesheet">
+ <!--[if lt IE 9]>
<link href="../css/github-fork-ribbon-css/0.1.1/gh-fork-ribbon.ie.css" rel="stylesheet" />
- <![endif]-->
-
-
-
- <style type="text/css">
+ <![endif]-->
+ <style type="text/css">
pre code {
background-color: inherit;
border-style: none;
@@ -192,9 +180,8 @@ table.CodeRay td.code>pre{padding:0}
color:#fff;
font-size: 1.1em;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 40.063em) {
.top-bar {
.contain-to-grid .top-bar {
@@ -205,9 +192,8 @@ table.CodeRay td.code>pre{padding:0}
.row {
max-width: 80rem;
}
- </style>
-
- <style>
+ </style>
+ <style>
.extended-quote,
.extended-quote-first {
margin-left: 40px;
@@ -231,9 +217,8 @@ table.CodeRay td.code>pre{padding:0}
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
}
- </style>
-
- <style>
+ </style>
+ <style>
body {
position: relative;
}
@@ -255,6 +240,7 @@ table.CodeRay td.code>pre{padding:0}
div#doc-content {
margin-top: 30px;
+ padding-top: 30px;
}
div.documentation-page table.frame-all {
@@ -286,9 +272,8 @@ table.CodeRay td.code>pre{padding:0}
min-height: 2000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
@media only screen and (min-width: 768px) {
#toc.toc2 ul ul { margin-left: -10px; }
@@ -316,15 +301,13 @@ table.CodeRay td.code>pre{padding:0}
body div#toc2 li.tocify-item.active a {
color: red;
}
- </style>
-
- <style>
+ </style>
+ <style>
footer {
margin-top: 1000px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* overriding colony.css stylesheet */
.literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
/*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
@@ -372,9 +355,8 @@ table.CodeRay td.code>pre{padding:0}
.imageblock img {
margin-bottom: 10px;
}
- </style>
-
- <style>
+ </style>
+ <style>
/* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
.header-link {
position: absolute;
@@ -395,9 +377,8 @@ table.CodeRay td.code>pre{padding:0}
h6:hover .header-link {
opacity: 1;
}
- </style>
-
- <style>
+ </style>
+ <style>
.top-bar
{
-webkit-transition-duration: .5s;
@@ -425,607 +406,505 @@ table.CodeRay td.code>pre{padding:0}
-webkit-transition-property: -webkit-transform;
transition-property: transform;
}
- </style>
-
- <style>
+ </style>
+ <style>
#doc-content a.guide {
color: white;
}
- </style>
-
- <style>
+ </style>
+ <style>
+ .tocify {
+ margin-top: 80px;
+ }
+ </style>
+ <style>
.tocify {
margin-top: 80px;
}
- </style>
-
-
-</script>
-
-</head>
-<body>
-
-<<div class="github-fork-ribbon-wrapper right" style="position: fixed;">
- <div class="github-fork-ribbon">
- <a href="https://github.com/apache/isis#fork-destination-box">Fork me on GitHub</a>
- </div>
-</div>
-
-
-<div class="row">
-
- <div class="fixed contain-to-grid header">
- <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
- <ul class="title-area">
- <li class="name">
- <h1>
- <a href="/index.html">Apache Isis™</a>
- </h1>
- </li>
- <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
- <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
- </ul>
-
- <section class="top-bar-section">
- <ul class="right">
-
- <li class="has-form">
- <FORM class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
- <div class="row collapse">
- <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
- <INPUT type="hidden" name="cof" value="FORID:0">
- <INPUT class="form-control" name="q" type="text" placeholder="Search">
- </div>
- </FORM>
- </li>
-
- </ul>
-
- <!-- Left Nav Section -->
- <ul class="left">
-
- <li><a href="/documentation.html">Documentation</a></li>
- <li><a href="/downloads.html">Downloads</a></li>
- <li><a href="/help.html">Help</a></li>
- <li><a href="/asf.html">@ASF</a></li>
-
- </ul>
-
- </section>
- </nav>
- </div>
-</div>
-
-<div class="row">
-
- <div id="doc-content-left" class="large-9 medium-9 columns">
-
-
- <div id="doc-content">
- <div class="sect1">
-<h2 id="_ugvw">1. Restful Objects Viewer</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>Apache Isis' Restful Objects viewer is an implementation of the <a href="http://restfulobjects.org">Restful Objects spec</a>,
-which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API. Having a REST
-API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps,
-through integration scenarious, through providing an API for bulk-upload/migration from an existing system.</p>
-</div>
-<div class="paragraph">
-<p>The Restful Objects viewer also provides a number of extensions specific to Apache Isis. Most significant of these is
-enhanced content negotiation support, making it easier to use the returned representations within bespoke clients using
-standard third-party configurations.</p>
-</div>
-<div class="paragraph">
-<p>This user guide discuss features, configuration and also how to extend the Restful Objects viewer.</p>
-</div>
-<div class="sect2">
-<h3 id="_other_guides">1.1. Other Guides</h3>
-<div class="paragraph">
-<p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
-</div>
-<div class="paragraph">
-<p>The user guides available are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="ugfun.html">Fundamentals</a></p>
-</li>
-<li>
-<p><a href="ugvw.html">Wicket viewer</a></p>
-</li>
-<li>
-<p><a href="#">Restful Objects viewer</a> (this guide)</p>
-</li>
-<li>
-<p><a href="ugdno.html">DataNucleus object store</a></p>
-</li>
-<li>
-<p><a href="ugsec.html">Security</a></p>
-</li>
-<li>
-<p><a href="ugtst.html">Testing</a></p>
-</li>
-<li>
-<p><a href="ugbtb.html">Beyond the Basics</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The reference guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="rgant.html">Annotations</a></p>
-</li>
-<li>
-<p><a href="rgsvc.html">Domain Services</a></p>
-</li>
-<li>
-<p><a href="rgcfg.html">Configuration Properties</a></p>
-</li>
-<li>
-<p><a href="rgcms.html">Classes, Methods and Schema</a></p>
-</li>
-<li>
-<p><a href="rgmvn.html">Apache Isis Maven plugin</a></p>
-</li>
-<li>
-<p><a href="rgfis.html">Framework Internal Services</a></p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The remaining guides are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="dg.html">Developers' Guide</a> (how to set up a development environment
-for Apache Isis and contribute back to the project)</p>
-</li>
-<li>
-<p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p>
-</li>
-</ul>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugvro_ro-spec">2. RO Specification</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and
-corresponding JSON representations, for accessing and manipulating a domain object model.</p>
-</div>
-<div class="paragraph">
-<p>The Restful Objects spec can be downloaded from <a href="http://restfulobjects.org">here</a> as either a PDF or Word doc.</p>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_ro-spec_goals">2.1. Goals of the Spec</h3>
-<div class="paragraph">
-<p>The goal of Restful Objects is to allow domain models to be accessed through HTTP resources, returning a set of JSON
-representations. These representations can then be consumed by any client (e.g. Javascript, Java, .NET, Ruby, Python).</p>
-</div>
-<div class="paragraph">
-<p>Both the resources and representations are generalized so that they can be applied to any domain model, and by default
-all representations have media types designed to allow a completely generic client to be written, capable of working,
-unmodified, with any domain model that has a Restful Objects interface.</p>
-</div>
-<div class="paragraph">
-<p>Alternatively, the developer may write a custom client that has some shared knowledge of the domain being exposed, and
-render the information in a more specific fashion.</p>
-</div>
-<div class="paragraph">
-<p>Restful Objects also defines that representations are served up with parameterized media types. This allows clients to
-use content negotiation to ensure that representations do not change in a breaking fashion, enabling server and client
-to evolve independently.</p>
-</div>
-<div class="paragraph">
-<p>The Restful Objects specification is at a higher-level of abstraction than, say, the JAX-RS specifications for Java
-platform, or the WCF specifications on .NET. Specifically, the domain classes that it exposes are represented in a very
-general form. They consist of:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>properties (fields), each holding either a scalar value or reference to another object;</p>
-</li>
-<li>
-<p>collections, each holding a vector reference to other entities;</p>
-</li>
-<li>
-<p>actions (operations/methods), whereby the object can execute business logic.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>Beyond this, though, Restful Objects makes very few assumptions. In particular, Restful Objects does not prescribe the
-nature of the domain model.</p>
-</div>
-<div class="paragraph">
-<p>The Restful Objects spec may be downloaded directly from github as either a PDF or as a Word doc.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_resources_and_representations">2.2. Resources and Representations</h3>
-<div class="paragraph">
-<p>The diagram below - taken from the Restful Objects spec - shows the various resources (URLs) and representations (JSON)
-that are defined:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/restfulobjects/ro-spec-resources-and-representations.png"><img src="images/restfulobjects/ro-spec-resources-and-representations.png" alt="ro spec resources and representations" width="800px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>The resource URLs are always well-defined, but Apache Isis' implementation allows for different representations to
-be returned, using content negotiation. This is discussed further below.</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>In fact, there’s nothing in Apache Isis to prevent you from defining your own REST controllers to provide custom
-resource URLs. One use case might be to support user registration/authentication, a topic out-of-scope of the RO spec
-itself.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_ro-spec_apache-isis-implementation">2.3. Apache Isis' implementation</h3>
-<div class="paragraph">
-<p>The Restful Objects viewer is Apache Isis' implementation of the Restful Objects spec. It implements all the mandatory
-features of the specification. It also implements some of the optional capabilities (as defined in section 3 of the
-RO spec, and as represented in the version resource, section 8.1):</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<colgroup>
-<col style="width: 33.3333%;">
-<col style="width: 33.3333%;">
-<col style="width: 33.3334%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Capability</th>
-<th class="tableblock halign-left valign-top">Support</th>
-<th class="tableblock halign-left valign-top">Notes</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>blobsClobs</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>yes</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>deleteObjects</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>yes</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>domainModel</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>formal</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>The 'simple' scheme is <em>not</em> supported</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>validateOnly</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>yes</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>protoPersistentObjects</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>yes</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div></div></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_ro-spec_extensions">2.4. Extensions</h3>
-<div class="paragraph">
-<p>The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but
-described in section 34, "ideas for future extensions".</p>
-</div>
-<div class="sect3">
-<h4 id="_ugvro_ro-spec_extensions_content-negotiation">2.4.1. Content Negotiation (34.1)</h4>
-<div class="paragraph">
-<p>Apache Isis provides two levels of support for content negotiation.</p>
-</div>
-<div class="sect4">
-<h5 id="_ugvro_ro-spec_extensions_content-negotiation_x-ro-domain-type"><code>x-ro-domain-type</code></h5>
-<div class="paragraph">
-<p>The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec. The client
-can send an <code>x-ro-domain-type</code> parameter for either domain object representations (section 14 of the spec) or
-action invocation results (section 19 of the spec). This can be combined with either <code>application/json</code> or
-<code>application/xml</code>.</p>
-</div>
-<div class="paragraph">
-<p>For example, the client could use an <code>Accept</code> header such as:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>The server will use the <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> to attempt to
-transform the domain object into the requested <code>x-ro-domain-type</code>. The whole process is discussed in more detail in
-the <a href="#_ugvro_architecture">architecture</a> chapter.</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_ugvro_ro-spec_extensions_content-negotiation_apache-isis-profile">Apache Isis profile</h5>
-<div class="paragraph">
-<p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
-However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party
-components that expect to consume much simpler representations. Examples of such tools are
-<a href="http://angular-ui.github.io/bootstrap/">Angular Bootstrap</a>,
-<a href="http://vitalets.github.io/angular-xeditable/">Angular XEditable</a>,
-<a href="https://github.com/mgcrea/angular-strap">Angular Strap</a>.</p>
-</div>
-<div class="paragraph">
-<p>This support is discussed further in the <a href="#_ugvro_simplified-representations">simplified representations</a>
-chapter.</p>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ugvro_ro-spec_extensions_minimizing-round-trips">2.4.2. Minimizing Round-trips (34.4)</h4>
-<div class="paragraph">
-<p>The Restful Objects viewer supports the <code>x-ro-follow-links</code> query parameter in a way very similar to that suggested
-in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls. For example, using
-this feature one can load a grid of data in a single call. (That said, the <a href="#_ugvro_simplified-representations">simplified representations</a>
-supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).</p>
-</div>
-<div class="paragraph">
-<p>This <a href="https://www.youtube.com/watch?v=hSKnqqBQ7Zo">screencast</a> demonstrates the Restful Object viewer’s support for <code>x-ro-follow-links</code> parameter, using the
-(non-ASF) <a href="http://github.com/isisaddons/isis-app-kitchensink">Isis addons' kitchensink</a> app as the example,
-This app contains three entities, <code>Grandparent</code>, <code>Parent</code> and <code>Child</code> that define a hierarchy of 1:m relationships.</p>
-</div>
-<div class="paragraph">
-<p>The queries that are shown in the screencast include:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>show parent and its children (titles)<br></p>
-<div class="paragraph">
-<p><pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value</p>
-</div>
-</li>
-<li>
-<p>show parent and its children (full details)<br></p>
-<div class="paragraph">
-<p><pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value.href</p>
-</div>
-</li>
-<li>
-<p>child’s parent (title)<br></p>
-<div class="paragraph">
-<p><pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value</p>
-</div>
-</li>
-<li>
-<p>child’s siblings (up to its parent, down to children)<br></p>
-<div class="paragraph">
-<p><pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value.members[children].value</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="sect4">
-<h5 id="_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints">Honor UI hints</h5>
-<div class="paragraph">
-<p>By default the representations generated by Restful Objects ignore any Apache Isis metamodel hints referring to the UI.
-In particular, if a collection is annotated then <code>Render(EAGERLY)</code> then the contents of the collection are <em>not</em>
-eagerly embedded in the object representation.</p>
-</div>
-<div class="paragraph">
-<p>However, this behaviour can be overridden globally using following property (typically added to <code>WEB-INF/viewer_restfulobjects.properties</code>):</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.viewer.restfulobjects.honorUiHints=true</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This means that standard Apache Isis annotations can be used as a simple way to obtain follow-links (driven from the
-server model, though, rather than the requesting client).</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugvro_architecture">3. Architecture</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The <a href="#">RestfulObjects viewer</a> implements the <a href="http://restfulobjects.org">Restful Object spec</a>, meaning
-that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON)
-representations when these resources are accessed.</p>
-</div>
-<div class="paragraph">
-<p>By default, the Restful Objects viewer will automatically handle requests and return representations according to the
-RO spec. However, its internal architecture provides several hooks for content negotiation, thereby allowing the
-generated representation to be influenced using the standard HTTP <code>Accept</code> header. In response, the server uses
-the <code>Content-Type</code> header which the client can use to know how to process the returned representation.</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>RepresentationService</code><br></p>
-<div class="paragraph">
-<p>The <a href="rgfis.html#_rgfis_spi_RepresentationService"><code>RepresentationService</code></a> is an SPI domain service (plugin-point)
-that allows an arbitrary representation to be generated for any of the resources defined in the RO spec.<br></p>
-</div>
-<div class="paragraph">
-<p>Normally this SPI service need not be replaced, because the default implementation
-(<code>RepresentationServiceContentNegotiator</code>) simply uses the HTTP <code>Accept</code> header and delegates onto another service, the
-(slightly misnamed) <code>ContentNegotiationService</code>, to actually generate the representation. There can be multiple
-implementations of the <code>ContentNegotiationService</code> and the content negotiator will delegate to each in turn until one
-is able to handle the request (per the chain of responsibliity pattern).</p>
-</div>
-</li>
-<li>
-<p><code>ContentNegotiationService</code><br></p>
-<div class="paragraph">
-<p>As noted above, there can be multiple implementations of the
-<a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>, each one handling a particular
-HTTP <code>Accept</code> header. If the implementation does not recognize the value of the header, if can simply return <code>null</code>.<br></p>
-</div>
-<div class="paragraph">
-<p>The framework provides a number of implementations; an implementation that handles the
-<a href="#_ugvro_simplified-representations">simplified representation</a> of the Apache Isis profile; an implementation that provides support for the <code>x-ro-domain-type</code> parameter, and a
-default/fallback implementation that returns the representations defined by the RO spec.</p>
-</div>
-</li>
-<li>
-<p><code>ContentMappingService</code><br></p>
-<div class="paragraph">
-<p>The <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> is used by the implementation of
-<code>ContentNegotationService</code> that recognizes the <code>x-ro-domain-type</code>, its role being to transform a domain object
-(usually an entity) into some other form (usually a DTO), as specified by the <code>x-ro-domain-type</code> parameter. There
-can be many such implementations, each handling a different target domain type.</p>
-</div>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>This diagram shows how these services collaborate:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/reference-services-spi/RepresentationService/service-collaborations.png"><img src="images/reference-services-spi/RepresentationService/service-collaborations.png" alt="service collaborations" width="800px"></a>
-</div>
-</div>
-<div class="paragraph">
-<p>Taken together these domain services offer a lot of flexibility in terms of the representations that can be generated
-from the RestfulObjects viewer.</p>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugvro_simplified-representations">4. Simplified Representations</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
-However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party
-components that expect to consume much simpler representations. Examples of such tools are
-<a href="http://angular-ui.github.io/bootstrap/">Angular Bootstrap</a>,
-<a href="http://vitalets.github.io/angular-xeditable/">Angular XEditable</a>,
-<a href="https://github.com/mgcrea/angular-strap">Angular Strap</a>.</p>
-</div>
-<div class="paragraph">
-<p>As of <code>1.11.0</code>, Apache Isis provides support for its own simplified representation for the most commonly-used
-representations. This is implemented using the <code>ContentNegotiationService</code> described in the
-<a href="#_ugvro_architecture">architecture</a> chapter.</p>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_apache-isis-profile">4.1. The Apache Isis "Profile"</h3>
-<div class="paragraph">
-<p>The RO spec uses the standard <code>Accept</code> header for content negotiation, and defines its own "profile" for the standard
-representations; these take the form:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>where "xxx" varies by resource. The detail can be found in section 2.4.1 of the RO spec.</p>
-</div>
-<div class="paragraph">
-<p>The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified
-representations for the most frequently accessed resources. This is done by specifying an <code>Accept</code> header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Not every resource supports this header, but the most commonly accessed ones do. In each case the server will set the
-<code>Content-Type</code> header so that the client knows how to process the representation.</p>
-</div>
-<div class="paragraph">
-<p>The <a href="https://www.youtube.com/watch?v=HMSqapQDY_4">screencast</a> demonstrates the feature.</p>
-</div>
-<div class="paragraph">
-<p>The sections below explain in a little more detail what is returned when this profile is activated.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_domain-object">4.2. Domain Object</h3>
-<div class="paragraph">
-<p>If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a
-JSON object with simple key/value pairs for each property.</p>
-</div>
-<div class="paragraph">
-<p>The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced
-object. Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
-Each element also has a special <code>href` property (so that the client can easily navigate to a resource for that
-object) and a `title</code> property (to use as a label, eg the hyperlink text).</p>
-</div>
-<div class="paragraph">
-<p>In addition, the representation defined by the RO spec is also included, under a special <code>$$ro</code> property.</p>
-</div>
-<div class="paragraph">
-<p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing
-this resource:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with an <code>Accept</code> request header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>returns the following representation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>{
+ </style>
+ </head>
+ <body>
+ <div class="row">
+ <div class="fixed contain-to-grid header">
+ <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
+ <ul class="title-area">
+ <li class="name"> <h1> <a href="/index.html">Apache Isis\u2122</a> </h1> </li>
+ <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
+ <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
+ </ul>
+ <section class="top-bar-section">
+ <ul class="right">
+ <li class="has-form">
+ <form class="searchbox navbar-form navbar-right" id="searchbox_012614087480249044419:dn-q5gtwxya" action="http://www.google.com/cse">
+ <div class="row collapse">
+ <input type="hidden" name="cx" value="012614087480249044419:dn-q5gtwxya">
+ <input type="hidden" name="cof" value="FORID:0">
+ <input class="form-control" name="q" type="text" placeholder="Search">
+ </div>
+ </form> </li>
+ </ul>
+ <!-- Left Nav Section -->
+ <ul class="left">
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/downloads.html">Downloads</a></li>
+ <li><a href="/help.html">Help</a></li>
+ <li><a href="/asf.html">@ASF</a></li>
+ </ul>
+ </section>
+ </nav>
+ </div>
+ </div>
+ <div class="row">
+ <div id="doc-content-left" class="large-9 medium-9 columns">
+ <div id="doc-content">
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugvro.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_ugvw">1. Restful Objects Viewer</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugvw.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>Apache Isis' Restful Objects viewer is an implementation of the <a href="http://restfulobjects.org">Restful Objects spec</a>, which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API. Having a REST API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps, through integration scenarious, through providing an API for bulk-upload/migration from an existing system.</p>
+ </div>
+ <div class="paragraph">
+ <p>The Restful Objects viewer also provides a number of extensions specific to Apache Isis. Most significant of these is enhanced content negotiation support, making it easier to use the returned representations within bespoke clients using standard third-party configurations.</p>
+ </div>
+ <div class="paragraph">
+ <p>This user guide discuss features, configuration and also how to extend the Restful Objects viewer.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="ugfun.html">Fundamentals</a></p> </li>
+ <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="#">Restful Objects viewer</a> (this guide)</p> </li>
+ <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="ugsec.html">Security</a></p> </li>
+ <li> <p><a href="ugtst.html">Testing</a></p> </li>
+ <li> <p><a href="ugbtb.html">Beyond the Basics</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The reference guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="rgant.html">Annotations</a></p> </li>
+ <li> <p><a href="rgsvc.html">Domain Services</a></p> </li>
+ <li> <p><a href="rgcfg.html">Configuration Properties</a></p> </li>
+ <li> <p><a href="rgcms.html">Classes, Methods and Schema</a></p> </li>
+ <li> <p><a href="rgmvn.html">Apache Isis Maven plugin</a></p> </li>
+ <li> <p><a href="rgfis.html">Framework Internal Services</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The remaining guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li>
+ <li> <p><a href="cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugvro_ro-spec">2. RO Specification</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugvro_ro-spec.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and corresponding JSON representations, for accessing and manipulating a domain object model.</p>
+ </div>
+ <div class="paragraph">
+ <p>The Restful Objects spec can be downloaded from <a href="http://restfulobjects.org">here</a> as either a PDF or Word doc.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_ro-spec_goals">2.1. Goals of the Spec</h3>
+ <div class="paragraph">
+ <p>The goal of Restful Objects is to allow domain models to be accessed through HTTP resources, returning a set of JSON representations. These representations can then be consumed by any client (e.g. Javascript, Java, .NET, Ruby, Python).</p>
+ </div>
+ <div class="paragraph">
+ <p>Both the resources and representations are generalized so that they can be applied to any domain model, and by default all representations have media types designed to allow a completely generic client to be written, capable of working, unmodified, with any domain model that has a Restful Objects interface.</p>
+ </div>
+ <div class="paragraph">
+ <p>Alternatively, the developer may write a custom client that has some shared knowledge of the domain being exposed, and render the information in a more specific fashion.</p>
+ </div>
+ <div class="paragraph">
+ <p>Restful Objects also defines that representations are served up with parameterized media types. This allows clients to use content negotiation to ensure that representations do not change in a breaking fashion, enabling server and client to evolve independently.</p>
+ </div>
+ <div class="paragraph">
+ <p>The Restful Objects specification is at a higher-level of abstraction than, say, the JAX-RS specifications for Java platform, or the WCF specifications on .NET. Specifically, the domain classes that it exposes are represented in a very general form. They consist of:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>properties (fields), each holding either a scalar value or reference to another object;</p> </li>
+ <li> <p>collections, each holding a vector reference to other entities;</p> </li>
+ <li> <p>actions (operations/methods), whereby the object can execute business logic.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Beyond this, though, Restful Objects makes very few assumptions. In particular, Restful Objects does not prescribe the nature of the domain model.</p>
+ </div>
+ <div class="paragraph">
+ <p>The Restful Objects spec may be downloaded directly from github as either a PDF or as a Word doc.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_resources_and_representations">2.2. Resources and Representations</h3>
+ <div class="paragraph">
+ <p>The diagram below - taken from the Restful Objects spec - shows the various resources (URLs) and representations (JSON) that are defined:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/restfulobjects/ro-spec-resources-and-representations.png"><img src="images/restfulobjects/ro-spec-resources-and-representations.png" alt="ro spec resources and representations" width="800px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The resource URLs are always well-defined, but Apache Isis' implementation allows for different representations to be returned, using content negotiation. This is discussed further below.</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>In fact, there\u2019s nothing in Apache Isis to prevent you from defining your own REST controllers to provide custom resource URLs. One use case might be to support user registration/authentication, a topic out-of-scope of the RO spec itself.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_ro-spec_apache-isis-implementation">2.3. Apache Isis' implementation</h3>
+ <div class="paragraph">
+ <p>The Restful Objects viewer is Apache Isis' implementation of the Restful Objects spec. It implements all the mandatory features of the specification. It also implements some of the optional capabilities (as defined in section 3 of the RO spec, and as represented in the version resource, section 8.1):</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3334%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Capability</th>
+ <th class="tableblock halign-left valign-top">Support</th>
+ <th class="tableblock halign-left valign-top">Notes</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>blobsClobs</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>yes</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div></div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>deleteObjects</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>yes</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div></div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>domainModel</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>formal</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>The 'simple' scheme is <em>not</em> supported</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>validateOnly</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>yes</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div></div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>protoPersistentObjects</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>yes</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div></div></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_ro-spec_extensions">2.4. Extensions</h3>
+ <div class="paragraph">
+ <p>The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but described in section 34, "ideas for future extensions".</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugvro_ro-spec_extensions_content-negotiation">2.4.1. Content Negotiation (34.1)</h4>
+ <div class="paragraph">
+ <p>Apache Isis provides two levels of support for content negotiation.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_ugvro_ro-spec_extensions_content-negotiation_x-ro-domain-type"><code>x-ro-domain-type</code></h5>
+ <div class="paragraph">
+ <p>The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec. The client can send an <code>x-ro-domain-type</code> parameter for either domain object representations (section 14 of the spec) or action invocation results (section 19 of the spec). This can be combined with either <code>application/json</code> or <code>application/xml</code>.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, the client could use an <code>Accept</code> header such as:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerViewModel"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>The server will use the <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> to attempt to transform the domain object into the requested <code>x-ro-domain-type</code>. The whole process is discussed in more detail in the <a href="#_ugvro_architecture">architecture</a> chapter.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_ugvro_ro-spec_extensions_content-negotiation_apache-isis-profile">Apache Isis profile</h5>
+ <div class="paragraph">
+ <p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built. However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations. Examples of such tools are <a href="http://angular-ui.github.io/bootstrap/">Angular Bootstrap</a>, <a href="http://vitalets.github.io/angular-xeditable/">Angular XEditable</a>, <a href="https://github.com/mgcrea/angular-strap">Angular Strap</a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>This support is discussed further in the <a href="#_ugvro_simplified-representations">simplified representations</a> chapter.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugvro_ro-spec_extensions_minimizing-round-trips">2.4.2. Minimizing Round-trips (34.4)</h4>
+ <div class="paragraph">
+ <p>The Restful Objects viewer supports the <code>x-ro-follow-links</code> query parameter in a way very similar to that suggested in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls. For example, using this feature one can load a grid of data in a single call. (That said, the <a href="#_ugvro_simplified-representations">simplified representations</a> supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).</p>
+ </div>
+ <div class="paragraph">
+ <p>This <a href="https://www.youtube.com/watch?v=hSKnqqBQ7Zo">screencast</a> demonstrates the Restful Object viewer\u2019s support for <code>x-ro-follow-links</code> parameter, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-kitchensink">Isis addons' kitchensink</a> app as the example, This app contains three entities, <code>Grandparent</code>, <code>Parent</code> and <code>Child</code> that define a hierarchy of 1:m relationships.</p>
+ </div>
+ <div class="paragraph">
+ <p>The queries that are shown in the screencast include:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>show parent and its children (titles)<br></p>
+ <div class="paragraph">
+ <p></p>
+ <pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value<p></p>
+</pre>
+ </div> </li>
+ <li> <p>show parent and its children (full details)<br></p>
+ <div class="paragraph">
+ <p></p>
+ <pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children].value.href<p></p>
+</pre>
+ </div> </li>
+ <li> <p>child\u2019s parent (title)<br></p>
+ <div class="paragraph">
+ <p></p>
+ <pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value<p></p>
+</pre>
+ </div> </li>
+ <li> <p>child\u2019s siblings (up to its parent, down to children)<br></p>
+ <div class="paragraph">
+ <p></p>
+ <pre>http://localhost:8080/restful/objects/CHILD/0?x-ro-follow-links=members[parent].value.members[children].value<p></p>
+</pre>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="sect4">
+ <h5 id="_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints">Honor UI hints</h5>
+ <div class="paragraph">
+ <p>By default the representations generated by Restful Objects ignore any Apache Isis metamodel hints referring to the UI. In particular, if a collection is annotated then <code>Render(EAGERLY)</code> then the contents of the collection are <em>not</em> eagerly embedded in the object representation.</p>
+ </div>
+ <div class="paragraph">
+ <p>However, this behaviour can be overridden globally using following property (typically added to <code>WEB-INF/viewer_restfulobjects.properties</code>):</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="ini">isis.viewer.restfulobjects.honorUiHints=true</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>This means that standard Apache Isis annotations can be used as a simple way to obtain follow-links (driven from the server model, though, rather than the requesting client).</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugvro_architecture">3. Architecture</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugvro_architecture.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>The <a href="#">RestfulObjects viewer</a> implements the <a href="http://restfulobjects.org">Restful Object spec</a>, meaning that it defines a well-defined set of endpoint URLs as resources, and generates a well-defined set of (JSON) representations when these resources are accessed.</p>
+ </div>
+ <div class="paragraph">
+ <p>By default, the Restful Objects viewer will automatically handle requests and return representations according to the RO spec. However, its internal architecture provides several hooks for content negotiation, thereby allowing the generated representation to be influenced using the standard HTTP <code>Accept</code> header. In response, the server uses the <code>Content-Type</code> header which the client can use to know how to process the returned representation.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><code>RepresentationService</code><br></p>
+ <div class="paragraph">
+ <p>The <a href="rgfis.html#_rgfis_spi_RepresentationService"><code>RepresentationService</code></a> is an SPI domain service (plugin-point) that allows an arbitrary representation to be generated for any of the resources defined in the RO spec.<br></p>
+ </div>
+ <div class="paragraph">
+ <p>Normally this SPI service need not be replaced, because the default implementation (<code>RepresentationServiceContentNegotiator</code>) simply uses the HTTP <code>Accept</code> header and delegates onto another service, the (slightly misnamed) <code>ContentNegotiationService</code>, to actually generate the representation. There can be multiple implementations of the <code>ContentNegotiationService</code> and the content negotiator will delegate to each in turn until one is able to handle the request (per the chain of responsibliity pattern).</p>
+ </div> </li>
+ <li> <p><code>ContentNegotiationService</code><br></p>
+ <div class="paragraph">
+ <p>As noted above, there can be multiple implementations of the <a href="rgfis.html#_rgfis_spi_ContentNegotiationService"><code>ContentNegotiationService</code></a>, each one handling a particular HTTP <code>Accept</code> header. If the implementation does not recognize the value of the header, if can simply return <code>null</code>.<br></p>
+ </div>
+ <div class="paragraph">
+ <p>The framework provides a number of implementations; an implementation that handles the <a href="#_ugvro_simplified-representations">simplified representation</a> of the Apache Isis profile; an implementation that provides support for the <code>x-ro-domain-type</code> parameter, and a default/fallback implementation that returns the representations defined by the RO spec.</p>
+ </div> </li>
+ <li> <p><code>ContentMappingService</code><br></p>
+ <div class="paragraph">
+ <p>The <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> is used by the implementation of <code>ContentNegotationService</code> that recognizes the <code>x-ro-domain-type</code>, its role being to transform a domain object (usually an entity) into some other form (usually a DTO), as specified by the <code>x-ro-domain-type</code> parameter. There can be many such implementations, each handling a different target domain type.</p>
+ </div> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>This diagram shows how these services collaborate:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/reference-services-spi/RepresentationService/service-collaborations.png"><img src="images/reference-services-spi/RepresentationService/service-collaborations.png" alt="service collaborations" width="800px"></a>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Taken together these domain services offer a lot of flexibility in terms of the representations that can be generated from the RestfulObjects viewer.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugvro_simplified-representations">4. Simplified Representations</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugvro_simplified-representations.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>The representations defined by the RO spec are very rich and enable complex client-side applications to be built. However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations. Examples of such tools are <a href="http://angular-ui.github.io/bootstrap/">Angular Bootstrap</a>, <a href="http://vitalets.github.io/angular-xeditable/">Angular XEditable</a>, <a href="https://github.com/mgcrea/angular-strap">Angular Strap</a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>As of <code>1.11.0</code>, Apache Isis provides support for its own simplified representation for the most commonly-used representations. This is implemented using the <code>ContentNegotiationService</code> described in the <a href="#_ugvro_architecture">architecture</a> chapter.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_simplified-representations_apache-isis-profile">4.1. The Apache Isis "Profile"</h3>
+ <div class="paragraph">
+ <p>The RO spec uses the standard <code>Accept</code> header for content negotiation, and defines its own "profile" for the standard representations; these take the form:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>where "xxx" varies by resource. The detail can be found in section 2.4.1 of the RO spec.</p>
+ </div>
+ <div class="paragraph">
+ <p>The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified representations for the most frequently accessed resources. This is done by specifying an <code>Accept</code> header of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Not every resource supports this header, but the most commonly accessed ones do. In each case the server will set the <code>Content-Type</code> header so that the client knows how to process the representation.</p>
+ </div>
+ <div class="paragraph">
+ <p>The <a href="https://www.youtube.com/watch?v=HMSqapQDY_4">screencast</a> demonstrates the feature.</p>
+ </div>
+ <div class="paragraph">
+ <p>The sections below explain in a little more detail what is returned when this profile is activated.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_simplified-representations_domain-object">4.2. Domain Object</h3>
+ <div class="paragraph">
+ <p>If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a JSON object with simple key/value pairs for each property.</p>
+ </div>
+ <div class="paragraph">
+ <p>The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced object. Each such element contains key/value pairs of each property (in other words, a grid of data is returned). Each element also has a special <code>href` property (so that the client can easily navigate to a resource for that object) and a `title</code> property (to use as a label, eg the hyperlink text).</p>
+ </div>
+ <div class="paragraph">
+ <p>In addition, the representation defined by the RO spec is also included, under a special <code>$$ro</code> property.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing this resource:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>with an <code>Accept</code> request header of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>returns the following representation:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>{
"$$href" : "http://localhost:8080/restful/objects/TODO/45", <i class="conum" data-value="1"></i><b>(1)</b>
"$$instanceId" : "45", <i class="conum" data-value="2"></i><b>(2)</b>
"$$title" : "Buy bread due by 2015-12-04", <i class="conum" data-value="3"></i><b>(3)</b>
@@ -1061,81 +940,79 @@ this resource:</p>
"instanceId" : "45",
"members" : { ... }
}
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>hyperlink to the representation</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>instance id of the domain object (unique within its type)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>title of the domain object</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>all the properties of the domain object (to which the caller has access), as key/value pairs</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>contents of each collection</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="6"></i><b>6</b></td>
-<td>special <code>$$ro</code> json-prop, being the normal RO Spec representation for this object</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>with a <code>Content-Type</code> header:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Content-Type: application/json;
- profile="urn:org.apache.isis/v1";repr-type="object"</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_object-collection">4.3. Domain Object Collection</h3>
-<div class="paragraph">
-<p>If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as
-an array of elements of key/value for each referenced object, and again each element the containing the key/value
-pairs of the properties of that object (a grid, again).<br></p>
-</div>
-<div class="paragraph">
-<p>In addition, the representation defined by the RO spec is also included, as a special object with a single <code>$$ro</code>
-property.</p>
-</div>
-<div class="paragraph">
-<p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing
-this resource:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45/collections/similarTo</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with an <code>Accept</code> request header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>returns the following representation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>[ <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>hyperlink to the representation</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>instance id of the domain object (unique within its type)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>title of the domain object</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="4"></i><b>4</b></td>
+ <td>all the properties of the domain object (to which the caller has access), as key/value pairs</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="5"></i><b>5</b></td>
+ <td>contents of each collection</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="6"></i><b>6</b></td>
+ <td>special <code>$$ro</code> json-prop, being the normal RO Spec representation for this object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>with a <code>Content-Type</code> header:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Content-Type: application/json;
+ profile="urn:org.apache.isis/v1";repr-type="object"</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_simplified-representations_object-collection">4.3. Domain Object Collection</h3>
+ <div class="paragraph">
+ <p>If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as an array of elements of key/value for each referenced object, and again each element the containing the key/value pairs of the properties of that object (a grid, again).<br></p>
+ </div>
+ <div class="paragraph">
+ <p>In addition, the representation defined by the RO spec is also included, as a special object with a single <code>$$ro</code> property.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing this resource:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45/collections/similarTo</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>with an <code>Accept</code> request header of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>returns the following representation:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>[ <i class="conum" data-value="1"></i><b>(1)</b>
{
"$$href" : "http://localhost:8080/restful/objects/TODO/46", <i class="conum" data-value="2"></i><b>(2)</b>
"$$instanceId" : "46", <i class="conum" data-value="3"></i><b>(3)</b>
@@ -1166,80 +1043,80 @@ this resource:</p>
"value" : [ ... ]
}
}
-]</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>returns a JSON array, not a JSON object</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>hyperlink to the representation</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>instance id of the domain object (unique within its type)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>title of the domain object</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>all the properties of the domain object (to which the caller has access), as key/value pairs</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="6"></i><b>6</b></td>
-<td>last element is a special object with a single <code>$$ro</code> json-prop, being the normal RO Spec representation for this object</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>with a <code>Content-Type</code> header:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"</code></pre>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_action-invocation">4.4. Action Invocation</h3>
-<div class="paragraph">
-<p>When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.</p>
-</div>
-<div class="sect3">
-<h4 id="_returning_an_object">4.4.1. Returning an Object</h4>
-<div class="paragraph">
-<p>If the action returned an object, then the domain object representation described
-<a href="#_ugvro_simplified-representations_domain-object">above</a> is returned.</p>
-</div>
-<div class="paragraph">
-<p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing
-this resource:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with an <code>Accept</code> request header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>returns the following representation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>{
+]</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>returns a JSON array, not a JSON object</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>hyperlink to the representation</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>instance id of the domain object (unique within its type)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="4"></i><b>4</b></td>
+ <td>title of the domain object</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="5"></i><b>5</b></td>
+ <td>all the properties of the domain object (to which the caller has access), as key/value pairs</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="6"></i><b>6</b></td>
+ <td>last element is a special object with a single <code>$$ro</code> json-prop, being the normal RO Spec representation for this object</td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>with a <code>Content-Type</code> header:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object-collection"</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugvro_simplified-representations_action-invocation">4.4. Action Invocation</h3>
+ <div class="paragraph">
+ <p>When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_returning_an_object">4.4.1. Returning an Object</h4>
+ <div class="paragraph">
+ <p>If the action returned an object, then the domain object representation described <a href="#_ugvro_simplified-representations_domain-object">above</a> is returned.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing this resource:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>http://localhost:8080/restful/objects/TODO/45/actions/updateCost/invoke</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>with an <code>Accept</code> request header of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>returns the following representation:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>{
"$$href" : "http://localhost:8080/restful/objects/TODO/45",
"$$instanceId" : "45",
"$$title" : "Buy bread due by 2015-12-04",
@@ -1251,52 +1128,48 @@ this resource:</p>
"similarTo" : [ ... ]
...
"$$ro" : { ... }
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with a <code>Content-Type</code> of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>... in other words no different to a representation obtained of the returned domain object directly.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_returning_a_list">4.4.2. Returning a List</h4>
-<div class="paragraph">
-<p>On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned.
-This is very similar to that returned by a
-<a href="#_ugvro_simplified-representations_object-collection">(parented) object collection</a>, though with a
-slightly different <code>Content-Type</code> to distinguish.</p>
-</div>
-<div class="paragraph">
-<p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing
-this resource:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with an <code>Accept</code> request header of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>returns the following representation:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>[ {
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>with a <code>Content-Type</code> of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="object"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>... in other words no different to a representation obtained of the returned domain object directly.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_returning_a_list">4.4.2. Returning a List</h4>
+ <div class="paragraph">
+ <p>On the other hand if the action returned a list (a "standalone" collection, then an array representation is returned. This is very similar to that returned by a <a href="#_ugvro_simplified-representations_object-collection">(parented) object collection</a>, though with a slightly different <code>Content-Type</code> to distinguish.</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, using the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>, accessing this resource:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>http://localhost:8080/restful/services/ToDoItems/actions/notYetComplete/invoke</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>with an <code>Accept</code> request header of:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>Accept: application/json;profile="urn:org.apache.isis/v1"</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>returns the following representation:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code>[ {
"$$href" : "http://localhost:8080/restful/objects/TODO/45",
"$$instanceId" : "45",
"$$title" : "Buy bread due by 2015-12-04",
@@ -1322,528 +1195,485 @@ this resource:</p>
"extensions" : { }
}
}
-} ]</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>with a <code>Content-Type</code> header:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code>Content-Type: application/json;profile="urn:org.apache.isis/v1";repr-type="list"</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_returning_scalar_nothing">4.4.3. Returning Scalar/Nothing</h4>
-<div class="paragraph">
-<p>Note that actions returning scalar values or nothing (which includes <code>void</code> actions) are not supported; for these the
-regular RO spec representation will be returned.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_other-representations">4.5. Supporting other Representations</h3>
-<div class="paragraph">
-<p>Sometimes though you may want to extend or change the representations generated. This might be because you want to
-write a RESTful client that uses a particular library (say a Javascript library or web components) that can only handle representations in a certain form.</p>
-</div>
-<div class="paragraph">
-<p>Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are
-many:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Mike Kelly’s <a href="http://stateless.co/hal_specification.html">HAL</a> specification</p>
-</li>
-<li>
-<p>Mike Amundsen’s <a href="http://amundsen.com/media-types/collection/">Collection+JSON</a> specification</p>
-</li>
-<li>
-<p>Kevin Swiber’s <a href="https://github.com/kevinswiber/siren">Siren</a> specification</p>
-</li>
-<li>
-<p>Steve Klabnik’s <a href="http://jsonapi.org/">JSON API</a> specification</p>
-</li>
-<li>
-<p>Gregg Cainus' <a href="https://github.com/cainus/hyper-json-spec">Hyper+JSON</a> specification</p>
-</li>
-<li>
-<p>the W3C’s <a href="https://www.w3.org/TR/json-ld/">JSON-LD</a> specification</p>
-</li>
-<li>
-<p>Markus Lanthaler’s <a href="http://www.markus-lanthaler.com/hydra/">Hydra</a> specification.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>A good discussion about the relative merits of several of these different hypermedia formats can be found <a href="https://groups.google.com/forum/#!msg/api-craft/NgjzQYVOE4s/EAB2jxtU_TMJ">here</a>.</p>
-</div>
-<div class="paragraph">
-<p>Or, of course, you may have your own internal specification that you wish to use.</p>
-</div>
-<div class="paragraph">
-<p>Supporting any of these alternative representations can be achieved by providing a suitable implementation of
-<code>ContentNegotiationService</code>. The existing implementations (eg <code>ContentNegotiationServiceSimplified</code>) can be used as a
-starting point.</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>These will, admittedly, need to access the internal APIs for the Apache Isis metamodel, and you should be aware that
-these are not formal API; they may change over time. That said, they are very stable and have not changed
-significantly over the last few years.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_simplified-representations_configuration-properties">4.6. Global Config Props (Deprecated)</h3>
-<div class="paragraph">
-<p>If all that is required is a very simple representations (of objects), you can configure the Restful Objects viewer
-to provide a simplified output, then this can be done with a number of (global) configuration properties.</p>
-</div>
-<div class="paragraph">
-<p>These configuration properties pre-date the support, introduced in <code>1.11.0</code>, for the Apache Isis profile, and
-are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request
-basis (as is the case with the <code>Accept</code> header used for the Apache Isis profile). They have therefore been
-deprecated, and may be removed in the future.</p>
-</div>
-<div class="paragraph">
-<p>Details can be found in <a href="#_ugvro_configuration-properties_deprecated">here</a>.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ugvro_configuration-properties">5. Configuration Properties</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>The Restful Objects viewer provides a couple of configuration option that extend/simplify/alter the representations
-generated from the Restful Objects specification.</p>
-</div>
-<div class="paragraph">
-<p>These configuration properties are typically stored in <code>WEB-INF/viewer_restfulobjects.properties</code>. However, you can
-place all configuration properties into <code>WEB-INF/isis.properties</code> if you wish (the configuration properties from all
-config files are merged together).</p>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_configuration-properties_standard">5.1. Standard</h3>
-<div class="paragraph">
-<p>The following configuration properties are supported:</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 1. Restful Objects Viewer Configuration Properties</caption>
-<colgroup>
-<col style="width: 33.3333%;">
-<col style="width: 16.6666%;">
-<col style="width: 50.0001%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Property</th>
-<th class="tableblock halign-left valign-top">Value<br>
-(<em>default value</em>)</th>
-<th class="tableblock halign-left valign-top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p><code>isis.viewer.restfulobjects.</code><br>
-<code>honorUiHints</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code> (<code><em>false</em></code>)</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed <a href="#_ugvro_ro-spec_extensions_minimizing-round-trips_honor-ui-hints">here</a>.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p><code>isis.viewer.restfulobjects.</code><br>
-<code>strictAcceptChecking</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code> (<code><em>false</em></code>)</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Whether to strictly enforce the <code>Accept</code> header checking for the default RO-spec representations (by the
-<code>ContentNegotiationServiceForRestfulObjectsV1_0</code> service). Will otherwise accept anything. <br>
-</p><p class="tableblock">This is convenient because it allows the <code>Accept</code> header to be set to that of the
-<a href="#_ugvro_simplified-representations">Apache Isis profile</a> for all resources, rather than simply the
-handful of resources that supported that profile.</p></td>
-</tr>
-</tbody>
-</table>
-</div>
-<div class="sect2">
-<h3 id="_ugvro_configuration-properties_deprecated">5.2. Deprecated</h3>
-<div class="paragraph">
-<p>There are also a number of configuration properties that can be used to suppress or simplify the default RO-spec
-representations.</p>
-</div>
-<div class="paragraph">
-<p>These configuration properties pre-date the support, introduced in <code>1.11.0</code>, for the Apache Isis profile, and
-are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request
-basis (as is the case with the <code>Accept</code> header used for the Apache Isis profile). They have therefore been
-deprecated, and may be removed in the future.</p>
-</div>
-<div class="paragraph">
-<p>Nevertheless, those configuration properties are:</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 2. Deprecated Configuration Properties</caption>
-<colgroup>
-<col style="width: 33.3333%;">
-<col style="width: 16.6666%;">
-<col style="width: 50.0001%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Property</th>
-<th class="tableblock halign-left valign-top">Value<br>
-(<em>default value</em>)</th>
-<th class="tableblock halign-left valign-top">Description</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p><code>isis.viewer.restfulobjects.</code><br>
-<code>suppressDescribedByLinks</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code> (<code><em>false</em></code>)</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Suppresses the "describedby" links (on all representations)</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p><code>isis.viewer.restfulobjects.</code><br>
-<code>suppressUpdateLink</code></p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code> (<code><em>false</em></code>)</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">suppresses the "update" link (on object representation)</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p><code>isis.viewer.restfulobjects.</code><br>
-<code>sup
<TRUNCATED>