Author: andyj Date: Sat Apr 9 10:16:58 2011 New Revision: 1090559 URL: http://svn.apache.org/viewvc?rev=1090559&view=rev Log: [JDO-680] Docs for attach/detach and fetch groups, based on DN docs Added: db/jdo/site/docs/attach_detach.html db/jdo/site/docs/fetchgroups.html db/jdo/site/xdocs/attach_detach.xml db/jdo/site/xdocs/fetchgroups.xml Modified: db/jdo/site/docs/class_types.html db/jdo/site/docs/dependencies.html db/jdo/site/docs/downloads.html db/jdo/site/docs/enhancement.html db/jdo/site/docs/exceptions.html db/jdo/site/docs/extents.html db/jdo/site/docs/faq.html db/jdo/site/docs/field_types.html db/jdo/site/docs/get-involved.html db/jdo/site/docs/glossary.html db/jdo/site/docs/guides.html db/jdo/site/docs/guides/maven-jdo.html db/jdo/site/docs/guides/replication.html db/jdo/site/docs/impls.html db/jdo/site/docs/index.html db/jdo/site/docs/issue-tracking.html db/jdo/site/docs/issuetracking.html db/jdo/site/docs/javadoc.html db/jdo/site/docs/jdo_dtd.html db/jdo/site/docs/jdo_v_jpa.html db/jdo/site/docs/jdo_v_jpa_api.html db/jdo/site/docs/jdo_v_jpa_orm.html db/jdo/site/docs/jdocentral.html db/jdo/site/docs/jdohelper.html db/jdo/site/docs/jdoql.html db/jdo/site/docs/jdoql_methods.html db/jdo/site/docs/jdoql_result.html db/jdo/site/docs/jdoquery_dtd.html db/jdo/site/docs/mail-lists.html db/jdo/site/docs/maven-reports.html db/jdo/site/docs/metadata.html db/jdo/site/docs/newshistory.html db/jdo/site/docs/object_retrieval.html db/jdo/site/docs/orm_dtd.html db/jdo/site/docs/pm.html db/jdo/site/docs/pmf.html db/jdo/site/docs/project-info.html db/jdo/site/docs/references.html db/jdo/site/docs/releases/release-2.0-beta.html db/jdo/site/docs/releases/release-2.0-rc1.html db/jdo/site/docs/releases/release-2.0.html db/jdo/site/docs/releases/release-2.1.1.html db/jdo/site/docs/releases/release-2.1.html db/jdo/site/docs/releases/release-2.2.html db/jdo/site/docs/releases/release-2.3-ea.html db/jdo/site/docs/releases/release-3.0.html db/jdo/site/docs/roadmap.html db/jdo/site/docs/specifications.html db/jdo/site/docs/state_transition.html db/jdo/site/docs/svn.html db/jdo/site/docs/tck.html db/jdo/site/docs/team-list.html db/jdo/site/docs/transactions.html db/jdo/site/docs/why_jdo.html db/jdo/site/xdocs/navigation.xml Added: db/jdo/site/docs/attach_detach.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/attach_detach.html?rev=1090559&view=auto ============================================================================== --- db/jdo/site/docs/attach_detach.html (added) +++ db/jdo/site/docs/attach_detach.html Sat Apr 9 10:16:58 2011 @@ -0,0 +1,207 @@ +Java Data Objects (JDO) - Attach/Detach

JDO Attach/Detach

+ JDO provides an interface to the persistence of objects. JDO 1.0 doesn't provide a way of taking + an object that was just persisted and just work on it and update the persisted object later. + The user has to copy the fields manually and copy them back to the persisted object later. + JDO 2.0 introduces a new way of handling this situation, by detaching an object from the + persistence graph, allowing it to be worked on in the users application. It can then be + attached to the persistence graph later. + Please refer to Object Lifecycle for where this fits in. + The first thing to do to use a class with this facility is to tag it as "detachable". + This is done by adding the attribute +

+
<class name="MyClass" detachable="true">
+

+ This acts as an instruction to the enhancement process to add + methods necessary to utilise the attach/detach process. +

+ The following code fragment highlights how to use the attach/detach mechanism +

