| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1"> |
| <title>Object Management (CRUD) :: Apache Isis</title> |
| <link rel="canonical" href="https://isis.apache.org/userguide/2.0.0-M3/fun/domain-entities-and-services/crud.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"> |
| </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="userguide" data-version="2.0.0-M3"> |
| <aside class="nav"> |
| <div class="panels"> |
| <div class="nav-panel-pagination"> |
| <a class="page-previous disabled" rel="prev" href="" title=""><span></span></a> |
| <a class="page-next disabled" rel="next" |
| href="" title=""><span></span></a> |
| <!-- |
| page.parent doesn't seem to be set... |
| <a class="page-parent disabled" rel="prev" href="" title=""><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">User Guide</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="../concepts-patterns.html">Concepts & Patterns</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../overview.html">Overview</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../domain-entities-and-services.html">Domain Entities & Services</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../object-members.html">Object Members</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../ui.html">UI Layout & Hints</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../business-rules.html">Business Rules</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../drop-downs-and-defaults.html">Drop downs and Defaults</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../meta-annotations.html">Meta-annotations</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../view-models.html">View Models</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../mixins.html">Mixins</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <a class="nav-link" href="../modules.html">Modules</a> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <a class="nav-link" href="../../btb/about.html">Beyond the Basics</a> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../../btb/i18n.html">i18n</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../../btb/headless-access.html">Headless Access</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../../btb/hints-and-tips.html">Hints-n-Tips</a> |
| </li> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../../btb/programming-model.html">Programming Model</a> |
| </li> |
| </ul> |
| </li> |
| <li class="nav-item" data-depth="1"> |
| <button class="nav-item-toggle"></button> |
| <span class="nav-text">Extensions</span> |
| <ul class="nav-list"> |
| <li class="nav-item" data-depth="2"> |
| <a class="nav-link" href="../../flyway/about.html">Flyway</a> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| </nav> |
| </div> |
| <div class="nav-panel-explore" data-panel="explore"> |
| <div class="context"> |
| <span class="title">User Guide</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"> |
| <span class="title">JDO/DataNucleus</span> |
| <ul class="versions"> |
| <li class="version is-latest"> |
| <a href="../../../../pjdo/2.0.0-M3/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 is-current"> |
| <span class="title">User Guide</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">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">User Guide</a></li> |
| <li><a href="crud.html">Object Management (CRUD)</a></li> |
| </ul> |
| </nav> |
| <div class="edit-this-page"><a href="https://github.com/apache/isis/edit/2.0.0-M3/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/crud.adoc">Edit</a></div> |
| </div> |
| <article class="doc"> |
| <a name="section-top"></a> |
| <h1 class="page">Object Management (CRUD)</h1> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>This chapter shows the idioms for creating, reading, updating and deleting <a href="../overview.html#domain-entities" class="page">domain entities</a>. |
| The main domain services used for this are <a href="../../../../refguide/2.0.0-M3/applib-svc/RepositoryService.html" class="page"><code>RepositoryService</code></a> and <a href="../../../../refguide/2.0.0-M3/applib-svc/FactoryService.html" class="page"><code>FactoryService</code></a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="instantiating"><a class="anchor" href="#instantiating"></a>Instantiating</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Domain entities can be instantiated using the <a href="../../../../refguide/2.0.0-M3/applib-svc/FactoryService.html" class="page"><code>FactoryService</code></a> provided by the framework. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = factoryService.detachedEntity(Customer.class);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The returned domain entity is not persistent and is unknown to the ORM; hence "detached".</p> |
| </div> |
| <div class="paragraph"> |
| <p>When the framework instantiates the object, all services are injected into the framework, and an <code>ObjectCreatedEvent</code> <a href="../overview.html#lifecycle-events" class="page">lifecycle event</a> will also be emitted.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You may prefer however for your domain entities to have regular constructor defining their minimum set of mandatory properties. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public class Customer { |
| |
| public Customer(String reference, String firstName, String lastName) { |
| // ... |
| } |
| |
| // ... |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In such cases, the domain object cannot be instantiated using <a href="../../../../refguide/2.0.0-M3/applib-svc/FactoryService.html" class="page"><code>FactoryService</code></a>. |
| Instead the <a href="../../../../refguide/2.0.0-M3/applib-svc/ServiceRegistry.html" class="page"><code>ServiceRegistry</code></a> service can be used to inject services:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = new Customer(reference, firstName, lastName); |
| serviceRegister.injectServicesInto(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you prefer, this can be performed in one step:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = serviceRegister.injectServicesInto( |
| new Customer(reference, firstName, lastName));</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note though that this does <em>not</em> raise any lifecycle event.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="persisting"><a class="anchor" href="#persisting"></a>Persisting</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Once a domain entity has been instantiated and initialized, it can be persisted using the <a href="../../../../refguide/2.0.0-M3/applib-svc/RepositoryService.html" class="page"><code>RepositoryService</code></a>.</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">Customer customer = ... |
| |
| repositoryService.persist(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If using the no-arg form to instantiate the entity, then (to save having to inject the <code>FactoryService</code> as well), the <code>RepositoryService</code> can also be used to instantiate. |
| This gives rise to this common idiom:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = repositoryService.instantiate(Customer.class); |
| customer.setReference(reference); |
| customer.setFirstName(firstName); |
| customer.setLastName(lastName); |
| ... |
| repositoryService.persist(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>On the other hand, there is often little need to inject services into the domain entity between its instantiation and persistence. |
| If the domain entity has an N-arg constructor, then the code is often simpler:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = repositoryService.persist(new Customer(reference, name, lastname));</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the <code>persist()</code> returns the object passed to it.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="eager-persistence"><a class="anchor" href="#eager-persistence"></a>Eager Persistence</h3> |
| <div class="paragraph"> |
| <p>It’s worth being aware that the framework does <em>not</em> eagerly persist the object. |
| Rather, it queues up an internal command structure representing the object persistence request. |
| This is then executed either at the end of the transaction, or if a <a href="../domain-entities-and-services.html#finding" class="page">query is run</a>, or if the internal queue is manually flushed using <a href="../../../../refguide/2.0.0-M3/applib-svc/TransactionService.html" class="page"><code>TransactionService</code></a>'s <code>flush()</code> method. |
| Flushing also happens when a repository query is executed, so that the pending persist operation is performed first. |
| Generally therefore the lazy persistence approach works well enough.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Nevertheless, if you want to ensure that the persist command is flushed immediately, you can use:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">repositoryService.persistAndFlush(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When an object is persisted the framework will emit <code>ObjectPersistingEvent</code> and <code>ObjectPersistedEvent</code> <a href="../overview.html#lifecycle-events" class="page">lifecycle events</a>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="persistence-by-reachability"><a class="anchor" href="#persistence-by-reachability"></a>Persistence by Reachability</h3> |
| <div class="paragraph"> |
| <p>It is also possible to configure ORM to automatically persist domain entities if they are associated with other already-persistent entities. |
| This avoid the need to explicitly call "persist".</p> |
| </div> |
| <div class="paragraph"> |
| <p>If using <a href="../../../../pjdo/2.0.0-M3/about.html" class="page">JDO/DataNucleus</a>, this is done using <a href="../../../../refguide/2.0.0-M3/config/sections/isis.persistence.jdo-datanucleus.impl.html#isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit" class="page">persistence-by-reachability</a> configuration property:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="title">application.properties</div> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-ini hljs" data-lang="ini">isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=true</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>One downside is that the code is arguably less easy to debug.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="finding"><a class="anchor" href="#finding"></a>Finding Objects (JDO)</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Retrieving domain entities depends on the ORM. |
| In the case of <a href="../../../../pjdo/2.0.0-M3/about.html" class="page">JDO/DataNucleus</a>, it typically requires a JDOQL query defined on the domain entity, and a corresponding repository service for that domain entity type. |
| This repository calls the framework-provided <a href="../../../../refguide/2.0.0-M3/applib-svc/RepositoryService.html" class="page"><code>RepositoryService</code></a> to actually submit the query.</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">@javax.jdo.annotations.Queries({ |
| @javax.jdo.annotations.Query( <i class="conum" data-value="1"></i><b>(1)</b> |
| name = "findByName", <i class="conum" data-value="2"></i><b>(2)</b> |
| value = "SELECT " <i class="conum" data-value="3"></i><b>(3)</b> |
| + "FROM com.mydomain.myapp.Customer " <i class="conum" data-value="4"></i><b>(4)</b> |
| + "WHERE name.indexOf(:name) >= 0 ") <i class="conum" data-value="5"></i><b>(5)</b> |
| }) |
| ... |
| public class Customer { |
| // ... |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>There may be several <code>@Query</code> annotations, nested within a <code>@Queries</code> annotation) defines queries using JDOQL.</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>Defines the name of the query.</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>The definition of the query, using JDOQL syntax.</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="4"></i><b>4</b></td> |
| <td>The fully-qualified class name. |
| Must correspond to the class on which the annotation is defined (the framework checks this automatically on bootstrapping).</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="5"></i><b>5</b></td> |
| <td>In this particular query, is an implementation of a LIKE "name%" query.</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">import org.springframework.stereotype.Repository; |
| import lombok.RequiredArgsConstructor; |
| |
| @Repository |
| @RequiredArgsConstructor(onConstructor_ = {@Inject} ) |
| public class CustomerRepository { |
| |
| private final RepositoryService repositoryService; |
| |
| public List<Customer> findByName(String name) { |
| return repositoryService.allMatches( <i class="conum" data-value="1"></i><b>(1)</b> |
| new QueryDefault<>(Customer.class, <i class="conum" data-value="2"></i><b>(2)</b> |
| "findByName", <i class="conum" data-value="3"></i><b>(3)</b> |
| "name", <i class="conum" data-value="4"></i><b>(4)</b> |
| name); |
| } |
| |
| }</code></pre> |
| </div> |
| </div> |
| <div class="colist arabic"> |
| <table> |
| <tr> |
| <td><i class="conum" data-value="1"></i><b>1</b></td> |
| <td>The <a href="../../../../refguide/2.0.0-M3/applib-svc/RepositoryService.html" class="page"><code>RepositoryService</code></a> is a generic facade over the JDO/DataNucleus API.</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="2"></i><b>2</b></td> |
| <td>Specifies the class that is annotated with @Query</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="3"></i><b>3</b></td> |
| <td>Corresponds to the <code>@Query#name</code> attribute</td> |
| </tr> |
| <tr> |
| <td><i class="conum" data-value="4"></i><b>4</b></td> |
| <td>Corresponds to the <code>:name</code> parameter in the query JDOQL string</td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Whenever a query is submitted, the framework will automatically "flush" any pending changes. |
| This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When an object is loaded from the database the framework will emit <code>ObjectLoadedEvent</code> <a href="../overview.html#lifecycle-events" class="page">lifecycle event</a>.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="type-safe-queries"><a class="anchor" href="#type-safe-queries"></a>Type-safe queries</h3> |
| <div class="paragraph"> |
| <p>DataNucleus also supports type-safe queries; these can be executed using the <a href="../../../../pjdo/2.0.0-M3/services/IsisJdoSupport.html" class="page"><code>IsisJdoSupport</code></a> (JDO-specific) domain service.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="../../../../pjdo/2.0.0-M3/services/IsisJdoSupport.html#type-safe-jdoql-queries" class="page">here</a> for further details.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="updating"><a class="anchor" href="#updating"></a>Updating Objects</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>There is no specific API to update a domain entity. |
| Rather, the ORM (DataNucleus) automatically keeps track of the state of each object and will update the corresponding database rows when the transaction completes.</p> |
| </div> |
| <div class="paragraph"> |
| <p>That said, it is possible to "flush" pending changes:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><a href="../../../../refguide/2.0.0-M3/applib-svc/TransactionService.html" class="page"><code>TransactionService</code></a> acts at the Apache Isis layer, and flushes any pending object persistence or object deletions</p> |
| </li> |
| <li> |
| <p>(if using <a href="../../../../pjdo/2.0.0-M3/about.html" class="page">JDO/DataNucleus</a>), the <a href="../../../../pjdo/2.0.0-M3/services/IsisJdoSupport.html" class="page"><code>IsisJdoSupport</code></a> domain service can be used reach down to the underlying JDO API, and perform a flush of pending object updates also.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>When an object is updated the framework will emit <code>ObjectUpdatingEvent</code> and <code>ObjectUpdatedEvent</code> <a href="../overview.html#lifecycle-events" class="page">lifecycle events</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="deleting"><a class="anchor" href="#deleting"></a>Deleting Objects</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Domain entities can be deleted using <a href="../../../../refguide/2.0.0-M3/applib-svc/RepositoryService.html" class="page"><code>RepositoryService</code></a>. |
| For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Customer customer = ... |
| repositoryService.remove(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It’s worth being aware that (as for persisting new entities) the framework does <em>not</em> eagerly delete the object. |
| Rather, it queues up an internal command structure representing the object deletion request. |
| This is then executed either at the end of the transaction, or if a <a href="../domain-entities-and-services.html#finding" class="page">query is run</a>, or if the internal queue is manually flushed using <a href="../../../../refguide/2.0.0-M3/applib-svc/TransactionService.html" class="page"><code>TransactionService</code></a>'s <code>flush()</code> method.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Alternatively, you can use:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">repositoryService.removeAndFlush(customer);</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>to eagerly perform the object deletion from the database.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When an object is deleted the framework will emit <code>ObjectRemovingEvent</code> <a href="../overview.html#lifecycle-events" class="page">lifecycle event</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> |
