You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/12/22 23:40:47 UTC
[2/3] isis-site git commit: ISIS-1243: reworking the ugbtb (beyond
the basics) guide a little, breaking out and renaming the techniques chapter
http://git-wip-us.apache.org/repos/asf/isis-site/blob/2f52444a/content/guides/ugbtb.html
----------------------------------------------------------------------
diff --git a/content/guides/ugbtb.html b/content/guides/ugbtb.html
index c5e4d2b..3e9aed2 100644
--- a/content/guides/ugbtb.html
+++ b/content/guides/ugbtb.html
@@ -506,7 +506,7 @@ table.CodeRay td.code>pre{padding:0}
<h2 id="_ugbtb">1. Beyond the Basics</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>This guide provides <a href="#_ugbtb_more-advanced">more advanced</a> guidance on writing maintainable larger
+<p>This guide provides <a href="#_ugbtb_other-techniques">more advanced</a> guidance on writing maintainable larger
applications.</p>
</div>
<div class="paragraph">
@@ -568,22 +568,40 @@ applications.</p>
</div>
</div>
<div class="sect1">
-<h2 id="_ugbtb_more-advanced">2. Techniques</h2>
+<h2 id="_ugbtb_view-models">2. View Models</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>This chapter pulls together a number of more advanced techniques that we’ve discovered and developed while building our own Isis applications.</p>
+<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_more-advanced_decoupling">2.1. Decoupling</h3>
+<h3 id="_ugbtb_view-models_use-cases">2.1. Use Cases</h3>
<div class="paragraph">
-<p>We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then
-reason about all the classes in that package/namespace as a single unit, or module.</p>
+<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="_externally_managed_entities">2.1.1. Externally-managed entities</h4>
<div class="paragraph">
-<p>This section describes how to use Apache Isis' features to ensure that your domain application remains decoupled. The techniques described here are also the ones that have been adopted by the various <a href="http://github.com/isisaddons">Isis Addons</a> modules (not ASF) for security, commands, auditing etc.</p>
+<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>The following sections describe how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules).</p>
+<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>
@@ -593,235 +611,329 @@ reason about all the classes in that package/namespace as a single unit, or modu
</td>
<td class="content">
<div class="paragraph">
-<p>There is some overlap with OSGi and Java 9’s Jigsaw concepts of "module"; in the future we expect to refactor Apache Isis to leverage these module systems.</p>
+<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_more-advanced_decoupling_db-schemas">2.1.1. Database Schemas</h4>
+<h4 id="_in_memory_entities">2.1.2. In-memory entities</h4>
<div class="paragraph">
-<p>In the same way that Java packages act as a namespace for domain objects, it’s good practice to map domain entities to
-their own (database) schemas. As of 1.9.0, all the <a href="http://www.isisaddons.org">Isis Addons</a> (non-ASF) modules do this, for example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable( ...
- schema = <span class="string"><span class="delimiter">"</span><span class="content">isissecurity</span><span class="delimiter">"</span></span>,
- table = <span class="string"><span class="delimiter">"</span><span class="content">ApplicationUser</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">ApplicationUser</span> ... { ... }</code></pre>
-</div>
+<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>results in a <code>CREATE TABLE</code> statement of:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="sql"><span class="class">CREATE</span> <span class="type">TABLE</span> isissecurity.<span class="string"><span class="delimiter">"</span><span class="content">ApplicationUser</span><span class="delimiter">"</span></span> (
- ...
-)</code></pre>
+<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="_application_layer_view_models">2.1.3. Application-layer view models</h4>
<div class="paragraph">
-<p>while:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable( ...
- schema = <span class="string"><span class="delimiter">"</span><span class="content">isisaudit</span><span class="delimiter">"</span></span>,
- table=<span class="string"><span class="delimiter">"</span><span class="content">AuditEntry</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">AuditEntry</span> ... { ... }</code></pre>
-</div>
+<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>similarly results in:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="sql"><span class="class">CREATE</span> <span class="type">TABLE</span> isisaudit.<span class="string"><span class="delimiter">"</span><span class="content">AuditEntry</span><span class="delimiter">"</span></span> (
- ...
-)</code></pre>
-</div>
+<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="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
<div class="paragraph">
-<p>If for some reason you don’t want to use schemas (though we strongly recommend that you do), then note that you can override the <code>@PersistenceCapable</code> annotation by providing XML metadata (the <code>mappings.jdo</code> file); see the section on <a href="rgcfg.html#_rgcfg_configuring-datanucleus">configuring DataNucleus Overriding Annotations</a> for more details.</p>
-</div>
-</td>
-</tr>
-</table>
+<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="sect4">
-<h5 id="_listener_to_create_schema">Listener to create schema</h5>
<div class="paragraph">
-<p>JDO/DataNucleus does not automatically create these schema objects, but it <em>does</em> provide a listener callback API
-on the initialization of each class into the JDO metamodel.</p>
+<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="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
<div class="paragraph">
-<p>Actually, the above statement isn’t quite true. In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas. As of Apache Isis 1.9.0 and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we’ve decided to leave it in.</p>
-</div>
-</td>
-</tr>
-</table>
+<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>Therefore Apache Isis attaches a listener, <code>CreateSchemaObjectFromClassMetadata</code>, that checks for the schema’s existence, and creates the schema if required.</p>
+<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>The guts of its implementation is:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CreateSchemaObjectFromClassMetadata</span>
- <span class="directive">implements</span> MetaDataListener,
- DataNucleusPropertiesAware {
- <span class="annotation">@Override</span>
- <span class="directive">public</span> <span class="type">void</span> loaded(<span class="directive">final</span> AbstractClassMetaData cmd) { ... }
-
- <span class="directive">protected</span> <span class="predefined-type">String</span> buildSqlToCheck(<span class="directive">final</span> AbstractClassMetaData cmd) {
- <span class="directive">final</span> <span class="predefined-type">String</span> schemaName = schemaNameFor(cmd);
- <span class="keyword">return</span> <span class="predefined-type">String</span>.format(
- <span class="string"><span class="delimiter">"</span><span class="content">SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'</span><span class="delimiter">"</span></span>, schemaName);
- }
- <span class="directive">protected</span> <span class="predefined-type">String</span> buildSqlToExec(<span class="directive">final</span> AbstractClassMetaData cmd) {
- <span class="directive">final</span> <span class="predefined-type">String</span> schemaName = schemaNameFor(cmd);
- <span class="keyword">return</span> <span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">"</span><span class="content">CREATE SCHEMA </span><span class="char">\"</span><span class="content">%s</span><span class="char">\"</span><span class="delimiter">"</span></span>, schemaName);
- }
-}</code></pre>
-</div>
+<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>where <code>MetaDataListener</code> is the DataNucleus listener API:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">MetaDataListener</span> {
- <span class="type">void</span> loaded(AbstractClassMetaData cmd);
-}</code></pre>
-</div>
+<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>Although not formal API, the default <code>CreateSchemaObjectFromClassMetadata</code> has been designed to be easily overrideable if you
-need to tweak it to support other RDBMS'. Any implementation must implement <code>org.datanucleus.metadata.MetaDataListener</code>:</p>
+<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>The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).</p>
-</div>
+<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 class="sect4">
-<h5 id="_alternative_implementation">Alternative implementation</h5>
-<div class="paragraph">
-<p>An alternative implementation can be registered and used through the following configuration property:</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="ini">isis.persistor.datanucleus.classMetadataLoadedListener=\
- org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata</code></pre>
</div>
</div>
+<div class="sect3">
+<h4 id="_dtos_code_1_11_0_snapshot_code">2.1.4. DTOs (<code>1.11.0-SNAPSHOT</code>)</h4>
<div class="paragraph">
-<p>Because this pertains to the JDO Objectstore we suggest you put this configuration property in <code>WEB-INF/persistor_datanucleus.properties</code>; but putting it in <code>isis.properties</code> will also work.</p>
+<p>DTOs (data transfer objects) are simple classes that (according to <a href="https://en.wikipedia.org/wiki/Data_transfer_object">wikipedia</a>) "carries data between processes".</p>
</div>
<div class="paragraph">
-<p>Any implementation must implement <code>org.datanucleus.metadata.MetaDataListener</code>. In many cases simply subclassing from <code>CreateSchemaObjectFromClassMetadata</code> and overriding <code>buildSqlToCheck(…​)</code> and <code>buildSqlToExec(…​)</code> should suffice.</p>
+<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>If you <em>do</em> need more control, your implementation can also optionally implement <code>org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware</code>:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">DataNucleusPropertiesAware</span> {
- <span class="directive">public</span> <span class="type">void</span> setDataNucleusProperties(<span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> properties);
-}</code></pre>
-</div>
+<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>This provides access to the properties passed through to JDO/DataNucleus.</p>
+<p>Instead, a view model can be defined to act as a DTO. To put this formal contract onto a solid footing, this view
+model can (as of <code>1.11.0-SNAPSHOT</code>) simply be defined as a JAXB-annotated entity; this allows the consumer to obtain
+the DTO in XML format along with a corresponding XSD schema describing the structure of that XML. These XML
+representations can be surfaced by the <a href="ugvro.html">RestfulObjects viewer</a> (by implementing
+the <a href="rgsvc.html#_rgsvc_spi_ContentMappingService"><code>ContentMappingService</code></a>); the XSD can be obtained
+using the <a href="rgsvc.html#_rgsvc_api_JaxbService"><code>JaxbService</code></a>. Using the formalism of XML also allows
+DTOs to be carefully and properly versioned using XML namespaces.</p>
</div>
-<div class="admonitionblock important">
+<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
-<i class="fa icon-important" title="Important"></i>
+<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>If you do extend Apache Isis' <code>CreateSchemaObjectFromClassMetadata</code> class for some other database, please <a href="https://issues.apache.org/jira/browse/ISIS">contribute back</a> your improvements.</p>
+<p>If the view model DTO implements the <a href="rgcms.html#_rgcms_classes_mixins_Dto"><code>Dto</code></a> marker interface, then the framework
+will also provide the ability to download the XML or its XSD directly from the UI.</p>
</div>
</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>In case it’s not clear, 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. Indeed (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 view model alternatives.</p>
</div>
</div>
<div class="sect3">
-<h4 id="_ugbtb_more-advanced_decoupling_mixins">2.1.2. Mixins</h4>
+<h4 id="_esb_subscribers">2.1.5. ESB Subscribers</h4>
<div class="paragraph">
-<p>A mixin object allows one class to contribute behaviour - actions, (derived) properties and
-(derived) collections - to another domain object, either a domain entity or view model.</p>
+<p>One important variation of the DTO use case concerns subscribers on an enterprise event bus such as
+<a href="http://camel.apache.org">Apache Camel™</a> and similar.</p>
</div>
<div class="paragraph">
-<p>Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own
-syntax for defining such constructs. In Apache Isis a mixin is very similar to a domain service, however it also
-defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.</p>
+<p>A <a href="rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a> implementation (eg that provided by
+(non-ASF) <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> module) can publish XML events
+onto a message queue, typically representing action invocations within the originating Isis application. The ESB
+(Apache Camel) then dispatches this event to all interested subscribers. These subscribers represent external systems
+in the enterprise, managed by other teams, and so act as the third-party consumers of the data.</p>
</div>
<div class="paragraph">
-<p>Why do this? The main reason is to allow the app to be decoupled, so that it doesn’t degrade into the proverbial
-<a href="http://www.laputan.org/mud/mud.html#BigBallOfMud">"big ball of mud"</a>. Mixins (and contributions) allow dependency
-to be inverted, so that the dependencies between modules can be kept acyclic and under control.</p>
+<p>Rather than try to anticipate their requirements and push the data that these subscribers might need into the original
+XML event (a hopeless task), DTO objects can be defined to allow these consumers to call back to the publishing Isis
+application to obtain the data they need.</p>
</div>
-<div class="sect4">
-<h5 id="_example">Example</h5>
-<div class="paragraph">
-<p>This is probably best explained by way of an example. Suppose we have the <code>Customer</code> domain object which implements
-a <code>DocumentHolder</code> interface:</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> <span class="directive">implements</span> DocumentHolder {
- ...
-}</code></pre>
</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>We could then imagine a mixin that would contribute behaviour to list, add and remove the <code>Document</code>s for this holder:</p>
+<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>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span> <i class="conum" data-value="1"></i><b>(1)</b>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentHolder_documents</span> {
- <span class="directive">private</span> <span class="directive">final</span> DocumentHolder holder;
- <span class="directive">public</span> DocumentHolder_documents(DocumentHolder holder) { <i class="conum" data-value="2"></i><b>(2)</b>
- <span class="local-variable">this</span>.holder = holder;
- }
- <span class="annotation">@Action</span>(semantics=SemanticsOf.SAFE)
- <span class="annotation">@ActionLayout</span>(contributed = Contributed.AS_ASSOCIATION)
- <span class="annotation">@CollectionLayout</span>(render = RenderType.EAGERLY)
- <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Document</span>> documents() {
- ... <i class="conum" data-value="3"></i><b>(3)</b>
- }
- <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
- <span class="directive">public</span> DocumentHolder add(<span class="predefined-type">Document</span> document) {
- ... <i class="conum" data-value="4"></i><b>(4)</b>
- }
- <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
- <span class="directive">public</span> DocumentHolder remove(<span class="predefined-type">Document</span> document) {
- ... <i class="conum" data-value="5"></i><b>(5)</b>
- }
+<table class="tableblock frame-all grid-all spread">
+<caption class="title">Table 1. View model programming model</caption>
+<colgroup>
+<col style="width: 14%;">
+<col style="width: 57%;">
+<col style="width: 28%;">
+</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 (<code>1.11.0-SNAPSHOT</code>)</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 (<code>1.11.0-SNAPSHOT</code>)</h3>
+<div class="paragraph">
+<p>This section provides some recommended practices if using JAXB and <code>@XmlRootElement</code> to define domain models. The
+examples are taken from the (non-ASF) <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a>.</p>
+</div>
+<div class="sect3">
+<h4 id="_ugbtb_view-models_jaxb_using-packages-to-version">2.3.1. Use packages to version DTOs</h4>
+<div class="paragraph">
+<p>The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two interoperating 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.</p>
+</div>
+<div class="paragraph">
+<p>With XML every element may be defined as belonging to a particular namespace; in JAXB this translates to Java packages.
+We therefore should place each DTO within its own package, and that package should include a version identifier.</p>
+</div>
+<div class="paragraph">
+<p>For example, the <a href="http://github.com/isisaddons/isis-app-todoapp">Isis addons' todoapp</a> defines this DTO (as a versioned
+representation of its underlying <code>ToDoItem</code> entity):</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>) <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="annotation">@XmlType</span>(
+ propOrder = { <i class="conum" data-value="2"></i><b>(2)</b>
+ <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">subcategory</span><span class="delimiter">"</span></span>,
+ <span class="string"><span class="delimiter">"</span><span class="content">cost</span><span class="delimiter">"</span></span>
+ }
+)
+<span class="annotation">@DomainObjectLayout</span>(
+ titleUiEvent = TitleUiEvent.Doop.class <i class="conum" data-value="3"></i><b>(3)</b>
+)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> <span class="directive">implements</span> Dto {
+ <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>)
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span> <i class="conum" data-value="4"></i><b>(4)</b>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> description;
+
+ <span class="annotation">@XmlElement</span>(required = <span class="predefined-constant">true</span>)
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> category;
+
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">String</span> subcategory;
+
+ <span class="annotation">@Getter</span> <span class="annotation">@Setter</span>
+ <span class="directive">protected</span> <span class="predefined-type">BigDecimal</span> cost;
}</code></pre>
</div>
</div>
@@ -829,203 +941,251 @@ a <code>DocumentHolder</code> interface:</p>
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>alternatively can use <code>@DomainObject(nature=Nature.MIXIN)</code></td>
+<td>identifies this class as a view model and defines the root element for JAXB serialization</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>constructor indicates the type that is contributed to</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="3"></i><b>3</b></td>
-<td>implementation could, for example, use the (non-ASF)
-<a href="http://github.com/isisaddons/isis-module-poly">Isis addons' poly</a> module.</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="4"></i><b>4</b></td>
-<td>implementation would probably delegate to an injected repository to (ultimately) insert data into some table</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="5"></i><b>5</b></td>
-<td>implementation would probably delegate to an injected repository to (ultimately) delete data from some table</td>
+<td>optional; JAXB metadata can specify such attributes as required/optional</td>
</tr>
</table>
</div>
<div class="paragraph">
-<p>The above example also omits any supporting methods, eg <code>hideXxx()</code>, <code>disableXxx()</code>, <code>validateXxx()</code>, etc.</p>
+<p>For the package in which the DTO class resides, we define a corresponding namespace. This goes in <code>package-info.java</code>:</p>
</div>
-<div class="paragraph">
-<p>In the user interface the "documents" collection, the "add" and the "delete" actions will appear to be part of
-<code>Customer</code>. In essence the framework constructs a composite UI from the parts of multiple objects.</p>
+<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_0/todoitem.xsd</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
+ elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+<span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_0</span>; <i class="conum" data-value="2"></i><b>(2)</b></code></pre>
</div>
-<div class="admonitionblock tip">
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<p>The (non-ASF) <a href="http://github.com/incodehq/incode-module-note">Incode note</a> and
-<a href="http://github.com/incodehq/incode-module-commchannel">Incode commchannel</a> modules are real-world examples that use this
-technique throughout.</p>
-</div>
-</td>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>the namespace URI, used by the DTO residing in this package. There is no requirement for this to correspond to a physical URL, but it should be unique (this
+usually implies the usage of a company domain name).</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>the package in which the DTO resides.</td>
</tr>
</table>
</div>
+<div class="paragraph">
+<p>Note how both the XML namespace and package are broadly equivalent to each other; in particular note that they both
+also include a version "v1_0".</p>
</div>
-<div class="sect4">
-<h5 id="_contributing_a_single_member">Contributing a single member</h5>
+</div>
+<div class="sect3">
+<h4 id="_ugbtb_view-models_jaxb_semantic-versioning">2.3.2. Semantic Versioning</h4>
<div class="paragraph">
-<p>The mixin can contribute as much or as little behaviour as makes sense. For example, in the example above it might be
-that <code>Document</code>s are created through some other mechanism (eg scanned) and are never deleted. In that case, the
-mixin might be simply:</p>
+<p>Versioning DTOs enables us to make changes without breaking existing consumers of the data. We can distinguish two
+types of changes:</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentHolder_documents</span> {
- ..
- public <span class="predefined-type">List</span><<span class="predefined-type">Document</span>> documents() { ... }
- ...
-}</code></pre>
+<div class="ulist">
+<ul>
+<li>
+<p>backwardly compatible changes</p>
+</li>
+<li>
+<p>breaking changes.</p>
+</li>
+</ul>
</div>
+<div class="paragraph">
+<p>Following <a href="http://semver.org">semantic versioning</a> approach, we suggest using <code>v1_0</code>, <code>v1_1</code>, <code>v1_2</code> etc as the
+package version for a sequence of backwardly compatible changes, then bump up to <code>v2_0</code> for a breaking change.</p>
</div>
<div class="paragraph">
-<p>For the case where there is only a single member being contributed, the special name "__" (that is, two underscores)
-can be used instead. In this case, the contributee member’s name will be inferred from the mixin’s class name. If the
-class name itself contains an underscore, then the last part of the class name will be used.</p>
+<p>Backwardly compatible changes can generally (always?) be modelled using class inheritance. Thus, <code>v1_1.ToDoItemDto</code>
+is a subclass of <code>v1_0.ToDoItemDto</code>. This makes sense too: OO inheritance means "is-substitutable-for", so what is
+true in an OO context is true when processing XML documents.</p>
</div>
<div class="paragraph">
-<p>Thus, for a mixin whose class name is <code>DocumentHolder_documents</code>, the effective member name is <code>documents</code>. We could
-therefore rewrite the mixin as:</p>
+<p>On the other hand, breaking changes probably (always?) imply that the next version of the DTO does not use inheritance.
+Thus <code>v2_0.ToDoItemDto</code> might share many of the same properties as the <code>v1_1.ToDoItemDto</code>, but any reuse would be
+copy-n-paste rather than through inheritance.</p>
+</div>
+<div class="paragraph">
+<p>To see this in practice, here’s (the outline of) v1.1 of <code>ToDoItemDto</code>:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentHolder_documents</span> {
- ..
- public <span class="predefined-type">List</span><<span class="predefined-type">Document</span>> __() { ... }
+<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_1</span>;
+...
+<span class="annotation">@XmlRootElement</span>(name = <span class="string"><span class="delimiter">"</span><span class="content">toDoItemDto</span><span class="delimiter">"</span></span>)
+<span class="annotation">@XmlType</span>(
+ propOrder = {
+ <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="directive">public</span> <span class="type">class</span> <span class="class">ToDoItemDto</span> <span class="directive">extends</span> todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
...
}</code></pre>
</div>
</div>
<div class="paragraph">
-<p>The benefit of this is marginal unless there are supporting methods, in which case the removal of boilerplate is welcome:</p>
+<p>The corresponding <code>package-info.java</code> is similar to that for <code>v1_0</code>, though note how it also defines a namespace prefix
+for <code>v1_0</code>:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span>
-<span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentHolder_documents</span> {
- ..
- public <span class="predefined-type">List</span><<span class="predefined-type">Document</span>> __() { ... }
- <span class="directive">public</span> <span class="type">boolean</span> hide__() { ... }
- <span class="directive">public</span> <span class="predefined-type">String</span> disable__() { ... }
- ...
-}</code></pre>
+<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_1/todoitem.xsd</span><span class="delimiter">"</span></span>, <i class="conum" data-value="1"></i><b>(1)</b>
+ xmlns = {
+ <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs( <i class="conum" data-value="2"></i><b>(2)</b>
+ namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://isis.apache.org/schema/common</span><span class="delimiter">"</span></span>,
+ prefix = <span class="string"><span class="delimiter">"</span><span class="content">common</span><span class="delimiter">"</span></span>
+ ),
+ <span class="annotation">@javax</span>.xml.bind.annotation.XmlNs(
+ namespaceURI = <span class="string"><span class="delimiter">"</span><span class="content">http://viewmodels.app.todoapp/todoitem/v1_0/todoitem.xsd</span><span class="delimiter">"</span></span>,
+ prefix = <span class="string"><span class="delimiter">"</span><span class="content">todoitem-v1_0</span><span class="delimiter">"</span></span>
+ )
+ },
+ elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
+)
+<span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_1</span>;</code></pre>
</div>
</div>
+<div class="colist arabic">
+<table>
+<tr>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>namespace URI for DTO in this class.</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="2"></i><b>2</b></td>
+<td>aliases for any other namespaces referenced.</td>
+</tr>
+</table>
+</div>
</div>
-<div class="sect4">
-<h5 id="_programmatic_usage">Programmatic usage</h5>
+<div class="sect3">
+<h4 id="_ugbtb_view-models_jaxb_referencing-domain-entities">2.3.3. Referencing Domain Entities</h4>
<div class="paragraph">
-<p>When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them
-dynamically. If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to
-instantiate mixins directly.</p>
+<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>For this you can use the
-xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[<code>DomainObjectContainer#mixin(…​)</code>
-method. For example:</p>
+<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">DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);</code></pre>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">package</span> <span class="namespace">todoapp.app.viewmodels.todoitem.v1_1</span>;
+...
+public <span class="type">class</span> <span class="class">ToDoItemDto</span> <span class="directive">extends</span> todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ <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>The <a href="ugtst.html#_ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract"><code>IntegrationTestAbstract</code></a> and
-<a href="rgcms.html#_rgcms_classes_super_FixtureScript"><code>FixtureScript</code></a> classes both provide a <code>mixin(…​)</code> convenience
-method.</p>
+<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 class="sect4">
-<h5 id="_other_reasons_to_use_mixins">Other reasons to use mixins</h5>
-<div class="paragraph">
-<p>In the introduction to this topic we mentioned that mixins are most useful for ensuring that the domain app remains
-decoupled. This applies to the case where the contributee (eg <code>Customer</code>, being mixed into) is in one module, while
-the contributor mixin (<code>DocumentHolder_documents</code>) is in some other module. The <code>customer</code> module knows about the
-<code>document</code> module, but not vice versa.</p>
</div>
-<div class="paragraph">
-<p>However, you might also want to consider moving behaviour out of entities even within the same module, perhaps even
-within the same Java package. And the reason for this is to support hot-reloading of Java classes, so that you can
-modify and recompile your application without having to restart it. This can provide substantial productivity gains.</p>
</div>
+<div class="sect3">
+<h4 id="_ugbtb_view-models_jaxb_collections">2.3.4. Collections</h4>
<div class="paragraph">
-<p>The Hotspot JVM has limited support for hot reloading; generally you can change method implementations but you cannot
-introduce new methods. However, the <a href="https://dcevm.github.io/">DCEVM</a> open source project will patch the JVM to
-support much more complete hot reloading support. There are also, of course, commercial products such as JRebel.</p>
+<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.</p>
</div>
<div class="paragraph">
-<p>The main snag in all this is the DataNucleus enhancer…​ any change to entities is going to require the entity to be
-re-enhanced, and the JDO metamodel recreated, which usually "stuffs things up". So hot-reloading of an app whose
-fundamental structure is changing is likely to remain a no-no.</p>
+<p>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>However, chances are that the structure of your domain objects (the data) will change much less rapidly than
-the behaviour of those domain objects. Thus, it’s the behaviour that you’re most likely wanting to change while the
-app is still running. If you move that behaviour out into mixins (or
-<a href="#_ugbtb_more-advanced_decoupling_contributions">contributed services</a>), then these can be reloaded happily.
-(When running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain
-object as it is rendered.</p>
-</div>
+<p>For example, the v1.1 of the <code>ToDoItemDto</code> could also contain:</p>
</div>
-<div class="sect4">
-<h5 id="_related_reading">Related reading</h5>
-<div class="paragraph">
-<p>Mixins are an implementation of the <a href="http://www.artima.com/articles/dci_vision.html">DCI architecture</a> architecture, as formulated and described by <a href="https://en.wikipedia.org/wiki/Trygve_Reenskaug">Trygve Reenskaug</a> and <a href="https://en.wikipedia.org/wiki/Jim_Coplien">Jim Coplien</a>. Reenskaug was the inventor of the MVC pattern (and also the external
-examiner for Richard Pawson’s PhD thesis), while Coplien has a long history in object-orientation, C++ and patterns.</p>
+<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_1</span>;
+...
+public <span class="type">class</span> <span class="class">ToDoItemDto</span> <span class="directive">extends</span> todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ <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">@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 class="paragraph">
-<p>DCI stands for Data-Context-Interaction and is presented as an evolution of object-oriented programming, but one where
-behaviour is bound to objects dynamically rather than statically in some context or other. The <code>@Mixin</code>
-pattern is Apache Isis' straightforward take on the same basic concept.</p>
</div>
<div class="paragraph">
-<p>You might also wish to check out <a href="http://zest.apache.org">Apache Zest</a> (formerly Qi4J), which implements a much more
-general purpose implementation of the same concepts.</p>
+<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 <code>UrlEncodingService</code>
+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_more-advanced_decoupling_contributions">2.1.3. Contributions</h4>
+<h4 id="_generating_xsds_and_dtos">2.3.5. Generating XSDs and DTOs</h4>
<div class="paragraph">
-<p>Contributed services provide many of the same benefits as <a href="#_ugbtb_more-advanced_decoupling_mixins">mixins</a>;
-indeed mixins are an evolution and refinement of the contributions concept.</p>
+<p>The <a href="cg.html#_cg_isis-maven-plugin">Apache Isis maven plugin</a> provides the <a href="cg.html#_cg_isis-maven-plugin_xsd">xsd</a> goal that allows the XSDs to be generated from any JAXB-annotated view models.
+These use the <a href="rgsvc.html#_rgsvc_api_JaxbService"><code>JaxbService</code></a> to generate the schemas; using the
+standard <code>schemagen</code> command line will not correctly interpret any references to domain entities as OIDs.</p>
</div>
<div class="paragraph">
-<p>The main difference between contributed services and mixins is that the actions of a contributed service will
-contribute to <em>all</em> the parameters of its actions, whereas a mixin only contributes to the type accepted in its
-constructor. Also, contributed services are long-lived
-singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.</p>
+<p>The documentation for the <code>xsd</code> goal also explains how to generate DTO classes from the generated XSDs. Note that these
+DTOs are not the same as the JAXB view models; they can be used outside of an Isis application, for example in a
+standalone subscriber running on an enterprise service bus such as Apache Camel.</p>
+</div>
+</div>
+</div>
</div>
+</div>
+<div class="sect1">
+<h2 id="_ugbtb_decoupling">3. Decoupling</h2>
+<div class="sectionbody">
<div class="paragraph">
-<p>For more on contributed services:</p>
+<p>We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then
+reason about all the classes in that package/namespace as a single unit, or module.</p>
</div>
-<div class="ulist">
-<ul>
-<li>
-<p>the syntax of writing contributed actions/properties/collections is described in this <a href="ugfun.html#_ugfun_how-tos_contributed-members">how-to</a></p>
-</li>
-<li>
-<p>there’s also useful information in the reference guide, discussing the <a href="rgant.html#_rgant-DomainService_nature">@DomainService#nature()</a> attribute, for the <code>NatureOfService.VIEW_CONTRIBUTIONS_ONLY</code> nature.</p>
-</li>
-</ul>
+<div class="paragraph">
+<p>This section describes how to use Apache Isis' features to ensure that your domain application remains decoupled. The techniques described here are also the ones that have been adopted by the various <a href="http://github.com/isisaddons">Isis Addons</a> modules (not ASF) for security, commands, auditing etc.</p>
</div>
+<div class="paragraph">
+<p>The following sections describe how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules).</p>
</div>
-<div class="sect3">
-<h4 id="_ugbtb_more-advanced_decoupling_vetoing-visibility">2.1.4. Vetoing Visibility</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -1033,189 +1193,236 @@ singletons, whereas mixins are instantiated as required (by the framework) and t
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO - a write-up of the "vetoing subscriber" design pattern, eg as described in the <a href="rgsvc.html#_rgsvc_api_BookmarkService"><code>BookmarkService</code></a>
+<div class="paragraph">
+<p>There is some overlap with OSGi and Java 9’s Jigsaw concepts of "module"; in the future we expect to refactor Apache Isis to leverage these module systems.</p>
+</div>
</td>
</tr>
</table>
</div>
+<div class="sect2">
+<h3 id="_ugbtb_decoupling_db-schemas">3.1. Database Schemas</h3>
<div class="paragraph">
-<p>eg if included an addon such as auditing or security.</p>
+<p>In the same way that Java packages act as a namespace for domain objects, it’s good practice to map domain entities to
+their own (database) schemas. As of 1.9.0, all the <a href="http://www.isisaddons.org">Isis Addons</a> (non-ASF) modules do this, for example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable( ...
+ schema = <span class="string"><span class="delimiter">"</span><span class="content">isissecurity</span><span class="delimiter">"</span></span>,
+ table = <span class="string"><span class="delimiter">"</span><span class="content">ApplicationUser</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">ApplicationUser</span> ... { ... }</code></pre>
+</div>
</div>
<div class="paragraph">
-<p>solution is to write a domain event subscriber that vetoes the visibility</p>
+<p>results in a <code>CREATE TABLE</code> statement of:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="sql"><span class="class">CREATE</span> <span class="type">TABLE</span> isissecurity.<span class="string"><span class="delimiter">"</span><span class="content">ApplicationUser</span><span class="delimiter">"</span></span> (
+ ...
+)</code></pre>
+</div>
</div>
<div class="paragraph">
-<p>All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required</p>
+<p>while:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable( ...
+ schema = <span class="string"><span class="delimiter">"</span><span class="content">isisaudit</span><span class="delimiter">"</span></span>,
+ table=<span class="string"><span class="delimiter">"</span><span class="content">AuditEntry</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">AuditEntry</span> ... { ... }</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_ugbtb_more-advanced_decoupling_event-bus">2.1.5. Event Bus</h4>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>similarly results in:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="sql"><span class="class">CREATE</span> <span class="type">TABLE</span> isisaudit.<span class="string"><span class="delimiter">"</span><span class="content">AuditEntry</span><span class="delimiter">"</span></span> (
+ ...
+)</code></pre>
+</div>
+</div>
+<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
-TODO - see <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>, <a href="rgant.html#_rgant-Action_domainEvent"><code>@Action#domainEvent()</code></a>, <a href="rgant.html#_rgant-Property_domainEvent"><code>@Property#domainEvent()</code></a>, <a href="rgant.html#_rgant-Collection_domainEvent"><code>@Collection#domainEvent()</code></a>, <a href="rgsvc.html#_rgsvc_api_WrapperFactory"><code>WrapperFactory</code></a>.
+<div class="paragraph">
+<p>If for some reason you don’t want to use schemas (though we strongly recommend that you do), then note that you can override the <code>@PersistenceCapable</code> annotation by providing XML metadata (the <code>mappings.jdo</code> file); see the section on <a href="rgcfg.html#_rgcfg_configuring-datanucleus">configuring DataNucleus Overriding Annotations</a> for more details.</p>
+</div>
</td>
</tr>
</table>
</div>
-</div>
<div class="sect3">
-<h4 id="_ugbtb_more-advanced_decoupling_pushing-changes">2.1.6. Pushing Changes</h4>
-<div class="admonitionblock note">
+<h4 id="_listener_to_create_schema">3.1.1. Listener to create schema</h4>
+<div class="paragraph">
+<p>JDO/DataNucleus does not automatically create these schema objects, but it <em>does</em> provide a listener callback API
+on the initialization of each class into the JDO metamodel.</p>
+</div>
+<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
-<p>This technique is much less powerful than using <a href="#_ugbtb_more-advanced_decoupling_event-bus">the event bus</a> . We present it mostly for completeness.</p>
+<p>Actually, the above statement isn’t quite true. In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas. As of Apache Isis 1.9.0 and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we’ve decided to leave it in.</p>
</div>
</td>
</tr>
</table>
</div>
-<div class="sect4">
-<h5 id="_when_a_property_is_changed">When a property is changed</h5>
<div class="paragraph">
-<p>If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting <code>modifyXxx()</code> method and include the functionality within that. The syntax is:</p>
+<p>Therefore Apache Isis attaches a listener, <code>CreateSchemaObjectFromClassMetadata</code>, that checks for the schema’s existence, and creates the schema if required.</p>
+</div>
+<div class="paragraph">
+<p>The guts of its implementation is:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> modifyPropertyName(PropertyType param) { ... }</code></pre>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">CreateSchemaObjectFromClassMetadata</span>
+ <span class="directive">implements</span> MetaDataListener,
+ DataNucleusPropertiesAware {
+ <span class="annotation">@Override</span>
+ <span class="directive">public</span> <span class="type">void</span> loaded(<span class="directive">final</span> AbstractClassMetaData cmd) { ... }
+
+ <span class="directive">protected</span> <span class="predefined-type">String</span> buildSqlToCheck(<span class="directive">final</span> AbstractClassMetaData cmd) {
+ <span class="directive">final</span> <span class="predefined-type">String</span> schemaName = schemaNameFor(cmd);
+ <span class="keyword">return</span> <span class="predefined-type">String</span>.format(
+ <span class="string"><span class="delimiter">"</span><span class="content">SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'</span><span class="delimiter">"</span></span>, schemaName);
+ }
+ <span class="directive">protected</span> <span class="predefined-type">String</span> buildSqlToExec(<span class="directive">final</span> AbstractClassMetaData cmd) {
+ <span class="directive">final</span> <span class="predefined-type">String</span> schemaName = schemaNameFor(cmd);
+ <span class="keyword">return</span> <span class="predefined-type">String</span>.format(<span class="string"><span class="delimiter">"</span><span class="content">CREATE SCHEMA </span><span class="char">\"</span><span class="content">%s</span><span class="char">\"</span><span class="delimiter">"</span></span>, schemaName);
+ }
+}</code></pre>
</div>
-<div class="paragraph">
-<p>Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.</p>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>where <code>MetaDataListener</code> is the DataNucleus listener API:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span>() {
- <span class="directive">public</span> <span class="predefined-type">Integer</span> getAmount() { ... }
- <span class="directive">public</span> <span class="type">void</span> setAmount(<span class="predefined-type">Integer</span> amount) { ... }
- <span class="directive">public</span> <span class="type">void</span> modifyAmount(<span class="predefined-type">Integer</span> amount) { <i class="conum" data-value="1"></i><b>(1)</b>
- setAmount(amount); <i class="conum" data-value="3"></i><b>(3)</b>
- addToTotal(amount); <i class="conum" data-value="2"></i><b>(2)</b>
- }
- ...
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">MetaDataListener</span> {
+ <span class="type">void</span> loaded(AbstractClassMetaData cmd);
}</code></pre>
</div>
</div>
-<div class="colist arabic">
-<table>
-<tr>
-<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>The <code>modifyAmount()</code> method calls …​</td>
-</tr>
-<tr>
-<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>…​ the <code>addToTotal()</code> (not shown) to maintain some running total.</td>
-</tr>
-</table>
+<div class="paragraph">
+<p>Although not formal API, the default <code>CreateSchemaObjectFromClassMetadata</code> has been designed to be easily overrideable if you
+need to tweak it to support other RDBMS'. Any implementation must implement <code>org.datanucleus.metadata.MetaDataListener</code>:</p>
</div>
<div class="paragraph">
-<p>We don’t want this <code>addToCall()</code> method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.</p>
+<p>The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).</p>
+</div>
</div>
+<div class="sect3">
+<h4 id="_alternative_implementation">3.1.2. Alternative implementation</h4>
<div class="paragraph">
-<p>You may optionally also specify a <code>clearXxx()</code> which works the same way as modify <code>modify Xxx()</code> but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:</p>
+<p>An alternative implementation can be registered and used through the following configuration property:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> clearPropertyName() { ... }</code></pre>
+<pre class="CodeRay highlight"><code data-lang="ini">isis.persistor.datanucleus.classMetadataLoadedListener=\
+ org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata</code></pre>
</div>
</div>
<div class="paragraph">
-<p>To extend the above example:</p>
+<p>Because this pertains to the JDO Objectstore we suggest you put this configuration property in <code>WEB-INF/persistor_datanucleus.properties</code>; but putting it in <code>isis.properties</code> will also work.</p>
+</div>
+<div class="paragraph">
+<p>Any implementation must implement <code>org.datanucleus.metadata.MetaDataListener</code>. In many cases simply subclassing from <code>CreateSchemaObjectFromClassMetadata</code> and overriding <code>buildSqlToCheck(…​)</code> and <code>buildSqlToExec(…​)</code> should suffice.</p>
+</div>
+<div class="paragraph">
+<p>If you <em>do</em> need more control, your implementation can also optionally implement <code>org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware</code>:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Order</span>() {
- <span class="directive">public</span> <span class="predefined-type">Integer</span> getAmount() { ... }
- <span class="directive">public</span> <span class="type">void</span> setAmount(<span class="predefined-type">Integer</span> amount) { ... }
- <span class="directive">public</span> <span class="type">void</span> modifyAmount(<span class="predefined-type">Integer</span> amount) { ... }
- <span class="directive">public</span> <span class="type">void</span> clearAmount() {
- removeFromTotal(<span class="local-variable">this</span>.amount);
- setAmount(<span class="predefined-constant">null</span>);
- }
- ...
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">interface</span> <span class="class">DataNucleusPropertiesAware</span> {
+ <span class="directive">public</span> <span class="type">void</span> setDataNucleusProperties(<span class="directive">final</span> <span class="predefined-type">Map</span><<span class="predefined-type">String</span>, <span class="predefined-type">String</span>> properties);
}</code></pre>
</div>
</div>
-</div>
-<div class="sect4">
-<h5 id="_when_a_collection_is_modified">When a collection is modified</h5>
<div class="paragraph">
-<p>A collection may have a corresponding <code>addToXxx()</code> and/or
-<code>removeFromXxx()</code> method. If present, and direct manipulation of the
-contents of the connection has not been disabled (see ?), then they will
-be called (instead of adding/removing an object directly to the
-collection returned by the accessor).</p>
+<p>This provides access to the properties passed through to JDO/DataNucleus.</p>
</div>
+<div class="admonitionblock important">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-important" title="Important"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>The reason for this behaviour is to allow other behaviour to be
-triggered when the contents of the collection is altered. That is, it is
-directly equivalent to the supporting <code>modifyXxx()</code> and <code>clearXxx()</code>
-methods for properties (see ?).</p>
+<p>If you do extend Apache Isis' <code>CreateSchemaObjectFromClassMetadata</code> class for some other database, please <a href="https://issues.apache.org/jira/browse/ISIS">contribute back</a> your improvements.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
</div>
+</div>
+<div class="sect2">
+<h3 id="_ugbtb_decoupling_mixins">3.2. Mixins</h3>
<div class="paragraph">
-<p>The syntax is:</p>
+<p>A mixin object allows one class to contribute behaviour - actions, (derived) properties and
+(derived) collections - to another domain object, either a domain entity or view model.</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> addTo<CollectionName>(EntityType param) { ... }</code></pre>
+<div class="paragraph">
+<p>Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own
+syntax for defining such constructs. In Apache Isis a mixin is very similar to a domain service, however it also
+defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.</p>
</div>
+<div class="paragraph">
+<p>Why do this? The main reason is to allow the app to be decoupled, so that it doesn’t degrade into the proverbial
+<a href="http://www.laputan.org/mud/mud.html#BigBallOfMud">"big ball of mud"</a>. Mixins (and contributions) allow dependency
+to be inverted, so that the dependencies between modules can be kept acyclic and under control.</p>
</div>
+<div class="sect3">
+<h4 id="_example">3.2.1. Example</h4>
<div class="paragraph">
-<p>and</p>
+<p>This is probably best explained by way of an example. Suppose we have the <code>Customer</code> domain object which implements
+a <code>DocumentHolder</code> interface:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">void</span> removeFromCollectionName(EntityType param) { ... }</code></pre>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> <span class="directive">implements</span> DocumentHolder {
+ ...
+}</code></pre>
</div>
-<div class="paragraph">
-<p>where <code>EntityType</code> is the same type as the generic collection type.</p>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>We could then imagine a mixin that would contribute behaviour to list, add and remove the <code>Document</code>s for this holder:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Employee</span> { ... }
-
-<span class="directive">public</span> <span class="type">class</span> <span class="class">Department</span> {
-
- <span class="directive">private</span> <span class="type">int</span> numMaleEmployees; <i class="conum" data-value="1"></i><b>(1)</b>
- <span class="directive">private</span> <span class="type">int</span> numFemaleEmployees; <i class="conum" data-value="2"></i><b>(2)</b>
-
- <span class="directive">private</span> <span class="predefined-type">Set</span><Employee> employees = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><Employee>();
- <span class="directive">public</span> <span class="predefined-type">Set</span><Employee> getEmployees() {
- <span class="keyword">return</span> employees;
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Mixin</span> <i class="conum" data-value="1"></i><b>(1)</b>
+<span class="directive">public</span> <span class="type">class</span> <span class="class">DocumentHolder_documents</span> {
+ <span class="directive">private</span> <span class="directive">final</span> DocumentHolder holder;
+ <span class="directive">public</span> DocumentHolder_documents(DocumentHolder holder) { <i class="conum" data-value="2"></i><b>(2)</b>
+ <span class="local-variable">this</span>.holder = holder;
}
- <span class="directive">private</span> <span class="type">void</span> setEmployees(<span class="predefined-type">Set</span><Employee> employees) {
- <span class="local-variable">this</span>.employees = employees;
+ <span class="annotation">@Action</span>(semantics=SemanticsOf.SAFE)
+ <span class="annotation">@ActionLayout</span>(contributed = Contributed.AS_ASSOCIATION)
+ <span class="annotation">@CollectionLayout</span>(render = RenderType.EAGERLY)
+ <span class="directive">public</span> <span class="predefined-type">List</span><<span class="predefined-type">Document</span>> documents() {
+ ... <i class="conum" data-value="3"></i><b>(3)</b>
}
- <span class="directive">public</span> <span class="type">void</span> addToEmployees(Employee employee) { <i class="conum" data-value="3"></i><b>(3)</b>
- numMaleEmployees += countOneMale(employee);
- numFemaleEmployees += countOneFemale(employee);
- employees.add(employee);
+ <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
+ <span class="directive">public</span> DocumentHolder add(<span class="predefined-type">Document</span> document) {
+ ... <i class="conum" data-value="4"></i><b>(4)</b>
}
- <span class="directive">public</span> <span class="type">void</span> removeFromEmployees(Employee employee) { <i class="conum" data-value="4"></i><b>(4)</b>
- numMaleEmployees -= countOneMale(employee);
- numFemaleEmployees -= countOneFemale(employee);
- employees.remove(employee);
+ <span class="annotation">@Action</span>(semantics=SemanticsOf.IDEMPOTENT)
+ <span class="directive">public</span> DocumentHolder remove(<span class="predefined-type">Document</span> document) {
+ ... <i class="conum" data-value="5"></i><b>(5)</b>
}
- <span class="directive">private</span> <span class="type">int</span> countOneMale(Employee employee) { <span class="keyword">return</span> employee.isMale()?<span class="integer">1</span>:<span class="integer">0</span>; }
- <span class="directive">private</span> <span class="type">int</span> countOneFemale(Employee employee) { <span class="keyword">return</span> employee.isFemale()?<span class="integer">1</span>:<span class="integer">0</span>; }
-
- ...
}</code></pre>
</div>
</div>
@@ -1223,66 +1430,33 @@ methods for properties (see ?).</p>
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
-<td>maintain a count of the number of male …​</td>
+<td>alternatively can use <code>@DomainObject(nature=Nature.MIXIN)</code></td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
-<td>…​ and female employees (getters and setters omitted)</td>
+<td>constructor indicates the type that is contributed to</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
-<td>the <a href="rgcms.html#_rgcms_methods_prefixes_addTo"><code>addTo…​()</code></a> method increments the derived properties</td>
+<td>implementation could, for example, use the (non-ASF)
+<a href="http://github.com/isisaddons/isis-module-poly">Isis addons' poly</a> module.</td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
-<td>the <a href="rgcms.html#_rgcms_methods_prefixes_removeFrom"><code>removeFrom…​()</code></a> method similarly decrements the derived properties</td>
+<td>implementation would probably delegate to an injected repository to (ultimately) insert data into some table</td>
+</tr>
+<tr>
+<td><i class="conum" data-value="5"></i><b>5</b></td>
+<td>implementation would probably delegate to an injected repository to (ultimately) delete data from some table</td>
</tr>
</table>
</div>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_ugbtb_more-advanced_overriding-jdo-annotations">2.2. Overriding JDO Annotations</h3>
-<div class="paragraph">
-<p>The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.</p>
-</div>
-<div class="paragraph">
-<p>For example, as of 1.9.0 the various <a href="http://www.isisaddons.org">Isis addons</a> modules (not ASF) use schemas for each entity. For example, the <code>AuditEntry</code> entity in the <a href="http://github.com/isisaddons/isis-module-audit">audit module</a> is annotated as:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.PersistenceCapable(
- identityType=IdentityType.DATASTORE,
- schema = <span class="string"><span class="delimiter">"</span><span class="content">IsisAddonsAudit</span><span class="delimiter">"</span></span>,
- table=<span class="string"><span class="delimiter">"</span><span class="content">AuditEntry</span><span class="delimiter">"</span></span>)
-<span class="directive">public</span> <span class="type">class</span> <span class="class">AuditEntry</span> {
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This will map the <code>AuditEntry</code> class to a table <code>"IsisAddonsAudit"."AuditEntry"</code>; that is using a custom schema to own the object.</p>
-</div>
<div class="paragraph">
-<p>Suppose though that for whatever reason we didn’t want to use a custom schema but would rather use the default. We can override the above annotation using a <code>package.jdo</code> file, for example:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="xml"><span class="preprocessor"><?xml version="1.0" encoding="UTF-8" ?></span>
-<span class="tag"><jdo</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://xmlns.jcp.org/xml/ns/jdo/jdo</span><span class="delimiter">"</span></span>
- <span class="attribute-name">xmlns:xsi</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://www.w3.org/2001/XMLSchema-instance</span><span class="delimiter">"</span></span>
- <span class="attribute-name">xsi:schemaLocation</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://xmlns.jcp.org/xml/ns/jdo/jdo</span>
- <span class="content">http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd</span><span class="delimiter">"</span></span> <span class="attribute-name">version</span>=<span class="string"><span class="delimiter">"</span><span class="content">3.0</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><package</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">org.isisaddons.module.audit.dom</span><span class="delimiter">"</span></span><span class="tag">></span>
- <span class="tag"><class</span> <span class="attribute-name">name<
<TRUNCATED>