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/[email protected]";>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">
