| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>JDO Mappings :: Apache Isis</title> |
| <link rel="canonical" href="https://isis.apache.org/pjdo/2.0.0-M3/jdo-mappings.html"> |
| <meta name="generator" content="Antora 2.2.0"> |
| <link rel="stylesheet" href="../../_/css/site.css"> |
| <link rel="stylesheet" href="../../_/css/site-custom.css"> |
| <link href="https://fonts.googleapis.com/css?family=Open+Sans:300,300i,400,400i,700,700i|Raleway:300,400,500,700,800|Montserrat:300,400,700" rel="stylesheet"> |
| <link rel="home" href="https://isis.apache.org" title="Apache Isis"> |
| <link rel="next" href="db-schemas.html" title="DB Schemas"> |
| <link rel="prev" href="configuring.html" title="Configuring"> |
| </head> |
| <body class="article"> |
| <header class="header"> |
| <nav class="navbar"> |
| <div class="navbar-brand"> |
| <a class="navbar-item" href="https://isis.apache.org"> |
| <span class="icon"> |
| <img src="../../_/img/isis-logo-48x48.png"></img> |
| </span> |
| <span>Apache Isis</span> |
| </a> |
| <button class="navbar-burger" data-target="topbar-nav"> |
| <span></span> |
| <span></span> |
| <span></span> |
| </button> |
| </div> |
| <div id="topbar-nav" class="navbar-menu"> |
| <a class="navbar-end"> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Quick Start</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Starter Apps</span> |
| <a class="navbar-item" href="../../docs/latest/starters/helloworld.html">Hello World</a> |
| <a class="navbar-item" href="../../docs/latest/starters/simpleapp.html">Simple App</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Demos & Tutorials</span> |
| <a class="navbar-item" href="../../docs/latest/demo/about.html">Demo App</a> |
| <a class="navbar-item" href="https://danhaywood.gitlab.io/isis-petclinic-tutorial-docs/petclinic/1.16.2/intro.html">Petclinic (tutorial)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Resources</span> |
| <a class="navbar-item" href="../../docs/latest/resources/cheatsheet.html">Cheatsheet</a> |
| <a class="navbar-item" href="../../docs/latest/resources/icons.html">Icons</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Guides</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Development</span> |
| <a class="navbar-item" href="../../setupguide/latest/about.html">Setup Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Core</span> |
| <a class="navbar-item" href="../../userguide/latest/about.html">User Guide</a> |
| <a class="navbar-item" href="../../refguide/latest/about.html">Reference Guide</a> |
| <a class="navbar-item" href="../../testing/latest/about.html">Testing Guide</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Libraries</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">For Use in Apps</span> |
| <a class="navbar-item" href="../../subdomains/latest/about.html">Subdomain Libraries</a> |
| <a class="navbar-item" href="../../valuetypes/latest/about.html">Value Types</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Integrate between Apps</span> |
| <a class="navbar-item" href="../../mappings/latest/about.html">Bounded Context Mapping Libraries</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Other</span> |
| <a class="navbar-item" href="../../incubator/latest/about.html">Incubator</a> |
| <a class="navbar-item" href="../../legacy/latest/about.html">Legacy</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Components</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Viewers</span> |
| <a class="navbar-item" href="../../vw/latest/about.html">Wicket UI</a> |
| <a class="navbar-item" href="../../vro/latest/about.html">Restful Objects (REST)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Security</span> |
| <a class="navbar-item" href="../../security/latest/about.html">Security Guide</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Persistence</span> |
| <a class="navbar-item" href="../../pjdo/latest/about.html">DataNucleus (JDO)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Extensions</span> |
| <a class="navbar-item" href="../../extensions/latest/about.html">Extensions Catalog</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">Support</a> |
| <div class="navbar-dropdown"> |
| <span class="navbar-item navbar-heading">Contact</span> |
| <a class="navbar-item" href="../../docs/latest/support/slack-channel.html">Slack</a> |
| <a class="navbar-item" href="../../docs/latest/support/mailing-list.html">Mailing Lists</a> |
| <a class="navbar-item" href="https://issues.apache.org/jira/browse/ISIS">JIRA</a> |
| <a class="navbar-item" href="https://stackoverflow.com/questions/tagged/isis">Stack Overflow</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Releases</span> |
| <a class="navbar-item" href="../../docs/latest/downloads/how-to.html">Downloads</a> |
| <a class="navbar-item" href="../../relnotes/latest/about.html">Release Notes</a> |
| <a class="navbar-item" href="../../docs/latest/archive/1-x.html">Archive (1.x)</a> |
| <hr class="navbar-divider"/> |
| <span class="navbar-item navbar-heading">Framework</span> |
| <a class="navbar-item" href="../../conguide/latest/about.html">Contributors' Guide</a> |
| <a class="navbar-item" href="../../comguide/latest/about.html">Committers' Guide</a> |
| <a class="navbar-item" href="../../core/latest/about.html">Core Design</a> |
| </div> |
| </div> |
| <div class="navbar-item has-dropdown is-hoverable"> |
| <a class="navbar-link" href="#">ASF</a> |
| <div class="navbar-dropdown"> |
| <a class="navbar-item" href="http://www.apache.org/">Apache Homepage</a> |
| <a class="navbar-item" href="https://www.apache.org/events/current-event">Events</a> |
| <a class="navbar-item" href="https://www.apache.org/licenses/">Licenses</a> |
| <a class="navbar-item" href="https://www.apache.org/security/">Security</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| <a class="navbar-item" href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| <hr class="navbar-divider"/> |
| <a class="navbar-item" href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a> |
| </div> |
| </div> |
| <a class="navbar-item" href="../../docs/latest/about.html"> |
| <span class="icon"> |
| <img src="../../_/img/home.png"></img> |
| </span> |
| </a> |
| </div> |
| </div> |
| </nav> |
| </header> |
| <div class="body "> |
| <div class="nav-container" data-component="pjdo" data-version="2.0.0-M3"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-pagination"> |
| <a class="page-previous" rel="prev" href="configuring.html" title="Configuring"><span></span></a> |
| <a class="page-next" rel="next" |
| href="db-schemas.html" title="DB Schemas"><span></span></a> |
| <!-- |
| page.parent doesn't seem to be set... |
| <a class="page-parent disabled" rel="prev" href="" title="Configuring"><span></span></a> |
| --> |
| </div> |
| <div class="nav-panel-menu is-active" data-panel="menu"> |
| <nav class="nav-menu"> |
| <h3 class="title"><a href="about.html">JDO/DataNucleus</a></h3> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="0"> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="configuring.html">Configuring</a> |
| </li> |
| <li class="nav-item is-current-page" data-depth="1"> |
| <a class="nav-link" href="jdo-mappings.html">JDO Mappings</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="db-schemas.html">DB Schemas</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="hints-and-tips.html">Hints-n-Tips</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <span class="nav-text">Domain Services</span> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="services/IsisJdoSupport.html">IsisJdoSupport</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">JDO/DataNucleus</span> |
| <span class="version">2.0.0-M3</span> |
| </div> |
| <ul class="components"> |
| <li class="component"> |
| <span class="title"> </span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../docs/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">BC Mappings Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../mappings/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Committers' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../comguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Contributors' Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../conguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Design Docs</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../core/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Extensions Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../extensions/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Incubator Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../incubator/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component is-current"> |
| <span class="title">JDO/DataNucleus</span> |
| <ul class="versions"> |
| <li class="version is-current is-latest"> |
| <a href="about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Legacy Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../legacy/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Reference Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../refguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Release Notes</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../relnotes/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Restful Objects Viewer</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../vro/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Security Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../security/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Setup Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../setupguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Subdomains Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../subdomains/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Testing Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../testing/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">User Guide</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../userguide/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Value Types Catalog</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../valuetypes/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| <li class="component"> |
| <span class="title">Wicket Viewer</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../vw/2.0.0-M3/about.html">2.0.0-M3</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </aside> |
| </div> |
| <main role="main"> |
| <div class="toolbar" role="navigation"> |
| <button class="nav-toggle"></button> |
| <a href="../../docs/2.0.0-M3/about.html" class="home-link"></a> |
| <nav class="breadcrumbs" aria-label="breadcrumbs"> |
| <ul> |
| <li><a href="about.html">JDO/DataNucleus</a></li> |
| <li><a href="jdo-mappings.html">JDO Mappings</a></li> |
| </ul> |
| </nav> |
| <div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M3/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc">Edit</a></div> |
| </div> |
| <article class="doc"> |
| <a name="section-top"></a> |
| <h1 class="page">JDO Mappings</h1> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| TODO: this content has not yet been reviewed/updated for v2.0 |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="one-to-m-bidirectional-relationships"><a class="anchor" href="#one-to-m-bidirectional-relationships"></a>1-m Bidirectional relationships</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Consider a bidirectional one-to-many association between two entities; a collection member in the "parent" and a property member on the "child".</p> |
| </div> |
| <div class="paragraph"> |
| <p>We can tell DataNucleus about the bidirectionality using <code>@Persistent(mappedBy=…​)</code>, or we can take responsibility for |
| this aspect ourselves.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In addition, the two entities can be associated either without or with a join table (indicated by the <code>@Join</code> annotation):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>without a join table is more common; a regular foreign key in the child table for <code>FermentationVessel</code> points back up to the associated parent <code>Batch</code></p> |
| </li> |
| <li> |
| <p>with a join table; a link table holds the tuple representing the linkage.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Testing (against <code>dn-core 4.1.7</code>/<code>dn-rdbms 4.1.9</code>) has determined there are two main rules:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>If not using <code>@Join</code>, then the association must be maintained by setting the child association on the parent.<br></p> |
| <div class="paragraph"> |
| <p>It is not sufficient to simply add the child object to the parent’s collection.</p> |
| </div> |
| </li> |
| <li> |
| <p><code>@Persistent(mappedBy=…​)</code> and <code>@Join</code> cannot be used together.<br></p> |
| <div class="paragraph"> |
| <p>Put another way, if using <code>@Join</code> then you must maintain both sides of the relationship in the application code.</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In the examples that follow, we use two entities, <code>Batch</code> and <code>FermentationVessel</code> (from a brewery domain). In the |
| original example domain the relationship between these two entities was optional (a <code>FermentationVessel</code> may |
| have either none or one <code>Batch</code> associated with it); for the purpose of this article we’ll explore both mandatory and |
| optional associations.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="mandatory-no-join"><a class="anchor" href="#mandatory-no-join"></a>Mandatory, no <code>@Join</code></h3> |
| <div class="paragraph"> |
| <p>In the first scenario we have use <code>@Persistent(mappedBy=…​)</code> to indicate a bidirectional association, without any <code>@Join</code>:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Batch { |
| |
| // getters and setters omitted |
| |
| @Persistent(mappedBy = "batch", dependentElement = "false") <i class="conum" data-value="1"></i><b>(1)</b> |
| private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>(); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>"mappedBy" means this is bidirectional</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>and</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class FermentationVessel implements Comparable<FermentationVessel> { |
| |
| // getters and setters omitted |
| |
| @Column(allowsNull = "false") <i class="conum" data-value="1"></i><b>(1)</b> |
| private Batch batch; |
| |
| @Column(allowsNull = "false") |
| private State state; <i class="conum" data-value="2"></i><b>(2)</b> |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>mandatory association up to parent</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>State is an enum (omitted)</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Which creates this schema:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">CREATE TABLE "batch"."Batch" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| ... |
| "version" BIGINT NOT NULL, |
| CONSTRAINT "Batch_PK" PRIMARY KEY ("id") |
| ) |
| CREATE TABLE "fvessel"."FermentationVessel" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| "batch_id_OID" BIGINT NOT NULL, |
| "state" NVARCHAR(255) NOT NULL, |
| ... |
| "version" TIMESTAMP NOT NULL, |
| CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id") |
| )</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>That is, there is an mandatory foreign key from <code>FermentationVessel</code> to <code>Batch</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this case we can use this code:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public Batch transfer(final FermentationVessel vessel) { |
| vessel.setBatch(this); <i class="conum" data-value="1"></i><b>(1)</b> |
| vessel.setState(FermentationVessel.State.FERMENTING); |
| return this; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>set the parent on the child</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>This sets up the association correctly, using this SQL:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">UPDATE "fvessel"."FermentationVessel" |
| SET "batch_id_OID"=<0> |
| ,"state"=<'FERMENTING'> |
| ,"version"=<2016-07-07 12:37:14.968> |
| WHERE "id"=<0></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The following code will also work:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public Batch transfer(final FermentationVessel vessel) { |
| vessel.setBatch(this); <i class="conum" data-value="1"></i><b>(1)</b> |
| getVessels().add(vessel); <i class="conum" data-value="2"></i><b>(2)</b> |
| vessel.setState(FermentationVessel.State.FERMENTING); |
| return this; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>set the parent on the child</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>add the child to the parent’s collection.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>However, obviously the second statement is redundant.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="optional-no-join"><a class="anchor" href="#optional-no-join"></a>Optional, no <code>@Join</code></h3> |
| <div class="paragraph"> |
| <p>If the association to the parent is made optional:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class FermentationVessel implements Comparable<FermentationVessel> { |
| |
| // getters and setters omitted |
| |
| @Column(allowsNull = "true") <i class="conum" data-value="1"></i><b>(1)</b> |
| private Batch batch; |
| |
| @Column(allowsNull = "false") |
| private State state; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>optional association up to parent</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Which creates this schema:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">CREATE TABLE "batch"."Batch" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| ... |
| "version" BIGINT NOT NULL, |
| CONSTRAINT "Batch_PK" PRIMARY KEY ("id") |
| ) |
| CREATE TABLE "fvessel"."FermentationVessel" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| "batch_id_OID" BIGINT NULL, |
| "state" NVARCHAR(255) NOT NULL, |
| ... |
| "version" TIMESTAMP NOT NULL, |
| CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id") |
| )</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This is almost exactly the same, except the foreign key from <code>FermentationVessel</code> to <code>Batch</code> is now nullable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this case then setting the parent on the child still works:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public Batch transfer(final FermentationVessel vessel) { |
| vessel.setBatch(this); <i class="conum" data-value="1"></i><b>(1)</b> |
| vessel.setState(FermentationVessel.State.FERMENTING); |
| return this; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>set the parent on the child</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p><strong>HOWEVER</strong>, if we (redundantly) update both sides, then - paradoxically - the association is NOT set up</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public Batch transfer(final FermentationVessel vessel) { |
| vessel.setBatch(this); <i class="conum" data-value="1"></i><b>(1)</b> |
| getVessels().add(vessel); <i class="conum" data-value="2"></i><b>(2)</b> |
| vessel.setState(FermentationVessel.State.FERMENTING); |
| return this; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>set the parent on the child</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>add the child to the parent’s collection.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="admonitionblock note"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-note" title="Note"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>It’s not clear if this is a bug in <code>dn-core 4.1.7</code>/<code>dn-rdbms 4.19</code>; an earlier thread on the mailing list from 2014 actually gave |
| the opposite advice, see <a href="http://isis.markmail.org/thread/ipu2lzqqikqdglox">this thread</a> and in particular this <a href="http://markmail.org/message/hblptpw675mlw723">message</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In fact we also have had a different case raised (url lost) which argues that the parent should only be set on the child, and the child <em>not</em> added to the parent’s collection. |
| This concurs with the most recent testing.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Therefore, the simple advice is that, for bidirectional associations, simply set the parent on the child, and this will work |
| reliably irrespective of whether the association is mandatory or optional.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="with-join"><a class="anchor" href="#with-join"></a>With <code>@Join</code></h3> |
| <div class="paragraph"> |
| <p>Although DataNucleus does not complain if <code>@Persistence(mappedBy=…​)</code> and <code>@Join</code> are combined, testing (against <code>dn-core 4.1.7</code>/<code>dn-rdbms 4.19</code>) has shown that the bidirectional association is not properly maintained.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Therefore, we recommend that if <code>@Join</code> is used, then manually maintain both sides of the relationship and do not indicate |
| that the association is bidirectional.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Batch { |
| |
| // getters and setters omitted |
| |
| @Join(table = "Batch_vessels") |
| @Persistent(dependentElement = "false") |
| private SortedSet<FermentationVessel> vessels = new TreeSet<FermentationVessel>(); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>and</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class FermentationVessel implements Comparable<FermentationVessel> { |
| |
| // getters and setters omitted |
| |
| @Column(allowsNull = "true") <i class="conum" data-value="1"></i><b>(1)</b> |
| private Batch batch; |
| |
| @Column(allowsNull = "false") |
| private State state; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>optional association up to parent</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>creates this schema:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">CREATE TABLE "batch"."Batch" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| ... |
| "version" BIGINT NOT NULL, |
| CONSTRAINT "Batch_PK" PRIMARY KEY ("id") |
| ) |
| CREATE TABLE "fvessel"."FermentationVessel" |
| ( |
| "id" BIGINT GENERATED BY DEFAULT AS IDENTITY, |
| "state" NVARCHAR(255) NOT NULL, |
| ... |
| "version" TIMESTAMP NOT NULL, |
| CONSTRAINT "FermentationVessel_PK" PRIMARY KEY ("id") |
| ) |
| CREATE TABLE "batch"."Batch_vessels" |
| ( |
| "id_OID" BIGINT NOT NULL, |
| "id_EID" BIGINT NOT NULL, |
| CONSTRAINT "Batch_vessels_PK" PRIMARY KEY ("id_OID","id_EID") |
| )</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>That is, there is NO foreign key from <code>FermentationVessel</code> to <code>Batch</code>, instead the <code>Batch_vessels</code> table links the two together.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These should then be maintained using:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public Batch transfer(final FermentationVessel vessel) { |
| vessel.setBatch(this); <i class="conum" data-value="1"></i><b>(1)</b> |
| getVessels().add(vessel); <i class="conum" data-value="2"></i><b>(2)</b> |
| vessel.setState(FermentationVessel.State.FERMENTING); |
| return this; |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>set the parent on the child</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>add the child to the parent’s collection.</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>that is, explicitly update both sides of the relationship.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This generates this SQL:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-sql hljs" data-lang="sql">INSERT INTO "batch"."Batch_vessels" ("id_OID","id_EID") VALUES (<0>,<0>) |
| UPDATE "batch"."Batch" |
| SET "version"=<3> |
| WHERE "id"=<0> |
| UPDATE "fvessel"."FermentationVessel" |
| SET "state"=<'FERMENTING'> |
| ,"version"=<2016-07-07 12:49:21.49> |
| WHERE "id"=<0></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It doesn’t matter in these cases whether the association is mandatory or optional; it will be the same SQL generated.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="mandatory-properties-in-subtypes"><a class="anchor" href="#mandatory-properties-in-subtypes"></a>Mandatory Properties in Subtypes</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>If you have a hierarchy of classes then you need to decide which inheritance strategy to use.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>"table per hierarchy", or "rollup" (<code>InheritanceStrategy.SUPERCLASS_TABLE</code>)<br></p> |
| <div class="paragraph"> |
| <p>whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up</p> |
| </div> |
| </li> |
| <li> |
| <p>"table per class" (<code>InheritanceStrategy.NEW_TABLE</code>)<br></p> |
| <div class="paragraph"> |
| <p>whereby there is a table for both superclass and subclass, in 1:1 correspondence</p> |
| </div> |
| </li> |
| <li> |
| <p>"rolldown" (<code>InheritanceStrategy.SUBCLASS_TABLE</code>)<br></p> |
| <div class="paragraph"> |
| <p>whereby a single table holds the properties of the subtype, and also holds the properties of its supertype</p> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the <code>@Property(optionality=Optionality.MANDATORY)</code> annotation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import javax.jdo.annotations.Column; |
| import javax.jdo.annotations.Inheritance; |
| import javax.jdo.annotations.InheritanceStrategy; |
| import lombok.Getter; |
| import lombok.Setter; |
| |
| @Inheritance(strategy = InheritanceStrategy.SUPER_TABLE) |
| public class SomeSubtype extends SomeSuperType { |
| @Column(allowsNull="true") |
| @Property(optionality=Optionality.MANDATORY) |
| @Getter @Setter |
| private LocalDate date; |
| }</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="mapping-to-a-view"><a class="anchor" href="#mapping-to-a-view"></a>Mapping to a View</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>JDO/DataNucleus supports the ability to map the entity that is mapped to a view rather than a database table. |
| Moreover, DataNucleus itself can create/maintain this view.</p> |
| </div> |
| <div class="paragraph"> |
| <p>One use case for this is to support use cases which act upon aggregate information. |
| An <a href="https://github.com/estatio/estatio/blob/b77d0b03ec86463227ba90f8341299066ddba69f/estatioapp/module/lease/dom/src/main/java/org/estatio/dom/lease/invoicing/viewmodel/InvoiceSummaryForPropertyDueDateStatus.java#L57">example</a> is in the (non-ASF) <a href="http://github.com/estatio/estatio">Estatio</a> application, which uses a view to define an "invoice run": a representatoin of all pending invoices to be sent out for a particular shopping centre. |
| (Note that example also shows the entity as being "non-durable", but if the view is read/write then — I think — that this isn’t necessary required).</p> |
| </div> |
| <div class="paragraph"> |
| <p>For more on this topic, see the <a href="http://www.datanucleus.org/products/datanucleus/jdo/mapping.html#schema_rdbms_views">DataNucleus documentation</a>.</p> |
| </div> |
| </div> |
| </div> |
| </article> |
| <aside class="article-aside toc" role="navigation"> |
| <p class="toc-title">On this page</p> |
| <div id="article-toc"></div> |
| </aside> |
| </main> |
| </div> |
| <footer class="footer"> |
| <div class="content"> |
| <div class="copyright"> |
| <p> |
| Copyright © 2010~2020 The Apache Software Foundation, licensed under the Apache License, v2.0. |
| <br/> |
| Apache, the Apache feather logo, Apache Isis, and the Apache Isis project logo are all trademarks of The Apache Software Foundation. |
| </p> |
| </div> |
| <div class="revision"> |
| <p>Revision: SNAPSHOT</p> |
| </div> |
| </div> |
| </footer> |
| <script src="../../_/js/site.js"></script> |
| <script async src="../../_/js/vendor/highlight.js"></script> |
| <script src="../../_/js/vendor/jquery-3.4.1.min.js"></script> |
| <script src="../../_/js/vendor/jquery-ui-1.12.1.custom.widget-only.min.js"></script> |
| <script src="../../_/js/vendor/jquery.tocify.min.js"></script> |
| |
| <script> |
| $(function() { |
| $("#article-toc").tocify( { |
| showEffect: "slideDown", |
| hashGenerator: "pretty", |
| hideEffect: "slideUp", |
| selectors: "h2, h3", |
| scrollTo: 120, |
| smoothScroll: true, |
| theme: "jqueryui", |
| highlightOnScroll: true |
| } ); |
| }); |
| </script> |
| </body> |
| </html> |
