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:21 UTC
[23/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/ugbtb.html
----------------------------------------------------------------------
diff --git a/content/guides/ugbtb.html b/content/guides/ugbtb.html
index 78fc56c..112cd91 100644
--- a/content/guides/ugbtb.html
+++ b/content/guides/ugbtb.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>Beyond the Basics</title>
-
- <!--
+ <head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Beyond the Basics</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,548 +406,467 @@ 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="_ugbtb">1. Beyond the Basics</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>This guide provides <a href="#_ugbtb_other-techniques">more advanced</a> guidance on writing maintainable larger
-applications.</p>
-</div>
-<div class="paragraph">
-<p>Later chapters discuss how to <a href="#_ugbtb_deployment">deploy</a> your app, and discuss other ways in which you can <a href="#">extend</a> or adapt the framework itself to your particular needs.</p>
-</div>
-<div class="sect2">
-<h3 id="_other_guides">1.1. Other Guides</h3>
-<div class="paragraph">
-<p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
-</div>
-<div class="paragraph">
-<p>The user guides available are:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><a href="ugfun.html">Fundamentals</a></p>
-</li>
-<li>
-<p><a href="ugvw.html">Wicket viewer</a></p>
-</li>
-<li>
-<p><a href="ugvro.html">Restful Objects viewer</a></p>
-</li>
-<li>
-<p><a href="ugdno.html">DataNucleus object store</a></p>
-</li>
-<li>
-<p><a href="ugsec.html">Security</a></p>
-</li>
-<li>
-<p><a href="ugtst.html">Testing</a></p>
-</li>
-<li>
-<p><a href="#">Beyond the Basics</a> (this guide)</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="_ugbtb_view-models">2. View Models</h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>View models are a type of domain object (with state, behaviour etc) but where the state is <em>not</em> persisted into the
- JDO/DataNucleus-managed database, but is instead converted to/from a string memento, and held by the calling client.
-This opens up a number of more advanced use cases.</p>
-</div>
-<div class="paragraph">
-<p>In this topic we’ll explore those use cases, and learn the programming model and conventions to use view models in your application.</p>
-</div>
-<div class="sect2">
-<h3 id="_ugbtb_view-models_use-cases">2.1. Use Cases</h3>
-<div class="paragraph">
-<p>When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-<code>Customer</code>, <code>Order</code>, <code>Product</code>, and so on. For some applications this may well suffice. However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.</p>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_use-cases_externally-managed-entities">2.1.1. Externally-managed entities</h4>
-<div class="paragraph">
-<p>Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service. Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn’t know about the entity nor how to retrieve or
-update it.</p>
-</div>
-<div class="paragraph">
-<p>There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).</p>
-</div>
-<div class="paragraph">
-<p>The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.</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>DataNucleus does in fact define its own <a href="http://www.datanucleus.org/documentation/extensions/store_manager.html">Store Manager</a> extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular <code>@PersistenceCapable</code> entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific <code>StoreManager</code> provided by DataNucleus itself.</p>
-</div>
-<div class="paragraph">
-<p>An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_use-cases_in-memory-entities">2.1.2. In-memory entities</h4>
-<div class="paragraph">
-<p>As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).</p>
-</div>
-<div class="paragraph">
-<p>A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_use-cases_application-layer-view-models">2.1.3. Application-layer view models</h4>
-<div class="paragraph">
-<p>Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid. Generally those domain entities will make sense to the business domain experts: they form the <em>ubiquitous language</em> of the domain. These domain entities are part of the domain layer.</p>
-</div>
-<div class="paragraph">
-<p>That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.</p>
-</div>
-<div class="paragraph">
-<p>A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model. It is not a persisted entity, instead it belongs to the application layer.</p>
-</div>
-<div class="paragraph">
-<p>A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
-some cases such view model actions might also modify state of underlying domain entities.</p>
-</div>
-<div class="paragraph">
-<p>Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.</p>
-</div>
-<div class="sidebarblock">
-<div class="content">
-<div class="title">Desire Lines</div>
-<div class="paragraph">
-<p>One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.</p>
-</div>
-<div class="paragraph">
-<p>To explain: there are <a href="http://ask.metafilter.com/62599/Where-the-sidewalk-ends">documented</a>
-<a href="https://sivers.org/walkways">examples</a>
-<a href="http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml">that</a> architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".</p>
-</div>
-<div class="paragraph">
-<p>What that means is you should add view models <em>after</em> having built up the domain layer, rather than before. These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.</p>
-</div>
-<div class="paragraph">
-<p>It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support. You certainly <em>shouldn’t</em> try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.</p>
-</div>
-<div class="paragraph">
-<p>Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
-business. Then build out the minimum domain entities to support that use case (refining the <a href="ugfun.html#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language">ubiquitous language</a> as you
-go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_use-cases_dtos">2.1.4. DTOs</h4>
-<div class="paragraph">
-<p>DTOs (data transfer objects) are simple classes that (according to <a href="https://en.wikipedia.org/wiki/Data_transfer_object">wikipedia</a>) "carry data between processes".</p>
-</div>
-<div class="paragraph">
-<p>If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there’s generally no need to define a DTO; just access the entities using Apache Isis'
-<a href="ugvro.html">RestfulObjects viewer</a>.</p>
-</div>
-<div class="paragraph">
-<p>On the other hand, if the client consuming the DTO is a different application — by which we mean developed/deployed by
-a different (possible third-party) team — then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over <a href="ugvro.html">RestfulObjects</a> would be
-"A Bad Thing"™ because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.</p>
-</div>
-<div class="paragraph">
-<p>To support this use case, a view model can be defined such that it can act as a DTO. This is done by annotating the
-class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
-XSD schema describing the structure of that XML. A discussion of how that might be done using an ESB such as
-<a href="http://camel.apache.org">Apache Camel™</a> follows <a href="#_ugbtb_view-models_use-cases_dtos_consumers">below</a>.</p>
-</div>
-<div class="paragraph">
-<p>In case it’s not obvious, these DTOs are still usable as "regular" view models; they will render in the <a href="ugvw.html">Wicket viewer</a> just like any other. In fact (as the <a href="#_ugbtb_view-models_programming-model">programming model</a> section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.</p>
-</div>
-<div class="paragraph">
-<p>It’s also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the <a href="rgcms.html#_rgcms_classes_mixins_Dto"><code>Dto</code></a> marker interface; the
-framework has <a href="rgcms.html#_rgcms_classes_mixins_Dto">mixins</a> that contribute the download actions to the view model.</p>
-</div>
-<div class="sect4">
-<h5 id="_ugbtb_view-models_use-cases_dtos_consumers">DTO Consumers</h5>
-<div class="paragraph">
-<p>The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the <a href="ugvro.html">RestfulObjects viewer</a>, or may have the XML sent to them asynchronously using an ESB
-such as Apache Camel.</p>
-</div>
-<div class="paragraph">
-<p>In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP <code>Accept</code> header.
-An appropriate implementation of <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> can then be
-used to return the appropriate DTO (as XML).</p>
-</div>
-<div class="paragraph">
-<p>For the latter case, one design is simply for the application to instantiate the view model, then call the
-<a href="rgsvc.html#_rgsvc_api_JaxbService"><code>JaxbService</code></a> to obtain its corresponding XML. This can then be published onto
-the ESB, for example using an <a href="http://activemq.apache.org">Apache ActiveMQ ™</a> queue.</p>
-</div>
-<div class="paragraph">
-<p>However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
- (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
- the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required. This can once again be done by calling the REST API with
- an appropriate HTTP <code>Accept</code> header.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>This is an example of the <a href="https://leanpub.com/camel-design-patterns">VETRO pattern</a> (validate, enrich, transform, route, operate). In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
-invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module provides an out-of-the-box solution of this design. It provides an implementation of the <a href="rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>,
-but which simply publishes instances of <a href="rgcms.html#_rgcms_schema-aim"><code>ActionInvocationMemento</code></a> to an ActiveMQ
-queue. Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
-parse the action memento to determine what has changed on the source system. Thereafter, a subsequent Camel processor
-can then call back to the source - via the <a href="#ugvro.adoc">Restful Objects viewer</a> - to enrich the message with
-additional details using a DTO.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugbtb_view-models_programming-model">2.2. Programming Model</h3>
-<div class="paragraph">
-<p>So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a>) if it exceeds the maximum length for a URL
-(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.</p>
-</div>
-<div class="paragraph">
-<p>While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost. They are:</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 1. View model programming model</caption>
-<colgroup>
-<col style="width: 14.2857%;">
-<col style="width: 57.1428%;">
-<col style="width: 28.5715%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Use case</th>
-<th class="tableblock halign-left valign-top">Code</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>External entity</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.EXTERNAL_ENTITY)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerRecordOnSAP</span> { ... }</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Annotated with <a href="rgant.html#_rgant-DomainObject_nature"><code>@DomainObject#nature()</code></a> and a nature of <code>EXTERNAL_ENTITY</code>, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as <a href="rgant.html#_rgant-Property_notPersisted">not persisted</a>.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>In-memory entity</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.INMEMORY_ENTITY)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Log4JAppender</span> { ... }</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>As preceding, but using a nature of <code>INMEMORY_ENTITY</code>.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Application view model</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.VIEW_MODEL)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Dashboard</span> { ... }</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>As preceding, but using a nature of <code>VIEW_MODEL</code>.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Application view model</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ViewModel</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Dashboard</span> { ... }</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Annotated with <a href="rgant.html#_rgant-ViewModel"><code>@ViewModel</code></a> annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Application view model</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><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">ExcelUploadManager</span> <span class="directive">implements</span> ViewModel {
+ </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/ugbtb.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_ugbtb">1. Beyond the Basics</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugbtb.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This guide provides <a href="#_ugbtb_other-techniques">more advanced</a> guidance on writing maintainable larger applications.</p>
+ </div>
+ <div class="paragraph">
+ <p>Later chapters discuss how to <a href="#_ugbtb_deployment">deploy</a> your app, and discuss other ways in which you can <a href="#">extend</a> or adapt the framework itself to your particular needs.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="ugfun.html">Fundamentals</a></p> </li>
+ <li> <p><a href="ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="ugvro.html">Restful Objects viewer</a></p> </li>
+ <li> <p><a href="ugdno.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="ugsec.html">Security</a></p> </li>
+ <li> <p><a href="ugtst.html">Testing</a></p> </li>
+ <li> <p><a href="#">Beyond the Basics</a> (this guide)</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="_ugbtb_view-models">2. View Models</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models.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>View models are a type of domain object (with state, behaviour etc) but where the state is <em>not</em> persisted into the JDO/DataNucleus-managed database, but is instead converted to/from a string memento, and held by the calling client. This opens up a number of more advanced use cases.</p>
+ </div>
+ <div class="paragraph">
+ <p>In this topic we\u2019ll explore those use cases, and learn the programming model and conventions to use view models in your application.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugbtb_view-models_use-cases">2.1. Use Cases</h3>
+ <div class="paragraph">
+ <p>When developing an Apache Isis application you will most likely start off with the persistent domain entities: <code>Customer</code>, <code>Order</code>, <code>Product</code>, and so on. For some applications this may well suffice. However, if the application needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_use-cases_externally-managed-entities">2.1.1. Externally-managed entities</h4>
+ <div class="paragraph">
+ <p>Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database but reside in some other system, for example accessible only through a SOAP web service. Logically that data might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be modelled as a domain entity if only because JDO/DataNucleus doesn\u2019t know about the entity nor how to retrieve or update it.</p>
+ </div>
+ <div class="paragraph">
+ <p>There are a couple of ways around this: we could either replicate the data somehow from the external system into the Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).</p>
+ </div>
+ <div class="paragraph">
+ <p>The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.</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>DataNucleus does in fact define its own <a href="http://www.datanucleus.org/documentation/extensions/store_manager.html">Store Manager</a> extension point, so an alternative architecture would be to implement this interface such that DataNucleus could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular <code>@PersistenceCapable</code> entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific <code>StoreManager</code> provided by DataNucleus itself.</p>
+ </div>
+ <div class="paragraph">
+ <p>An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but implementing one that also supported updating external entities would need to carefully consider error conditions if the external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not desirable in any case).</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_use-cases_in-memory-entities">2.1.2. In-memory entities</h4>
+ <div class="paragraph">
+ <p>As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose state is not actually persisted anywhere, merely held in-memory (eg in a hash).</p>
+ </div>
+ <div class="paragraph">
+ <p>A simple example might be read-only configuration data that is read from a config file (eg log4j appender definitions) but thereafter is presented in the UI just like any other entity.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_use-cases_application-layer-view-models">2.1.3. Application-layer view models</h4>
+ <div class="paragraph">
+ <p>Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are solid. Generally those domain entities will make sense to the business domain experts: they form the <em>ubiquitous language</em> of the domain. These domain entities are part of the domain layer.</p>
+ </div>
+ <div class="paragraph">
+ <p>That said, it may not always be practical to expect end-users of the application to interact solely with those domain entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user, often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for the end user.</p>
+ </div>
+ <div class="paragraph">
+ <p>A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view model. It is not a persisted entity, instead it belongs to the application layer.</p>
+ </div>
+ <div class="paragraph">
+ <p>A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in some cases such view model actions might also modify state of underlying domain entities.</p>
+ </div>
+ <div class="paragraph">
+ <p>Another common use for view models is to help co-ordinate complex business processes; for example to perform a quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model might have some state of its own, but in most cases that state does not need to be persisted per se.</p>
+ </div>
+ <div class="sidebarblock">
+ <div class="content">
+ <div class="title">
+ Desire Lines
+ </div>
+ <div class="paragraph">
+ <p>One way to think of application view models is as modelling the "desire line": the commonly-trod path that end-users must follow to get from point A to point B as quickly as possible.</p>
+ </div>
+ <div class="paragraph">
+ <p>To explain: there are <a href="http://ask.metafilter.com/62599/Where-the-sidewalk-ends">documented</a> <a href="https://sivers.org/walkways">examples</a> <a href="http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml">that</a> architects of university campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the routes they want to take. The name we like best for this idea is "desire lines", though it has also been called a "desire path", "paving the path" or "paving the sidewalk".</p>
+ </div>
+ <div class="paragraph">
+ <p>What that means is you should add view models <em>after</em> having built up the domain layer, rather than before. These view models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.</p>
+ </div>
+ <div class="paragraph">
+ <p>It takes a little practice though, because even when building the domain layer "first", you should still bear in mind what the use cases are that those domain entities are trying to support. You certainly <em>shouldn\u2019t</em> try to build out a domain layer that could support every conceivable use case before starting to think about view models.</p>
+ </div>
+ <div class="paragraph">
+ <p>Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the business. Then build out the minimum domain entities to support that use case (refining the <a href="ugfun.html#_ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language">ubiquitous language</a> as you go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions with the system (perhaps automating several related use cases together).</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_use-cases_dtos">2.1.4. DTOs</h4>
+ <div class="paragraph">
+ <p>DTOs (data transfer objects) are simple classes that (according to <a href="https://en.wikipedia.org/wiki/Data_transfer_object">wikipedia</a>) "carry data between processes".</p>
+ </div>
+ <div class="paragraph">
+ <p>If those two processes are parts of the same overall application (the same team builds and deploys both server and client) then there\u2019s generally no need to define a DTO; just access the entities using Apache Isis' <a href="ugvro.html">RestfulObjects viewer</a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>On the other hand, if the client consuming the DTO is a different application\u2009\u2014\u2009by which we mean developed/deployed by a different (possible third-party) team\u2009\u2014\u2009then the DTOs act as a formal contract between the provider and the consumer. In such cases, exposing domain entities over <a href="ugvro.html">RestfulObjects</a> would be "A Bad Thing"\u2122 because the consumer would in effect have access to implementation details that could then not be easily changed by the producer.</p>
+ </div>
+ <div class="paragraph">
+ <p>To support this use case, a view model can be defined such that it can act as a DTO. This is done by annotating the class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding XSD schema describing the structure of that XML. A discussion of how that might be done using an ESB such as <a href="http://camel.apache.org">Apache Camel\u2122</a> follows <a href="#_ugbtb_view-models_use-cases_dtos_consumers">below</a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>In case it\u2019s not obvious, these DTOs are still usable as "regular" view models; they will render in the <a href="ugvw.html">Wicket viewer</a> just like any other. In fact (as the <a href="#_ugbtb_view-models_programming-model">programming model</a> section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.</p>
+ </div>
+ <div class="paragraph">
+ <p>It\u2019s also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development. The view model simply needs to implement the <a href="rgcms.html#_rgcms_classes_mixins_Dto"><code>Dto</code></a> marker interface; the framework has <a href="rgcms.html#_rgcms_classes_mixins_Dto">mixins</a> that contribute the download actions to the view model.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_ugbtb_view-models_use-cases_dtos_consumers">DTO Consumers</h5>
+ <div class="paragraph">
+ <p>The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly, eg using the <a href="ugvro.html">RestfulObjects viewer</a>, or may have the XML sent to them asynchronously using an ESB such as Apache Camel.</p>
+ </div>
+ <div class="paragraph">
+ <p>In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP <code>Accept</code> header. An appropriate implementation of <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a> can then be used to return the appropriate DTO (as XML).</p>
+ </div>
+ <div class="paragraph">
+ <p>For the latter case, one design is simply for the application to instantiate the view model, then call the <a href="rgsvc.html#_rgsvc_api_JaxbService"><code>JaxbService</code></a> to obtain its corresponding XML. This can then be published onto the ESB, for example using an <a href="http://activemq.apache.org">Apache ActiveMQ \u2122</a> queue.</p>
+ </div>
+ <div class="paragraph">
+ <p>However, rather than try to push all the data that might be needed by any of these external systems in a single XML event (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required. This can once again be done by calling the REST API with an appropriate HTTP <code>Accept</code> header.</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>This is an example of the <a href="https://leanpub.com/camel-design-patterns">VETRO pattern</a> (validate, enrich, transform, route, operate). In our case we focus on the validation (to determine the nature of the inbound message, ie which action was invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="paragraph">
+ <p>The (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module provides an out-of-the-box solution of this design. It provides an implementation of the <a href="rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>, but which simply publishes instances of <a href="rgcms.html#_rgcms_schema-aim"><code>ActionInvocationMemento</code></a> to an ActiveMQ queue. Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to parse the action memento to determine what has changed on the source system. Thereafter, a subsequent Camel processor can then call back to the source - via the <a href="#ugvro.adoc">Restful Objects viewer</a> - to enrich the message with additional details using a DTO.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugbtb_view-models_programming-model">2.2. Programming Model</h3>
+ <div class="paragraph">
+ <p>So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this URL can become quite long, but Apache Isis offers a mechanism (the <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a>) if it exceeds the maximum length for a URL (2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within a URL.</p>
+ </div>
+ <div class="paragraph">
+ <p>While the underlying technique is the same irrespective of use case, the programming model provides various ways of defining a view model so that the original intent is not lost. They are:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <caption class="title">
+ Table 1. View model programming model
+ </caption>
+ <colgroup>
+ <col style="width: 14.2857%;">
+ <col style="width: 57.1428%;">
+ <col style="width: 28.5715%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Use case</th>
+ <th class="tableblock halign-left valign-top">Code</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>External entity</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.EXTERNAL_ENTITY)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerRecordOnSAP</span> { ... }</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Annotated with <a href="rgant.html#_rgant-DomainObject_nature"><code>@DomainObject#nature()</code></a> and a nature of <code>EXTERNAL_ENTITY</code>, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as <a href="rgant.html#_rgant-Property_notPersisted">not persisted</a>.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>In-memory entity</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.INMEMORY_ENTITY)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Log4JAppender</span> { ... }</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>As preceding, but using a nature of <code>INMEMORY_ENTITY</code>.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Application view model</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@DomainObject</span>(nature=Nature.VIEW_MODEL)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Dashboard</span> { ... }</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>As preceding, but using a nature of <code>VIEW_MODEL</code>.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Application view model</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@ViewModel</span>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">Dashboard</span> { ... }</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Annotated with <a href="rgant.html#_rgant-ViewModel"><code>@ViewModel</code></a> annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Application view model</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <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">ExcelUploadManager</span> <span class="directive">implements</span> ViewModel {
<span class="directive">public</span> <span class="predefined-type">String</span> viewModelMemento() { ... }
<span class="directive">public</span> <span class="type">void</span> viewModelInit(<span class="predefined-type">String</span> memento) { ... }
-}</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Implement <a href="rgcms.html#_rgcms_classes_super_ViewModel"><code>ViewModel</code></a> interface. The memento is as defined by the
-interface’s methods: the programmer has full control (but also full responsibility) for the string memento.</p>
-</div></div></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>DTO</p>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlRootElement</span>(<span class="string"><span class="delimiter">"</span><span class="content">customer</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerDto</span> { ... }</code></pre>
-</div>
-</div></div></td>
-<td class="tableblock halign-left valign-top"><div><div class="paragraph">
-<p>Annotate using JAXB <a href="rgant.html#<em>rgant-XmlRootElement"><code>@XmlRootElement</code></a> annotation. Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike <code>@ViewModel</code>
-et al) this state _can</em> include collections.</p>
-</div></div></td>
-</tr>
-</tbody>
-</table>
-<div class="paragraph">
-<p>JAXB-annotated DTOs are discussed in more detail immediately <a href="rg.html#_ugbtb_view-models_jaxb">below</a>.</p>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugbtb_view-models_jaxb">2.3. JAXB-annotated DTOs</h3>
-<div class="paragraph">
-<p>As noted in the <a href="#_ugbtb_view-models_use-cases">introduction</a>, view models can also be defined using JAXB annotations.
-The serialized form of these view models is therefore XML, which also enables these view models
-to act as DTOs.</p>
-</div>
-<div class="paragraph">
-<p>In case it’s not obvious, these DTOs are still usable as "regular" view models; they will render in the <a href="ugvw.html">Wicket viewer</a> just like any other.
-In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>their entire state (collections as well as properties) is automatically managed from interaction to interaction.<br></p>
-<div class="paragraph">
-<p>In contrast, using <a href="rgant.html#_rgant-ViewModel"><code>@ViewModel</code></a> (or its <a href="rgant.html#_rgant-DomainObject_nature"><code>@DomainObject#nature()</code></a> equivalent) will only manage the state of properties, but not collections.
-And if using the <a href="rgcms.html#_rgcms_classes_super_ViewModel"><code>ViewModel</code></a> interface, then the programmer must write all the state management (lots of boilerplate).</p>
-</div>
-</li>
-<li>
-<p>JAXB-annotated view models are editable.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The examples in this section uses the DTO for <code>ToDoItem</code>, taken from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>.
-This DTO is defined as follows:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>; <i class="conum" data-value="1"></i><b>(1)</b>
-<span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>) <i class="conum" data-value="2"></i><b>(2)</b>
+}</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Implement <a href="rgcms.html#_rgcms_classes_super_ViewModel"><code>ViewModel</code></a> interface. The memento is as defined by the interface\u2019s methods: the programmer has full control (but also full responsibility) for the string memento.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>DTO</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlRootElement</span>(<span class="string"><span class="delimiter">"</span><span class="content">customer</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">CustomerDto</span> { ... }</code></pre>
+ </div>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Annotate using JAXB <a href="rgant.html#<em>rgant-XmlRootElement"><code>@XmlRootElement</code></a> annotation. Memento derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike <code>@ViewModel</code> et al) this state _can include collections.</p>
+ </div>
+ </div></td>
+ </tr>
+ </tbody>
+ </table>
+ <div class="paragraph">
+ <p>JAXB-annotated DTOs are discussed in more detail immediately <a href="rg.html#_ugbtb_view-models_jaxb">below</a>.</p>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugbtb_view-models_jaxb">2.3. JAXB-annotated DTOs</h3>
+ <div class="paragraph">
+ <p>As noted in the <a href="#_ugbtb_view-models_use-cases">introduction</a>, view models can also be defined using JAXB annotations. The serialized form of these view models is therefore XML, which also enables these view models to act as DTOs.</p>
+ </div>
+ <div class="paragraph">
+ <p>In case it\u2019s not obvious, these DTOs are still usable as "regular" view models; they will render in the <a href="ugvw.html">Wicket viewer</a> just like any other. In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>their entire state (collections as well as properties) is automatically managed from interaction to interaction.<br></p>
+ <div class="paragraph">
+ <p>In contrast, using <a href="rgant.html#_rgant-ViewModel"><code>@ViewModel</code></a> (or its <a href="rgant.html#_rgant-DomainObject_nature"><code>@DomainObject#nature()</code></a> equivalent) will only manage the state of properties, but not collections. And if using the <a href="rgcms.html#_rgcms_classes_super_ViewModel"><code>ViewModel</code></a> interface, then the programmer must write all the state management (lots of boilerplate).</p>
+ </div> </li>
+ <li> <p>JAXB-annotated view models are editable.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The examples in this section uses the DTO for <code>ToDoItem</code>, taken from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>. This DTO is defined as follows:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>; <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>) <i class="conum" data-value="2"></i><b>(2)</b>
<span class="annotation">@XmlType</span>(
propOrder = { <i class="conum" data-value="3"></i><b>(3)</b>
- <span class="string"><span class="delimiter">"</span><span class="content">majorVersion</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">minorVersion</span><span class="delimiter">"</span></span>,
- <span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">category</span><span class="delimiter">"</span></span>, ...
- <span class="string"><span class="delimiter">"</span><span class="content">toDoItem</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">similarItems</span><span class="delimiter">"</span></span>
+ <span class="string"><span class="delimiter">"</span><span class="content">majorVersion</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">minorVersion</span><span class="delimiter">"</span></span>,
+ <span class="string"><span class="delimiter">"</span><span class="content">description</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">category</span><span class="delimiter">"</span></span>, ...
+ <span class="string"><span class="delimiter">"</span><span class="content">toDoItem</span><span class="delimiter">"</span></span>, <span class="string"><span class="delimiter">"</span><span class="content">similarItems</span><span class="delimiter">"</span></span>
}
)
<span class="annotation">@DomainObjectLayout</span>(
titleUiEvent = TitleUiEvent.Doop.class <i class="conum" data-value="4"></i><b>(4)</b>
)
<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemV1_1</span> <span class="directive">implements</span> Dto { <i class="conum" data-value="5"></i><b>(5)</b>
- <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>, defaultValue = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) <i class="conum" data-value="6"></i><b>(6)</b>
- <span class="directive">public</span> <span class="directive">final</span> <span class="predefined-type">String</span> getMajorVersion() { <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>; }
- <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>, defaultValue = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) <i class="conum" data-value="7"></i><b>(7)</b>
- <span class="directive">public</span> <span class="predefined-type">String</span> getMinorVersion() { <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>; }
+ <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>, defaultValue = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) <i class="conum" data-value="6"></i><b>(6)</b>
+ <span class="directive">public</span> <span class="directive">final</span> <span class="predefined-type">String</span> getMajorVersion() { <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>; }
+ <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>, defaultValue = <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>) <i class="conum" data-value="7"></i><b>(7)</b>
+ <span class="directive">public</span> <span class="predefined-type">String</span> getMinorVersion() { <span class="keyword">return</span> <span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>; }
<span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>) <i class="conum" data-value="8"></i><b>(8)</b>
<span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
@@ -979,320 +879,295 @@ This DTO is defined as follows:</p>
<span class="annotation">@Getter</span> <span class="annotation">@Setter</span> <i class="conum" data-value="9"></i><b>(9)</b>
<span class="directive">protected</span> ToDoItem toDoItem;
<span class="annotation">@XmlElementWrapper</span> <i class="conum" data-value="10"></i><b>(10)</b>
- <span class="annotation">@XmlElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">todoItem</span><span class="delimiter">"</span></span>)
+ <span class="annotation">@XmlElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">todoItem</span><span class="delimiter">"</span></span>)
<span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
<span class="directive">protected</span> <span class="predefined-type">List</span><ToDoItem> similarItems = Lists.newArrayList();
-}</code></pre>
-</div>
-</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>package name encodes major version; see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>identifies this class as a view model and defines the root element for JAXB serialization</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>all properties in the class must be listed; (they can be ignored using <code>@XmlTransient</code>)</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>demonstrating use of UI events for a subscriber to provide the DTO’s title; see <a href="rgant.html#_rgant-DomainObjectLayout_titleUiEvent"><code>@DomainObjectLayout#titleUiEvent()</code></a>.</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>class name encodes (major and) minor version; see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="6"></i><b>6</b></td>
-<td>again, see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="7"></i><b>7</b></td>
-<td>again, see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="8"></i><b>8</b></td>
-<td>simple scalar properties</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="9"></i><b>9</b></td>
-<td>reference to a persistent entity; discussed <a href="#_ugbtb_view-models_jaxb_referencing-domain-entities">below</a></td>
-</tr>
-<tr>
-<td><i class="conum" data-value="10"></i><b>10</b></td>
-<td>reference to a collection of persistent entities; again discussed <a href="#_ugbtb_view-models_jaxb_referencing-domain-entities">below</a></td>
-</tr>
-</table>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_jaxb_referencing-domain-entities">2.3.1. Referencing Domain Entities</h4>
-<div class="paragraph">
-<p>It’s quite common for view models to be "backed by" (be projections of) some underlying domain entity.
-The <code>ToDoItemDto</code> we’ve been using as the example in this section is an example: there is an underlying <code>ToDoItem</code> entity.</p>
-</div>
-<div class="paragraph">
-<p>It wouldn’t make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity’s structure) don’t leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the <a href="rgcms.html#_rgcms_schema-common">Common schema</a> which defines the <code><oid-dto></code> element (and corresponding <code>OidDto</code> class): the object’s type and its identifier.
-This is basically a formal XML equivalent to the <code>Bookmark</code> object obtained from the <a href="rgsvc.html#_rgsvc_api_BookmarkService"><code>BookmarkService</code></a>.</p>
-</div>
-<div class="paragraph">
-<p>There is only one requirement to make this work: every referenced domain entity must be annotated with <a href="rgant.html#_rgant-XmlJavaTypeAdapter"><code>@XmlJavaTypeAdapter</code></a>, specifying the framework-provided <code>PersistentEntityAdapter.class</code>.
-This class is similar to the <code>BookmarkService</code>: it knows how to create an <code>OidDto</code> from an object reference.</p>
-</div>
-<div class="paragraph">
-<p>Thus, in our view model we can legitimately write:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>;
+}</code></pre>
+ </div>
+ </div>
+ <div class="colist arabic">
+ <table>
+ <tbody>
+ <tr>
+ <td><i class="conum" data-value="1"></i><b>1</b></td>
+ <td>package name encodes major version; see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="2"></i><b>2</b></td>
+ <td>identifies this class as a view model and defines the root element for JAXB serialization</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="3"></i><b>3</b></td>
+ <td>all properties in the class must be listed; (they can be ignored using <code>@XmlTransient</code>)</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="4"></i><b>4</b></td>
+ <td>demonstrating use of UI events for a subscriber to provide the DTO\u2019s title; see <a href="rgant.html#_rgant-DomainObjectLayout_titleUiEvent"><code>@DomainObjectLayout#titleUiEvent()</code></a>.</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="5"></i><b>5</b></td>
+ <td>class name encodes (major and) minor version; see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="6"></i><b>6</b></td>
+ <td>again, see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="7"></i><b>7</b></td>
+ <td>again, see discussion on <a href="#_ugbtb_view-models_jaxb_versioning">versioning</a></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="8"></i><b>8</b></td>
+ <td>simple scalar properties</td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="9"></i><b>9</b></td>
+ <td>reference to a persistent entity; discussed <a href="#_ugbtb_view-models_jaxb_referencing-domain-entities">below</a></td>
+ </tr>
+ <tr>
+ <td><i class="conum" data-value="10"></i><b>10</b></td>
+ <td>reference to a collection of persistent entities; again discussed <a href="#_ugbtb_view-models_jaxb_referencing-domain-entities">below</a></td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_jaxb_referencing-domain-entities">2.3.1. Referencing Domain Entities</h4>
+ <div class="paragraph">
+ <p>It\u2019s quite common for view models to be "backed by" (be projections of) some underlying domain entity. The <code>ToDoItemDto</code> we\u2019ve been using as the example in this section is an example: there is an underlying <code>ToDoItem</code> entity.</p>
+ </div>
+ <div class="paragraph">
+ <p>It wouldn\u2019t make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity\u2019s structure) don\u2019t leak out to the consumer. However, the identity of the underlying entity can be well defined; Apache Isis defines the <a href="rgcms.html#_rgcms_schema-common">Common schema</a> which defines the <code><oid-dto></code> element (and corresponding <code>OidDto</code> class): the object\u2019s type and its identifier. This is basically a formal XML equivalent to the <code>Bookmark</code> object obtained from the <a href="rgsvc.html#_rgsvc_api_BookmarkService"><code>BookmarkService</code></a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>There is only one requirement to make this work: every referenced domain entity must be annotated with <a href="rgant.html#_rgant-XmlJavaTypeAdapter"><code>@XmlJavaTypeAdapter</code></a>, specifying the framework-provided <code>PersistentEntityAdapter.class</code>. This class is similar to the <code>BookmarkService</code>: it knows how to create an <code>OidDto</code> from an object reference.</p>
+ </div>
+ <div class="paragraph">
+ <p>Thus, in our view model we can legitimately write:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>;
...
public <span class="type">class</span> <span class="class">ToDoItemV1_1</span> <span class="directive">implements</span> Dto {
...
<span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
<span class="directive">protected</span> ToDoItem toDoItem;
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>All we need to do is remember to add that <code>@XmlJavaTypeAdapter</code> annotation to the referenced entity:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlJavaTypeAdapter</span>(PersistentEntityAdapter.class)
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>All we need to do is remember to add that <code>@XmlJavaTypeAdapter</code> annotation to the referenced entity:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlJavaTypeAdapter</span>(PersistentEntityAdapter.class)
<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItem</span> ... {
...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>It’s also possible for a DTO to hold collections of objects.
-These can be of any type, either simple properties, or references to other objects.
-The only bit of boilerplate that is required is the <code>@XmlElementWrapper</code> annotation.
-This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
-(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).</p>
-</div>
-<div class="paragraph">
-<p>For example, the DTO also contains:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>;
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>It\u2019s also possible for a DTO to hold collections of objects. These can be of any type, either simple properties, or references to other objects. The only bit of boilerplate that is required is the <code>@XmlElementWrapper</code> annotation. This instructs JAXB to create an XML element (based on the field name) to contain each of the elements. (If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).</p>
+ </div>
+ <div class="paragraph">
+ <p>For example, the DTO also contains:</p>
+ </div>
+ <div class="listingblock">
+ <div class="content">
+ <pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1</span>;
...
public <span class="type">class</span> <span class="class">ToDoItemV1_1</span> <span class="directive">implements</span> Dto {
...
<span class="annotation">@XmlElementWrapper</span>
- <span class="annotation">@XmlElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">todoItem</span><span class="delimiter">"</span></span>)
+ <span class="annotation">@XmlElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">todoItem</span><span class="delimiter">"</span></span>)
<span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
<span class="directive">protected</span> <span class="predefined-type">List</span><ToDoItem> similarItems = Lists.newArrayList();
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>There’s nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO’s memento, ultimately converted into a URL-safe form, by way of the <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a>.</p>
-</div>
-<div class="paragraph">
-<p>There are limits to the lengths of URLs, however.
-Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a> to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ugbtb_view-models_jaxb_versioning">2.3.2. Versioning</h4>
-<div class="paragraph">
-<p>The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
-Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
-This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.</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>There are several ways that versioning might be accomplished; we base our guidelines on this <a href="http://www.xfront.com/Versioning.pdf">article</a> taken from Roger Costello’s blog, well worth a read.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>We can distinguish two types of changes:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>backwardly compatible changes</p>
-</li>
-<li>
-<p>breaking changes.</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following <a href="http://semver.org">semantic versioning</a> that means when we bump the major version number v1, v2, etc.</p>
-</div>
-<div class="paragraph">
-<p>XML namespaces correspond (when using JAXB) to Java packages.
-We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
-The package should also have a <code>package-info.java</code>; it is this that declares the XSD namespace:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.xml.bind.annotation.XmlSchema(
- namespace = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
+}</code></pre>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>There\u2019s nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children. Be aware though that all of this state will become the DTO\u2019s memento, ultimately converted into a URL-safe form, by way of the <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>There are limits to the lengths of URLs, however. Therefore the DTO should not include state that can easily be derived from other information. If the URL does exceed limits, then provide a custom implementation of <a href="rgsvc.html#_rgsvc_spi_UrlEncodingService"><code>UrlEncodingService</code></a> to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugbtb_view-models_jaxb_versioning">2.3.2. Versioning</h4>
+ <div class="paragraph">
+ <p>The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications. Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go. This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.</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>There are several ways that versioning might be accomplished; we base our guidelines on this <a href="http://www.xfront.com/Versioning.pdf">ar
<TRUNCATED>