Added: db/jdo/site/docs/state_transition.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/state_transition.html?rev=581559&view=auto ============================================================================== --- db/jdo/site/docs/state_transition.html (added) +++ db/jdo/site/docs/state_transition.html Wed Oct 3 03:29:44 2007 @@ -0,0 +1,85 @@ +Java Data Objects (JDO) - JDO State Transitions

JDO State Transition

+ JDO manages the lifecycle of an object, from creation (Transient) through to persistence in the datastore (Hollow, Persistent Clean) and all of the various states between these. The transition between these states are achieved by using methods on the Persistence Manager such as makePersistent(), makeTransient(), deletePersistent(), and by commiting the changes made by these operations, or by rolling them back. +

+ The various lifecycle states supported by JDO are shown below. +

NameDescription
TransientAny object created by the developer that do are not persisted. These don't have a JDO identity.
Persistent NewAny object that is newly persisted in the current transaction. A JDO identity has been assigned to these objects.
Persistent DirtyAny persistent object that has been changed in the current transaction.
HollowAny persistent object that represents data in the datastore, but whose values are not in the instance.
Persistent CleanAny persistent object that represents data in the datastore, and whose values have not been changed in the current transaction.
Persistent DeletedAny persistent object that represents data in the datastore, and that has been deleted in the cur rent transaction.
Persistent New DeletedAny object that have been newly made persistent and then deleted in the same current transaction.
Persistent Non transactionalAny persistent object that represents data in the datastore, whose values are loaded but not transactionally consistent.
Persistent Non transactional DirtyAny persistent object that represents data in the datastore, whose values are loaded but not transactionally consistent, and that has been modified.
Transient CleanAny transient object that represents a transactional instance whose values have not been changed in the current transaction.
Transient DirtyAny transient object that represents a transactional instance whose values have been changed in the current transaction.
Detached CleanAny detached object that represents a persistent instance whose values have not been changed since detaching.
Detached DirtyAny detached object that represents a persistent instance whose values have been changed since detaching.

Detecting Object State

+ JDO provides a class JDOHelper that allows you to interrogate the object state via its attributes (isPersistent(), isDeleted(), etc). + In JDO 2.1 for JDKs 1.5+ JDOHelper is extended to also provide a method that gives the full object state. +

+
ObjectState state = JDOHelper.getObjectState(obj);
+

Persisting an object

+ 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 +

+
+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();
+    }
+}
+                
+

+ The Product object progresses from Transient (initial, unpersisted state), through to Persistent New, and then finally to Hollow 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 +





Updating an object

+ When you have persisted objects you need to update them. The following code is an example of how you can do this +

+
+Transaction tx=pm.currentTransaction();
+try
+{
+    tx.begin();
+    String product_name = product.getName();
+    ...
+    product.setPrice(7.50);
+    tx.commit();
+}
+finally
+{
+    if (tx.isActive())
+    {
+        tx.rollback();
+    }
+}
+                
+

+ The Product object starts off in Hollow state and progresses to Persistent Clean when the user requires to read from it. It then migrates to Persistent Dirty when the price is updated. Finally it returns to Hollow when the user commits/rolls back the transaction. The following diagram shows this graphically +





Deleting an object

+ When you no longer need an object persisted, you can delete it. The following code is an example of how you can do this +

+
+Transaction tx=pm.currentTransaction();
+try
+{
+    tx.begin();
+    String product_name = product.getName();
+    ...
+    pm.deletePersistent(product);
+    tx.commit();
+}
+finally
+{
+    if (tx.isActive())
+    {
+        tx.rollback();
+    }
+}
+                
+

+ The Product object starts off in Hollow state and progresses to Persistent Clean when the user requires to read from it. It then migrates to Persistent Deleted when the deletePersistent() called. Finally it either progresses to Transient when commit is called, or returns to Hollow if it is rolled back. The following diagram shows this graphically +





Possible state transitions

+ The following diagram shows the state transitions possible with JDO and JPOX. +



JDO State Transition


\ No newline at end of file Modified: db/jdo/site/docs/svn.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/svn.html?rev=581559&r1=581558&r2=581559&view=diff ============================================================================== --- db/jdo/site/docs/svn.html (original) +++ db/jdo/site/docs/svn.html Wed Oct 3 03:29:44 2007 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Source Code

Source Code Version Control

Apache JDO uses Subversion to manage its source code. + @import url("./style/maven-theme.css");

Source Code Version Control

Apache JDO uses Subversion to manage its source code. If you're new to Subversion, you can check out the online book about Subversion. Note that we are currently using Subversion 1.1.x (there are separate Modified: db/jdo/site/docs/tck.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/tck.html?rev=581559&r1=581558&r2=581559&view=diff ============================================================================== --- db/jdo/site/docs/tck.html (original) +++ db/jdo/site/docs/tck.html Wed Oct 3 03:29:44 2007 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - TCK

About the Technology Compatibility Kit

+ @import url("./style/maven-theme.css");

About the Technology Compatibility Kit

In order to demonstrate compliance with the Java Data Objects specification, an implementation must pass all of the tests in the Technology Compatibility Kit (TCK). Modified: db/jdo/site/docs/team-list.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/team-list.html?rev=581559&r1=581558&r2=581559&view=diff ============================================================================== --- db/jdo/site/docs/team-list.html (original) +++ db/jdo/site/docs/team-list.html Wed Oct 3 03:29:44 2007 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Project Team

The Apache JDO Team

+ @import url("./style/maven-theme.css");

The Apache JDO Team

