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 2018/01/03 14:48:44 UTC
[12/87] [abbrv] [partial] isis-site git commit: adds SNAPSHOT version
http://git-wip-us.apache.org/repos/asf/isis-site/blob/d215fa50/content/versions/SNAPSHOT/guides/ugodn/ugodn.html
----------------------------------------------------------------------
diff --git a/content/versions/SNAPSHOT/guides/ugodn/ugodn.html b/content/versions/SNAPSHOT/guides/ugodn/ugodn.html
new file mode 100644
index 0000000..bbc3b22
--- /dev/null
+++ b/content/versions/SNAPSHOT/guides/ugodn/ugodn.html
@@ -0,0 +1,2009 @@
+<!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?users@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="http://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="http://www.apache.org/">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">Licenses</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://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>
+ </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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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>(<code>1.16.0-SNAPSHOT</code>) 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>(As of <code>1.16.0-SNAPSHOT</code>), 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>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><code>isis.persistor.datanucleus.</code><br> <code>PublishingService.serializedForm</code></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>zipped</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>(<code>PublishingService</code> is deprecated, and therefore so is this 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 (<code>1.16.0-SNAPSHOT</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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_bulk-load.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_disabling-persistence-by-reachability.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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"><?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>
+ <span class="tag"></persistence-unit></span>
+<span class="tag"></persistence></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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_using-jndi-data-source.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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"><resource-ref></span>
+ <span class="tag"><description></span>db<span class="tag"></description></span>
+ <span class="tag"><res-ref-name></span>jdbc/simpleapp<span class="tag"></res-ref-name></span>
+ <span class="tag"><res-type></span>javax.sql.DataSource<span class="tag"></res-type></span>
+ <span class="tag"><res-auth></span>Container<span class="tag"></res-auth></span>
+<span class="tag"></resource-ref></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"><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">/></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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc""><i class="fa fa-pencil-square-o"></i> 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> 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> 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> 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> 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 (as of <code>1.13.0</code>, 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><FermentationVessel> vessels = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><FermentationVessel>();
+}</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><FermentationVessel> {
+
+ <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>=<<span class="integer">0</span>>
+ ,<span class="string"><span class="delimiter">"</span><span class="content">state</span><span class="delimiter">"</span></span>=<<span class="string"><span class="delimiter">'</span><span class="content">FERMENTING</span><span class="delimiter">'</span></span>>
+ ,<span class="string"><span class="delimiter">"</span><span class="content">version</span><span class="delimiter">"</span></span>=<<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>>
+ <span class="keyword">WHERE</span> <span class="string"><span class="delimiter">"</span><span class="content">id</span><span class="delimiter">"</span></span>=<<span class="integer">0</span>></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><FermentationVessel> {
+
+ <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><FermentationVessel> vessels = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><FermentationVessel>();
+}</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="predefined-type">Comparable</span><FermentationVessel> {
+
+ <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>
+
<TRUNCATED>