Google Git
Sign in
apache / db-jdo-site / refs/heads/publish / . / state_transition.html
blob: 28b2b1f14e0a011ce1f9dbb00088b0000ea8cc2c [file] [log] [blame]
<!DOCTYPE html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!-- No caching headers -->
<meta http-equiv="cache-control" content="no-cache"/>
<meta http-equiv="pragma" content="no-cache"/>
<meta http-equiv="expires" content="-1"/>
<meta name="keywords" content="JDO, Apache, Java, Data, Objects"/>
<meta name="description" content="Apache JDO - Java Data Objects"/>
<title>JDO State Transition</title>
<link rel="icon" type="image/png" href="images/JDOx150.png"/>
<!--
Apache JDO Documentation Template
==================================
This template derived various aspects from Apache Deltaspike template, the Apache ISIS template and the Datanucleus template.
This template uses
* Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
* Asciidoctor "foundation" CSS
* Bootswatch "cosmo" theme for Bootstrap (https://bootswatch.com/cosmo).
* Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/) for the table of contents.
* jQuery (necessary for Bootstrap's JavaScript plugins)
* Font-Awesome for some icons used by Asciidoctor
NOTE: tried using Font-Awesome CSS hosted locally but then fails to work!
-->
<link href="css/bootswatch/3.3.7/bootstrap-cosmo.css" rel="stylesheet"/>
<link href="css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet"/>
<link href="css/asciidoctor/foundation.css" rel="stylesheet"/>
<link href="css/datanucleus_theme.css" rel="stylesheet"/>
<link href="css/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet"/>
<script src="js/jquery/1.12.4/jquery.min.js"></script>
<script src="js/bootstrap/3.3.7/bootstrap.min.js"></script>
<script src="js/bootstrap-toc/0.4.1/bootstrap-toc.min.js"></script>
<!-- Coderay syntax formatter -->
<style type="text/css">
/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
pre.CodeRay{background:#f7f7f8}
.CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
.CodeRay .line-numbers strong{color:#000}
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.CodeRay td{vertical-align:top;line-height:inherit}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.code{padding:0 0 0 .75em}
.CodeRay .debug{color:#fff!important;background:navy!important}
.CodeRay .annotation{color:#007}
.CodeRay .attribute-name{color:navy}
.CodeRay .attribute-value{color:#700}
.CodeRay .binary{color:#509}
.CodeRay .comment{color:#998;font-style:italic}
.CodeRay .char{color:#04d}
.CodeRay .char .content{color:#04d}
.CodeRay .char .delimiter{color:#039}
.CodeRay .class{color:#458;font-weight:bold}
.CodeRay .complex{color:#a08}
.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
.CodeRay .color{color:#099}
.CodeRay .class-variable{color:#369}
.CodeRay .decorator{color:#b0b}
.CodeRay .definition{color:#099}
.CodeRay .delimiter{color:#000}
.CodeRay .doc{color:#970}
.CodeRay .doctype{color:#34b}
.CodeRay .doc-string{color:#d42}
.CodeRay .escape{color:#666}
.CodeRay .entity{color:#800}
.CodeRay .error{color:#808}
.CodeRay .exception{color:inherit}
.CodeRay .filename{color:#099}
.CodeRay .function{color:#900;font-weight:bold}
.CodeRay .global-variable{color:teal}
.CodeRay .hex{color:#058}
.CodeRay .integer,.CodeRay .float{color:#099}
.CodeRay .include{color:#555}
.CodeRay .inline{color:#000}
.CodeRay .inline .inline{background:#ccc}
.CodeRay .inline .inline .inline{background:#bbb}
.CodeRay .inline .inline-delimiter{color:#d14}
.CodeRay .inline-delimiter{color:#d14}
.CodeRay .important{color:#555;font-weight:bold}
.CodeRay .interpreted{color:#b2b}
.CodeRay .instance-variable{color:teal}
.CodeRay .label{color:#970}
.CodeRay .local-variable{color:#963}
.CodeRay .octal{color:#40e}
.CodeRay .predefined{color:#369}
.CodeRay .preprocessor{color:#579}
.CodeRay .pseudo-class{color:#555}
.CodeRay .directive{font-weight:bold}
.CodeRay .type{font-weight:bold}
.CodeRay .predefined-type{color:inherit}
.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
.CodeRay .key{color:#808}
.CodeRay .key .delimiter{color:#606}
.CodeRay .key .char{color:#80f}
.CodeRay .value{color:#088}
.CodeRay .regexp .delimiter{color:#808}
.CodeRay .regexp .content{color:#808}
.CodeRay .regexp .modifier{color:#808}
.CodeRay .regexp .char{color:#d14}
.CodeRay .regexp .function{color:#404;font-weight:bold}
.CodeRay .string{color:#d20}
.CodeRay .string .string .string{background:#ffd0d0}
.CodeRay .string .content{color:#d14}
.CodeRay .string .char{color:#d14}
.CodeRay .string .delimiter{color:#d14}
.CodeRay .shell{color:#d14}
.CodeRay .shell .delimiter{color:#d14}
.CodeRay .symbol{color:#990073}
.CodeRay .symbol .content{color:#a60}
.CodeRay .symbol .delimiter{color:#630}
.CodeRay .tag{color:teal}
.CodeRay .tag-special{color:#d70}
.CodeRay .variable{color:#036}
.CodeRay .insert{background:#afa}
.CodeRay .delete{background:#faa}
.CodeRay .change{color:#aaf;background:#007}
.CodeRay .head{color:#f8f;background:#505}
.CodeRay .insert .insert{color:#080}
.CodeRay .delete .delete{color:#800}
.CodeRay .change .change{color:#66f}
.CodeRay .head .head{color:#f4f}
</style>
</head>
<body data-spy="scroll" data-target="#toc">
<!-- Navbar -->
<nav class="navbar navbar-default navbar-static-top">
<div class="container">
<div class="navbar-header">
<!-- Three line menu button for use on mobile screens -->
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<!-- 'style' added to align image with navbar. FIX THIS -->
<a class="navbar-brand" href="https://db.apache.org/jdo/">
<img style="margin-top: -12px;" alt="Brand" width="45.5" height="45.5" src="images/JDOx150.png"/>
</a>
<!-- TODO Any way to abstract the version from Maven? -->
<a class="navbar-brand" href="index.html">Apache JDO</a>
</div>
<!-- Navbar that will collapse on mobile screens -->
<div id="navbar" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<!-- menu item General -->
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">General<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="why_jdo.html">Why JDO?</a></li>
<li><a href="getting-started.html">Getting Started</a></li>
<li><a href="specifications.html">Specifications</a></li>
<li><a href="tck.html">TCK</a></li>
<li><a href="javadoc.html">API Javadoc</a></li>
<li role="separator" class="divider"></li>
<li><a href="jdo_v_jpa.html">JDO v JPA</a></li>
<li><a href="jdo_v_jpa_api.html">JDO v JPA : API</a></li>
<li><a href="jdo_v_jpa_orm.html">JDO v JPA : ORM</a></li>
<li role="separator" class="divider"></li>
<li><a href="license.html">License</a></li>
<li><a href="impls.html">Implementations</a></li>
<li><a href="jdo_3_0_overview.html">JDO 3.0 Overview</a></li>
<li><a href="references.html">References</a></li>
<li><a href="glossary.html">Glossary</a></li>
</ul>
</li>
<!-- menu item API Usage -->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false" style="background-color:#2385c6">API Usage<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="pmf.html">PersistenceManagerFactory</a></li>
<li><a href="pm.html">PersistenceManager</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="attach_detach.html">Attach-Detach</a></li>
<li><a href="fetchgroups.html">Fetch Plan/Groups</a></li>
<li><a href="state_transition.html">Object States</a></li>
<li><a href="object_retrieval.html">Object Retrieval</a></li>
<li><a href="exceptions.html">Exceptions</a></li>
<li><a href="jdohelper.html">JDO Helper</a></li>
<li role="separator" class="divider"></li>
<li><a href="guides-replication.html">Data Replication</a></li>
</ul>
</li>
<!-- menu item Types & Metadata -->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Types &amp; Metadata<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="class_types.html">Types of Classes</a></li>
<li><a href="field_types.html">Types of Fields</a></li>
<li role="separator" class="divider"></li>
<!-- <li class="dropdown-header">Metadata</li> -->
<li><a href="metadata.html">MetaData</a></li>
<li><a href="annotations.html">Annotations</a></li>
<li><a href="jdo_dtd.html">jdo DTD/XSD</a></li>
<li><a href="orm_dtd.html">orm DTD/XSD</a></li>
<li><a href="jdoquery_dtd.html">jdoquery DTD/XSD</a></li>
<li><a href="jdoconfig_dtd.html">jdoconfig DTD/XSD</a></li>
<li role="separator" class="divider"></li>
<li><a href="enhancement.html">Bytecode Enhancement</a></li>
</ul>
</li>
<!-- menu item Query -->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Query<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="query_api.html">Query API</a></li>
<li role="separator" class="divider"></li>
<li><a href="jdoql.html">JDOQL</a></li>
<li><a href="jdoql_methods.html">Methods</a></li>
<li><a href="jdoql_result.html">Result</a></li>
<li><a href="jdoql_quickref.pdf">Quick Ref PDF</a></li>
<li><a href="jdoql_typed.html">JDOQL Typed API</a></li>
<li role="separator" class="divider"></li>
<li><a href="query_sql.html">SQL</a></li>
</ul>
</li>
<!-- menu item Community -->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Community<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="get-involved.html">Get Involved</a></li>
<li><a href="team-list.html">Project Team</a></li>
<li><a href="mail-lists.html">Mailing Lists</a></li>
<li><a href="faq.html">FAQ</a></li>
</ul>
</li>
<!-- menu item Development -->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Development<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="roadmap.html">RoadMap / TODO</a></li>
<li><a href="downloads.html">Downloads</a></li>
<li><a href="source-code.html">Source Code</a></li>
<li><a href="coding-standards.html">Coding Standards</a></li>
<li><a href="issuetracking.html">Issue Tracking</a></li>
</ul>
</li>
</ul>
<!-- 'style' added to fix height of input box. FIX THIS -->
<form class="navbar-form navbar-left" role="search" id="search-form" action="https://www.google.com/search" method="get" style="padding: 1px 15px;">
<div class="form-group">
<input name="sitesearch" value="db.apache.org/jdo" type="hidden">
<input name="q" type="text" class="form-control" placeholder="Search" style="margin-top: 7px; padding: 1px; border-radius: 5px; height: 30px; vertical-align: middle;">
</div>
</form>
</div>
</div>
</nav>
<div class="container">
<div class="row-fluid">
<div class="col-sm-9">
<!-- <div class="page-title">
<h3>JDO State Transition<a id="JDO_State_Transition"></a></h3>
</div>
-->
<div id="doc-content">
<div class="sect1">
<h2 id="index">JDO State Transition<a id="JDO_State_Transition"></a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>JDO manages the lifecycle of an object, from creation (<strong>Transient</strong>)
through to persistence in the datastore (<strong>Hollow</strong>, <strong>Persistent Clean</strong>)
and all of the various states between these. The transition between
these states are achieved by using methods on the Persistence Manager
such as <em>makePersistent()</em>, <em>makeTransient()</em>, <em>deletePersistent()</em>, and
by commiting the changes made by these operations, or by rolling them
back.</p>
</div>
<div class="paragraph">
<p>The various lifecycle states supported by JDO are shown below.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Name</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transient</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any object created by the developer that do are not
persisted. These don&#8217;t have a JDO identity.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent New</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any object that is newly persisted in the current
transaction. A JDO identity has been assigned to these objects.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent Dirty</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that has been changed in the
current transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Hollow</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that represents data in the datastore,
but whose values are not in the instance.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent Clean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that represents data in the
datastore, and whose values have not been changed in the current
transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent Deleted</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that represents data in the
datastore, and that has been deleted in the current transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent New Deleted</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any object that have been newly made persistent
and then deleted in the same current transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent Non transactional</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that represents
data in the datastore, whose values are loaded but not transactionally
consistent.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Persistent Non transactional Dirty</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any persistent object that
represents data in the datastore, whose values are loaded but not
transactionally consistent, and that has been modified.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transient Clean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any transient object that represents a transactional
instance whose values have not been changed in the current transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Transient Dirty</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any transient object that represents a transactional
instance whose values have been changed in the current transaction.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detached Clean</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any detached object that represents a persistent
instance whose values have not been changed since detaching.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">Detached Dirty</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Any detached object that represents a persistent
instance whose values have been changed since detaching.</p></td>
</tr>
</tbody>
</table>
<div class="sect2">
<h3 id="_detecting_object_state">Detecting Object State<a id="Detecting_Object_State"></a></h3>
<div class="paragraph">
<p>JDO provides a class <a href="jdohelper.html">JDOHelper</a> that allows you to
interrogate the object state via its attributes (isPersistent(),
isDeleted(), etc). In JDO 2.1 for JDKs 1.5+ <em>JDOHelper</em> is extended to
also provide a method that gives the full object state.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ObjectState state = JDOHelper.getObjectState(obj);</pre>
</div>
</div>
<div class="paragraph">
<p><br></p>
</div>
</div>
<div class="sect2">
<h3 id="_persisting_an_object">Persisting an object<a id="Persisting_an_object"></a></h3>
<div class="paragraph">
<p>The most basic thing you can do with JDO is persist an object. The
following code is an example of how you can do this</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Transaction tx=pm.currentTransaction();
try
{
tx.begin();
Product product = new Product("Plate", 9.99);
pm.makePersistent(product);
tx.commit();
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>The <em>Product</em> object progresses from <strong>Transient</strong> (initial, unpersisted
state), through to <strong>Persistent New</strong>, and then finally to <strong>Hollow</strong> when
it reaches the data store (after the "commit"). If the persist failed,
it would "rollback" and hence end up in the same state as when it
started. The following diagram shows this graphically</p>
</div>
<div class="paragraph">
<p><br></p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/state_transition_persist.png" alt="image"></span><br></p>
</div>
</div>
<div class="sect2">
<h3 id="_updating_an_object">Updating an object<a id="Updating_an_object"></a></h3>
<div class="paragraph">
<p>When you have persisted objects you need to update them. The following
code is an example of how you can do this</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Transaction tx=pm.currentTransaction();
try
{
tx.begin();
String product_name = product.getName();
...
product.setPrice(7.50);
tx.commit();
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>The <em>Product</em> object starts off in <strong>Hollow</strong> state and progresses to
<strong>Persistent Clean</strong> when the user requires to read from it. It then
migrates to <strong>Persistent Dirty</strong> when the price is updated. Finally it
returns to <strong>Hollow</strong> when the user commits/rolls back the transaction.
The following diagram shows this graphically</p>
</div>
<div class="paragraph">
<p><br></p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/state_transition_update.png" alt="image"></span><br></p>
</div>
</div>
<div class="sect2">
<h3 id="_deleting_an_object">Deleting an object<a id="Deleting_an_object"></a></h3>
<div class="paragraph">
<p>When you no longer need an object persisted, you can delete it. The
following code is an example of how you can do this</p>
</div>
<div class="literalblock">
<div class="content">
<pre>Transaction tx=pm.currentTransaction();
try
{
tx.begin();
String product_name = product.getName();
...
pm.deletePersistent(product);
tx.commit();
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>The <em>Product</em> object starts off in <strong>Hollow</strong> state and progresses to
<strong>Persistent Clean</strong> when the user requires to read from it. It then
migrates to <strong>Persistent Deleted</strong> when the deletePersistent() called.
Finally it either progresses to <strong>Transient</strong> when commit is called, or
returns to <strong>Hollow</strong> if it is rolled back. The following diagram shows
this graphically</p>
</div>
<div class="paragraph">
<p><br></p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/state_transition_delete.png" alt="image"></span><br></p>
</div>
</div>
<div class="sect2">
<h3 id="_possible_state_transitions">Possible state transitions<a id="Possible_state_transitions"></a></h3>
<div class="paragraph">
<p>The following diagram shows the state transitions possible with JDO.</p>
</div>
<div class="paragraph">
<p><br></p>
</div>
<div class="paragraph">
<p><span class="image"><img src="images/state_transition.png" alt="JDO State Transition"></span><br></p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="col-sm-3">
<nav id="toc" data-spy="affix" data-toggle="toc"></nav>
</div>
</div>
</div>
<footer style="color:#fff; background-color:#222222; padding: 5px;">
<div class="container">
<div class="row" style="margin-top:25px">
<div class="col-sm" align="center">
<a href="https://www.facebook.com/JavaDataObjects" class="externalLink" title="Facebook">Facebook</a>
|
<a href="https://twitter.com/JavaDataObjects" class="externalLink" title="Twitter">Twitter</a>
|
<a href="http://wiki.apache.org/jdo" class="externalLink" title="Wiki">Wiki</a>
|
<a href="http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10630" class="externalLink" title="Issue Tracker">Issue Tracker</a>
|
<a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a>
|
<a href="api31/apidocs/index.html" title="Latest Javadocs">Latest Javadocs</a>
|
<a href="https://privacy.apache.org/policies/privacy-policy-public.html" title="Privacy Policy">Privacy Policy</a>
</div>
</div>
<p class="text-center" style="margin-top:16px">&copy; 2005-2025 Apache Software Foundation. All Rights Reserved.</p>
</div>
</footer>
</body>
</html>