You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/11/02 19:52:36 UTC
[7/8] isis-site git commit: ISIS-1195: introductory sections
http://git-wip-us.apache.org/repos/asf/isis-site/blob/8b7ec063/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index 8f40bfd..d18a6b3 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -609,7 +609,7 @@ table.CodeRay td.code>pre{padding:0}
<p>Bah and humbug! If we use our ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.</p>
</div>
<div class="paragraph">
-<p>What do we mean by <strong>model</strong> anyway? For some, the term will bring to mind <em>UML</em> class or sequence diagrams and the like. But this isn’t a model; it’s a visual <strong>representation</strong> of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We’re not looking to simply model everything that’s out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us. A model is neither right nor wrong, just more or less useful.</p>
+<p>What do we mean by <strong>model</strong> anyway? For some, the term will bring to mind UML class or sequence diagrams and the like. But this isn’t a model; it’s a visual <strong>representation</strong> of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We’re not looking to simply model everything that’s out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us. A model is neither right nor wrong, just more or less useful.</p>
</div>
<div class="paragraph">
<p>For our ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation. Our software’s design should be driven by this model; we should have a model-driven design.</p>
@@ -626,10 +626,10 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="paragraph">
-<p>Here also the word <strong>design</strong> might mislead; some might again be thinking of design documents and design diagrams. But by <strong>design</strong> we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.</p>
+<p>Here also the word <strong>design</strong> might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design. But by <strong>design</strong> we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.</p>
</div>
<div class="paragraph">
-<p>Luckily, using <strong><em>object-oriented</em></strong> ( <em>OO</em>) languages such as Java, this is relatively easy to do; <em>OO</em> is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.</p>
+<p>Luckily, using <strong><em>object-oriented</em></strong> (<em>OO</em>) languages such as Java, this is relatively easy to do; <em>OO</em> is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.</p>
</div>
<div class="paragraph">
<p>So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the <em>DDD</em> concepts isn’t the same as being able to apply them, and some of the <em>DDD</em> ideas can be difficult to put into practice. Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of <em>DDD</em> in a very concrete way.</p>
@@ -646,7 +646,7 @@ table.CodeRay td.code>pre{padding:0}
</p></div></p>
</div>
<div class="paragraph">
-<p><div class="extended-quote"><p>A common complaint from <em>DDD</em> practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with <em>UML</em> diagrams. It was much easier to engage them in rapid prototyping — where they could see and interact with the results — but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
+<p><div class="extended-quote"><p>A common complaint from <em>DDD</em> practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with UML diagrams. It was much easier to engage them in rapid prototyping — where they could see and interact with the results — but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
</p></div></p>
</div>
<div class="paragraph">
@@ -872,12 +872,12 @@ challenges that <em>DDD</em> throws up and see how Apache Isis (and its impleme
</div>
</div>
<div class="sect4">
-<h5 id="_abstract_models_are_difficult_to_represent">Abstract models are difficult to represent</h5>
+<h5 id="_model_must_be_understandable">Model must be understandable</h5>
<div class="paragraph">
<p>If we are using code as the primary means of expressing the model, then we need to find a way to make this model understandable to the business.</p>
</div>
<div class="paragraph">
-<p>We could generate <em>UML</em> diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a <em>PDF</em> document from Javadoc comments, but comments aren’t code and so the document may be inaccurate. Anyway, even if we do create such a document, not everyone will read it.</p>
+<p>We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren’t code and so the document may be inaccurate. Anyway, even if we do create such a document, not everyone will read it.</p>
</div>
<div class="paragraph">
<p>A better way to represent the model is to show it in action as a working prototype. As we show in the <a href="#_ug_getting-started">Getting Started</a> section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.</p>
@@ -887,7 +887,7 @@ challenges that <em>DDD</em> throws up and see how Apache Isis (and its impleme
</div>
</div>
<div class="sect4">
-<h5 id="_layered_architectures_are_easily_compromised">Layered architectures are easily compromised</h5>
+<h5 id="_architecture_must_be_robust">Architecture must be robust</h5>
<div class="paragraph">
<p><em>DDD</em> rightly requires that the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.</p>
</div>
@@ -934,20 +934,12 @@ challenges that <em>DDD</em> throws up and see how Apache Isis (and its impleme
</div>
<div class="sect3">
<h4 id="_ug_core-concepts_principles_your-apps">2.2.1. Your Applications</h4>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<div class="paragraph">
+<p>Apache Isis is primarily aimed at custom-built "enterprise" applications. The UI exposed by the <a href="#_ug_wicket-viewer">Wicket viewer</a> is intended to be usable by domain experts, typically end-users within the organization. The REST API exposed by the <a href="#_ug_restfulobjects-viewer">RestfulObjects viewer</a> allows custom apps to be developed - eg using AngularJS or similar - for use by those requiring more guidance; typically end-users outside of the organization.</p>
+</div>
+<div class="paragraph">
+<p>But should your organization buy, or build? Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval. But it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.</p>
</div>
-<div class="sect4">
-<h5 id="_decoupled">Decoupled</h5>
<div class="admonitionblock note">
<table>
<tr>
@@ -955,17 +947,21 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+TODO - flesh out the following:
</td>
</tr>
</table>
</div>
-<div class="paragraph">
+<div class="ulist">
+<ul>
+<li>
+<p>Flexible, "just enough"</p>
+</li>
+<li>
+<p>Decoupled</p>
+</li>
+<li>
<p>Long-term Cost of ownership</p>
-</div>
-<div class="paragraph">
-<p>Using:</p>
-</div>
<div class="ulist">
<ul>
<li>
@@ -985,39 +981,31 @@ TODO
</li>
</ul>
</div>
+</li>
+<li>
+<p>Honouring the Single Responsibility Principle</p>
+<div class="ulist">
+<ul>
+<li>
+<p>behaviourally Complete vs Contributions/Mixins</p>
+</li>
+</ul>
</div>
-<div class="sect4">
-<h5 id="_honouring_the_single_responsibility_principle">Honouring the Single Responsibility Principle</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO - behaviourally Complete vs Contributions
-</td>
-</tr>
-</table>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_testable">Testable</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+</li>
+<li>
+<p>Testable<br></p>
+<div class="paragraph">
+<p>While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in
+such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.</p>
</div>
+</li>
+<li>
+<p>Reusable building blocks<br></p>
<div class="paragraph">
-<p>While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.</p>
+<p>Isis addons, catalog.incode.org</p>
</div>
+</li>
+</ul>
</div>
</div>
<div class="sect3">
@@ -1138,48 +1126,54 @@ do they compare to Apache Isis?</p>
</div>
</div>
<div class="sect4">
-<h5 id="_vs_cqrs">vs CQRS</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<h5 id="_ug_core-concepts_principles_apache-isis-vs_cqrs">vs CQRS</h5>
+<div class="paragraph">
+<p>The CQRS architectural pattern (it stands for "Command Query Responsbility Separation") is the idea that the domain objects that mutate the state of the system - to which commands are sent and which then execute - should be separated from the mechanism by which the state of the system is queried (rendered). The former are sometimes called the "write (domain) model", the latter the "read model".</p>
</div>
+<div class="paragraph">
+<p>In the canonical version of this pattern there are separate datastores. The commands act upon a command/write datastore. The data in this datastore is then replicated in some way to the query/read datastore, usually denormalized or otherwise such that it is easy to query. CQRS advocates recommend using very simple (almost naive) technology for the query/read model; it should be a simple projection of the query datastore. Complexity instead lives elsewhere: business logic in the command/write model, and in the transformation logic betweeen the command/write and read/query datastores. In particular, there is no requirement for the two datastores to use the same technology: one might be an RDBMS while the other a NoSQL datastore or even datawarehouse.</p>
</div>
-<div class="sect4">
-<h5 id="_vs_event_sourcing">vs Event Sourcing</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<div class="paragraph">
+<p>In most implementations the command and query datastores are <em>not</em> updated in the same transaction; instead there is some sort of replication mechanism. This also means that the query datastore is eventually consistent rather than always consistent; there could be a lag of a few seconds before it is updated. This means in turn that CQRS implementations require mechanisms to cater for offline query datastores; usually some sort of event bus.</p>
+</div>
+<div class="paragraph">
+<p>The CQRS architecture’s extreme separation of responsibilities can result in a lot of boilerplate. Any given domain concept, eg <code>Customer</code>, must be represented both in the command/write model and also in the query/read model. Each business operation upon the command model is reified as a command object, for example <code>PlaceOrderCommand</code>.</p>
+</div>
+<div class="paragraph">
+<p>Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis does not separate out a command/write model from a query/read model, and there is usually just a single datastore. But then again, having a separate read model just so that the querying is very straightforward is pointless with Apache Isis because, of course, Isis provides the UI "for free".</p>
+</div>
+<div class="paragraph">
+<p>There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data. In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic. In such cases there is still only a single physical datastore, and so transactional integrity is retained.</p>
+</div>
+<div class="paragraph">
+<p>Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the <a href="rg.html#_rg_services-api_manpage-PublishingService"><code>PublishingService</code></a>, or using <a href="rg.html#_rg_classes_super_manpage-AbstractSubscriber">subscribers</a> on the <a href="rg.html#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a>. One can then use <a href="#_ug_more-advanced_view-models">view models</a> to surface the data in the external read datastore.</p>
+</div>
+<div class="paragraph">
+<p>With respect to commands, Apache Isis does of course support the <a href="rg.html#_rg_services-spi_manpage-CommandService"><code>CommandService</code></a> which allows each business action to be reified into a <code>Command</code>. However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation. In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects. More significantly, in CQRS each command has its own class, such as <code>PlaceOrderCommand</code>, instantiated by the client and then executed. With Apache Isis, though, the end-user merely invokes the <code>placeOrder(…​)</code> action upon the domain object; the framework itself creates the <code>Command</code> as a side-effect of this.</p>
+</div>
+<div class="paragraph">
+<p>In CQRS the commands correspond to the business logic that mutates the system. Whether this logic is part of the command class (<code>PlaceOrderCommand</code>) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.</p>
+</div>
+<div class="paragraph">
+<p>In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using <a href="#_ug_more-advanced_decoupling_mixins">mixins</a> or <a href="#_ug_how-tos_contributed-members">contributions</a>. In the UI (surfaced by the <a href="#_ug_wicket-viewer">Wicket viewer</a>) or in the REST API (surfaced by the <a href="#_ug_restfulobjects-viewer">RestfulObjects viewer</a>) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.</p>
</div>
</div>
<div class="sect4">
-<h5 id="_vs_angular">vs Angular</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<h5 id="_ug_core-concepts_principles_apache-isis-vs_event-sourcing">vs Event Sourcing</h5>
+<div class="paragraph">
+<p>The <a href="_ug_core-concepts_principles_apache-isis-vs_cqrs">CQRS architecture</a>, discussed above, is often combined with <em>Event Sourcing</em> pattern, though they are separate ideas.</p>
+</div>
+<div class="paragraph">
+<p>With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly. For example, if a customer places an order then this might emit the <code>OrderPlacedEvent</code>. Most significantly, the subscribers to these events can include the datastore itself; the state of the system is in effect a transaction log of every event that has occurred since "the beginning of time": it is sometimes called an event store. With CQRS, this event datastore corresponds to the command/write datastore (the query/read datastore is of course derived from the command datastore).</p>
+</div>
+<div class="paragraph">
+<p>Although it might seem counter-intuitive to be able store persistent state in this way (as a souped up "transaction log"), the reality is that with modern compute capabilities make it quite feasible to replay many 10s/100s of thousands of events in a second. And the architecture supports some interesting use cases; for example it becomes quite trivial to rewind the system back to some previous point in time.</p>
+</div>
+<div class="paragraph">
+<p>When combined with CQRS we see a command that triggers a business operation, and an event that results from it. So, a <code>PlaceOrderCommand</code> command can result in an <code>OrderPlacedEvent</code> event. A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system). Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process. If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required. CQRS/event sourcing advocates point out - correctly that this is just how things are in the "real world" too.</p>
+</div>
+<div class="paragraph">
+<p>In Apache Isis every business action (and indeed, property and collection) emits domain events through the <a href="rg.html#_rg_services-api_manpage-EventBusService"><code>EventBusService</code></a> , and can optionally also be published through the <a href="rg.html#_rg_services-spi_manpage-PublishingService"><code>PublishingService</code></a>. The former are dispatched and consumed in-process and within the same transaction, and for this reason the <a href="rg.html#_rg_classes_super_manpage-AbstractSubscriber">subscribers</a> can also veto the events. The latter are intended for out-of-process consumption; the (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishing">Isis addons' publishing</a> and <a href="http://github.com/isisaddons/isis-module-publishmq">Isis addons' publishmq</a> modules provide implementations for dispatching either through a RDBMS database table, or directly through to an <a href="http://camel.apache.org">ActiveMQ</a> message queue (eg wir
ed up to <a href="http://camel.apache.org">Apache Camel</a> event bus).</p>
</div>
</div>
<div class="sect4">
@@ -1197,135 +1191,287 @@ TODO
<p>Also, it’s worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced. It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Apache Isis domain application.</p>
</div>
</div>
-<div class="sect4">
-<h5 id="_vs_openxava">vs OpenXava</h5>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
-</div>
-</div>
</div>
</div>
<div class="sect2">
<h3 id="_ug_core-concepts_building-blocks">2.3. Building Blocks</h3>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<div class="paragraph">
+<p>In this section we run through the main building blocks that make up an Apache Isis application.</p>
</div>
<div class="sect3">
-<h4 id="_a_metamodel_with_explicit_and_inferred_semantics">2.3.1. A MetaModel with Explicit and Inferred Semantics</h4>
-<div class="admonitionblock note">
+<h4 id="_ug_core-concepts_building-blocks_metamodel">2.3.1. A MetaModel</h4>
+<div class="paragraph">
+<p>At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg <code>Customer.java</code>), along
+with optional supporting metadata (eg <code>Customer.layout.json</code>).</p>
+</div>
+<div class="paragraph">
+<p>The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and
+supporting services, as well the members of those classes. The detail of the metamodel is generally explicit, usually
+represented by Java annotations such as <code>@Title</code> or <code>@Action</code>. Notably the metamodel is
+<a href="#_ug_extending_programming-model">extensible</a>; it is possible to teach Apache Isis new programming
+conventions/rules (and conversely to remove those that are built in).</p>
+</div>
+<div class="paragraph">
+<p>Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the
+<code>@Title</code> annotation - which identifies how the framework should derive a human-readable label for each rendered
+domain object - is part of the <code>org.apache.isis.applib.annotations</code> package. However the framework also recognizes
+certain other JEE annotations such as <code>@javax.inject.Inject</code> (used for dependency injection).</p>
+</div>
+<div class="paragraph">
+<p>The framework uses DataNucleus for its persistence mechanism. This is an ORM that implements the JDO and JPA APIs, and
+which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J. Apache Isis
+recognizes a number of the JDO annotations such as <code>@javax.jdo.annotations.Column(allowNulls=…​)</code>.</p>
+</div>
+<div class="paragraph">
+<p>In addition, the framework builds up the metamodel for each domain object using
+<a href="rg.html#_rg_object-layout">layout hints</a>, such as <code>Customer.layout.json</code>. These provide metadata such as
+grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the
+application is still running, and are picked up automatically; a useful way to speed up feedback.</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">
-TODO
+<div class="paragraph">
+<p>At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
+in the future. We also expect to generalize support for <code>.layout.json</code> to be able to read such metadata from other
+sources.</p>
+</div>
</td>
</tr>
</table>
</div>
+</div>
+<div class="sect3">
+<h4 id="_ug_core-concepts_building-blocks_types-of-domain-objects">2.3.2. Type of Domain Objects</h4>
+<div class="paragraph">
+<p>Most domain objects that the end-user interacts with are <strong>domain entities</strong>, such as <code>Customer</code>, <code>Order</code>, <code>Product</code> and
+so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
+annotations. From the end-user’s perspective the UI displays a single domain object per page; they can then inspect
+and modify its state, and navigate to related objects.</p>
+</div>
+<div class="paragraph">
+<p>The next type of domain object to discuss is <strong>domain services</strong>. These are (usually) singleton stateless services
+that provide additional functionality. The behaviour of these services is rendered in various ways, though the most
+obvious is as the menu actions on the top-level menu bars in the <a href="#_ug_wicket-viewer">Wicket viewer</a>'s UI.</p>
+</div>
+<div class="paragraph">
+<p>Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
+object; this includes domain entities as well as other services. This injection of domain services into entities is
+significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
+supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic
+domain model anti-pattern.</p>
+</div>
+<div class="paragraph">
+<p>As well as domain entities - mapped to a datastore - Apache Isis also supports <strong>view models</strong>. End users interact with
+view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other. However
+view models are <em>not</em> mapped to the underlying database, rather they represent some aggregation of state from one or
+more underlying entities. Their state is serialized and recreated from their internal identifier; this identifier is
+visible as the object’s URL in the <a href="#_ug_wicket-viewer">Wicket viewer</a> or
+<a href="#_ug_restfulobjects-viewer">RestfulObjects viewer</a>.</p>
+</div>
+<div class="paragraph">
+<p>There’s no need though for the view model to aggregate the state of regular domain entities. A view model could also
+be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
+representation of state held in-memory (such as user preferences, for example).</p>
+</div>
+<div class="paragraph">
+<p>There are also several types of domain services. Most easily described are those domain services (discussed above)
+that are represented as the menu actions on top-level menu bars. Another variation are <strong>contributed services</strong> - domain
+services that contribute behaviour or (derived) state to entities/view models. Finally domain services may also
+simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
+google-maps API.</p>
+</div>
+<div class="paragraph">
+<p>Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
+being annotated with <code>@javax.enterprise.context.RequestScoped</code>. An example of the request-scoped service is the
+<a href="rg.html#_rg_services-api_manpage-Scratchpad"><code>Scratchpad</code></a> service, for sharing arbitrary data between multiple objects.</p>
+</div>
+<div class="paragraph">
+<p>The final type of domain object is the <strong>mixin</strong>. These are similar to contributed services in that they also contribute (or rather,
+mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services,
+with a cleaner programming model similar to traits found in other languages.</p>
+</div>
+<div class="paragraph">
+<p>The diagram below summarizes the various types of domain object:</p>
+</div>
+<div class="imageblock">
+<div class="content">
+<a class="image" href="images/core-concepts/building-blocks/types-of-domain-object.png"><img src="images/core-concepts/building-blocks/types-of-domain-object.png" alt="types of domain object" width="860px"></a>
+</div>
+</div>
+<div class="paragraph">
+<p>The Apache Isis programming model uses annotations to distinguish these object types:</p>
+</div>
<div class="ulist">
<ul>
<li>
-<p>use of annotations</p>
-<div class="ulist">
-<ul>
-<li>
-<p>reuse JEE annotations where possible</p>
+<p><strong>view models</strong> are annotated either with <code>@DomainObject(nature=VIEW_MODEL)</code> or using <code>@ViewModel</code>. Which is used is
+a matter of personal preference. <br></p>
+<div class="paragraph">
+<p>It is also possible to implement the <code>ViewModel</code> interface, for finer-grained control.</p>
+</div>
</li>
-</ul>
+<li>
+<p><strong>domain entities</strong> that are persisted to the database (as the vast majority will) are annotated with
+<code>@DomainObject(nature=ENTITY)</code>. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+<code>@javax.jdo.annotations.PersistenceCapable</code>.<br></p>
+<div class="paragraph">
+<p>In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
+in-memory, then <code>@DomainObject(nature=EXTERNAL_ENTITY)</code> or <code>@DomainObject(nature=INMEMORY_ENTITY)</code> can be used.</p>
</div>
</li>
<li>
-<p>layout hints are overridable, to avoid restarting the app/speed up feedback</p>
+<p><strong>mixins</strong> are annotated either with <code>@DomainObject(nature=MIXIN)</code> or using <code>@Mixin</code>. As for view models, which is
+used is a matter of personal preference.</p>
+</li>
+<li>
+<p>finally, <strong>domain services</strong>` are annotated with <code>@DomainService(nature=…​)</code> where the nature is either
+<code>VIEW_MENU_ONLY</code> (for domain services whose actions appear on the top-level menu bars), or <code>VIEW_CONTRIBUTIONS_ONLY</code>
+(for domain services whose actions are contributed to entities or view models), or <code>DOMAIN</code> (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).</p>
+<div class="paragraph">
+<p>It is also possible to specify a nature of simply <code>VIEW</code>, this combining <code>VIEW_MENU_ONLY</code> and <code>VIEW_CONTRIBUTIONS_ONLY</code>.
+This is in fact the default, useful for initial prototyping. A final nature is <code>VIEW_REST_ONLY</code> which is for domain
+services whose functionality is surfaced only by the <a href="#_ug_restfulobjects-viewer">RestfulObjects viewer</a>.</p>
+</div>
</li>
</ul>
</div>
+<div class="paragraph">
+<p>Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
+stateless. If a domain service does hold state (eg the <code>Scratchpad</code> service noted above) then it should be
+<code>@RequestScoped</code> so that this state is short-lived and usable only within a single request.</p>
+</div>
</div>
<div class="sect3">
-<h4 id="_objects_services">2.3.2. Objects & Services</h4>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<h4 id="_ug_core-concepts_building-blocks_objects-members">2.3.3. Object Members</h4>
+<div class="paragraph">
+<p>Every domain object in Apache Isis consists of (at most) three types of members:</p>
</div>
<div class="ulist">
<ul>
<li>
-<p>domain model</p>
-<div class="ulist">
-<ul>
-<li>
-<p>domain objects</p>
-<div class="ulist">
-<ul>
-<li>
-<p>domain entity</p>
-</li>
-<li>
-<p>view model</p>
-</li>
-</ul>
-</div>
+<p>properties, such as a `Customer’s `firstName</p>
</li>
<li>
-<p>domain service</p>
+<p>collections, such as a <code>Customer’s `orders</code> collection of <code>Order</code>s</p>
</li>
<li>
-<p>value type</p>
+<p>actions, such as a <code>Customer'`s `placeOrder(…​)</code> method.</p>
</li>
</ul>
</div>
-</li>
-</ul>
+<div class="paragraph">
+<p>Some domain objects - specifically domain services and mixins - only have actions. In the case of contributing services
+and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
+collections on the entity/view model to which they contribute/mix-in.</p>
</div>
+<div class="sect4">
+<h5 id="_properties">Properties</h5>
<div class="paragraph">
-<p>Anything else can be (should be) ignored by annotating with <code>@Programmatic</code>.</p>
+<p>Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
+entity or view model).</p>
</div>
+<div class="paragraph">
+<p>For example, with:</p>
</div>
-<div class="sect3">
-<h4 id="_properties_collections_and_actions">2.3.3. Properties, Collections and Actions</h4>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
-</tr>
-</table>
+<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">private</span> <span class="predefined-type">String</span> firstName;
+ <span class="directive">public</span> <span class="predefined-type">String</span> getFirstName() { <span class="keyword">return</span> firstName; }
+ <span class="directive">public</span> <span class="type">void</span> setFirstName(<span class="predefined-type">String</span> firstName) { <span class="local-variable">this</span>.firstName = firstName; }
+ ...
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_domain_entities_vs_view_models">2.3.4. Domain Entities vs View Models</h4>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>the framework infers the <code>Customer</code> domain entity, which in turn has a <code>firstName</code> string <em>property</em>.</p>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_collections">Collections</h5>
+<div class="paragraph">
+<p>Collections are also represented by a getter and setter, however the return type is a <code>Collection</code> or subtype.</p>
+</div>
+<div class="paragraph">
+<p>For example, with:</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">private</span> <span class="predefined-type">SortedSet</span><Order> orders = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><Order>();
+ <span class="directive">public</span> <span class="predefined-type">SortedSet</span><Order> getOrders() { <span class="keyword">return</span> orders; }
+ <span class="directive">public</span> <span class="type">void</span> setOrders(<span class="predefined-type">SortedSet</span><Order> orders) { <span class="local-variable">this</span>.orders = orders; }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>the framework infers the <code>orders</code> <em>collection</em>.</p>
+</div>
+<div class="admonitionblock tip">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-tip" title="Tip"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The most commonly used collection type is <code>java.util.SortedSet</code>; entities are most commonly mapped to a relational
+database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
+rendered in the UI they will be ordered "meaningfully" to the end-user.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_actions">Actions</h5>
+<div class="paragraph">
+<p>The third type of object member is actions. (To a first approximation), actions are all public methods that do not
+represent properties or collections.</p>
+</div>
+<div class="paragraph">
+<p>For example:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span>
+ <span class="directive">public</span> Customer placeOrder(Product p, <span class="type">int</span> quantity) { ... }
+ ...
+}</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>corresponds to the <code>placeOrder</code> <em>action</em>.</p>
+</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+<div class="paragraph">
+<p>The above <em>is</em> a simplification; the Apache Isis programming model also recognizes a number of other supporting methods
+each of which has its own prefix such as <code>hide</code>, <code>disable</code> or <code>validate</code>. These can be considered as "reserved words"
+in Apache Isis, and do <em>not</em> correspond to actions even though they have public visibility.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_domain_entities_vs_view_models">2.3.4. Domain Entities vs View Models</h4>
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
@@ -1342,7 +1488,7 @@ TODO
</div>
</div>
<div class="sect3">
-<h4 id="_domain_services">2.3.5. Domain Services</h4>
+<h4 id="_ug_core-concepts_building-blocks_domain-services">2.3.5. Domain Services</h4>
<div class="paragraph">
<p>Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.</p>
</div>
@@ -1383,7 +1529,7 @@ TODO
</div>
</div>
<div class="sect3">
-<h4 id="_value_objects_primitives">2.3.6. Value Objects (Primitives)</h4>
+<h4 id="_ug_core-concepts_building-blocks_value-objects">2.3.6. Value Objects (Primitives)</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -1398,7 +1544,7 @@ TODO
</div>
</div>
<div class="sect3">
-<h4 id="_contributions">2.3.7. Contributions</h4>
+<h4 id="_ug_core-concepts_building-blocks_mixins-and-contributions">2.3.7. Mixins & Contributions</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -1413,7 +1559,7 @@ TODO
</div>
</div>
<div class="sect3">
-<h4 id="_event_bus">2.3.8. Event Bus</h4>
+<h4 id="_ug_core-concepts_building-blocks_domain-events">2.3.8. Domain Events</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -1687,495 +1833,525 @@ So, if you have used Apache Isis for prototyping (discussed above), then note th
</div>
</div>
<div class="sect1">
-<h2 id="_ug_getting-started">3. Getting Started</h2>
+<h2 id="_ug_how-tos">3. How tos</h2>
<div class="sectionbody">
<div class="paragraph">
-<p>To get you up and running quickly, Apache Isis provides a <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a> to setup a simple application as the basis of your own apps. This is deliberately very minimal so that you won’t have to spend lots of time removing generated artifacts. On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app. We strongly recommend that you preserve this structure as you develop your own Isis application.</p>
+<p>This chapter provides instructions on how to go about actually developing Apache Isis domain applications.</p>
</div>
+<div class="sect2">
+<h3 id="_ug_how-tos_class-structure">3.1. Class Structure</h3>
<div class="paragraph">
-<p>In this chapter we also discuss the <a href="#_ug_getting-started_datanucleus-enhancer">DataNucleus enhancer</a>. <a href="http://www.datanucleus.org/">DataNucleus</a> is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.</p>
+<p>Apache Isis works by building a metamodel of the domain objects: entities, view models and services. The class members of both entities and view models represent both state — (single-valued) properties and (multi-valued) collections — and behaviour — actions. The class members of domain services is simpler: just behaviour, ie actions.</p>
</div>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>In the automatically generated UI a property is rendered as a field. This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity. A collection is generally rendered as a table.</p>
+</div>
+<div class="paragraph">
+<p>In order for Apache Isis to build its metamodel the domain objects must follow some conventions: what we call the <em>Apache Isis Programming Model</em>. This is just an extension of the pojo / JavaBean standard of yesteryear: properties and collections are getters/setters, while actions are simply any remaining <code>public</code> methods.</p>
+</div>
+<div class="paragraph">
+<p>Additional metamodel semantics are inferred both imperatively from <em>supporting methods</em> and declaratively from annotations.</p>
+</div>
+<div class="paragraph">
+<p>In this section we discuss the mechanics of writing domain objects that comply with Apache Isis' programming model.</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>The <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a> automatically configures the enhancer, so there’s little you need to do at this stage. Even so we feel it’s a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you’ll find the app fails to start with (what will seem like) quite an obscure exception message.</p>
+<p>In fact, the Apache Isis programming model is extensible; you can teach Apache Isis new programming conventions and you can remove existing ones; ultimately they amount to syntax. The only real fundamental that can’t be changed is the notion that objects consist of properties, collections and actions.</p>
+</div>
+<div class="paragraph">
+<p>You can learn more about extending Apache Isis programming model <a href="#_ug_extending_programming-model">here</a>.</p>
</div>
</td>
</tr>
</table>
</div>
-<div class="sect2">
-<h3 id="_prerequisites">3.1. Prerequisites</h3>
+<div class="sect3">
+<h4 id="_ug_how-tos_class-structure_class-definition">3.1.1. Class Definition</h4>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
+</div>
<div class="paragraph">
-<p>Apache Isis is a Java based framework, so in terms of prerequisites, you’ll need to install:</p>
+<p>Classes are defined both to Isis and (if an entity) also to JDO/DataNucleus.</p>
</div>
-<div class="ulist">
-<ul>
-<li>
-<p>Java 7 or 8 JDK</p>
-</li>
-<li>
-<p><a href="http://maven.apache.org">Apache Maven</a> 3.0.5 or later</p>
-</li>
-</ul>
+<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.</p>
</div>
<div class="paragraph">
-<p>You’ll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the <a href="cg.html#_cg_ide">Contributors' Guide</a> we have detailed setup instructions for using these two IDEs. If you’re a NetBeans user you should have no problems as it too has strong support for Maven.</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.</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>When building and running within an IDE, you’ll also need to configure the Datanucleus enhancer. This is implemented as a Maven plugin, so in the case of IntelliJ, it’s easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.</p>
+<p>For more on this topic, see the topic discussing modules and <a href="#_ug_more-advanced_decoupling">decoupling</a>.</p>
+</div>
+</td>
+</tr>
+</table>
+</div>
+</div>
+<div class="sect3">
+<h4 id="_ug_how-tos_class-structure_properties">3.1.2. Property</h4>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
+</div>
+<div class="sect4">
+<h5 id="_value_vs_reference_types">Value vs Reference Types</h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>For Eclipse the maven integration story is a little less refined. All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.</p>
+<p>The annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties. The table in the <a href="#_ug_how-tos_class-structure_properties-vs-parameters">Properties vs Parameters</a> section provides a handy reference of each.</p>
</div>
</div>
-<div class="sect2">
-<h3 id="_ug_getting-started_simpleapp-archetype">3.2. SimpleApp Archetype</h3>
+<div class="sect4">
+<h5 id="_optional_properties">Optional Properties</h5>
<div class="paragraph">
-<p>The quickest way to get started with Apache Isis is to run the simple archetype. This will generate a very simple one-class domain model, called <code>SimpleObject</code>, with a single property <code>name</code>.</p>
+<p>JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg <code>int</code>, <code>boolean</code>), but optional if a reference type (eg <code>String</code>, <code>BigDecimal</code> etc). To override optionality in JDO/DataNucleus the <code>@Column(allowsNull="…​")</code> annotations is used.</p>
</div>
<div class="paragraph">
-<p>There is also a corresponding <code>SimpleObjectRepository</code> domain service. From this you can easily rename these initial classes, and extend to build up your own Apache Isis domain application.</p>
+<p>Apache Isis on the other hand assumes that all properties (and action parameters, for that matter) are mandatory, not optional. These defaults can also be overridden using Apache Isis' own annotations, specifically <code>@Property(optionality=…​)</code>.</p>
</div>
-<div class="sect3">
-<h4 id="_generating_the_app">3.2.1. Generating the App</h4>
<div class="paragraph">
-<p>Create a new directory, and <code>cd</code> into that directory.</p>
+<p>These different defaults can lead to incompatibilities between the two frameworks. To counteract that, Apache Isis also recognizes and honours JDO’s <code>@Column(allowsNull=…​)</code>.</p>
</div>
<div class="paragraph">
-<p>To build the app from the latest stable release, then run the following command:</p>
+<p>For example, rather than:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.9.0 \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -B</code></pre>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(allowNulls=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+<span class="directive">private</span> LocalDate date;
+<span class="annotation">@Property</span>(optionality=Optionality.OPTIONAL)
+<span class="directive">public</span> LocalDate getDate() { ... }
+<span class="directive">public</span> <span class="type">void</span> setDate(LocalDate d) { ... }</code></pre>
</div>
</div>
<div class="paragraph">
-<p>where:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>groupId</code> represents your own organization, and</p>
-</li>
-<li>
-<p><code>artifactId</code> is a unique identifier for this app within your organization.</p>
-</li>
-<li>
-<p><code>version</code> is the initial (snapshot) version of your app</p>
-</li>
-</ul>
+<p>you should instead simply write:</p>
</div>
-<div class="paragraph">
-<p>The archetype generation process will then run; it only takes a few seconds.</p>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">private</span> LocalDate date;
+<span class="annotation">@javax</span>.jdo.annotations.Column(allowNulls=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+<span class="directive">public</span> LocalDate getDate() { ... }
+<span class="directive">public</span> <span class="type">void</span> setDate(LocalDate d) { ... }</code></pre>
</div>
-<div class="paragraph">
-<p>We also maintain the archetype for the most current <code>-SNAPSHOT</code>; an app generated with this archetype will contain the latest features of Apache Isis, but the usual caveats apply: some features still in development may be unstable.</p>
</div>
+<div class="admonitionblock warning">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-warning" title="Warning"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>The process is almost identical to that for stable releases, however the <code>archetype:generate</code> goal is called with slightly different arguments:</p>
+<p>With JDO/DataNucleus it’s valid for the <code>@Column</code> annotation to be placed on either the field or the getter. Apache Isis (currently) only looks for annotations on the getter. We therefore recommend that you always place <code>@Column</code> on the gettter.</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.10.0-SNAPSHOT \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
- -B</code></pre>
+</td>
+</tr>
+</table>
</div>
+<div class="paragraph">
+<p>In all cases the framework will search for any incompatibilities in optionality (whether specified explicitly or defaulted implicitly) between Isis' defaults and DataNucleus, and refuse to boot if any are found (fail fast).</p>
</div>
+<div class="sect5">
+<h6 id="_handling_mandatory_properties_in_subtypes">Handling Mandatory Properties in Subtypes</h6>
<div class="paragraph">
-<p>where as before:</p>
+<p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p>
</div>
<div class="ulist">
<ul>
<li>
-<p><code>groupId</code> represents your own organization, and</p>
-</li>
-<li>
-<p><code>artifactId</code> is a unique identifier for this app within your organization.</p>
+<p>"table per hierarchy", or "rollup" (<code>InheritanceStrategy.SUPERCLASS_TABLE</code>)<br></p>
+<div class="paragraph">
+<p>whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up</p>
+</div>
</li>
<li>
-<p><code>version</code> is the initial (snapshot) version of your app</p>
-</li>
-</ul>
-</div>
+<p>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p>
<div class="paragraph">
-<p>but also:</p>
+<p>whereby is a table for both superclass and subclass, in 1:1 correspondence</p>
</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>archetypeVersion</code> is the SNAPSHOT version of Apache Isis.</p>
</li>
<li>
-<p><code>archetypeRepository</code> specifies the location of our snapshot repo (hosted on <a href="http://www.cloudbees.com">CloudBees</a>), and</p>
+<p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p>
+<div class="paragraph">
+<p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p>
+</div>
</li>
</ul>
</div>
<div class="paragraph">
-<p>The archetype generation process will then run; it only takes a few seconds.</p>
+<p>In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.</p>
</div>
+<div class="paragraph">
+<p>In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the <code>@Property(optionality=Optionality.MANDATORY)</code> annotation.</p>
</div>
-<div class="sect3">
-<h4 id="_building_the_app">3.2.2. Building the App</h4>
<div class="paragraph">
-<p>Switch into the root directory of your newly generated app, and build your app:</p>
+<p>For example:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">cd myapp
-mvn clean install</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>where <code>myapp</code> is the <code>artifactId</code> entered above.</p>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubtype</span> <span class="directive">extends</span> SomeSuperType {
+ <span class="directive">private</span> LocalDate date;
+ <span class="annotation">@javax</span>.jdo.annotations.Column(allowNulls=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+ <span class="annotation">@Property</span>(optionality=Optionality.MANDATORY)
+ <span class="directive">public</span> LocalDate getDate() { ... }
+ <span class="directive">public</span> <span class="type">void</span> setDate(LocalDate d) { ... }
+}</code></pre>
</div>
-<div class="sect3">
-<h4 id="_running_the_app">3.2.3. Running the App</h4>
-<div class="paragraph">
-<p>The <code>simpleapp</code> archetype generates a single WAR file, configured to run both the <a href="#_ug_wicket-viewer">Wicket viewer</a> and the <a href="#_ug_restfulobjects-viewer">Restful Objects viewer</a>. The archetype also configures the DataNucleus/JDO Objectstore to use an in-memory HSQLDB connection.</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>Once you’ve built the app, you can run the WAR in a variety of ways.</p>
+<p>The <code>@Property(optionality=…​)</code> annotation is equivalent to the older but still supported <code>@Optional</code> annotation and <code>@Mandatory</code> annotations. Its benefit is that it lumps together all Apache Isis' property metadata in a single annotation. Its downside is that it is rather verbose if the only semantic that needs to be specified — as is often the case — is optionality.</p>
</div>
-<div class="sect4">
-<h5 id="_self_hosted">Self-hosted</h5>
-<div class="paragraph">
-<p>The easiest way to run the app, at least while getting started, is to run the self-hosting version of the WAR. With this style the app runs up its own internal instance of Jetty web server.</p>
+</td>
+</tr>
+</table>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>An alternative way to achieve this is to leave the JDO annotation on the field (where it is invisible to Apache Isis), and rely on Isis' default, eg:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar</code></pre>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+<span class="directive">public</span> <span class="type">class</span> <span class="class">SomeSubtype</span> <span class="directive">extends</span> SomeSuperType {
+ <span class="annotation">@javax</span>.jdo.annotations.Column(allowNulls=<span class="string"><span class="delimiter">"</span><span class="content">true</span><span class="delimiter">"</span></span>)
+ <span class="directive">private</span> LocalDate date;
+ <span class="comment">// mandatory in Apache Isis by default</span>
+ <span class="directive">public</span> LocalDate getDate() { }
+ <span class="directive">public</span> <span class="type">void</span> setDate(LocalDate d) { }
+}</code></pre>
</div>
-<div class="paragraph">
-<p>This can also be accomplished using an embedded Ant target provided in the build script:</p>
</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">mvn -P self-host antrun:run</code></pre>
+<div class="paragraph">
+<p>We recommend the former mapping, though, using <code>@Property(optionality=Optionality.MANDATORY)</code>.</p>
</div>
</div>
</div>
<div class="sect4">
-<h5 id="_using_mvn_jetty_plugin">Using mvn Jetty plugin</h5>
-<div class="paragraph">
-<p>Alternatively, you could run the WAR in a Maven-hosted Jetty instance, though you need to <code>cd</code> into the <code>webapp</code> module:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">cd webapp
-mvn jetty:run</code></pre>
+<h5 id="__code_string_code_s_length"><code>String</code>s (Length)</h5>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
+TODO
+</td>
+</tr>
+</table>
</div>
</div>
+<div class="sect4">
+<h5 id="_ug_how-tos_class-structure_properties_mapping-joda-dates">Mapping JODA Dates</h5>
<div class="paragraph">
-<p>If you use <code>mvn jetty:run</code>, then the context path changes; check the console output (eg link:http://localhost:8080/myapp-webapp [<a href="http://localhost:8080/myapp-webapp" class="bare">http://localhost:8080/myapp-webapp</a>]).</p>
+<p>Isis' JDO objectstore bundles DataNucleus' <a href="http://www.datanucleus.org/documentation/products/plugins.html">built-in support</a> for Joda <code>LocalDate</code> and <code>LocalDateTime</code> datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.</p>
</div>
<div class="paragraph">
-<p>You can also provide a system property to change the port:</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">cd webapp
-mvn jetty:run -D jetty.port=9090</code></pre>
-</div>
+<p>It is, however, necessary to annotate your properties with <code>@javax.jdo.annotations.Persistent</code>, otherwise the data won’t actually be persisted. See the <a href="http://db.apache.org/jdo/field_types.html">JDO docs</a> for more details on this.</p>
</div>
+<div class="paragraph">
+<p>Moreover, these datatypes are <em>not</em> in the default fetch group, meaning that JDO/DataNucleus will perform an additional <code>SELECT</code> query for each attribute. To avoid this extra query, the annotation should indicate that the property is in the default fetch group.</p>
</div>
-<div class="sect4">
-<h5 id="_using_a_regular_servlet_container">Using a regular servlet container</h5>
<div class="paragraph">
-<p>You can also take the built WAR file and deploy it into a standalone servlet container such as [Tomcat](<a href="http://tomcat.apache.org" class="bare">http://tomcat.apache.org</a>). The default configuration does not require any configuration of the servlet container; just drop the WAR file into the <code>webapps</code> directory.</p>
+<p>For example, the <code>ToDoItem</code> (in the <a href="https://github.com/isisaddons/isis-app-todoapp">todoapp example app</a> (not ASF)) defines the <code>dueBy</code> property as follows:</p>
</div>
</div>
<div class="sect4">
-<h5 id="_from_within_the_ide">From within the IDE</h5>
+<h5 id="__code_bigdecimal_code_s_precision"><code>BigDecimal</code>s (Precision)</h5>
<div class="paragraph">
-<p>Most of the time, though, you’ll probably want to run the app from within your IDE. The mechanics of doing this will vary by IDE; see the <a href="cg.html#_cg_ide">Contributors' Guide</a> for details of setting up Eclipse or IntelliJ IDEA. Basically, though, it amounts to running <code>org.apache.isis.WebServer</code>, and ensuring that the <a href="#_ug_getting-started_datanucleus-enhancer">DataNucleus enhancer</a> has properly processed all domain entities.</p>
+<p>Working with <code>java.math.BigDecimal</code> properties takes a little care due to scale/precision issues.</p>
</div>
<div class="paragraph">
-<p>Here’s what the setup looks like in IntelliJ IDEA:</p>
+<p>For example, suppose we have:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/simpleapp-webapp.png"><img src="images/getting-started/simpleapp-webapp.png" alt="simpleapp webapp" width="600px"></a>
-</div>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">private</span> <span class="predefined-type">BigDecimal</span> impact;
+<span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getImpact() {
+ <span class="keyword">return</span> impact;
+}
+<span class="directive">public</span> <span class="type">void</span> setImpact(<span class="directive">final</span> <span class="predefined-type">BigDecimal</span> impact) {
+ <span class="local-variable">this</span>.impact = impact;
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_running_with_fixtures">3.2.4. Running with Fixtures</h4>
<div class="paragraph">
-<p>It is also possible to start the application with a pre-defined set of data; useful for demos or manual exploratory testing. This is done by specifying a <a href="#_ug_testing_fixture-scripts">fixture script</a> on the command line.</p>
+<p>JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details <a href="http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types">here</a>).</p>
</div>
<div class="paragraph">
-<p>If running the self-hosted console, you can specify the fixtures using the <code>--initParam</code> flag:</p>
+<p>What this implies is that, when a record is inserted, a log entry similar to this one appears:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar \
- --initParam isis.persistor.datanucleus.install-fixtures=true \
- --initParam isis.fixtures=domainapp.fixture.scenarios.RecreateSimpleObjects</code></pre>
+<pre class="CodeRay highlight"><code data-lang="java">INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., <span class="float">0.5</span>, ....)</code></pre>
</div>
</div>
<div class="paragraph">
-<p>where (in the above example) <code>domainapp.fixture.scenarios.RecreateSimpleObjects</code> is the fully qualified class name of the fixture
-script to be run.</p>
+<p>But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.</p>
</div>
<div class="paragraph">
-<p>If you are running the app from an IDE, then you can specify the fixture script using the <code>--fixture</code> flag:</p>
+<p>The solution is to explicitly add the scale to the field like this:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/simpleapp-webapp-with-fixtures.png"><img src="images/getting-started/simpleapp-webapp-with-fixtures.png" alt="simpleapp webapp with fixtures" width="600px"></a>
-</div>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(scale=<span class="integer">2</span>)
+<span class="directive">private</span> <span class="predefined-type">BigDecimal</span> impact;
+<span class="directive">public</span> <span class="predefined-type">BigDecimal</span> getImpact() {
+ <span class="keyword">return</span> impact;
+}
+<span class="directive">public</span> <span class="type">void</span> setImpact(<span class="directive">final</span> <span class="predefined-type">BigDecimal</span> impact) {
+ <span class="local-variable">this</span>.impact = impact;
+}</code></pre>
</div>
</div>
-<div class="sect3">
-<h4 id="_using_the_app">3.2.5. Using the App</h4>
<div class="paragraph">
-<p>When you start the app, you’ll be presented with a welcome page from which you can access the webapp using either the <a href="#_ug_wicket-viewer">Wicket viewer</a> or the <a href="#_ug_restfulobjects-viewer">Restful Objects viewer</a>:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/010-root-page.png"><img src="images/getting-started/using-simple-app/010-root-page.png" alt="010 root page" width="600px"></a>
-</div>
+<p>In addition, you should also set the scale of the <code>BigDecimal</code>, using <code>setScale(scale, roundingMode)</code>.</p>
</div>
<div class="paragraph">
-<p>The Wicket viewer provides a human usable web UI (implemented, as you might have guessed from its name, using <a href="http://wicket.apache.org">Apache Wicket</a>), so choose that and navigate to the login page:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/020-login-to-wicket-viewer.png"><img src="images/getting-started/using-simple-app/020-login-to-wicket-viewer.png" alt="020 login to wicket viewer" width="600px"></a>
+<p>More information can be found <a href="http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial">here</a> and <a href="http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm">here</a>.</p>
</div>
</div>
+<div class="sect4">
+<h5 id="_mapping_blobs_and_clobs">Mapping Blobs and Clobs</h5>
<div class="paragraph">
-<p>The app itself is configured to run using <a href="#_ug_security">shiro security</a>, as configured in the <code>WEB-INF/shiro.ini</code> config file. You can login with:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p>username: <em>sven</em></p>
-</li>
-<li>
-<p>password: <em>pass</em></p>
-</li>
-</ul>
+<p>Apache Isis configures JDO/DataNucleus so that the properties of type <code>org.apache.isis.applib.value.Blob</code> and <code>org.apache.isis.applib.value.Clob</code> can also be persisted.</p>
</div>
<div class="paragraph">
-<p>The application is configured to run with an in-memory database, and (unless you started the app with fixture scripts as described above), initially there is no data. We can though run a fixture script from the app itself:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png"><img src="images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png" alt="030 home page run fixture scripts" width="600px"></a>
-</div>
+<p>As for <a href="#_ug_how-tos_class-structure_properties_mapping-joda-dates">Joda dates</a>, this requires the <code>@javax.jdo.annotations.Persistent</code> annotation. However, whereas for dates one would always expect this value to be retrieved eagerly, for blobs and clobs it is not so clear cut.</p>
</div>
+<div class="sect5">
+<h6 id="_mapping_blobs">Mapping Blobs</h6>
<div class="paragraph">
-<p>The fixture script creates three objects, and the action returns the first of these:</p>
+<p>For example, in the <code>ToDoItem</code> class (of the <a href="https://github.com/isisaddons/isis-app-todoapp/blob/61b8114a8e01dbb3c380b31cf09eaed456407570/dom/src/main/java/todoapp/dom/module/todoitem/ToDoItem.java#L475">todoapp example app</a> (non-ASF) the <code>attachment</code> property is as follows:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/040-first-object.png"><img src="images/getting-started/using-simple-app/040-first-object.png" alt="040 first object" width="600px"></a>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Persistent(defaultFetchGroup=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>, columns = {
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_name</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_mimetype</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_bytes</span><span class="delimiter">"</span></span>, jdbcType=<span class="string"><span class="delimiter">"</span><span class="content">BLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">LONGVARBINARY</span><span class="delimiter">"</span></span>)
+})
+<span class="directive">private</span> <span class="predefined-type">Blob</span> attachment;
+<span class="annotation">@Property</span>(
+ optionality = Optionality.OPTIONAL
+)
+<span class="directive">public</span> <span class="predefined-type">Blob</span> getAttachment() {
+ <span class="keyword">return</span> attachment;
+}
+<span class="directive">public</span> <span class="type">void</span> setAttachment(<span class="directive">final</span> <span class="predefined-type">Blob</span> attachment) {
+ <span class="local-variable">this</span>.attachment = attachment;
+}</code></pre>
</div>
</div>
<div class="paragraph">
-<p>The application generated is deliberaetly very minimal; we don’t want you to have to waste valuable time removing generated files. The object contains a single "name" property, and a single action to update that property:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/050-update-name-prompt.png"><img src="images/getting-started/using-simple-app/050-update-name-prompt.png" alt="050 update name prompt" width="600px"></a>
-</div>
+<p>The three <code>@javax.jdo.annotations.Column</code> annotations are required because the mapping classes that Apache Isis provides (<a href="https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59">IsisBlobMapping</a> and <a href="https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59">IsisClobMapping</a>) map to 3 columns. (It is not an error to omit these <code>@Column</code> annotations, but without them the names of the table columns are simply suffixed <code>_0</code>, <code>_1</code>, <code>_2</code> etc.</p>
</div>
<div class="paragraph">
-<p>When you hit OK, the object is updated:</p>
+<p>If the <code>Blob</code> is mandatory, then use:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/060-object-updated.png"><img src="images/getting-started/using-simple-app/060-object-updated.png" alt="060 object updated" width="600px"></a>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Persistent(defaultFetchGroup=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>, columns = {
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_name</span><span class="delimiter">"</span></span>, allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_mimetype</span><span class="delimiter">"</span></span>, allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_bytes</span><span class="delimiter">"</span></span>,
+ jdbcType=<span class="string"><span class="delimiter">"</span><span class="content">BLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">LONGVARBINARY</span><span class="delimiter">"</span></span>,
+ allowsNull=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>)
+})
+<span class="directive">private</span> <span class="predefined-type">Blob</span> attachment;
+<span class="annotation">@Property</span>(
+ optionality = Optionality.MANDATORY
+)
+<span class="directive">public</span> <span class="predefined-type">Blob</span> getAttachment() {
+<span class="keyword">return</span> attachment;
+}
+<span class="directive">public</span> <span class="type">void</span> setAttachment(<span class="directive">final</span> <span class="predefined-type">Blob</span> attachment) {
+<span class="local-variable">this</span>.attachment = attachment;
+}</code></pre>
</div>
</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>For your most signficant domain entities you’ll likely have a domain service to retrieve or create instances of those obejcts. In the generated app we have a "Simple Objects" domain service that lets us list all objects:</p>
+<p>If specifying a <code>sqlType</code> of "LONGVARBINARY" does not work, try instead "BLOB". There can be differences in behaviour between JDBC drivers.</p>
</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/070-list-all-prompt.png"><img src="images/getting-started/using-simple-app/070-list-all-prompt.png" alt="070 list all prompt" width="600px"></a>
+</td>
+</tr>
+</table>
</div>
</div>
+<div class="sect5">
+<h6 id="_mapping_clobs">Mapping Clobs</h6>
<div class="paragraph">
-<p>whereby we see the three objects created by the fixture script (one having been updated):</p>
+<p>Mapping <code>Clob`s works in a very similar way, but the `jdbcType</code> and <code>sqlType</code> attributes will, respectively, be <code>CLOB</code> and <code>LONGVARCHAR</code>:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/080-list-all.png"><img src="images/getting-started/using-simple-app/080-list-all.png" alt="080 list all" width="600px"></a>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Persistent(defaultFetchGroup=<span class="string"><span class="delimiter">"</span><span class="content">false</span><span class="delimiter">"</span></span>, columns = {
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_name</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_mimetype</span><span class="delimiter">"</span></span>),
+ <span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_chars</span><span class="delimiter">"</span></span>,
+ jdbcType=<span class="string"><span class="delimiter">"</span><span class="content">CLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">LONGVARCHAR</span><span class="delimiter">"</span></span>)
+})
+<span class="directive">private</span> <span class="predefined-type">Clob</span> doc;
+<span class="annotation">@Property</span>(
+ optionality = Optionality.OPTIONAL
+)
+<span class="directive">public</span> <span class="predefined-type">Clob</span> getDoc() {
+ <span class="keyword">return</span> doc;
+}
+<span class="directive">public</span> <span class="type">void</span> setDoc(<span class="directive">final</span> <span class="predefined-type">Clob</span> doc) {
+ <span class="local-variable">this</span>.doc = doc;
+}</code></pre>
</div>
</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>and we can also use the domain service to create new instances:</p>
+<p>If specifying a <code>sqlType</code> of "LONGVARCHAR" does not work, try instead "CLOB". There can be differences in behaviour between JDBC drivers.</p>
</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/090-create.png"><img src="images/getting-started/using-simple-app/090-create.png" alt="090 create" width="600px"></a>
+</td>
+</tr>
+</table>
</div>
</div>
+<div class="sect5">
+<h6 id="_mapping_to_varbinary_or_varchar">Mapping to VARBINARY or VARCHAR</h6>
<div class="paragraph">
-<p>prompting us for the mandatory information (the name):</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/100-create-prompt.png"><img src="images/getting-started/using-simple-app/100-create-prompt.png" alt="100 create prompt" width="600px"></a>
-</div>
+<p>Instead of mapping to a sqlType of <code>LONGVARBINARY</code> (or perhaps <code>BLOB</code>), you might instead decide to map to a <code>VARBINARY</code>. The difference is whether the binary data is held "on-row" or as a pointer "off-row"; with a <code>VARBINARY</code> the data is held on-row and so you will need to specify a length.</p>
</div>
<div class="paragraph">
-<p>which, of course, returns the newly created object:</p>
+<p>For example:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/110-object-created.png"><img src="images/getting-started/using-simple-app/110-object-created.png" alt="110 object created" width="600px"></a>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_bytes</span><span class="delimiter">"</span></span>, jdbcTypr=<span class="string"><span class="delimiter">"</span><span class="content">BLOB</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">VARBINARY</span><span class="delimiter">"</span></span>, length=<span class="integer">2048</span>)</code></pre>
</div>
</div>
<div class="paragraph">
-<p>When we list all objects again, we can see that the object was indeed created:</p>
+<p>The same argument applies to <code>LONGVARCHAR</code> (or <code>CLOB</code>); you could instead map to a regular <code>VARCHAR</code>:</p>
</div>
-<div class="imageblock">
+<div class="listingblock">
<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/120-list-all.png"><img src="images/getting-started/using-simple-app/120-list-all.png" alt="120 list all" width="600px"></a>
+<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@javax</span>.jdo.annotations.Column(name = <span class="string"><span class="delimiter">"</span><span class="content">attachment_chars</span><span class="delimiter">"</span></span>, sqlType = <span class="string"><span class="delimiter">"</span><span class="content">VARCHAR</span><span class="delimiter">"</span></span>, length=<span class="integer">2048</span>)</code></pre>
</div>
</div>
<div class="paragraph">
-<p>Going back to the home page (<a href="http://localhost:8080">localhost:8080</a>) we can also access the Restful Objects viewer. The generated application is configured to use HTTP Basic Auth:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/220-login-to-restful-viewer.png"><img src="images/getting-started/using-simple-app/220-login-to-restful-viewer.png" alt="220 login to restful viewer" width="600px"></a>
-</div>
+<p>Support and maximum allowed length will vary by database vendor.</p>
</div>
-<div class="paragraph">
-<p>The Restful Objects viewer provides a REST API for computer-to-computer interaction, but we can still interact with it from a browser:</p>
</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/230-home-page.png"><img src="images/getting-started/using-simple-app/230-home-page.png" alt="230 home page" width="600px"></a>
</div>
</div>
-<div class="admonitionblock tip">
+<div class="sect3">
+<h4 id="_ug_how-tos_class-structure_collections">3.1.3. Collections</h4>
+<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
-<i class="fa icon-tip" title="Tip"></i>
+<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-<div class="paragraph">
-<p>Depending on your browser, you may need to install plugins. For Chrome, we recommend json-view (which renders the JSON indented and automatically detects hyperlinks) and REST Postman.</p>
-</div>
+TODO
</td>
</tr>
</table>
</div>
+<div class="admonitionblock note">
+<table>
+<tr>
+<td class="icon">
+<i class="fa icon-note" title="Note"></i>
+</td>
+<td class="content">
<div class="paragraph">
-<p>The REST API is a complete hypermedia API, in other words you can follow the links to access all the behaviour exposed in the regular Wicket app. For example, we can navigate to the <code>listAll/invoke</code> resource:</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/240-list-all-invoke.png"><img src="images/getting-started/using-simple-app/240-list-all-invoke.png" alt="240 list all invoke" width="600px"></a>
-</div>
+<p>While Apache Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn’t possible to define a collection of type <code>Set<String></code>.</p>
</div>
<div class="paragraph">
-<p>which when invoked (with an HTTP GET) will return a representation of the domain objects.</p>
-</div>
-<div class="imageblock">
-<div class="content">
-<a class="image" href="images/getting-started/using-simple-app/250-list-all-results.png"><img src="images/getting-started/using-simple-app/250-list-all-results.png" alt="250 list all results" width="600px"></a>
-</div>
+<p>Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Apache Isis has no default visualization.</p>
</div>
<div class="paragraph">
-<p>To log in, use <code>sven/pass</code>.</p>
-</div>
+<p>One workaround is to mark the collection as <a href="rg.html#_rg_annotations_manpage-Programmatic"><code>@Programmatic</code></a>. This ensures that the collection is ignored by Apache Isis.</p>
</div>
-<div class="sect3">
-<h4 id="_modifying_the_app">3.2.6. Modifying the App</h4>
<div class="paragraph">
-<p>Once you are familiar with the generated app, you’ll want to start modifying it. There is plenty of guidance on this site; check out the 'programming model how-tos' section on the main <a href="../documentation.html">documentation</a> page first).</p>
+<p>Another workaround is to wrap each value in a view model, as explained in this <a href="#_ug_more-advanced_tips-n-tricks_simulating-collections-of-values">tip</a>.</p>
</div>
-<div class="paragraph">
-<p>If you use Eclipse or IntelliJ IDEA, do also install the <a href="cg.html#_cg_ide-templates">IDE templates</a>; these will help you follow the Apache Isis naming conventions.</p>
+</td>
+</tr>
+</table>
</div>
</div>
<div class="sect3">
-<h4 id="_app_structure">3.2.7. App Structure</h4>
-<div class="paragraph">
-<p>As noted above, the generated app is a very simple application consisting of a single domain object that can be easily renamed and extended. The intention is not to showcase all of Apache Isis' capabilities; rather it is to allow you to very easily modify the generated application (eg rename <code>SimpleObject</code> to <code>Customer</code>) without having to waste time deleting lots of generated code.</p>
-</div>
-<table class="tableblock frame-all grid-all spread">
-<colgroup>
-<col style="width: 25%;">
-<col st
<TRUNCATED>