[10/51] [partial] isis-site git commit: ISIS-1810: updates with first draft of 2.0.0-M1 release.

danhaywood Sun, 12 Aug 2018 10:38:23 -0700

http://git-wip-us.apache.org/repos/asf/isis-site/blob/2f475bbf/content/versions/2.0.0-M1/guides/ugodn/ugodn.html
----------------------------------------------------------------------
diff --git a/content/versions/2.0.0-M1/guides/ugodn/ugodn.html 
b/content/versions/2.0.0-M1/guides/ugodn/ugodn.html
new file mode 100644
index 0000000..0c5f25c
--- /dev/null
+++ b/content/versions/2.0.0-M1/guides/ugodn/ugodn.html
@@ -0,0 +1,2102 @@
+<!doctype html>
+<html>
+ <head> 
+  <!--
+        Licensed to the Apache Software Foundation (ASF) under one
+        or more contributor license agreements.  See the NOTICE file
+        distributed with this work for additional information
+        regarding copyright ownership.  The ASF licenses this file
+        to you under the Apache License, Version 2.0 (the
+        "License"); you may not use this file except in compliance
+        with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing,
+        software distributed under the License is distributed on an
+        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+        KIND, either express or implied.  See the License for the
+        specific language governing permissions and limitations
+        under the License.
+    --> 
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 
+  <meta charset="utf-8"> 
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"> 
+  <!-- No caching headers --> 
+  <meta http-equiv="cache-control" content="no-cache"> 
+  <meta http-equiv="pragma" content="no-cache"> 
+  <meta http-equiv="expires" content="-1"> 
+  <title>DataNucleus Object Store</title> 
+  <link rel="icon" type="image/png" href="../../images/isis-favicon.png"> 
+  <!--
+        Based on DataNucleus' template,
+        that was in turn based on an earlier version of Apache Isis' template,
+        that was in turn based on Apache Deltaspike's template.
+
+        This template uses
+        * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
+        * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
+          for the table of contents.
+        * jQuery (necessary for Bootstrap's JavaScript plugins)
+        * Font-Awesome for some icons used by Asciidoctor
+
+        Also:
+        * Bootswatch "flatly" theme for Bootstrap 
(https://bootswatch.com/flatly).
+        * slick.js (carousel)
+        * add a link to all headers (home-grown, adapted from blog posts)
+        * integration of elasticlunr.js (home-grown, adapted from blog posts)
+    --> 
+  <link 
href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css";
 rel="stylesheet"> 
+  <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" 
rel="stylesheet"> 
+  <link href="../../css/asciidoctor/foundation.css" rel="stylesheet"> 
+  <link 
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css";
 rel="stylesheet"> 
+  <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet"> 
+  <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet"> 
+  <link href="../../css/search-panel/search-panel.css" rel="stylesheet"> 
+  <link href="../../css/header-links/header-links.css" rel="stylesheet"> 
+  <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet"> 
+  <link href="../../css/customisations.css" rel="stylesheet"> 
+  <!-- Coderay syntax formatter --> 
+  <style type="text/css">
+        /* Stylesheet for CodeRay to match GitHub theme | MIT License | 
http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay 
span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top;line-height:1.45}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+    </style> 
+ </head> 
+ <body data-spy="scroll" data-target="#toc"> 
+  <div id="basedir" style="display:none;">
+   ../../
+  </div> 
+  <div id="docname" style="display:none;">
+   ugodn
+  </div> 
+  <div id="filetype" style="display:none;">
+   html
+  </div> 
+  <!-- Navbar --> 
+  <nav class="navbar navbar-default navbar-static-top header"> 
+   <div class="container"> 
+    <div class="navbar-header"> 
+     <!-- Three line menu button for use on mobile screens --> 
+     <button type="button" class="navbar-toggle collapsed" 
data-toggle="collapse" data-target="#navbar" aria-expanded="false" 
aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span 
class="icon-bar"></span> <span class="icon-bar"></span> <span 
class="icon-bar"></span> </button> 
+     <a class="navbar-brand" href="../../index.html"> <img alt="Brand" 
src="../../images/isis-logo-48x48.png"> </a> 
+     <a class="navbar-brand" href="../../index.html">Apache Isis</a> 
+    </div> 
+    <!-- Navbar that will collapse on mobile screens --> 
+    <div id="navbar" class="navbar-collapse collapse"> 
+     <ul class="nav navbar-nav"> 
+      <li class="dropdown"> <a href="#" class="dropdown-toggle" 
data-toggle="dropdown" role="button" aria-haspopup="true" 
aria-expanded="false">Documentation<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li><a href="../../documentation.html">Table of Contents</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">User Guides</li> 
+        <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li> 
+        <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li> 
+        <li><a href="../../guides/ugvro/ugvro.html">Restful Objects 
Viewer</a></li> 
+        <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object 
Store</a></li> 
+        <li><a href="../../guides/ugsec/ugsec.html">Security</a></li> 
+        <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li> 
+        <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Reference Guides</li> 
+        <li><a href="../../guides/rgant/rgant.html">Annotations</a></li> 
+        <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li> 
+        <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' 
Properties</a></li> 
+        <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and 
Schema</a></li> 
+        <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li> 
+        <li><a href="../../guides/rgfis/rgfis.html">Framework Internal 
Services</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Javadoc</li> 
+        <li><a 
href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib";>Applib</a></li>
 
+       </ul> </li> 
+      <li class="dropdown  hidden-sm hidden-md"> <a href="#" 
class="dropdown-toggle" data-toggle="dropdown" role="button" 
aria-haspopup="true" aria-expanded="false">Downloads<span 
class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li class="dropdown-header">Maven archetypes</li> 
+        <li><a 
href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
 
+        <li><a 
href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
 
+        <li role="separator" class="divider"></li> 
+        <li><a href="../../downloads.html">Downloads</a></li> 
+        <li><a href="../../release-notes/release-notes.html">Release 
Notes</a></li> 
+        <li><a href="../../migration-notes/migration-notes.html">Migration 
Notes</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li><a href="https://github.com/apache/isis";>Github mirror</a></li> 
+       </ul> </li> 
+      <li class="dropdown  hidden-sm"> <a href="#" class="dropdown-toggle" 
data-toggle="dropdown" role="button" aria-haspopup="true" 
aria-expanded="false">Support<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li class="dropdown-header">Guides</li> 
+        <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li> 
+        <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li> 
+        <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Mailing Lists</li> 
+        <li><a href="../../support.html">How to subscribe</a></li> 
+        <li><a 
href="https://lists.apache.org/list.html?us...@isis.apache.org";>Archives (ASF 
Pony mail)</a></li> 
+        <li><a href="http://isis.markmail.org/search/?q=";>Archives 
(Markmail)</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li class="dropdown-header">Other Resources</li> 
+        <li><a href="https://issues.apache.org/jira/browse/ISIS";>ASF 
JIRA</a></li> 
+        <li><a href="https://stackoverflow.com/questions/tagged/isis";>Stack 
Overflow</a></li> 
+        <li><a href="../../help.html">Wiki, Fisheye etc.</a></li> 
+       </ul> </li> 
+      <li class="dropdown hidden-sm hidden-md"> <a href="#" 
class="dropdown-toggle" data-toggle="dropdown" role="button" 
aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a> 
+       <ul class="dropdown-menu"> 
+        <li><a href="https://www.apache.org/";>Apache Homepage</a></li> 
+        <li><a 
href="https://www.apache.org/events/current-event";>Events</a></li> 
+        <li><a href="https://www.apache.org/licenses/";>Licenses</a></li> 
+        <li><a href="https://www.apache.org/security/";>Security</a></li> 
+        <li><a 
href="https://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li> 
+        <li><a 
href="https://www.apache.org/foundation/thanks.html";>Thanks</a></li> 
+        <li role="separator" class="divider"></li> 
+        <li><a href="https://whimsy.apache.org/board/minutes/Isis.html";>PMC 
board minutes</a></li> 
+       </ul> </li> 
+     </ul> 
+     <div class="nav navbar-nav navbar-right"> 
+      <!-- 'style' added to fix height of input box. FIX THIS --> 
+      <form class="navbar-form" role="search" id="search-form" style="padding: 
1px 15px;"> 
+       <div class="form-group"> 
+        <input class="form-control" id="search-field" type="text" size="30" 
placeholder="Search"> 
+       </div> 
+      </form> 
+     </div> 
+     <p class="nav navbar-text navbar-right small">v2.0.0-M1</p> 
+    </div> 
+   </div> 
+  </nav> 
+  <div class="container"> 
+   <div class="row-fluid"> 
+    <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9"> 
+     <div id="search-panel"> 
+      <div id="search-results"></div> 
+      <div> 
+       <br> 
+       <a href="#" id="search-results-clear">clear</a> 
+      </div> 
+     </div> 
+     <span class="pdf-link"><a href="ugodn.pdf"><img 
src="../../images/PDF-50.png"></a></span> 
+     <div class="page-title"> 
+      <h1>DataNucleus Object Store</h1> 
+     </div> 
+     <div id="doc-content">
+      <div class="btn-group" style="float: right; font-size: small; padding: 
6px;  ">
+       <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+       <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+       <ul class="dropdown-menu">
+        <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+        <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+        <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+        <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+       </ul>
+      </div> 
+      <div class="sect1"> 
+       <h2 id="__ugodn">1. DataNucleus Object Store</h2> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>The DataNucleus Object Store enables domain objects to be 
persisted to relational as well as NoSQL databases. The object store is 
implemented using <a href="http://datanucleus.org";>DataNucleus</a>.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>This user guide discuss end-user features, configuration and 
customization of the DataNucleus object store.</p> 
+        </div> 
+        <div class="admonitionblock note"> 
+         <table> 
+          <tbody>
+           <tr> 
+            <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+            <td class="content"> 
+             <div class="paragraph"> 
+              <p>DataNucleus as a product also supports the JPA API; Apache 
Isis is likely to also support JPA in the future.</p> 
+             </div> </td> 
+           </tr> 
+          </tbody>
+         </table> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_other_guides">1.1. Other Guides</h3> 
+         <div class="paragraph"> 
+          <p>Apache Isis documentation is broken out into a number of user and 
reference guides.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The user guides available are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../ugfun/ugfun.html">Fundamentals</a></p> </li> 
+           <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li> 
+           <li> <p><a href="../ugvro/ugvro.html">Restful Objects 
viewer</a></p> </li> 
+           <li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a> 
(this guide)</p> </li> 
+           <li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li> 
+           <li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li> 
+           <li> <p><a href="../ugbtb/ugbtb.html">Beyond the Basics</a></p> 
</li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The reference guides are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../rgant/rgant.html">Annotations</a></p> </li> 
+           <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li> 
+           <li> <p><a href="../rgcfg/rgcfg.html">Configuration 
Properties</a></p> </li> 
+           <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and 
Schema</a></p> </li> 
+           <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven 
plugin</a></p> </li> 
+           <li> <p><a href="../rgfis/rgfis.html">Framework Internal 
Services</a></p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The remaining guides are:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p><a href="../dg/dg.html">Developers' Guide</a> (how to set 
up a development environment for Apache Isis and contribute back to the 
project)</p> </li> 
+           <li> <p><a href="../cgcom/cgcom.html">Committers' Guide</a> 
(release procedures and related practices)</p> </li> 
+          </ul> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+      <div class="sect1"> 
+       <h2 id="_ugodn_configuring">2. Configuring DataNucleus</h2>
+       <div class="btn-group" style="float: right; font-size: small; padding: 
6px; margin-top: -55px; ">
+        <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+        <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+        <ul class="dropdown-menu">
+         <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+         <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+         <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+         <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+        </ul>
+       </div> 
+       <div class="sectionbody"> 
+        <div class="paragraph"> 
+         <p>Apache Isis programmatically configures DataNucleus; any Apache 
Isis properties with the prefix <code>isis.persistor.datanucleus.impl</code> 
are passed through directly to the JDO/DataNucleus objectstore (with the prefix 
stripped off, of course).</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>DataNucleus will for itself also and read the 
<code>META-INF/persistence.xml</code>; at a minimum this defines the name of 
the "persistence unit". In theory it could also hold mappings, though in Apache 
Isis we tend to use annotations instead.</p> 
+        </div> 
+        <div class="paragraph"> 
+         <p>Furthermore, DataNucleus will search for various other XML mapping 
files, eg <code>mappings.jdo</code>. A full list can be found <a 
href="http://www.datanucleus.org/products/datanucleus/jdo/metadata.html";>here</a>.
 The metadata in these XML can be used to override the annotations of annotated 
entities; see <a 
href="../ugbtb/ugbtb.html#_ugbtb_other-techniques_overriding-jdo-annotations">Overriding
 JDO Annotatons</a> for further discussion.</p> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_ugodn_configuring_properties">2.1. Configuration 
Properties</h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>These configuration properties are typically stored in 
<code>WEB-INF/persistor_datanucleus.properties</code>. However, you can place 
all configuration properties into <code>WEB-INF/isis.properties</code> if you 
wish (the configuration properties from all config files are merged 
together).</p> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_configuration_properties_for_apache_isis_itself">2.1.1. 
Configuration Properties for Apache Isis itself</h4> 
+          <table class="tableblock frame-all grid-all spread"> 
+           <caption class="title">
+            Table 1. JDO/DataNucleus Objectstore Configuration Properties
+           </caption> 
+           <colgroup> 
+            <col style="width: 33.3333%;"> 
+            <col style="width: 33.3333%;"> 
+            <col style="width: 33.3334%;"> 
+           </colgroup> 
+           <thead> 
+            <tr> 
+             <th class="tableblock halign-left valign-top">Property</th> 
+             <th class="tableblock halign-left valign-top">Value<br> 
(<em>default value</em>)</th> 
+             <th class="tableblock halign-left valign-top">Description</th> 
+            </tr> 
+           </thead> 
+           <tbody> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.</code><br> 
<code>datanucleus.</code><br> <code>standaloneCollection.</code><br> 
<code>bulkLoad</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>true</code>, <code>false</code><br> 
(<code>false</code>)</p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>Enables bulk load of standalone collections.</p> 
+               </div> 
+               <div class="paragraph"> 
+                <p>Further <a 
href="../ugodn/ugodn.html#_ugodn_configuring_bulk-load">discussion 
below</a>.</p> 
+               </div>
+              </div></td> 
+            </tr> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.</code><br> 
<code>datanucleus.</code><br> <code>classMetadataLoadedListener</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>fully qualified class name<br> (<code>o.a.i.os.</code><br> 
<code>jdo.dn.</code><br> <code>CreateSchemaObject</code><br> 
<code>FromClassMetadata</code>)</p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>The default implementation creates a DB schema object.</p> 
+               </div> 
+               <div class="paragraph"> 
+                <p>There generally is no need to change this from its 
default.</p> 
+               </div>
+              </div></td> 
+            </tr> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.</code><br> 
<code>datanucleus.</code><br> <code>RegisterEntities.</code><br> 
<code>packagePrefix</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>fully qualified package names, CSV</p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>This property is derived automatically derived from the set 
of modules provided in the <a 
href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a>,
 and so does not need to be specified explicitly.</p> 
+               </div> 
+               <div class="paragraph"> 
+                <p>It holds the set of packages to search so that DataNucleus 
builds its metamodel eagerly rather than lazily.</p> 
+               </div>
+              </div></td> 
+            </tr> 
+           </tbody> 
+          </table> 
+          <div class="paragraph"> 
+           <p>Also:</p> 
+          </div> 
+          <table class="tableblock frame-all grid-all spread"> 
+           <colgroup> 
+            <col style="width: 33.3333%;"> 
+            <col style="width: 16.6666%;"> 
+            <col style="width: 50.0001%;"> 
+           </colgroup> 
+           <thead> 
+            <tr> 
+             <th class="tableblock halign-left valign-top">Property</th> 
+             <th class="tableblock halign-left valign-top">Value<br> (default 
value)</th> 
+             <th class="tableblock halign-left valign-top">Description</th> 
+            </tr> 
+           </thead> 
+           <tbody> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.</code><br> <code>disable</code><br> 
<code>ConcurrencyChecking</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top"><p 
class="tableblock"><code>true</code>,<code>false</code><br> 
(<code>false</code>)</p></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>Disables concurrency checking globally. <br></p> 
+               </div> 
+               <div class="paragraph"> 
+                <p>Only intended for "emergency use" as a workaround while 
pending fix/patch to Apache Isis itself. (Note that there is no "datanucleus" 
in the property).</p> 
+               </div>
+              </div></td> 
+            </tr> 
+           </tbody> 
+          </table> 
+         </div> 
+         <div class="sect3"> 
+          <h4 
id="_configuration_properties_passed_through_directly_to_datanucleus">2.1.2. 
Configuration Properties passed through directly to DataNucleus.</h4> 
+          <table class="tableblock frame-all grid-all spread"> 
+           <caption class="title">
+            Table 2. JDO/DataNucleus Objectstore Configuration Properties
+           </caption> 
+           <colgroup> 
+            <col style="width: 33.3333%;"> 
+            <col style="width: 16.6666%;"> 
+            <col style="width: 50.0001%;"> 
+           </colgroup> 
+           <thead> 
+            <tr> 
+             <th class="tableblock halign-left valign-top">Property</th> 
+             <th class="tableblock halign-left valign-top">Value<br> 
(<em>default value</em>)</th> 
+             <th class="tableblock halign-left valign-top">Description</th> 
+            </tr> 
+           </thead> 
+           <tbody> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.datanucleus.impl.*</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top"></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>Passed through directly to Datanucleus (with 
<code>isis.persistor.datanucleus.impl</code> prefix stripped)</p> 
+               </div>
+              </div></td> 
+            </tr> 
+            <tr> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p><code>isis.persistor.datanucleus.impl.</code><br> 
<code>datanucleus.persistenceByReachabilityAtCommit</code></p> 
+               </div>
+              </div></td> 
+             <td class="tableblock halign-left valign-top"><p 
class="tableblock"><code>false</code></p></td> 
+             <td class="tableblock halign-left valign-top">
+              <div>
+               <div class="paragraph"> 
+                <p>We recommend this setting is disabled. <br> Further <a 
href="../ugodn/ugodn.html#_ugodn_configuring_disabling-persistence-by-reachability">discussion
 below</a>.</p> 
+               </div>
+              </div></td> 
+            </tr> 
+           </tbody> 
+          </table> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_ugodn_configuring_bulk-load">2.2. Bulk Load of Standalone 
Collections</h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>The implementation of user interactions (meaning either an action 
invocations or a property edits) in the <a href="../ugvw/ugvw.html">Wicket 
viewer</a> is splits into two. The first phase performs the actual interaction, 
with the results (dirtied objects) flushed to the database. The second phase 
then renders the results of the interaction.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>When the user interaction in question is an action invocation 
that returns a list of objects, the resultant list is not rendered in the first 
phase. Instead, only the IDs of the objects in the list are captured. When the 
list is then rendered, the framework re-loads each object.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>The default implementation does this row-by-row, resulting in 
multiple queries against the database. Setting the property:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code 
data-lang="ini">isis.persistor.datanucleus.standaloneCollection.bulkLoad=true</code></pre>
 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>changes to a more efficient implementation that bulk loads all 
the objects using a single query.</p> 
+         </div> 
+         <div class="admonitionblock note"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>In the future the bulkLoad implementation may be made the 
default.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+         <div class="admonitionblock note"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-note" title="Note"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>The implementation of parented collections does not suffer 
from this issue; the rendering phase runs the query to obtain the matches.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 
id="_ugodn_configuring_disabling-persistence-by-reachability">2.3. Persistence 
by Reachability</h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>By default, JDO/DataNucleus supports the concept of <a 
href="http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistence_by_reachability";>persistence-by-reachability</a>.
 That is, if a non-persistent entity is associated with an already-persistent 
entity, then DataNucleus will detect this and will automatically persist the 
associated object. Put another way: there is no need to call Apache Isis' 
<code>RepositoryService#persist(.)</code> or 
<code>RepositoryService#persistAndFlush(.)</code> methods.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>However, convenient though this feature is, you may find that it 
causes performance issues.</p> 
+         </div> 
+         <div class="admonitionblock warning"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-warning" title="Warning"></i> 
</td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>DataNucleus' persistence-by-reachability may cause 
performance issues. We strongly recommend that you disable it.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+         <div class="paragraph"> 
+          <p>One scenario in particular where this performance issues can 
arise is if your entities implement the <code>java.lang.Comparable</code> 
interface, and you have used Apache Isis' <a 
href="../rgcms/rgcms.html#_rgcms_classes_utility_ObjectContracts"><code>ObjectContracts</code></a>
 utility class. The issue here is that <code>ObjectContracts</code> 
implementation can cause DataNucleus to recursively rehydrate a larger number 
of associated entities. (More detail below).</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>We therefore recommend that you disable 
persistence-by-reachability by adding the following to 
<code>persistor_datanucleus.properties</code>:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code 
data-lang="ini">isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false</code></pre>
 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>This change has been made to both the <a 
href="../ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">HelloWorld</a>
 and <a 
href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp</a>
 archetypes.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>If you do disable this feature, then you will (of course) need to 
ensure that you explicitly persist all entities using the 
<code>RepositoryService#persist(.)</code> or 
<code>RepositoryService#persistAndFlush(.)</code> methods.</p> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_the_issue_in_more_detail">2.3.1. The issue in more 
detail</h4> 
+          <div class="paragraph"> 
+           <p>Consider these entities (<a 
href="http://yuml.me/edit/b8681268";>yuml.me/b8681268</a>):</p> 
+          </div> 
+          <div class="imageblock"> 
+           <div class="content"> 
+            <a class="image" 
href="images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png"><img
 
src="images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png"
 alt="party agreementrole agreement" width="750px"></a> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>In the course of a transaction, the <code>Agreement</code> 
entity is loaded into memory (not necessarily modified), and then new 
<code>AgreementRole</code>s are associated to it.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>All these entities implement <code>Comparable</code> using 
<code>ObjectContracts</code>, and the implementation of 
<code>AgreementRole</code>'s (simplified) is:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> <span class="type">class</span> <span 
class="class">AgreementRole</span> {
+    ...
+    public <span class="type">int</span> compareTo(AgreementRole other) {
+        <span class="keyword">return</span> ObjectContracts.compareTo(<span 
class="local-variable">this</span>, other, <span class="string"><span 
class="delimiter">"</span><span class="content">agreement</span><span 
class="delimiter">"</span></span>,<span class="string"><span 
class="delimiter">"</span><span class="content">startDate</span><span 
class="delimiter">"</span></span>,<span class="string"><span 
class="delimiter">"</span><span class="content">party</span><span 
class="delimiter">"</span></span>);
+    }
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>while <code>Agreement</code>'s is implemented as:</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">Agreement</span> {
+    ...
+    public <span class="type">int</span> compareTo(Agreement other) {
+        <span class="keyword">return</span> ObjectContracts.compareTo(<span 
class="local-variable">this</span>, other, <span class="string"><span 
class="delimiter">"</span><span class="content">reference</span><span 
class="delimiter">"</span></span>);
+    }
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>and <code>Party</code>'s is similarly implemented as:</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">Party</span> {
+    ...
+    public <span class="type">int</span> compareTo(Party other) {
+        <span class="keyword">return</span> ObjectContracts.compareTo(<span 
class="local-variable">this</span>, other, <span class="string"><span 
class="delimiter">"</span><span class="content">reference</span><span 
class="delimiter">"</span></span>);
+    }
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>DataNucleusâs persistence-by-reachability algorithm adds the 
<code>AgreementRole</code> instances into a <code>SortedSet</code>, which 
causes <code>AgreementRole#compareTo()</code> to fire:</p> 
+          </div> 
+          <div class="ulist"> 
+           <ul> 
+            <li> <p>the evaluation of the "agreement" property delegates back 
to the <code>Agreement</code>, whose own <code>Agreement#compareTo()</code> 
uses the scalar <code>reference</code> property. As the <code>Agreement</code> 
is already in-memory, this does not trigger any further database queries</p> 
</li> 
+            <li> <p>the evaluation of the "startDate" property is just a 
scalar property of the <code>AgreementRole</code>, so will already 
in-memory</p> </li> 
+            <li> <p>the evaluation of the "party" property delegates back to 
the <code>Party</code>, whose own <code>Party#compareTo()</code> requires the 
uses the scalar <code>reference</code> property. However, since the 
<code>Party</code> is not yet in-memory, using the <code>reference</code> 
property triggers a database query to "rehydrate" the <code>Party</code> 
instance.</p> </li> 
+           </ul> 
+          </div> 
+          <div class="paragraph"> 
+           <p>In other words, in figuring out whether 
<code>AgreementRole</code> requires the persistence-by-reachability algorithm 
to run, it causes the adjacent associated entity <code>Party</code> to also be 
retrieved.</p> 
+          </div> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_ugodn_configuring_persistence-xml">2.4. 
<code>persistence.xml</code></h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>DataNucleus will for itself also and read the 
<code>META-INF/persistence.xml</code>. In theory it can hold mappings and even 
connection strings. However, with Apache Isis we tend to use annotations 
instead and externalize connection strings. so its definition is extremely 
simply, specifying just the name of the "persistence unit".</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Hereâs the one provided by the <a 
href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp 
archetype</a>:</p> 
+         </div> 
+         <div class="listingblock"> 
+          <div class="content"> 
+           <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="preprocessor">&lt;?xml version="1.0" encoding="UTF-8" ?&gt;</span>
+<span class="tag">&lt;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">&gt;</span>
+
+    <span class="tag">&lt;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">&gt;</span>
+    <span class="tag">&lt;/persistence-unit&gt;</span>
+<span class="tag">&lt;/persistence&gt;</span></code></pre> 
+          </div> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Normally all one needs to do is to change the 
<code>persistence-unit</code> name.</p> 
+         </div> 
+         <div class="admonitionblock tip"> 
+          <table> 
+           <tbody>
+            <tr> 
+             <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> 
+             <td class="content"> 
+              <div class="paragraph"> 
+               <p>If you use Eclipse IDE on Windows then <a 
href="../dg/dg.html#__dg_ide_eclipse_workaround-for-path-limits">note the 
importance</a> of the <code>persistence.xml</code> file to make DataNucleus 
enhancer work correctly.</p> 
+              </div> </td> 
+            </tr> 
+           </tbody>
+          </table> 
+         </div> 
+         <div class="paragraph"> 
+          <p>See <a 
href="http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit";>DataNucleus'
 documentation</a> on <code>persistence.xml</code> to learn more.</p> 
+         </div> 
+        </div> 
+        <div class="sect2"> 
+         <h3 id="_ugodn_configuring_using-jndi-data-source">2.5. Using JNDI 
DataSource</h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>Isis' JDO objectstore can be configured either to connect to the 
database using its own connection pool, or by using a container-managed 
datasource.</p> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_application_managed">2.5.1. Application managed</h4> 
+          <div class="paragraph"> 
+           <p>Using a connection pool managed directly by the application 
(that is, by Apache Isis' JDO objectstore and ultimately by DataNucleus) 
requires a single set of configuration properties to be specified.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>In either <code>WEB-INF\isis.properties</code> file (or 
<code>WEB-INF\persistor.properties</code>, or 
<code>WEB-INF\persistor_datanucleus.properties</code>), specify the connection 
driver, url, username and password.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>For example:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code 
data-lang="ini">isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre>
 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Those configuration properties that start with the prefix 
<code>isis.persistor.datanucleus.impl.</code> are passed through directly to 
DataNucleus (with the prefix removed).</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>It is also possible to specify the ` 
datanucleus.ConnectionPasswordDecrypter ` property; see the <a 
href="http://www.datanucleus.org/products/accessplatform_4_1/persistence_properties.html#ConnectionPasswordDecrypter";>DataNucleus
 documentation</a> for further details.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_container_managed_jndi">2.5.2. Container managed 
(JNDI)</h4> 
+          <div class="paragraph"> 
+           <p>Using a datasource managed by the servlet container requires 
three separate bits of configuration.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Firstly, specify the name of the datasource in the 
<code>WEB-INF\persistor_datanucleus.properties</code> file. For example:</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>If connection pool settings are also present in this file, they 
will simply be ignored. Any other configuration properties that start with the 
prefix <code>isis.persistor.datanucleus.impl.</code> are passed through 
directly to DataNucleus (with the prefix removed).</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Secondly, in the <code>WEB-INF/web.xml</code>, declare the 
resource reference:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="tag">&lt;resource-ref&gt;</span>
+    <span class="tag">&lt;description&gt;</span>db<span 
class="tag">&lt;/description&gt;</span>
+    <span class="tag">&lt;res-ref-name&gt;</span>jdbc/simpleapp<span 
class="tag">&lt;/res-ref-name&gt;</span>
+    <span class="tag">&lt;res-type&gt;</span>javax.sql.DataSource<span 
class="tag">&lt;/res-type&gt;</span>
+    <span class="tag">&lt;res-auth&gt;</span>Container<span 
class="tag">&lt;/res-auth&gt;</span>
+<span class="tag">&lt;/resource-ref&gt;</span></code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Finally, declare the datasource as required by the servlet 
container. For example, if using Tomcat 7, the datasource can be specified by 
adding the following to <code>$TOMCAT_HOME/conf/context.xml</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="xml"><span 
class="tag">&lt;Resource</span> <span class="attribute-name">name</span>=<span 
class="string"><span class="delimiter">"</span><span 
class="content">jdbc/simpleapp</span><span class="delimiter">"</span></span>
+  <span class="attribute-name">auth</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">Container</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">type</span>=<span class="string"><span 
class="delimiter">"</span><span 
class="content">javax.sql.DataSource</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">maxActive</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">100</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">maxIdle</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">30</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">maxWait</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">10000</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">username</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">sa</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">password</span>=<span class="string"><span 
class="delimiter">"</span><span class="content">p4ssword</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">driverClassName</span>=<span 
class="string"><span class="delimiter">"</span><span 
class="content">com.microsoft.sqlserver.jdbc.SQLServerDriver</span><span 
class="delimiter">"</span></span>
+  <span class="attribute-name">url</span>=<span class="string"><span 
class="delimiter">"</span><span 
class="content">jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp</span><span
 class="delimiter">"</span></span><span class="tag">/&gt;</span></code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>You will also need to make sure that the JDBC driver is on the 
servlet containerâs classpath. For Tomcat, this means copying the driver to 
<code>$TOMCAT_HOME/lib</code>.</p> 
+          </div> 
+          <div class="admonitionblock note"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td class="icon"> <i class="fa icon-note" title="Note"></i> 
</td> 
+              <td class="content"> 
+               <div class="paragraph"> 
+                <p>According to Tomcatâs documentation, it is supposedly 
possible to copy the <code>conf/context.xml</code> to the name of the webapp, 
eg <code>conf/mywebapp.xml</code>, and scope the connection to that webapp 
only. I was unable to get this working, however.</p> 
+               </div> </td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+         </div> 
+        </div> 
+       </div> 
+      </div> 
+      <div class="sect1"> 
+       <h2 id="_ugodn_jdo-mappings">3. JDO Mappings</h2>
+       <div class="btn-group" style="float: right; font-size: small; padding: 
6px; margin-top: -55px; ">
+        <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+        <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+        <ul class="dropdown-menu">
+         <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+         <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+         <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+         <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+        </ul>
+       </div> 
+       <div class="sectionbody"> 
+        <div class="sect2"> 
+         <h3 id="_ugodn_jdo-mappings_1-to-m-bidirectional-relationships">3.1. 
1-m Bidirectional relationships</h3>
+         <div class="btn-group" style="float: right; font-size: small; 
padding: 6px; margin-top: -55px; ">
+          <button type="button" class="btn btn-xs btn-default" 
onclick="window.location.href=&quot;https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc&quot;";><i
 class="fa fa-pencil-square-o"></i>&nbsp;Edit</button>
+          <button type="button" class="btn btn-xs btn-default dropdown-toggle" 
data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span 
class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+          <ul class="dropdown-menu">
+           <li><a 
href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc";
 target="_blank"><i class="fa fa-pencil-square-o fa-fw" 
aria-hidden="true"></i>&nbsp; Edit</a></li>
+           <li><a 
href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc";
 target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i>&nbsp; 
History</a></li>
+           <li><a 
href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc";
 target="_blank"><i class="fa fa-file-text-o fa-fw" 
aria-hidden="true"></i>&nbsp; Raw</a></li>
+           <li><a 
href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc";
 target="_blank"><i class="fa fa-hand-o-right fa-fw" 
aria-hidden="true"></i>&nbsp; Blame</a></li>
+          </ul>
+         </div> 
+         <div class="paragraph"> 
+          <p>Consider a bidirectional one-to-many association between two 
entities; a collection member in the "parent" and a property member on the 
"child".</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>We can tell DataNucleus about the bidirectionality using 
<code>@Persistent(mappedBy=â¦â)</code>, or we can take responsibility for 
this aspect ourselves.</p> 
+         </div> 
+         <div class="paragraph"> 
+          <p>In addition, the two entities can be associated either without or 
with a join table (indicated by the <code>@Join</code> annotation):</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p>without a join table is more common; a regular foreign key 
in the child table for <code>FermentationVessel</code> points back up to the 
associated parent <code>Batch</code></p> </li> 
+           <li> <p>with a join table; a link table holds the tuple 
representing the linkage.</p> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>Testing (against <code>dn-core 4.1.7</code>/<code>dn-rdbms 
4.1.9</code>) has determined there are two main rules:</p> 
+         </div> 
+         <div class="ulist"> 
+          <ul> 
+           <li> <p>If not using <code>@Join</code>, then the association must 
be maintained by setting the child association on the parent.<br></p> 
+            <div class="paragraph"> 
+             <p>It is not sufficient to simply add the child object to the 
parentâs collection.</p> 
+            </div> </li> 
+           <li> <p><code>@Persistent(mappedBy=â¦â)</code> and 
<code>@Join</code> cannot be used together.<br></p> 
+            <div class="paragraph"> 
+             <p>Put another way, if using <code>@Join</code> then you must 
maintain both sides of the relationship in the application code.</p> 
+            </div> </li> 
+          </ul> 
+         </div> 
+         <div class="paragraph"> 
+          <p>In the examples that follow, we use two entities, 
<code>Batch</code> and <code>FermentationVessel</code> (from a brewery domain). 
In the original example domain the relationship between these two entities was 
optional (a <code>FermentationVessel</code> may have either none or one 
<code>Batch</code> associated with it); for the purpose of this article weâll 
explore both mandatory and optional associations.</p> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_mandatory_no_code_join_code">3.1.1. Mandatory, no 
<code>@Join</code></h4> 
+          <div class="paragraph"> 
+           <p>In the first scenario we have use 
<code>@Persistent(mappedBy=â¦â)</code> to indicate a bidirectional 
association, without any <code>@Join</code>:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> <span class="type">class</span> <span 
class="class">Batch</span> {
+
+    <span class="comment">// getters and setters omitted</span>
+
+    <span class="annotation">@Persistent</span>(mappedBy = <span 
class="string"><span class="delimiter">"</span><span 
class="content">batch</span><span class="delimiter">"</span></span>, 
dependentElement = <span class="string"><span class="delimiter">"</span><span 
class="content">false</span><span class="delimiter">"</span></span>)     <i 
class="conum" data-value="1"></i><b>(1)</b>
+    <span class="directive">private</span> <span 
class="predefined-type">SortedSet</span>&lt;FermentationVessel&gt; vessels = 
<span class="keyword">new</span> <span 
class="predefined-type">TreeSet</span>&lt;FermentationVessel&gt;();
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>"mappedBy" means this is bidirectional</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>and</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">FermentationVessel</span> <span 
class="directive">implements</span> <span 
class="predefined-type">Comparable</span>&lt;FermentationVessel&gt; {
+
+    <span class="comment">// getters and setters omitted</span>
+
+    <span class="annotation">@Column</span>(allowsNull = <span 
class="string"><span class="delimiter">"</span><span 
class="content">false</span><span class="delimiter">"</span></span>)       <i 
class="conum" data-value="1"></i><b>(1)</b>
+    <span class="directive">private</span> Batch batch;
+
+    <span class="annotation">@Column</span>(allowsNull = <span 
class="string"><span class="delimiter">"</span><span 
class="content">false</span><span class="delimiter">"</span></span>)
+    <span class="directive">private</span> State state;                <i 
class="conum" data-value="2"></i><b>(2)</b>
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>mandatory association up to parent</td> 
+             </tr> 
+             <tr> 
+              <td><i class="conum" data-value="2"></i><b>2</b></td> 
+              <td>State is an enum (omitted)</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Which creates this schema:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="sql"><span 
class="class">CREATE</span> <span class="type">TABLE</span> <span 
class="string"><span class="delimiter">"</span><span 
class="content">batch</span><span class="delimiter">"</span></span>.<span 
class="string"><span class="delimiter">"</span><span 
class="content">Batch</span><span class="delimiter">"</span></span>
+(
+    <span class="string"><span class="delimiter">"</span><span 
class="content">id</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> GENERATED <span class="keyword">BY</span> 
<span class="directive">DEFAULT</span> <span class="keyword">AS</span> IDENTITY,
+    ...
+    <span class="string"><span class="delimiter">"</span><span 
class="content">version</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> <span class="keyword">NOT</span> <span 
class="predefined-constant">NULL</span>,
+    <span class="type">CONSTRAINT</span> <span class="string"><span 
class="delimiter">"</span><span class="content">Batch_PK</span><span 
class="delimiter">"</span></span> <span class="directive">PRIMARY</span> <span 
class="type">KEY</span> (<span class="string"><span 
class="delimiter">"</span><span class="content">id</span><span 
class="delimiter">"</span></span>)
+)
+<span class="class">CREATE</span> <span class="type">TABLE</span> <span 
class="string"><span class="delimiter">"</span><span 
class="content">fvessel</span><span class="delimiter">"</span></span>.<span 
class="string"><span class="delimiter">"</span><span 
class="content">FermentationVessel</span><span class="delimiter">"</span></span>
+(
+    <span class="string"><span class="delimiter">"</span><span 
class="content">id</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> GENERATED <span class="keyword">BY</span> 
<span class="directive">DEFAULT</span> <span class="keyword">AS</span> IDENTITY,
+    <span class="string"><span class="delimiter">"</span><span 
class="content">batch_id_OID</span><span class="delimiter">"</span></span> 
<span class="predefined-type">BIGINT</span> <span class="keyword">NOT</span> 
<span class="predefined-constant">NULL</span>,
+    <span class="string"><span class="delimiter">"</span><span 
class="content">state</span><span class="delimiter">"</span></span> 
NVARCHAR(<span class="integer">255</span>) <span class="keyword">NOT</span> 
<span class="predefined-constant">NULL</span>,
+    ...
+    <span class="string"><span class="delimiter">"</span><span 
class="content">version</span><span class="delimiter">"</span></span> <span 
class="predefined-type">TIMESTAMP</span> <span class="keyword">NOT</span> <span 
class="predefined-constant">NULL</span>,
+    <span class="type">CONSTRAINT</span> <span class="string"><span 
class="delimiter">"</span><span 
class="content">FermentationVessel_PK</span><span 
class="delimiter">"</span></span> <span class="directive">PRIMARY</span> <span 
class="type">KEY</span> (<span class="string"><span 
class="delimiter">"</span><span class="content">id</span><span 
class="delimiter">"</span></span>)
+)</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>That is, there is an mandatory foreign key from 
<code>FermentationVessel</code> to <code>Batch</code>.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>In this case we can use this code:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> Batch transfer(<span 
class="directive">final</span> FermentationVessel vessel) {
+    vessel.setBatch(<span class="local-variable">this</span>);                 
                 <i class="conum" data-value="1"></i><b>(1)</b>
+    vessel.setState(FermentationVessel.State.FERMENTING);
+    <span class="keyword">return</span> <span 
class="local-variable">this</span>;
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>set the parent on the child</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>This sets up the association correctly, using this SQL:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="sql"><span 
class="class">UPDATE</span> <span class="string"><span 
class="delimiter">"</span><span class="content">fvessel</span><span 
class="delimiter">"</span></span>.<span class="string"><span 
class="delimiter">"</span><span class="content">FermentationVessel</span><span 
class="delimiter">"</span></span>
+   <span class="class">SET</span> <span class="string"><span 
class="delimiter">"</span><span class="content">batch_id_OID</span><span 
class="delimiter">"</span></span>=&lt;<span class="integer">0</span>&gt;
+       ,<span class="string"><span class="delimiter">"</span><span 
class="content">state</span><span class="delimiter">"</span></span>=&lt;<span 
class="string"><span class="delimiter">'</span><span 
class="content">FERMENTING</span><span class="delimiter">'</span></span>&gt;
+       ,<span class="string"><span class="delimiter">"</span><span 
class="content">version</span><span class="delimiter">"</span></span>=&lt;<span 
class="integer">2016</span><span class="integer">-07</span><span 
class="integer">-07</span> <span class="integer">12</span>:<span 
class="integer">37</span>:<span class="float">14.968</span>&gt;
+ <span class="keyword">WHERE</span> <span class="string"><span 
class="delimiter">"</span><span class="content">id</span><span 
class="delimiter">"</span></span>=&lt;<span 
class="integer">0</span>&gt;</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>The following code will also work:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> Batch transfer(<span 
class="directive">final</span> FermentationVessel vessel) {
+    vessel.setBatch(<span class="local-variable">this</span>);                 
                 <i class="conum" data-value="1"></i><b>(1)</b>
+    getVessels().add(vessel);                               <i class="conum" 
data-value="2"></i><b>(2)</b>
+    vessel.setState(FermentationVessel.State.FERMENTING);
+    <span class="keyword">return</span> <span 
class="local-variable">this</span>;
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>set the parent on the child</td> 
+             </tr> 
+             <tr> 
+              <td><i class="conum" data-value="2"></i><b>2</b></td> 
+              <td>add the child to the parentâs collection.</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>However, obviously the second statement is redundant.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_optional_no_code_join_code">3.1.2. Optional, no 
<code>@Join</code></h4> 
+          <div class="paragraph"> 
+           <p>If the association to the parent is made optional:</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">FermentationVessel</span> <span 
class="directive">implements</span> <span 
class="predefined-type">Comparable</span>&lt;FermentationVessel&gt; {
+
+    <span class="comment">// getters and setters omitted</span>
+
+    <span class="annotation">@Column</span>(allowsNull = <span 
class="string"><span class="delimiter">"</span><span 
class="content">true</span><span class="delimiter">"</span></span>)       <i 
class="conum" data-value="1"></i><b>(1)</b>
+    <span class="directive">private</span> Batch batch;
+
+    <span class="annotation">@Column</span>(allowsNull = <span 
class="string"><span class="delimiter">"</span><span 
class="content">false</span><span class="delimiter">"</span></span>)
+    <span class="directive">private</span> State state;
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>optional association up to parent</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Which creates this schema:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="sql"><span 
class="class">CREATE</span> <span class="type">TABLE</span> <span 
class="string"><span class="delimiter">"</span><span 
class="content">batch</span><span class="delimiter">"</span></span>.<span 
class="string"><span class="delimiter">"</span><span 
class="content">Batch</span><span class="delimiter">"</span></span>
+(
+    <span class="string"><span class="delimiter">"</span><span 
class="content">id</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> GENERATED <span class="keyword">BY</span> 
<span class="directive">DEFAULT</span> <span class="keyword">AS</span> IDENTITY,
+    ...
+    <span class="string"><span class="delimiter">"</span><span 
class="content">version</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> <span class="keyword">NOT</span> <span 
class="predefined-constant">NULL</span>,
+    <span class="type">CONSTRAINT</span> <span class="string"><span 
class="delimiter">"</span><span class="content">Batch_PK</span><span 
class="delimiter">"</span></span> <span class="directive">PRIMARY</span> <span 
class="type">KEY</span> (<span class="string"><span 
class="delimiter">"</span><span class="content">id</span><span 
class="delimiter">"</span></span>)
+)
+<span class="class">CREATE</span> <span class="type">TABLE</span> <span 
class="string"><span class="delimiter">"</span><span 
class="content">fvessel</span><span class="delimiter">"</span></span>.<span 
class="string"><span class="delimiter">"</span><span 
class="content">FermentationVessel</span><span class="delimiter">"</span></span>
+(
+    <span class="string"><span class="delimiter">"</span><span 
class="content">id</span><span class="delimiter">"</span></span> <span 
class="predefined-type">BIGINT</span> GENERATED <span class="keyword">BY</span> 
<span class="directive">DEFAULT</span> <span class="keyword">AS</span> IDENTITY,
+    <span class="string"><span class="delimiter">"</span><span 
class="content">batch_id_OID</span><span class="delimiter">"</span></span> 
<span class="predefined-type">BIGINT</span> <span 
class="predefined-constant">NULL</span>,
+    <span class="string"><span class="delimiter">"</span><span 
class="content">state</span><span class="delimiter">"</span></span> 
NVARCHAR(<span class="integer">255</span>) <span class="keyword">NOT</span> 
<span class="predefined-constant">NULL</span>,
+    ...
+    <span class="string"><span class="delimiter">"</span><span 
class="content">version</span><span class="delimiter">"</span></span> <span 
class="predefined-type">TIMESTAMP</span> <span class="keyword">NOT</span> <span 
class="predefined-constant">NULL</span>,
+    <span class="type">CONSTRAINT</span> <span class="string"><span 
class="delimiter">"</span><span 
class="content">FermentationVessel_PK</span><span 
class="delimiter">"</span></span> <span class="directive">PRIMARY</span> <span 
class="type">KEY</span> (<span class="string"><span 
class="delimiter">"</span><span class="content">id</span><span 
class="delimiter">"</span></span>)
+)</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>This is almost exactly the same, except the foreign key from 
<code>FermentationVessel</code> to <code>Batch</code> is now nullable.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>In this case then setting the parent on the child still 
works:</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> Batch transfer(<span 
class="directive">final</span> FermentationVessel vessel) {
+    vessel.setBatch(<span class="local-variable">this</span>);                 
                 <i class="conum" data-value="1"></i><b>(1)</b>
+    vessel.setState(FermentationVessel.State.FERMENTING);
+    <span class="keyword">return</span> <span 
class="local-variable">this</span>;
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>set the parent on the child</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p><strong>HOWEVER</strong>, if we (redundantly) update both sides, 
then - paradoxically - the association is NOT set up</p> 
+          </div> 
+          <div class="listingblock"> 
+           <div class="content"> 
+            <pre class="CodeRay highlight"><code data-lang="java"><span 
class="directive">public</span> Batch transfer(<span 
class="directive">final</span> FermentationVessel vessel) {
+    vessel.setBatch(<span class="local-variable">this</span>);                 
                 <i class="conum" data-value="1"></i><b>(1)</b>
+    getVessels().add(vessel);                               <i class="conum" 
data-value="2"></i><b>(2)</b>
+    vessel.setState(FermentationVessel.State.FERMENTING);
+    <span class="keyword">return</span> <span 
class="local-variable">this</span>;
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="colist arabic"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td><i class="conum" data-value="1"></i><b>1</b></td> 
+              <td>set the parent on the child</td> 
+             </tr> 
+             <tr> 
+              <td><i class="conum" data-value="2"></i><b>2</b></td> 
+              <td>add the child to the parentâs collection.</td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="admonitionblock note"> 
+           <table> 
+            <tbody>
+             <tr> 
+              <td class="icon"> <i class="fa icon-note" title="Note"></i> 
</td> 
+              <td class="content"> 
+               <div class="paragraph"> 
+                <p>Itâs not clear if this is a bug in <code>dn-core 
4.1.7</code>/<code>dn-rdbms 4.19</code>; an earlier thread on the mailing list 
from 2014 actually gave the opposite advice, see <a 
href="http://isis.markmail.org/thread/ipu2lzqqikqdglox";>this thread</a> and in 
particular this <a 
href="http://markmail.org/message/hblptpw675mlw723";>message</a>.</p> 
+               </div> 
+               <div class="paragraph"> 
+                <p>In fact we also have had a different case raised (url lost) 
which argues that the parent should only be set on the child, and the child 
<em>not</em> added to the parentâs collection. This concurs with the most 
recent testing.</p> 
+               </div> </td> 
+             </tr> 
+            </tbody>
+           </table> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Therefore, the simple advice is that, for bidirectional 
associations, simply set the parent on the child, and this will work reliably 
irrespective of whether the association is mandatory or optional.</p> 
+          </div> 
+         </div> 
+         <div class="sect3"> 
+          <h4 id="_with_code_join_code">3.1.3. With <code>@Join</code></h4> 
+          <div class="paragraph"> 
+           <p>Although DataNucleus does not complain if 
<code>@Persistence(mappedBy=â¦â)</code> and <code>@Join</code> are combined, 
testing (against <code>dn-core 4.1.7</code>/<code>dn-rdbms 4.19</code>) has 
shown that the bidirectional association is not properly maintained.</p> 
+          </div> 
+          <div class="paragraph"> 
+           <p>Therefore, we recommend that if <code>@Join</code> is used, then 
manually maintain both sides of the relationship and do not indicate that the 
association is bidirectional.</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">Batch</span> {
+
+    <span class="comment">// getters and setters omitted</span>
+
+    <span class="annotation">@Join</span>(table = <span class="string"><span 
class="delimiter">"</span><span class="content">Batch_vessels</span><span 
class="delimiter">"</span></span>)
+    <span class="annotation">@Persistent</span>(dependentElement = <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">SortedSet</span>&lt;FermentationVessel&gt; vessels = 
<span class="keyword">new</span> <span 
class="predefined-type">TreeSet</span>&lt;FermentationVessel&gt;();
+}</code></pre> 
+           </div> 
+          </div> 
+          <div class="paragraph"> 
+           <p>and</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">FermentationVessel</span> <span 
class="directive">implements</span> <span class="predef


<TRUNCATED>

[10/51] [partial] isis-site git commit: ISIS-1810: updates with first draft of 2.0.0-M1 release.

Reply via email to