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/06 06:49:31 UTC
[1/2] isis-site git commit: republishing without missing ug.adoc
sections
Repository: isis-site
Updated Branches:
refs/heads/asf-site 617ea7b1a -> 0cd1bc39c
http://git-wip-us.apache.org/repos/asf/isis-site/blob/0cd1bc39/content/guides/ug.html
----------------------------------------------------------------------
diff --git a/content/guides/ug.html b/content/guides/ug.html
index d18a6b3..057fde1 100644
--- a/content/guides/ug.html
+++ b/content/guides/ug.html
@@ -1833,47 +1833,14 @@ So, if you have used Apache Isis for prototyping (discussed above), then note th
</div>
</div>
<div class="sect1">
-<h2 id="_ug_how-tos">3. How tos</h2>
+<h2 id="_ug_getting-started">3. Getting Started</h2>
<div class="sectionbody">
<div class="paragraph">
-<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>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="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-tip" title="Tip"></i>
-</td>
-<td class="content">
-<div class="paragraph">
-<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>
+<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>
</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>
+<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>
</div>
-<div class="sect3">
-<h4 id="_ug_how-tos_class-structure_class-definition">3.1.1. Class Definition</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -1881,466 +1848,481 @@ So, if you have used Apache Isis for prototyping (discussed above), then note th
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+<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>
+</div>
</td>
</tr>
</table>
</div>
+<div class="sect2">
+<h3 id="_prerequisites">3.1. Prerequisites</h3>
<div class="paragraph">
-<p>Classes are defined both to Isis and (if an entity) also to JDO/DataNucleus.</p>
+<p>Apache Isis is a Java based framework, so in terms of prerequisites, you’ll need to install:</p>
</div>
-<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 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>
<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.</p>
+<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>
</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>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>
+<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>
</div>
<div class="paragraph">
-<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>
+<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>
</div>
</div>
-<div class="sect4">
-<h5 id="_optional_properties">Optional Properties</h5>
+<div class="sect2">
+<h3 id="_ug_getting-started_simpleapp-archetype">3.2. SimpleApp Archetype</h3>
<div class="paragraph">
-<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>
+<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>
</div>
<div class="paragraph">
-<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>
+<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>
</div>
+<div class="sect3">
+<h4 id="_generating_the_app">3.2.1. Generating the App</h4>
<div class="paragraph">
-<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>
+<p>Create a new directory, and <code>cd</code> into that directory.</p>
</div>
<div class="paragraph">
-<p>For example, rather than:</p>
+<p>To build the app from the latest stable release, then run the following command:</p>
</div>
<div class="listingblock">
<div class="content">
-<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>
+<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>
</div>
</div>
<div class="paragraph">
-<p>you should instead simply write:</p>
-</div>
-<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>
+<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>
</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>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>
+<p>The archetype generation process will then run; it only takes a few seconds.</p>
</div>
-</td>
-</tr>
-</table>
+<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="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>
+<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>
+</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>
+</div>
</div>
-<div class="sect5">
-<h6 id="_handling_mandatory_properties_in_subtypes">Handling Mandatory Properties in Subtypes</h6>
<div class="paragraph">
-<p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p>
+<p>where as before:</p>
</div>
<div class="ulist">
<ul>
<li>
-<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>
+<p><code>groupId</code> represents your own organization, and</p>
</li>
<li>
-<p>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p>
-<div class="paragraph">
-<p>whereby is a table for both superclass and subclass, in 1:1 correspondence</p>
-</div>
+<p><code>artifactId</code> is a unique identifier for this app within your organization.</p>
</li>
<li>
-<p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p>
+<p><code>version</code> is the initial (snapshot) version of your app</p>
+</li>
+</ul>
+</div>
<div class="paragraph">
-<p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p>
+<p>but also:</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>
</li>
</ul>
</div>
<div class="paragraph">
-<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>
+<p>The archetype generation process will then run; it only takes a few seconds.</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>For example:</p>
+<p>Switch into the root directory of your newly generated app, and build your app:</p>
</div>
<div class="listingblock">
<div class="content">
-<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>
+<pre class="CodeRay highlight"><code data-lang="bash">cd myapp
+mvn clean install</code></pre>
</div>
</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 <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>
+<p>where <code>myapp</code> is the <code>artifactId</code> entered above.</p>
</div>
-</td>
-</tr>
-</table>
</div>
+<div class="sect3">
+<h4 id="_running_the_app">3.2.3. Running the App</h4>
<div class="paragraph">
-<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>
+<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="paragraph">
+<p>Once you’ve built the app, you can run the WAR in a variety of ways.</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>
+</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="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>
+<pre class="CodeRay highlight"><code data-lang="bash">java -jar webapp/target/myapp-webapp-1.0-SNAPSHOT-jetty-console.jar</code></pre>
</div>
</div>
<div class="paragraph">
-<p>We recommend the former mapping, though, using <code>@Property(optionality=Optionality.MANDATORY)</code>.</p>
-</div>
+<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>
-<div class="sect4">
-<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>
+<h5 id="_using_mvn_jetty_plugin">Using mvn Jetty plugin</h5>
<div class="paragraph">
-<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>
+<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>
+</div>
</div>
<div class="paragraph">
-<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>
+<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>
</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>
+<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>
+</div>
+</div>
+<div class="sect4">
+<h5 id="_using_a_regular_servlet_container">Using a regular servlet container</h5>
<div class="paragraph">
-<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>
+<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>
</div>
</div>
<div class="sect4">
-<h5 id="__code_bigdecimal_code_s_precision"><code>BigDecimal</code>s (Precision)</h5>
+<h5 id="_from_within_the_ide">From within the IDE</h5>
<div class="paragraph">
-<p>Working with <code>java.math.BigDecimal</code> properties takes a little care due to scale/precision issues.</p>
+<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>
</div>
<div class="paragraph">
-<p>For example, suppose we have:</p>
+<p>Here’s what the setup looks like in IntelliJ IDEA:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</div>
+</div>
+<div class="sect3">
+<h4 id="_running_with_fixtures">3.2.4. Running with Fixtures</h4>
<div class="paragraph">
-<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>
+<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>
</div>
<div class="paragraph">
-<p>What this implies is that, when a record is inserted, a log entry similar to this one appears:</p>
+<p>If running the self-hosted console, you can specify the fixtures using the <code>--initParam</code> flag:</p>
</div>
<div class="listingblock">
<div class="content">
-<pre class="CodeRay highlight"><code data-lang="java">INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., <span class="float">0.5</span>, ....)</code></pre>
+<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>
</div>
</div>
<div class="paragraph">
-<p>But when that same record is retrieved, the log will show that a value of "0" is returned, instead of 0.5.</p>
+<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>
</div>
<div class="paragraph">
-<p>The solution is to explicitly add the scale to the field like this:</p>
+<p>If you are running the app from an IDE, then you can specify the fixture script using the <code>--fixture</code> flag:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</div>
</div>
+<div class="sect3">
+<h4 id="_using_the_app">3.2.5. Using the App</h4>
<div class="paragraph">
-<p>In addition, you should also set the scale of the <code>BigDecimal</code>, using <code>setScale(scale, roundingMode)</code>.</p>
+<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>
</div>
<div class="paragraph">
-<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>
+<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>
</div>
</div>
-<div class="sect4">
-<h5 id="_mapping_blobs_and_clobs">Mapping Blobs and Clobs</h5>
<div class="paragraph">
-<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>
+<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>
</div>
<div class="paragraph">
-<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>
+<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>
</div>
-<div class="sect5">
-<h6 id="_mapping_blobs">Mapping Blobs</h6>
<div class="paragraph">
-<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>
+<p>The fixture script creates three objects, and the action returns the first of these:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</div>
</div>
<div class="paragraph">
-<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>
+<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>
</div>
<div class="paragraph">
-<p>If the <code>Blob</code> is mandatory, then use:</p>
+<p>When you hit OK, the object is updated:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</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>If specifying a <code>sqlType</code> of "LONGVARBINARY" does not work, try instead "BLOB". There can be differences in behaviour between JDBC drivers.</p>
+<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>
</div>
-</td>
-</tr>
-</table>
+<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>
</div>
</div>
-<div class="sect5">
-<h6 id="_mapping_clobs">Mapping Clobs</h6>
<div class="paragraph">
-<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>
+<p>whereby we see the three objects created by the fixture script (one having been updated):</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</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>If specifying a <code>sqlType</code> of "LONGVARCHAR" does not work, try instead "CLOB". There can be differences in behaviour between JDBC drivers.</p>
+<p>and we can also use the domain service to create new instances:</p>
</div>
-</td>
-</tr>
-</table>
+<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>
</div>
</div>
-<div class="sect5">
-<h6 id="_mapping_to_varbinary_or_varchar">Mapping to VARBINARY or VARCHAR</h6>
<div class="paragraph">
-<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>
+<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>
</div>
<div class="paragraph">
-<p>For example:</p>
+<p>which, of course, returns the newly created object:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</div>
</div>
<div class="paragraph">
-<p>The same argument applies to <code>LONGVARCHAR</code> (or <code>CLOB</code>); you could instead map to a regular <code>VARCHAR</code>:</p>
+<p>When we list all objects again, we can see that the object was indeed created:</p>
</div>
-<div class="listingblock">
+<div class="imageblock">
<div class="content">
-<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>
+<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>
</div>
</div>
<div class="paragraph">
-<p>Support and maximum allowed length will vary by database vendor.</p>
+<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>
</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="sect3">
-<h4 id="_ug_how-tos_class-structure_collections">3.1.3. Collections</h4>
-<div class="admonitionblock note">
+<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">
<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>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>
</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>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>
+<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>
</div>
<div class="paragraph">
-<p>Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Apache Isis has no default visualization.</p>
+<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>
</div>
<div class="paragraph">
-<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>
+<p>To log in, use <code>sven/pass</code>.</p>
+</div>
</div>
+<div class="sect3">
+<h4 id="_modifying_the_app">3.2.6. Modifying the App</h4>
<div class="paragraph">
-<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>
+<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>
</div>
-</td>
+<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>
+</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 style="width: 75%;">
+</colgroup>
+<thead>
+<tr>
+<th class="tableblock halign-left valign-top">Module</th>
+<th class="tableblock halign-left valign-top">Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The parent (aggregator) module</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp-app</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">(1.9.0) The "app" module, containing the (optional) app manifest and any application-level services.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp-dom</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">The domain object model, consisting of <code>SimpleObject</code> and <code>SimpleObjects</code> (repository) domain service.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp-fixture</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Domain object fixtures used for initializing the system when being demo’ed or for unit testing.</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp-integtests</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">End-to-end <a href="#_ug_testing_integ-test-support">integration tests</a> that exercise from the UI through to the database</p></td>
+</tr>
+<tr>
+<td class="tableblock halign-left valign-top"><p class="tableblock"><code>myapp-webapp</code></p></td>
+<td class="tableblock halign-left valign-top"><p class="tableblock">Run as a webapp (from <code>web.xml</code>) hosting the <a href="#_ug_wicket-viewer">Wicket viewer</a> and/or the <a href="#_ug_restfulobjects-viewer">RestfulObjects viewer</a></p></td>
</tr>
+</tbody>
</table>
+<div class="paragraph">
+<p>If you run into issues, please don’t hesitate to ask for help on the <a href="http://isis.apache.org/help.html">users mailing list</a>.</p>
</div>
</div>
-<div class="sect3">
-<h4 id="_ug_how-tos_class-structure_actions">3.1.4. Actions</h4>
+</div>
+<div class="sect2">
+<h3 id="_ug_getting-started_datanucleus-enhancer">3.3. Datanucleus Enhancer</h3>
+<div class="paragraph">
+<p><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. Datanucleus is a very powerful library, allowing domain entities to be mapped not only to relational database tables, but also to NoSQL stores such as <a href="http://neo4j.com/">Neo4J</a>, <a href="http://www.mongodb.org/">MongoDB</a> and <a href="http://cassandra.apache.org/">Apache Cassandra</a>.</p>
+</div>
+<div class="paragraph">
+<p>With such power comes a little bit of complexity to the development environment: all domain entities must be enhanced through the DataNucleus enhancer.</p>
+</div>
<div class="admonitionblock note">
<table>
<tr>
@@ -2348,75 +2330,177 @@ TODO
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<p>Bytecode enhancement is actually a requirement of the JDO spec; the process is described in outline <a href="http://db.apache.org/jdo/enhancement.html">here</a>.</p>
+</div>
</td>
</tr>
</table>
</div>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>What this means is that the enhancer — available as both a Maven plugin and as an Eclipse plugin — must, one way or another, be integrated into your development environment.</p>
+</div>
+<div class="paragraph">
+<p>If working from the Maven command line, JDO enhancement is done using the <code>maven-datanucleus-plugin</code>. As of 1.9.0, we put all the configuration into an (always active) profile:</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>While Apache Isis support actions whose parameters' types are scalar (values such as <code>String</code>, <code>int</code>, or references such as <code>Customer</code>), the framework (currently) does not support parameter types that are collections or maps.</p>
-</div>
-<div class="paragraph">
-<p>The workaround is to mark the collection as <code>@Programmatic</code>, as described in <a href="#_ug_how-tos_class-structure_ignoring-methods">Ignoring Methods</a>. This ensures that the collection is ignored by Apache Isis.</p>
+<p>The configuration described below is automatically set up by the <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a>.</p>
</div>
</td>
</tr>
</table>
</div>
+<div class="listingblock">
+<div class="content">
+<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag"><profile></span>
+ <span class="tag"><id></span>enhance<span class="tag"></id></span>
+ <span class="tag"><activation></span>
+ <span class="tag"><activeByDefault></span>true<span class="tag"></activeByDefault></span>
+ <span class="tag"></activation></span>
+ <span class="tag"><properties></span>
+ <span class="tag"><datanucleus-maven-plugin.version></span>4.0.1<span class="tag"></datanucleus-maven-plugin.version></span>
+ <span class="tag"></properties></span>
+ <span class="tag"><build></span>
+ <span class="tag"><plugins></span>
+ <span class="tag"><plugin></span>
+ <span class="tag"><groupId></span>org.datanucleus<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>datanucleus-maven-plugin<span class="tag"></artifactId></span>
+ <span class="tag"><version></span>${datanucleus-maven-plugin.version}<span class="tag"></version></span>
+ <span class="tag"><configuration></span>
+ <span class="tag"><fork></span>false<span class="tag"></fork></span>
+ <span class="tag"><log4jConfiguration></span>${basedir}/log4j.properties<span class="tag"></log4jConfiguration></span>
+ <span class="tag"><verbose></span>true<span class="tag"></verbose></span>
+ <span class="tag"><props></span>${basedir}/datanucleus.properties<span class="tag"></props></span>
+ <span class="tag"></configuration></span>
+ <span class="tag"><executions></span>
+ <span class="tag"><execution></span>
+ <span class="tag"><phase></span>process-classes<span class="tag"></phase></span>
+ <span class="tag"><goals></span>
+ <span class="tag"><goal></span>enhance<span class="tag"></goal></span>
+ <span class="tag"></goals></span>
+ <span class="tag"></execution></span>
+ <span class="tag"></executions></span>
+ <span class="tag"></plugin></span>
+ <span class="tag"></plugins></span>
+ <span class="tag"></build></span>
+ <span class="tag"><dependencies></span>
+ <span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>org.datanucleus<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>datanucleus-core<span class="tag"></artifactId></span>
+ <span class="tag"></dependency></span>
+ <span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>org.datanucleus<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>datanucleus-jodatime<span class="tag"></artifactId></span>
+ <span class="tag"></dependency></span>
+ <span class="tag"><dependency></span>
+ <span class="tag"><groupId></span>org.datanucleus<span class="tag"></groupId></span>
+ <span class="tag"><artifactId></span>datanucleus-api-jdo<span class="tag"></artifactId></span>
+ <span class="tag"></dependency></span>
+ <span class="tag"></dependencies></span>
+<span class="tag"></profile></span></code></pre>
+</div>
+</div>
+<div class="paragraph">
+<p>The <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a> sets up the plugin correctly in the <code>dom</code> (domain object model) module. (It’s actually a little bit more complex to cater for users of the Eclipse IDE using Eclipse’s m2e plugin).</p>
</div>
<div class="sect3">
-<h4 id="_ug_how-tos_class-structure_action-parameters">3.1.5. Action Parameters</h4>
-<div class="admonitionblock note">
+<h4 id="__code_meta_inf_persistence_xml_code">3.3.1. <code>META-INF/persistence.xml</code></h4>
+<div class="paragraph">
+<p>It’s also a good idea to ensure that the <code>dom</code> module has a JDO <code>META-INF/persistence.xml</code> file:</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"><persistence</span> <span class="attribute-name">xmlns</span>=<span class="string"><span class="delimiter">"</span><span class="content">http://java.sun.com/xml/ns/persistence</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://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd</span><span class="delimiter">"</span></span> <span class="attribute-name">version</span>=<span class="string"><span class="delimiter">"</span><span class="content">1.0</span><span class="delimiter">"</span></span><span class="tag">></span>
+
+ <span class="tag"><persistence-unit</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">"</span><span class="content">simple</span><span class="delimiter">"</span></span><span class="tag">></span> <i class="conum" data-value="1"></i><b>(1)</b>
+ <span class="tag"></persistence-unit></span>
+<span class="tag"></persistence></span></code></pre>
+</div>
+</div>
+<div class="colist arabic">
<table>
<tr>
-<td class="icon">
-<i class="fa icon-note" title="Note"></i>
-</td>
-<td class="content">
-TODO
-</td>
+<td><i class="conum" data-value="1"></i><b>1</b></td>
+<td>change as required; typically is the name of the app.</td>
</tr>
</table>
</div>
-<div class="sect4">
-<h5 id="__code_string_code_s_length_2"><code>String</code>s (Length)</h5>
-<div class="admonitionblock note">
+<div class="paragraph">
+<p>Again, the <a href="#_ug_getting-started_simpleapp-archetype">SimpleApp archetype</a> does this.</p>
+</div>
+<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<p>If running on Windows, then there’s a good chance you’ll hit the <a href="http://msdn.microsoft.com/en-us/library/aa365247%28VS.85%29.aspx#maxpath">maximum path length limit</a>. In this case the <code>persistence.xml</code> file is mandatory rather than optional.</p>
+</div>
+<div class="paragraph">
+<p>This file is also required if you are using developing in Eclipse and relying on the DataNucleus plugin for Eclipse rather than the DataNucleus plugin for Maven. More information can be found <a href="cg.html#_cg_ide_eclipse">here</a>.</p>
+</div>
</td>
</tr>
</table>
</div>
</div>
-<div class="sect4">
-<h5 id="__code_bigdecimal_code_s_precision_2"><code>BigDecimal</code>s (Precision)</h5>
-<div class="admonitionblock note">
+</div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_ug_how-tos">4. How tos</h2>
+<div class="sectionbody">
+<div class="paragraph">
+<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">4.1. Class Structure</h3>
+<div class="paragraph">
+<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="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">
-TODO
+<div class="paragraph">
+<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>
-<div class="sect4">
-<h5 id="_optional">Optional</h5>
+<div class="sect3">
+<h4 id="_ug_how-tos_class-structure_class-definition">4.1.1. Class Definition</h4>
<div class="admonitionblock note">
<table>
<tr>
@@ -2429,96 +2513,46 @@ TODO
</tr>
</table>
</div>
+<div class="paragraph">
+<p>Classes are defined both to Isis and (if an entity) also to JDO/DataNucleus.</p>
</div>
+<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="sect3">
-<h4 id="_ug_how-tos_class-structure_inject-services">3.1.6. Injecting services</h4>
<div class="paragraph">
-<p>Apache Isis autowires (automatically injects) domain services into each entity, as well as into the domain services themselves, using either method injection or field injection. The applib <code>DomainObjectContainer</code> is also a service, so can be injected in exactly the same manner.</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 note">
+<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>Isis currently does <em>not</em> support qualified injection of services; the domain service of each type must be distinct from any other.</p>
-</div>
-<div class="paragraph">
-<p>If you find a requirement to inject two instances of type <code>SomeService</code>, say, then the work-around is to create trivial subclasses <code>SomeServiceA</code> and <code>SomeServiceB</code> and inject these instead.</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 class="sect4">
-<h5 id="_field_injection">Field Injection</h5>
-<div class="paragraph">
-<p>Field injection is recommended, using the <code>@javax.inject.Inject</code> annotation. 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="annotation">@javax</span>.inject.Inject
- OrderRepository orderRepository;
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>We recommend using default rather than <code>private</code> visibility so that the field can be mocked out within unit tests (placed in the same package as the code under test).</p>
-</div>
-</div>
-<div class="sect4">
-<h5 id="_method_injection">Method Injection</h5>
-<div class="paragraph">
-<p>Isis also supports two forms of method injection. All that is required to inject a service into a entity/service is to provide an appropriate method or field. The name
-of the method does not matter, only that it is prefixed either <code>set</code> or <code>inject</code>, is
-public, and has a single parameter of the correct type.</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">private</span> OrderRepository orderRepository;
- <span class="directive">public</span> <span class="type">void</span> setOrderRepository(OrderRepository orderRepository) {
- <span class="local-variable">this</span>.orderRepository = orderRepository;
- }
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>or alternatively, using 'inject' as the prefix:</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> OrderRepository orderRepository;
- <span class="directive">public</span> <span class="type">void</span> injectOrderRepository(OrderRepository orderRepository) {
- <span class="local-variable">this</span>.orderRepository = orderRepository;
- }
- ...
-}</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Note that the method name can be anything; it doesn’t need to be related to the type being injected.</p>
</div>
+<div class="sect3">
+<h4 id="_ug_how-tos_class-structure_properties">4.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="_constructor_injection">Constructor injection</h5>
-<div class="paragraph">
-<p>Simply to note that constructor injection is <em>not</em> supported by Apache Isis (and is unlikely to be, because the JDO specification for entities requires a no-arg constructor).</p>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_ug_how-tos_class-structure_properties-vs-parameters">3.1.7. Properties vs Parameters</h4>
+<h5 id="_value_vs_reference_types">Value vs Reference Types</h5>
<div class="admonitionblock note">
<table>
<tr>
@@ -2532,321 +2566,7498 @@ TODO
</table>
</div>
<div class="paragraph">
-<p>In many cases the value types of properties and of action parameters align. For example, a <code>Customer</code> entity might have a <code>surname</code> property, and there might also be corresponding <code>changeSurname</code>. Ideally we want the surname property and surname action parameter to use the same value type.</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="sect4">
+<h5 id="_optional_properties">Optional Properties</h5>
<div class="paragraph">
-<p>Having first-class support for this is a goal of Apache Isis, and it is already possible (by writing some plumbing and glue code using Isis and DataNucleus APIs) to get some way towards this ideal. However, in the vast majority of cases it is much easier and more practical to simply use standard value types such as <code>java.lang.String</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>However, the JDO/DataNucleus annotations for specifying semantics such as optionality or maximum length are restricted to only apply to fields and to methods; they cannot be applied to action parameters. It is therefore necessary to use Apache Isis' equivalent annotations for action parameters.</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="paragraph">
-<p>The table below summarises the equivalence of some of the most common cases.</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>
-<table class="tableblock frame-all grid-all spread">
-<caption class="title">Table 1. Comparing annotations of Properties vs Action Parameters</caption>
-<colgroup>
-<col style="width: 25%;">
-<col style="width: 37%;">
-<col style="width: 37%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">value type/semantic</th>
-<th class="tableblock halign-left valign-top">property</th>
-<th class="tableblock halign-left valign-top">action parameter</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">string (length)</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">big decimal (precision)</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Isis blob</p></td>
-<td class="tableblock halign-left valign-top"></td>
-<td class="tableblock halign-left valign-top"></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">optional</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>@Column(allowsNull="true")</code></p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>ParameterLayout(optionality=Optionality.OPTIONAL</code>) or <code>@Optional</code></p></td>
-</tr>
-</tbody>
-</table>
+<div class="paragraph">
+<p>For example, rather than:</p>
</div>
-<div class="sect3">
-<h4 id="_ug_how-tos_class-structure_ignoring-methods">3.1.8. Ignoring Methods</h4>
-<div class="admonitionblock note">
+<div class="listingblock">
+<div class="content">
+<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>you should instead simply write:</p>
+</div>
+<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>
+<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
-<i class="fa icon-note" title="Note"></i>
+<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
-TODO
+<div class="paragraph">
+<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>
</td>
</tr>
</table>
</div>
<div class="paragraph">
-<p>Sometimes you want to define a <code>public</code> method on a domain object that is not intended to be rendered in Apache Isis' UI.</p>
-</div>
-<div class="paragraph">
-<p>To exclude such methods, use the <a href="rg.html#_rg_annotations_manpage-Programmatic"><code>@Programmatic</code></a> annotation.</p>
-</div>
-</div>
+<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="sect2">
-<h3 id="_ug_how-tos_ui-hints">3.2. UI Hints</h3>
+<div class="sect5">
+<h6 id="_handling_mandatory_properties_in_subtypes">Handling Mandatory Properties in Subtypes</h6>
<div class="paragraph">
-<p>The Apache Isis programming model includes several mechanisms for a domain object to provide UI hints. These range from their title (so an end-user can distinguish one object from another) through to hints that can impact their CSS styling.</p>
+<p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p>
</div>
-<div class="sect3">
-<h4 id="_ug_how-tos_ui-hints_object-titles-and-icons">3.2.1. Object Titles and Icons</h4>
+<div class="ulist">
+<ul>
+<li>
+<p>"table per hierarchy", or "rollup" (<code>InheritanceStrategy.SUPERCLASS_TABLE</code>)<br></p>
<div class="paragraph">
-<p>In Apache Isis every object is identified to the user by a title (label) and an icon. This is shown in several places: as the main heading for an object; as a link text for an object referencing another object, and also in tables representing collections of objects.</p>
+<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>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p>
<div class="paragraph">
-<p>The icon is often the same for all instances of a particular class, but it’s also possible for an individual instance to return a custom icon. This could represent the state of that object (eg a shipped order, say, or overdue library book).</p>
+<p>whereby is a table for both superclass and subclass, in 1:1 correspondence</p>
</div>
+</li>
+<li>
+<p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p>
<div class="paragraph">
-<p>It is also possible for an object to provide a CSS class hint. In conjunction with <a href="#_ug_wicket-viewer_customisation_tweaking-css-classes">customized CSS</a> this can be used to apply arbitrary styling; for example each object could be rendered in a page with a different background colour.</p>
+<p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p>
</div>
-<div class="sect4">
-<h5 id="_object_title">Object Title</h5>
-<div class="paragraph">
-<p>The object title is a label to identify an object to the end-user. Generally the object title is a label to identify an object to the end-user. There is no requirement for it to be absolutely unique, but it should be "unique enough" to distinguish the object from other object’s likely to be rendered on the same page.</p>
+</li>
+</ul>
</div>
<div class="paragraph">
-<p>The title is always shown with an icon, so there is generally no need for the title to include information about the object’s type. For example the title of a customer object shouldn’t include the literal string "Customer"; it can just have the customer’s name, reference or some other meaningful business identifier.</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="sect5">
-<h6 id="_declarative_style">Declarative style</h6>
<div class="paragraph">
-<p>The <a href="rg.html#_rg_annotations_manpage-Title"><code>@Title</code></a> annotation can be used build up the title of an object from its constituent parts.</p>
+<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="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="annotation">@Title</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">1</span><span class="delimiter">"</span></span>, append=<span class="string"><span class="delimiter">"</span><span class="content"> </span><span class="delimiter">"</span></span>)
- <span class="directive">public</span> <span class="predefined-type">String</span> getFirstName() { ... }
- <span class="annotation">@Title</span>(sequence=<span class="string"><span class="delimiter">"</span><span class="content">2</span><span class="delimiter">"</span></span>)
- <span class="directive">public</span> Product getLastName() { ... }
- ...
+<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>
+<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 <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>
+</td>
+</tr>
+</table>
+</div>
+<div class="paragraph">
+<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="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>
+<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="__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>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>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="paragraph">
+<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="__code_bigdecimal_code_s_precision"><code>BigDecimal</code>s (Precision)</h5>
+<div class="paragraph">
+<p>Working with <code>java.math.BigDecimal</code> properties takes a little care due to scale/precision issues.</p>
+</div>
+<div class="paragraph">
+<p>For example, suppose we have:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<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="paragraph">
+<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>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="java">INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., <span class="float">0.5</span>, ....)</code></pre>
+</div>
+</div>
+<div class="paragraph">
+<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>The solution is to explicitly add the scale to the field like this:</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<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="paragraph">
+<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>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>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>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 t
<TRUNCATED>
[2/2] isis-site git commit: republishing without missing ug.adoc
sections
Posted by da...@apache.org.
republishing without missing ug.adoc sections
Project: http://git-wip-us.apache.org/repos/asf/isis-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis-site/commit/0cd1bc39
Tree: http://git-wip-us.apache.org/repos/asf/isis-site/tree/0cd1bc39
Diff: http://git-wip-us.apache.org/repos/asf/isis-site/diff/0cd1bc39
Branch: refs/heads/asf-site
Commit: 0cd1bc39cedb4a48d93e0dc2943c358eda8037eb
Parents: 617ea7b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Fri Nov 6 00:11:57 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Fri Nov 6 00:11:57 2015 +0000
----------------------------------------------------------------------
content/guides/ug.html | 14332 ++++++++++++++++++++++++++++++++++--------
1 file changed, 11771 insertions(+), 2561 deletions(-)
----------------------------------------------------------------------