The people listed below have made significant contributions to JDO by working long and hard to make quality software for the rest of the world to use. Modified: db/jdo/site/docs/why_jdo.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/why_jdo.html?rev=581559&r1=581558&r2=581559&view=diff ============================================================================== --- db/jdo/site/docs/why_jdo.html (original) +++ db/jdo/site/docs/why_jdo.html Wed Oct 3 03:29:44 2007 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Why JDO ?

Why JDO ?

+ @import url("./style/maven-theme.css");

Why JDO ?

The majority of applications need to persist (or store) data during their lifecycle. There are many ways of doing this with an application written in Java.

Added: db/jdo/site/xdocs/images/state_transition.gif URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/images/state_transition.gif?rev=581559&view=auto ============================================================================== Binary file - no diff available. Propchange: db/jdo/site/xdocs/images/state_transition.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: db/jdo/site/xdocs/images/state_transition_delete.gif URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/images/state_transition_delete.gif?rev=581559&view=auto ============================================================================== Binary file - no diff available. Propchange: db/jdo/site/xdocs/images/state_transition_delete.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: db/jdo/site/xdocs/images/state_transition_persist.gif URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/images/state_transition_persist.gif?rev=581559&view=auto ============================================================================== Binary file - no diff available. Propchange: db/jdo/site/xdocs/images/state_transition_persist.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Added: db/jdo/site/xdocs/images/state_transition_update.gif URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/images/state_transition_update.gif?rev=581559&view=auto ============================================================================== Binary file - no diff available. Propchange: db/jdo/site/xdocs/images/state_transition_update.gif ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Modified: db/jdo/site/xdocs/navigation.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/navigation.xml?rev=581559&r1=581558&r2=581559&view=diff ============================================================================== --- db/jdo/site/xdocs/navigation.xml (original) +++ db/jdo/site/xdocs/navigation.xml Wed Oct 3 03:29:44 2007 @@ -29,6 +29,7 @@ + Added: db/jdo/site/xdocs/state_transition.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/state_transition.xml?rev=581559&view=auto ============================================================================== --- db/jdo/site/xdocs/state_transition.xml (added) +++ db/jdo/site/xdocs/state_transition.xml Wed Oct 3 03:29:44 2007 @@ -0,0 +1,183 @@ + + + + JDO State Transitions + + + +

+

+ JDO manages the lifecycle of an object, from creation (Transient) through to persistence in the datastore (Hollow, Persistent Clean) and all of the various states between these. The transition between these states are achieved by using methods on the Persistence Manager such as makePersistent(), makeTransient(), deletePersistent(), and by commiting the changes made by these operations, or by rolling them back. +

+

+ The various lifecycle states supported by JDO are shown below. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameDescription
TransientAny object created by the developer that do are not persisted. These don't have a JDO identity.
Persistent NewAny object that is newly persisted in the current transaction. A JDO identity has been assigned to these objects.
Persistent DirtyAny persistent object that has been changed in the current transaction.
HollowAny persistent object that represents data in the datastore, but whose values are not in the instance.
Persistent CleanAny persistent object that represents data in the datastore, and whose values have not been changed in the current transaction.
Persistent DeletedAny persistent object that represents data in the datastore, and that has been deleted in the current transaction.
Persistent New DeletedAny object that have been newly made persistent and then deleted in the same current transaction.
Persistent Non transactionalAny persistent object that represents data in the datastore, whose values are loaded but not transactionally consistent.
Persistent Non transactional DirtyAny persistent object that represents data in the datastore, whose values are loaded but not transactionally consistent, and that has been modified.
Transient CleanAny transient object that represents a transactional instance whose values have not been changed in the current transaction.
Transient DirtyAny transient object that represents a transactional instance whose values have been changed in the current transaction.
Detached CleanAny detached object that represents a persistent instance whose values have not been changed since detaching.
Detached DirtyAny detached object that represents a persistent instance whose values have been changed since detaching.
+ + +

+ JDO provides a class JDOHelper that allows you to interrogate the object state via its attributes (isPersistent(), isDeleted(), etc). + In JDO 2.1 for JDKs 1.5+ JDOHelper is extended to also provide a method that gives the full object state. +

+ ObjectState state = JDOHelper.getObjectState(obj); +
+
+ + +

+ 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 +

+ +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(); + } +} + +

+ The Product object progresses from Transient (initial, unpersisted state), through to Persistent New, and then finally to Hollow 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 +

+
+ +
+
+ + +

+ When you have persisted objects you need to update them. The following code is an example of how you can do this +

+ +Transaction tx=pm.currentTransaction(); +try +{ + tx.begin(); + String product_name = product.getName(); + ... + product.setPrice(7.50); + tx.commit(); +} +finally +{ + if (tx.isActive()) + { + tx.rollback(); + } +} + +

+ The Product object starts off in Hollow state and progresses to Persistent Clean when the user requires to read from it. It then migrates to Persistent Dirty when the price is updated. Finally it returns to Hollow when the user commits/rolls back the transaction. The following diagram shows this graphically +

+
+ +
+
+ + +

+ When you no longer need an object persisted, you can delete it. The following code is an example of how you can do this +

+ +Transaction tx=pm.currentTransaction(); +try +{ + tx.begin(); + String product_name = product.getName(); + ... + pm.deletePersistent(product); + tx.commit(); +} +finally +{ + if (tx.isActive()) + { + tx.rollback(); + } +} + +

+ The Product object starts off in Hollow state and progresses to Persistent Clean when the user requires to read from it. It then migrates to Persistent Deleted when the deletePersistent() called. Finally it either progresses to Transient when commit is called, or returns to Hollow if it is rolled back. The following diagram shows this graphically +

+
+ +
+
+ + +

+ The following diagram shows the state transitions possible with JDO and JPOX. +

+
+ JDO State Transition +
+
+
+ + +