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 2017/05/08 23:11:34 UTC
[13/59] [partial] isis-site git commit: ISIS-1579: reworks site to
use bootstrap
http://git-wip-us.apache.org/repos/asf/isis-site/blob/28f1cbe5/content/guides/ugodn/ugodn.html
----------------------------------------------------------------------
diff --git a/content/guides/ugodn/ugodn.html b/content/guides/ugodn/ugodn.html
index 157a424..314045a 100644
--- a/content/guides/ugodn/ugodn.html
+++ b/content/guides/ugodn/ugodn.html
@@ -1,9 +1,6 @@
<!doctype html>
-<html class="no-js" lang="en">
+<html>
<head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1.0">
- <title>DataNucleus Object Store</title>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
@@ -22,796 +19,680 @@
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">
- <!-- TODO: need to (re)instate CDN in the future (not using for now just so can develop off-line -->
- <link href="../../css/foundation/5.5.1/foundation.css" rel="stylesheet">
- <script src="../../js/foundation/5.5.1/vendor/modernizr.js"></script>
- <link href="../../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
- <link href="../../css/asciidoctor/colony.css" rel="stylesheet">
- <link href="../../css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <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="../../css/datanucleus_theme.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/customisations.css" rel="stylesheet">
+ <!-- Coderay syntax formatter -->
<style type="text/css">
- pre code {
- background-color: inherit;
- border-style: none;
- }
-
- pre code > span:first-child {
- margin-left: -5px;
- }
-
- <style>
-
-
-
- <style>
- @media only screen and (min-width: 40.063em) {
- .top-bar {
- .contain-to-grid .top-bar {
- max-width: 80rem;
- }
- }
- }
- .row {
- max-width: 80rem;
- }
- </style>
- <style>
- .extended-quote,
- .extended-quote-first {
- margin-left: 40px;
- margin-right: 40px;
- font-style: italic;
- }
- .extended-quote-attribution {
- text-align: right;
- margin-right: 100px;
- color: #10B061;
- }
-
- .extended-quote-first:before {
- content: "\201c";
- float: left;
- font-size: 2.75em;
- font-weight: bold;
- line-height: 0.6em;
- margin-left: -0.6em;
- color: #003b6b;
- text-shadow: 0 1px 2px rgba(0, 0, 0, 0.1);
- }
- </style>
- <style>
- body {
- position: relative;
- }
-
- *:not(pre) a > code {
- color: #210DDC;
- }
-
- *:not(pre) > code {
- background-color: inherit;
- border: none;
- font-weight: normal;
- }
-
- body div#toc li,
- body div#toc2 li {
- list-style-type: none;
- }
-
- div#doc-content {
- margin-top: 30px;
- padding-top: 30px;
- }
-
- div.documentation-page table.frame-all {
- border-left: none;
- border-right: none;
- }
-
- body div#toc li.active-region:before,
- body div#toc2 li.active-region:before {
- content: "\00BB \0020";
- margin-left: -12px;
- }
-
- body div#toc li a.active,
- body div#toc2 li a.active {
- color: red;
- }
-
- body div#toc.toc,
- body div#toc.toc2 {
- position: fixed;
- left: auto;
- padding-top: 60px;
- z-index: auto;
- background-color: white;
- border-left-color: #eee;
- border-left-style: solid;
- border-right: none;
- min-height: 2000px;
- }
-
- </style>
- <style>
-
- @media only screen and (min-width: 768px) {
- #toc.toc2 ul ul { margin-left: -10px; }
- }
-
-
- body div#toc .tocify-subheader ul {
- margin-bottom: 0px;
- }
-
- body div#toc .tocify-subheader li {
- font-size: 14px;
- }
- .tocify li.tocify-item, .tocify ul.tocify-item {
- line-height: 24px;
- }
-
- body div#toc li.tocify-item.active:before,
- body div#toc2 li.tocify-item.active:before {
- content: "\00BB \0020";
- margin-left: -12px;
- }
-
- body div#toc li.tocify-item.active a,
- body div#toc2 li.tocify-item.active a {
- color: red;
- }
- </style>
- <style>
- footer {
- margin-top: 1000px;
- }
-
- .searchLink {
- font-size: larger;
- color:#10B061;
- }
-
- .searchScore {
- font-size: 12px;
- color: #D5810A;
- }
-
- .searchDescription {
- margin-top: 0px;
- margin-bottom: 0px;
- }
-
- #search-panel {
- display: none;
- border: lightgray solid 1px;
- padding: 10px;
- margin-top: 10px;
- margin-bottom: 10px;
- }
-
- #search-panel.active {
- display: inherit;
- }
- </style>
- <style>
- /* overriding colony.css stylesheet */
- .literalblock pre, .literalblock pre[class], .listingblock pre, .listingblock pre[class] {
- /*padding: 1.25em 1.5625em 1.125em 1.5625em;*/
- padding: 0.3em 0.6em 0.25em 0.6em;
- }
- @media only screen and (min-width: 1280px)
- #toc.toc2 {
- /*width: 20em;*/
- width: 25em;
- }
-
- #doc-content a {
- color: #210DDC;
- }
-
- .top-bar h1 {
- border-bottom: inherit;
- }
-
- h2 {
- margin-top: 80px;
- }
- h3 {
- margin-top: 40px;
- }
- h4,h5 {
- margin-top: 30px;
- }
-
- .admonitionblock.tip > table td.content {
- color: #10B061;
- }
- .admonitionblock.note > table td.content {
- color: #B509AB;
- }
- .admonitionblock.important > table td.content {
- color: #D5810A;
- }
-
- .admonitionblock .title {
- font-size: larger;
- font-style: italic;
- }
-
- .imageblock img {
- margin-bottom: 10px;
- }
- </style>
- <style>
- /* from http://ben.balter.com/2014/03/13/pages-anchor-links/ */
- .header-link {
- position: absolute;
- left: -0.5em;
- opacity: 0;
-
- /*
- -webkit-transition: opacity 0.2s ease-in-out 0.1s;
- -moz-transition: opacity 0.2s ease-in-out 0.1s;
- -ms-transition: opacity 0.2s ease-in-out 0.1s;
- */
- }
-
- h2:hover .header-link,
- h3:hover .header-link,
- h4:hover .header-link,
- h5:hover .header-link,
- h6:hover .header-link {
- opacity: 1;
- }
- </style>
- <style>
- .top-bar
- {
- -webkit-transition-duration: .5s;
- transition-duration: .5s;
-
- -webkit-transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
- transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
-
- -webkit-transition-property: -webkit-transform;
- transition-property: transform;
- }
-
- /*
- http://osvaldas.info/auto-hide-sticky-header
- MIT license
- */
- .header--hidden
- {
- -webkit-transform: translateY( -100% );
- -ms-transform: translateY( -100% );
- transform: translateY( -100% );
-
- transition-duration: .5s;
- transition-timing-function: cubic-bezier( 0.215, 0.610, 0.355, 1.000 );
- -webkit-transition-property: -webkit-transform;
- transition-property: transform;
- }
- </style>
- <style>
- #doc-content a.guide {
- color: white;
- }
+ /* 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>
- <style>
- .tocify {
- margin-top: 80px;
- }
- </style>
- <style>
- .tocify {
- margin-top: 80px;
- }
- </style>
</head>
- <body>
- <div class="row">
- <!-- pass through to app.js -->
- <div id="basedir" style="display:none;">
- ../../
- </div>
- <div id="docname" style="display:none;">
- ugodn
- </div>
- <div id="filetype" style="display:none;">
- html
- </div>
- <div class="fixed contain-to-grid header">
- <nav class="top-bar" data-topbar role="navigation" style="max-width: 80rem">
- <ul class="title-area">
- <li class="name"> <h1> <a href="../../index.html">Apache Isis™</a> </h1> </li>
- <!-- Remove the class "menu-icon" to get rid of menu icon. Take out "Menu" to just have icon alone -->
- <li class="toggle-topbar menu-icon"><a href="#"><span>Menu</span></a></li>
- </ul>
- <section class="top-bar-section">
- <ul class="right">
- <li class="has-form">
- <form id="search-form">
- <input class="form-control" id="search-field" type="text" length="30" placeholder="Search">
- </form> </li>
- </ul>
- <!-- Left Nav Section -->
- <ul class="left">
- <li><a href="../../documentation.html">Documentation</a></li>
- <li><a href="../../downloads.html">Downloads</a></li>
- <li><a href="../../help.html">Help</a></li>
- <li><a href="../../asf.html">@ASF</a></li>
- </ul>
- </section>
- </nav>
- </div>
+ <body data-spy="scroll" data-target="#toc">
+ <div id="basedir" style="display:none;">
+ ../../
</div>
- <div class="row">
- <div class="large-12 medium-12 columns">
- <br>
- <br>
- <br>
- </div>
+ <div id="docname" style="display:none;">
+ ugodn
+ </div>
+ <div id="filetype" style="display:none;">
+ html
</div>
- <div class="row">
- <div class="large-12 medium-12 columns">
- <div id="search-panel">
- <div id="search-results"></div>
- <div>
- <br>
- <a href=".">clear</a>
+ <!-- Navbar -->
+ <nav class="navbar navbar-default navbar-fixed-top">
+ <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/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>
+ </ul> </li>
+ <li class="dropdown"> <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><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="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype.html">Maven archetype</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></li>
+ <li><a href="http://github.com/apache/isis">Github mirror</a></li>
+ </ul> </li>
+ <li class="dropdown"> <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><a href="../../support.html">Mailing lists</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><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
+ <li><a href="guides/dg.html/dg.html">How to contribute</a></li>
+ <li><a href="../../help.html">Other resources</a></li>
+ </ul> </li>
+ <li class="dropdown"> <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>
- </div>
- <div class="row">
- <div id="doc-content-left" class="large-9 medium-9 columns">
- <div id="doc-content">
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <div class="sect1">
- <h2 id="_ugodn">1. DataNucleus Object Store</h2>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <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://datanuclues.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>
+ </nav>
+ <div class="container">
+ <div class="row-fluid">
+ <div class="col-sm-12">
+ <div id="search-panel">
+ <div id="search-results"></div>
+ <div>
+ <br>
+ <a href="#" id="search-results-clear">clear</a>
</div>
</div>
- <div class="sect1">
- <h2 id="_ugodn_configuring">2. Configuring DataNucleus</h2>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <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>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <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: 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.</code><br> <code>datanucleus.</code><br> <code>classMetadataLoadedListener</code></p>
- </div>
- </div></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock"><code>FQCN</code></p></td>
- <td class="tableblock halign-left valign-top">
- <div>
- <div class="paragraph">
- <p>The default (<code>o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata</code>) creates a DB schema object</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>RegisterEntities.packagePrefix</code></p>
- </div>
- </div></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">fully qualified package names (CSV)</p></td>
- <td class="tableblock halign-left valign-top">
- <div>
- <div class="paragraph">
- <p>that specifies the entities early rather than allow DataNucleus to find the entities lazily. Further <a href="../ugodn/ugodn.html#_ugodn_configuring_eagerly-registering-entities">discussion below</a>.</p>
- </div>
- <div class="paragraph">
- <p>This property is IGNORED if the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-components"><code>isis.appManifest</code></a> configuration property is specified, or if an <a href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a> is provided programmatically.</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"><p class="tableblock">zipped</p></td>
- <td class="tableblock halign-left valign-top">
- <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_persistence-xml">2.2. <code>persistence.xml</code></h3>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <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_eagerly-registering-entities">2.3. Eagerly Registering Entities</h3>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <div class="paragraph">
- <p>Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache Isis builds its metamodel by walking the graph of types of the domain services. The JDO/DataNucleus objectstore then takes these types and registers them with DataNucleus.</p>
- </div>
- <div class="paragraph">
- <p>In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.</p>
- </div>
- <div class="paragraph">
- <p>Apache Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating). In any case, it’s probably not good practice to have DataNucleus work this way.</p>
- </div>
- <div class="paragraph">
- <p>The framework thus provide mechanisms to search for all <code>@PersistenceCapable</code> entities under specified package(s), and registers them all eagerly. In fact there are two:</p>
- </div>
- <div class="ulist">
- <ul>
- <li> <p>as of 1.9.0 the recommended (and simpler) approach is to specify an <a href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a>, either as a <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-components"><code>isis.appManifest</code></a> configuration property or programmatically.</p> </li>
- <li> <p>for earlier versions the <code>isis.persistor.datanucleus.RegisterEntities.packagePrefix</code> configuration property can be specified. To bootstrap as a webapp this is usually specified in <code>persistor_datanucleus.properties</code>. (This is also supported in 1.9.0 if no <code>AppManifest</code> is specified. For integration testing this can be specified programatically.</p> </li>
- </ul>
- </div>
- <div class="paragraph">
- <p>Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the <a href="../ugtst/ugtst.html#_ugtst_integ-test-support_bootstrapping">user guide</a>.</p>
- </div>
- </div>
- <div class="sect2">
- <h3 id="_ugodn_configuring_disabling-persistence-by-reachability">2.4. Persistence by Reachability</h3>
- <button type="button" class="button secondary" 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"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ </div>
+ </div>
+ <div class="row-fluid">
+ <div class="col-sm-9">
+ <div class="page-title">
+ <h1>DataNucleus Object Store</h1>
+ </div>
+ <div id="doc-content">
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc"" style="float: right; font-size: small; padding: 6px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sect1">
+ <h2 id="_ugodn">1. DataNucleus Object Store</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
<div class="paragraph">
- <p>By default, JDO/DataNucleus supports the concept of <a href="http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html">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>DomainObjectContainer#persist(.)</code> or <code>DomainObjectContainer#persistIfNotAlready(.)</code> methods.</p>
+ <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://datanuclues.org">DataNucleus</a>.</p>
</div>
<div class="paragraph">
- <p>However, convenient though this feature is, you may find that it causes performance issues.</p>
+ <p>This user guide discuss end-user features, configuration and customization of the DataNucleus object store.</p>
</div>
- <div class="admonitionblock warning">
+ <div class="admonitionblock note">
<table>
<tbody>
<tr>
- <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td>
+ <td class="icon"> <i class="fa icon-note" title="Note"></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>
+ <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="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 the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a></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>DomainObjectContainer#persist(.)</code> or <code>DomainObjectContainer#persistIfNotAlready(.)</code> methods.</p>
- </div>
- <div class="sect3">
- <h4 id="_the_issue_in_more_detail">2.4.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">
- <img src="images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png" alt="party agreementrole agreement" width="750px">
- </div>
- </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
<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>
+ <p>Apache Isis documentation is broken out into a number of user and reference guides.</p>
</div>
<div class="paragraph">
- <p>while <code>Agreement</code>'s is implemented as:</p>
+ <p>The user guides available are:</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 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>and <code>Party</code>'s is similarly implemented as:</p>
+ <p>The reference guides are:</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 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>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>
+ <p>The remaining guides are:</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>
+ <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 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_using-jndi-data-source">2.5. Using JNDI DataSource</h3>
- <button type="button" class="button secondary" 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"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugodn_configuring">2. Configuring DataNucleus</h2>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="sectionbody">
<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>
+ <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="sect3">
- <h4 id="_application_managed">2.5.1. Application managed</h4>
+ <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>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_properties.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
<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>
+ <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: 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.</code><br> <code>datanucleus.</code><br> <code>classMetadataLoadedListener</code></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>FQCN</code></p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>The default (<code>o.a.i.os.jdo.dn.CreateSchemaObjectFromClassMetadata</code>) creates a DB schema object</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>RegisterEntities.packagePrefix</code></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock">fully qualified package names (CSV)</p></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>that specifies the entities early rather than allow DataNucleus to find the entities lazily. Further <a href="../ugodn/ugodn.html#_ugodn_configuring_eagerly-registering-entities">discussion below</a>.</p>
+ </div>
+ <div class="paragraph">
+ <p>This property is IGNORED if the <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-components"><code>isis.appManifest</code></a> configuration property is specified, or if an <a href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a> is provided programmatically.</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"><p class="tableblock">zipped</p></td>
+ <td class="tableblock halign-left valign-top">
+ <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_persistence-xml">2.2. <code>persistence.xml</code></h3>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
<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>
+ <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>For example:</p>
+ <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="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>
+ <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>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>
+ <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_eagerly-registering-entities">2.3. Eagerly Registering Entities</h3>
+ <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_eagerly-registering-entities.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <div class="paragraph">
+ <p>Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Apache Isis builds its metamodel by walking the graph of types of the domain services. The JDO/DataNucleus objectstore then takes these types and registers them with DataNucleus.</p>
+ </div>
+ <div class="paragraph">
+ <p>In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating). In any case, it’s probably not good practice to have DataNucleus work this way.</p>
+ </div>
+ <div class="paragraph">
+ <p>The framework thus provide mechanisms to search for all <code>@PersistenceCapable</code> entities under specified package(s), and registers them all eagerly. In fact there are two:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>as of 1.9.0 the recommended (and simpler) approach is to specify an <a href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a>, either as a <a href="../rgcfg/rgcfg.html#_rgcfg_configuring-components"><code>isis.appManifest</code></a> configuration property or programmatically.</p> </li>
+ <li> <p>for earlier versions the <code>isis.persistor.datanucleus.RegisterEntities.packagePrefix</code> configuration property can be specified. To bootstrap as a webapp this is usually specified in <code>persistor_datanucleus.properties</code>. (This is also supported in 1.9.0 if no <code>AppManifest</code> is specified. For integration testing this can be specified programatically.</p> </li>
+ </ul>
</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>
+ <p>Further discussion on specifying the package(s) in integration testing (for either approach) can be found in the <a href="../ugtst/ugtst.html#_ugtst_integ-test-support_bootstrapping">user guide</a>.</p>
</div>
</div>
- <div class="sect3">
- <h4 id="_container_managed_jndi">2.5.2. Container managed (JNDI)</h4>
+ <div class="sect2">
+ <h3 id="_ugodn_configuring_disabling-persistence-by-reachability">2.4. Persistence by Reachability</h3>
+ <button type="button" class="button secondary" 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"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
<div class="paragraph">
- <p>Using a datasource managed by the servlet container requires three separate bits of configuration.</p>
+ <p>By default, JDO/DataNucleus supports the concept of <a href="http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html">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>DomainObjectContainer#persist(.)</code> or <code>DomainObjectContainer#persistIfNotAlready(.)</code> methods.</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>
+ <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>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>
+ <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>Secondly, in the <code>WEB-INF/web.xml</code>, declare the resource reference:</p>
+ <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="xml"><span class="tag"><resource-ref></span>
+ <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 the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a></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>DomainObjectContainer#persist(.)</code> or <code>DomainObjectContainer#persistIfNotAlready(.)</code> methods.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_the_issue_in_more_detail">2.4.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">
+ <img src="images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png" alt="party agreementrole agreement" width="750px">
+ </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_using-jndi-data-source">2.5. Using JNDI DataSource</h3>
+ <button type="button" class="button secondary" 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"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <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>
- <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>
+ <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>
@@ -821,100 +702,100 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre
<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 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>
- <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <div class="sectionbody">
- <div class="sect2">
- <h3 id="_ugodn_jdo-mappings_1-to-m-bidirectional-relationships">3.1. 1-m Bidirectional relationships</h3>
- <button type="button" class="button secondary" 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"" style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button>
- <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>
<TRUNCATED>