Modified: db/jdo/site/docs/team-list.html URL: http://svn.apache.org/viewvc/db/jdo/site/docs/team-list.html?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/docs/team-list.html (original) +++ db/jdo/site/docs/team-list.html Sat Apr 9 10:16:58 2011 @@ -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. @@ -16,4 +16,4 @@ Get Involved.

Apache JDO Committers

NameOrganization
Matthew AdamsSpringSource
Erik BengtsonJPOX
Michael BouschenTech@Spree
Michelle CaisseSun Microsystems, Inc.
Andy JeffersonDataNucleus
Patrick LinskeyOracle
Geir Magnusson Jr.IBM
Brian McCallister
Craig RussellSun Microsystems, Inc.
Dain Sundstrom
Brian Topping
Michael WatzekTech@Spree
Martin ZaunSun Microsystems, Inc.

Apache JDO Contributors

NameOrganization
Chris BeamsSpringSource
Ilan KirschObjectDB

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

Transactions

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

Transactions

When managing the persistence of objects using a PersistenceManager it is normal to handle all datastore operations in a transaction. For this reason each PersistenceManager has its own transaction. Consequently a typical JDO persistence method @@ -41,4 +41,4 @@ finally

pm.currentTransaction().setOptimistic(true);

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

Why JDO ?

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

\ No newline at end of file Added: db/jdo/site/xdocs/attach_detach.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/attach_detach.xml?rev=1090559&view=auto ============================================================================== --- db/jdo/site/xdocs/attach_detach.xml (added) +++ db/jdo/site/xdocs/attach_detach.xml Sat Apr 9 10:16:58 2011 @@ -0,0 +1,235 @@ + + + + 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.
  • +
+ + + +

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

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

+ +

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

+
+
+ + +

+ 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 +} + +
+
+
+ + +
Added: db/jdo/site/xdocs/fetchgroups.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/fetchgroups.xml?rev=1090559&view=auto ============================================================================== --- db/jdo/site/xdocs/fetchgroups.xml (added) +++ db/jdo/site/xdocs/fetchgroups.xml Sat Apr 9 10:16:58 2011 @@ -0,0 +1,265 @@ + + + + Fetch-Groups + + + +
+

+ When an object is retrieved from the datastore by JDO typically not all fields are retrieved immediately. + This is because for efficiency purposes only particular field types are retrieved in the initial access + of the object, and then any other objects are retrieved when accessed (lazy loading). + The group of fields that are loaded is called a fetch group. + There are 3 types of "fetch groups" to consider +

+
    +
  • Default Fetch Group : defined in all JDO specs, containing the fields + of a class that will be retrieved by default (with no user specification).
  • +
  • Named Fetch Groups : defined by the JDO2 specification, and defined + in MetaData (XML/annotations) with the fields of a class that are part of that fetch group. + The definition here is static
  • +
  • Dynamic Fetch Groups : Programmatic definition of fetch groups at + runtime via an API
  • +
+

+ The fetch group in use for a class is controled via the FetchPlan + + interface. To get a handle on the current FetchPlan we do +

+ FetchPlan fp = pm.getFetchPlan(); +
+ + + +

+ JDO provides an initial fetch group, comprising the fields that will be retrieved when an object + is retrieved if the user does nothing to define the required behaviour. By default the default + fetch group comprises all fields of the following types :- +

+
    +
  • primitives : boolean, byte, char, double, float, int, long, short
  • +
  • Object wrappers of primitives : Boolean, Byte, Character, Double, Float, Integer, Long, Short
  • +
  • java.lang.String, java.lang.Number, java.lang.Enum
  • +
  • java.math.BigDecimal, java.math.BigInteger
  • +
  • java.util.Date
  • +
+

+ If you wish to change the Default Fetch Group for a class you can update the Meta-Data + for the class as follows (for XML) +

+ + ... + +]]> +

or using annotations

+ +

+ When a PersistenceManager is created it starts with a FetchPlan of the "default" fetch group. + That is, if we call +

+ Collection fetchGroups = fp.getGroups(); +

+ this will have one group, called "default". At runtime, if you have been using other + fetch groups and want to revert back to the default fetch group at any time you simply do +

+ fp.setGroup(FetchPlan.DEFAULT); +
+
+ +
+ +

+ As mentioned above, JDO allows specification of users own fetch groups. These are specified in the + MetaData of the class. For example, if we have the following class +

+ +class MyClass +{ + String name; + HashSet coll; + MyOtherClass other; +} +

