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/08 23:28:10 UTC
[25/52] [abbrv] [partial] isis-site git commit: republishes,
updating content and creates new SNAPSHOT
http://git-wip-us.apache.org/repos/asf/isis-site/blob/9d921a51/content/guides/ugodn/ugodn.html
----------------------------------------------------------------------
diff --git a/content/guides/ugodn/ugodn.html b/content/guides/ugodn/ugodn.html
index 198a5aa..cd9bf05 100644
--- a/content/guides/ugodn/ugodn.html
+++ b/content/guides/ugodn/ugodn.html
@@ -179,6 +179,7 @@ table.CodeRay td.code>pre{padding:0}
<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>
@@ -196,25 +197,32 @@ table.CodeRay td.code>pre{padding:0}
</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><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 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="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></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><a href="../../support.html">Mailing lists</a></li>
+ <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="../../guides/dg/dg.html">How to contribute</a></li>
- <li><a href="../../help.html">Other resources</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">
@@ -374,8 +382,8 @@ table.CodeRay td.code>pre{padding:0}
</caption>
<colgroup>
<col style="width: 33.3333%;">
- <col style="width: 16.6666%;">
- <col style="width: 50.0001%;">
+ <col style="width: 33.3333%;">
+ <col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
@@ -389,14 +397,45 @@ table.CodeRay td.code>pre{padding:0}
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
+ <p><code>isis.persistor.</code><br> <code>datanucleus.</code><br> <code>standaloneCollection.</code><br> <code>bulkLoad</code></p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p><code>true</code>, <code>false</code><br> (<code>false</code>)</p>
+ </div>
+ </div></td>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
+ <p>Enables bulk load of standalone collections.</p>
+ </div>
+ <div class="paragraph">
+ <p>Further <a href="../ugodn/ugodn.html#_ugodn_configuring_bulk-load">discussion below</a>.</p>
+ </div>
+ </div></td>
+ </tr>
+ <tr>
+ <td class="tableblock halign-left valign-top">
+ <div>
+ <div class="paragraph">
<p><code>isis.persistor.</code><br> <code>datanucleus.</code><br> <code>classMetadataLoadedListener</code></p>
</div>
</div></td>
- <td class="tableblock halign-left valign-top"><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>
+ <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>
@@ -404,30 +443,81 @@ table.CodeRay td.code>pre{padding:0}
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p><code>isis.persistor.datanucleus.</code><br> <code>RegisterEntities.packagePrefix</code></p>
+ <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"><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>
+ <p>This property is derived automatically derived from the set of modules provided in the <a href="../rgcms/rgcms.html#_rgcms_classes_super_AppManifest"><code>AppManifest</code></a>, and so does not need to be specified explicitly.</p>
</div>
<div class="paragraph">
- <p>This property is IGNORED if the <a href="../rgcfg/rgcfg.html#_rgcfg_specifying-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>
+ <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.</code><br> <code>datanucleus.</code><br> <code>PublishingService.</code><br> <code>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 class="paragraph">
+ <p>Also:</p>
+ </div>
+ <table class="tableblock frame-all grid-all spread">
+ <colgroup>
+ <col style="width: 33.3333%;">
+ <col style="width: 16.6666%;">
+ <col style="width: 50.0001%;">
+ </colgroup>
+ <thead>
+ <tr>
+ <th class="tableblock halign-left valign-top">Property</th>
+ <th class="tableblock halign-left valign-top">Value<br> (default value)</th>
+ <th class="tableblock halign-left valign-top">Description</th>
+ </tr>
+ </thead>
+ <tbody>
<tr>
<td class="tableblock halign-left valign-top">
<div>
<div class="paragraph">
- <p><code>isis.persistor.datanucleus.</code><br> <code>PublishingService.serializedForm</code></p>
+ <p><code>isis.persistor.</code><br> <code>disable</code><br> <code>ConcurrencyChecking</code></p>
</div>
</div></td>
- <td class="tableblock halign-left valign-top"><p class="tableblock">zipped</p></td>
+ <td class="tableblock halign-left valign-top"><p class="tableblock"><code>true</code>,<code>false</code><br> (<code>false</code>)</p></td>
<td class="tableblock halign-left valign-top">
- <div></div></td>
+ <div>
+ <div class="paragraph">
+ <p>Disables concurrency checking globally. <br></p>
+ </div>
+ <div class="paragraph">
+ <p>Only intended for "emergency use" as a workaround while pending fix/patch to Apache Isis itself. (Note that there is no "datanucleus" in the property).</p>
+ </div>
+ </div></td>
</tr>
</tbody>
</table>
@@ -486,91 +576,63 @@ table.CodeRay td.code>pre{padding:0}
</div>
</div>
<div class="sect2">
- <h3 id="_ugodn_configuring_persistence-xml">2.2. <code>persistence.xml</code></h3>
+ <h3 id="_ugodn_configuring_bulk-load">2.2. Bulk Load of Standalone Collections</h3>
<div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
- <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="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" 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_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>
+ <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>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>
+ <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>Here’s the one provided by the <a href="../ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">SimpleApp archetype</a>:</p>
+ <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="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>
+ <pre class="CodeRay highlight"><code data-lang="ini">isis.persistor.datanucleus.standaloneCollection.bulkLoad=true</code></pre>
</div>
</div>
<div class="paragraph">
- <p>Normally all one needs to do is to change the <code>persistence-unit</code> name.</p>
+ <p>changes to a more efficient implementation that bulk loads all the objects using a single query.</p>
</div>
- <div class="admonitionblock tip">
+ <div class="admonitionblock note">
<table>
<tbody>
<tr>
- <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="icon"> <i class="fa icon-note" title="Note"></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>
+ <p>In the future the bulkLoad implementation may be made the default.</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>
- <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_eagerly-registering-entities.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_eagerly-registering-entities.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_eagerly-registering-entities.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_eagerly-registering-entities.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_eagerly-registering-entities.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>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 <code>1.9.0</code> 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_specifying-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 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.4. Persistence by Reachability</h3>
+ <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>
@@ -618,7 +680,7 @@ table.CodeRay td.code>pre{padding:0}
<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.4.1. The issue in more detail</h4>
+ <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>
@@ -685,6 +747,56 @@ table.CodeRay td.code>pre{padding:0}
</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>
@@ -827,7 +939,7 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre
</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>
+ <p>Testing (against <code>dn-core 4.1.7</code>/<code>dn-rdbms 4.1.9</code>) has determined there are two main rules:</p>
</div>
<div class="ulist">
<ul>
@@ -1353,7 +1465,7 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre
<p>In the same way that Java packages act as a namespace for domain objects, it’s good practice to map domain entities to their own (database) schemas.</p>
</div>
<div class="paragraph">
- <p>As of <code>1.9.0</code>, all the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules do this. For example:</p>
+ <p>All the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules do this. For example:</p>
</div>
<div class="listingblock">
<div class="content">
@@ -1410,23 +1522,10 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre
<div class="sect2">
<h3 id="_listener_to_create_schema">4.1. Listener to create schema</h3>
<div class="paragraph">
- <p>JDO/DataNucleus does not automatically create these schema objects, but it <em>does</em> provide a listener callback API on the initialization of each class into the JDO metamodel.</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>Actually, the above statement isn’t quite true. In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas. As of Apache Isis 1.9.0 and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we’ve decided to leave it in.</p>
- </div> </td>
- </tr>
- </tbody>
- </table>
+ <p>Apache Isis automatically creates owning schema objects for the tables that correspond to each entity class in the JDO metamodel.</p>
</div>
<div class="paragraph">
- <p>Therefore Apache Isis attaches a listener, <code>CreateSchemaObjectFromClassMetadata</code>, that checks for the schema’s existence, and creates the schema if required.</p>
+ <p>This is done by installing a listener, <code>CreateSchemaObjectFromClassMetadata</code>, on a callback provided by JDO/DataNucleus. The listener is invoked on the initialization of each class. It checks for the schema’s existence, and creates the schema if required.</p>
</div>
<div class="paragraph">
<p>The guts of its implementation is:</p>
@@ -1583,7 +1682,7 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=</code></pre
<p>The second approach (using an <code>.orm</code> file) is therefore often more useful than the first, because the metadata provided overrides rather than replaces the annotations (and annotations not overridden continue to be honoured).</p>
</div>
<div class="paragraph">
- <p>A typical use case is to change the database schema for an entity. For example, as of <code>1.9.0</code> the various (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules use schemas for each entity. For example, the <code>AuditEntry</code> entity in the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit module is annotated as:</p>
+ <p>A typical use case is to change the database schema for an entity. For example, the various (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> modules use schemas for each entity. For example, the <code>AuditEntry</code> entity in the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s audit module is annotated as:</p>
</div>
<div class="listingblock">
<div class="content">