+
+Product working_product=null;
+Transaction tx=pm.currentTransaction();
+try
+{
+    tx.begin();
+
+    Product prod=new Product(name,description,price);
+    pm.makePersistent(prod);
+
+    // Detach the product for use
+    working_product = (Product)pm.detachCopy(prod);
+
+    tx.commit();
+}
+catch (Exception e)
+{
+    // Handle the exception
+}
+finally
+{
+    if (tx.isActive())
+    {
+        tx.rollback();
+    }
+}
+
+// Work on the detached object in our application
+working_product.setPrice(new_price);
+
+...
+
+// Reattach the updated object
+tx = pm.currentTransaction();
+try
+{
+    tx.begin();
+
+    Product attached_product = pm.makePersistent(working_product);
+
+    tx.commit();
+}
+catch (Exception e)
+{
+    // Handle the exception
+}
+finally
+{
+    if (tx.isActive())
+    {
+        tx.rollback();
+    }
+}
+

+ So we now don't need to do any manual copying of object fields just using a simple call to + detach the object, and then attach it again later. Here are a few things to note with + attach/detach :- +

    +
  • Calling detachCopy on an object that is not detachable will return a transient + instance that is a COPY of the original, so use the COPY thereafter.
  • +
  • Calling detachCopy on an object that is detachable will return a detached + instance that is a COPY of the original, so use this COPY thereafter
  • +
  • A detached object retain the id of its datastore entity. Detached objects should be used + where you want to update the objects and attach them later (updating the associated object in the + datastore. If you want to create copies of the objects in the datastore with their own identities + you should use makeTransient instead of detachCopy.
  • +
  • Calling detachCopy will detach all fields of that object that are in the current + Fetch Group for that class for that PersistenceManager.
  • +
  • By default the fields of the object that will be detached are those in the Default Fetch Group.
  • +
  • You should choose your Fetch Group carefully, bearing in mind which + object(s) you want to access whilst detached. Detaching a relation field will detach the related object + as well.
  • +
  • If you don't detach a field of an object, you cannot access the value for that field while + the object is detached.
  • +
  • If you don't detach a field of an object, you can update the value for that field while detached, + and thereafter you can access the value for that field.
  • +
  • Calling makePersistent will return an (attached) copy of the detached object. It will attach all fields that + were originally detached, and will also attach any other fields that were modified whilst detached.
  • +

Detach All On Commit

+ JDO2 also provides a mechanism whereby all objects that were enlisted in a transaction are + automatically detached when the transaction is committed. You can enable this in one of 3 ways. + If you want to use this mode globally for all PersistenceManagers (PMs) from a + PersistenceManagerFactory (PMF) you could either set the PMF property + "datanucleus.DetachAllOnCommit", or you could create your PMF and call the PMF method + setDetachAllOnCommit(true). If instead you wanted to use this mode only for a particular + PM, or only for a particular transaction for a particular PM, then you can call the PM method + setDetachAllOnCommit(true) before the commit of the transaction, and it will apply for all + transaction commits thereafter, until turned off (setDetachAllOnCommit(false). + Here's an example +

+
+// Create a PMF
+...
+
+// Create an object
+MyObject my = new MyObject();
+
+PersistenceManager pm = pmf.getPersistenceManager();
+Transaction tx = pm.currentTransaction();
+try
+{
+    tx.begin();
+
+    // We want our object to be detached when it's been persisted
+    pm.setDetachAllOnCommit(true);
+
+    // Persist the object that we created earlier
+    pm.makePersistent(my);
+
+    tx.commit();
+    // The object "my" is now in detached state and can be used further
+}
+finally
+{
+    if (tx.isActive)
+    {
+        tx.rollback();
+    }
+}
+

Copy On Attach

+ By default when you are attaching a detached object it will return an attached copy + of the detached object. JDO2.1 provides a new feature that allows this attachment to + just migrate the existing detached object into attached state. +

+ You enable this by setting the PersistenceManagerFactory (PMF) property + datanucleus.CopyOnAttach to false. Alternatively you can use the methods + PersistenceManagerFactory.setCopyOnAttach(boolean flag) or + PersistenceManager.setCopyOnAttach(boolean flag). + If we return to the example at the start of this page, this now becomes +

+
+// Reattach the updated object
+pm.setCopyOnAttach(false);
+tx = pm.currentTransaction();
+try
+{
+    tx.begin();
+
+    // working product is currently in detached state
+
+    pm.makePersistent(working_product);
+    // working_product is now in persistent (attached) state
+
+    tx.commit();
+}
+catch (Exception e)
+{
+    // Handle the exception
+}
+finally
+{
+    if (tx.isActive())
+    {
+        tx.rollback();
+    }
+}
+

+ Please note that if you try to attach two detached objects representing the same underlying + persistent object within the same transaction (i.e a persistent object with the same identity + already exists in the level 1 cache), then a JDOUserException will be thrown. +



Serialization of Detachable classes

+ During enhancement of Detachable classes, a field called jdoDetachedState is added to + the class definition. This field allows reading and changing tracking of detached objects + while they are not managed by a PersistenceManager. +

+ When serialization occurs on a Detachable object, the jdoDetachedState field is written + to the serialized object stream. On deserialize, this field is written back to the new + deserialized instance. This process occurs transparently to the application. However, if + deserialization occurs with an un-enhanced version of the class, the detached state is lost. +

+ Serialization and deserialization of Detachable classes and un-enhanced versions of the same + class is only possible if the field serialVersionUID is added. It's recommended during + development of the class, to define the serialVersionUID and make the class to implement + the java.io.Serializable interface, as the following example: +

+
+class MyClass implements java.io.Serializable
+{
+    private static final long serialVersionUID = 2765740961462495537L; // any random value here
+    
+    //.... other fields
+}
+
+


\ No newline at end of file Modified: db/jdo/site/docs/class_types.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/class_types.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/class_types.html (original) +++ db/jdo/site/docs/class_types.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - JDO Class Types
\ No newline at end of file Modified: db/jdo/site/docs/dependencies.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/dependencies.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/dependencies.html (original) +++ db/jdo/site/docs/dependencies.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Project Dependencies
\ No newline at end of file Modified: db/jdo/site/docs/downloads.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/downloads.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/downloads.html (original) +++ db/jdo/site/docs/downloads.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - Downloads
\ No newline at end of file Modified: db/jdo/site/docs/enhancement.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/enhancement.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/enhancement.html (original) +++ db/jdo/site/docs/enhancement.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - JDO Enhancement

JDO Enhancement

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

JDO Enhancement

JDO defines a byte-code enhancement process that provides for dirty detection of fields. Before a class is used at runtime it is compiled and then "enhanced" to implement the interface PersistenceCapable, and optionally also Detachable. @@ -548,4 +548,4 @@ public class A implements PersistenceCap }


\ No newline at end of file + © 2005-2011 Apache Software Foundation
\ No newline at end of file Modified: db/jdo/site/docs/exceptions.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/exceptions.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/exceptions.html (original) +++ db/jdo/site/docs/exceptions.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - JDO Exceptions

JDO Exceptions

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

JDO Exceptions

All exceptions raised by a JDO implementation are runtime exceptions which means that you can choose to catch the exceptions or not. The reason for JDO using unchecked exceptions is that JDO tries to provide transparent persistence, and so needs to present the same interface and exceptions whatever the state an object has. @@ -25,4 +25,4 @@ The user will never see this exception except as a result of commit.JDODetachedFieldAccessExceptionThis exception is the result of a user accessing a field of a detached instance, where the field was not copied to the detached instance.


\ No newline at end of file + © 2005-2011 Apache Software Foundation
\ No newline at end of file Modified: db/jdo/site/docs/extents.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/extents.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/extents.html (original) +++ db/jdo/site/docs/extents.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - JDO Extents

JDO Extents

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

JDO Extents

JDO implementations manage the persistence of objects into the datastore. An Extent is a collection of objects of a particular type of object that have been persisted. When you define the MetaData for a class you can define if the class requires an Extent. The default is true. @@ -17,4 +17,4 @@ Extent e = pm.getExtent(MyClass.class, t all persisted objects of a type (as an alternative to using a Query).


\ No newline at end of file + © 2005-2011 Apache Software Foundation
\ No newline at end of file Modified: db/jdo/site/docs/faq.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/faq.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/faq.html (original) +++ db/jdo/site/docs/faq.html Sat Apr 9 10:16:58 2011 @@ -1,7 +1,7 @@ Java Data Objects (JDO) - FAQ