+ and we want to have the other field loaded whenever we load objects of this class, we define + our MetaData as +

+ + + + + + + + + + + + + + +]]> +

or using annotations

+ +

+ So we have defined a fetch group called "otherfield" that just includes the field with name + other. We can then use this at runtime in our persistence code. +

+ +PersistenceManager pm = pmf.getPersistenceManager(); +pm.getFetchPlan().addGroup("otherfield"); + +... (load MyClass object) +

+ By default the FetchPlan will include the default fetch group. We have changed this above by + adding the fetch group "otherfield", so when we retrieve an object using this + PersistenceManager we will be retrieving the fields name AND other since they + are both in the current FetchPlan. We can take the above much further than what is shown by + defining nested fetch groups in the MetaData. In addition we can change the FetchPlan just + before any PersistenceManager operation to control what is fetched during that operation. + The user has full flexibility to add many groups to the current Fetch Plan. + This gives much power and control over what will be loaded and when. +

+

+ The FetchPlan applies not just to calls to PersistenceManager.getObjectById(), but also + to PersistenceManager.newQuery(), PersistenceManager.getExtent(), + PersistenceManager.detachCopy and much more besides. +

+

+ You can read more about named fetch-groups and how to use it with + attach/detach +

+ + + + +

+ The mechanism above provides static fetch groups defined in XML or annotations. + That is great when you know in advance what fields you want to fetch. In some situations + you may want to define your fields to fetch at run time. This became standard in JDO2.2 + It operates as follows +

+ +import org.datanucleus.FetchGroup; + +// Create a FetchGroup on the PMF called "TestGroup" for MyClass +FetchGroup grp = myPMF.getFetchGroup("TestGroup", MyClass.class); +grp.addMember("field1").addMember("field2"); + +// Add this group to the fetch plan (using its name) +fp.addGroup("TestGroup"); +

+ So we use the DataNucleus PMF as a way of creating a FetchGroup, and then register that + FetchGroup with the PMF for use by all PMs. We then enable our FetchGroup for use in the + FetchPlan by using its group name (as we do for a static group). The FetchGroup allows you + to add/remove the fields necessary so you have full API control over the fields to be + fetched. +

+
+
+ + +

+ The basic fetch group defines which fields are to be fetched. It doesn't explicitly define how far + down an object graph is to be fetched. JDO provides two ways of controlling this. +

+

+ The first is to set the maxFetchDepth for the FetchPlan. This value specifies how + far out from the root object the related objects will be fetched. A positive value means that + this number of relationships will be traversed from the root object. A value of -1 means that + no limit will be placed on the fetching traversal. The default is 1. Let's take an example +

+ +

+ and we want to detach field1 of instances of MyClass1, down 2 levels - so detaching + the initial "field1" MyClass2 object, and its "field2" MyClass3 instance. So we + define our fetch-groups like this +

+ + ... + + + + + + ... + + + +]]> +

+ and we then define the maxFetchDepth as 2, like this +

+ pm.getFetchPlan().setMaxFetchDepth(2); +

+ A further refinement to this global fetch depth setting is to control the fetching of recursive + fields. This is performed via a MetaData setting "recursion-depth". A value of 1 means that only + 1 level of objects will be fetched. A value of -1 means there is no limit on the amount of recursion. + The default is 1. Let's take an example +

+ +public class Directory +{ + Collection children; + ... +} + + + + + + + + + ... +]]> +

+ So when we fetch a Directory, it will fetch 2 levels of the children field, hence fetching + the children and the grandchildren. +

+
+ + +

+ A FetchPlan can also be used for defining the fetching policy when using queries. This can be + set using +

+ pm.getFetchPlan().setFetchSize(value); +

+ The default is FetchPlan.FETCH_SIZE_OPTIMAL which leaves it to DataNucleus to optimise the fetching + of instances. A positive value defines the number of instances to be fetched. Using + FetchPlan.FETCH_SIZE_GREEDY means that all instances will be fetched immediately. +

+
+
+ + Modified: db/jdo/site/xdocs/navigation.xml URL: http://svn.apache.org/viewvc/db/jdo/site/xdocs/navigation.xml?rev=1090559&r1=1090558&r2=1090559&view=diff ============================================================================== --- db/jdo/site/xdocs/navigation.xml (original) +++ db/jdo/site/xdocs/navigation.xml Sat Apr 9 10:16:58 2011 @@ -33,6 +33,8 @@ + +