Modified: websites/production/db/content/jdo/exceptions.html ============================================================================== --- websites/production/db/content/jdo/exceptions.html (original) +++ websites/production/db/content/jdo/exceptions.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,102 +209,102 @@
- - -

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

- -

JDOException

-

- This is the base class for all JDO exceptions. It is a subclass of RuntimeException, and need not be declared or caught. -

-
-
- -

Can Retry Exceptions

-
- JDO Can Retry Exceptions -
- - - - - - - - - - - - - - - - - - - - - - - - -
ExceptionDescription
JDOCanRetryExceptionThis is the base class for errors that can be retried.
JDOUserExceptionThis is the base class for user errors that can be retried.
JDODataStoreExceptionThis is the base class for datastore errors that can be retried. - Any root SQLException that caused this will typically be nested within this exception.
JDOObjectNotFoundExceptionThis exception is to notify the application that an object does not exist in the - datastore. When this exception is thrown during a transaction, there has been no change - in the status of the transaction in progress. If this exception is a nested exception - thrown during commit, then the transaction is rolled back.
JDOUnsupportedOptionExceptionThis exception is thrown by an implementation to indicate that it does not implement a - JDO optional feature.
-
-
- -

Fatal Exceptions

-
- JDO Fatal Exceptions -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExceptionDescription
JDOFatalExceptionThis is the base class for errors that cannot be retried. This exception generally - means that the transaction associated with the PersistenceManager has been rolled back, - and the transaction should be abandoned.
JDOFatalUserExceptionThis is the base class for user errors that cannot be retried.
JDOFatalInternalExceptionThis is the base class for JDO implementation failures.
JDOFatalDataStoreExceptionThis is the base class for fatal datastore errors. When this exception is thrown, the - transaction has been rolled back. Any root SQLException that caused this will typically be nested - within this exception.
JDOOptimisticVerificationExceptionThis exception is the result of a user commit operation in an optimistic transaction - where the verification of new, modified, or deleted instances fails the verification. - 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.
-
-
- + + +

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

+ +

JDOException

+

+ This is the base class for all JDO exceptions. It is a subclass of RuntimeException, and need not be declared or caught. +

+
+
+ +

Can Retry Exceptions

+
+ JDO Can Retry Exceptions +
+ + + + + + + + + + + + + + + + + + + + + + + + +
ExceptionDescription
JDOCanRetryExceptionThis is the base class for errors that can be retried.
JDOUserExceptionThis is the base class for user errors that can be retried.
JDODataStoreExceptionThis is the base class for datastore errors that can be retried. + Any root SQLException that caused this will typically be nested within this exception.
JDOObjectNotFoundExceptionThis exception is to notify the application that an object does not exist in the + datastore. When this exception is thrown during a transaction, there has been no change + in the status of the transaction in progress. If this exception is a nested exception + thrown during commit, then the transaction is rolled back.
JDOUnsupportedOptionExceptionThis exception is thrown by an implementation to indicate that it does not implement a + JDO optional feature.
+
+
+ +

Fatal Exceptions

+
+ JDO Fatal Exceptions +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExceptionDescription
JDOFatalExceptionThis is the base class for errors that cannot be retried. This exception generally + means that the transaction associated with the PersistenceManager has been rolled back, + and the transaction should be abandoned.
JDOFatalUserExceptionThis is the base class for user errors that cannot be retried.
JDOFatalInternalExceptionThis is the base class for JDO implementation failures.
JDOFatalDataStoreExceptionThis is the base class for fatal datastore errors. When this exception is thrown, the + transaction has been rolled back. Any root SQLException that caused this will typically be nested + within this exception.
JDOOptimisticVerificationExceptionThis exception is the result of a user commit operation in an optimistic transaction + where the verification of new, modified, or deleted instances fails the verification. + 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.
+
+
+
Modified: websites/production/db/content/jdo/extents.html ============================================================================== --- websites/production/db/content/jdo/extents.html (original) +++ websites/production/db/content/jdo/extents.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,27 +209,27 @@
- - -

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. - You access the Extent as follows -

-
-Extent e = pm.getExtent(MyClass.class, true);
-            
-

- This example will return an Extent that contains all persisted instances of the class MyClass - and its subclasses (the second argument in the call). An Extent is useful where you want to restrict a - Query to query over just that set of objects. It can also be used where you just want to retrieve - all persisted objects of a type (as an alternative to using a Query). -

-
- - + + +

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. + You access the Extent as follows +

+
+Extent e = pm.getExtent(MyClass.class, true);
+            
+

+ This example will return an Extent that contains all persisted instances of the class MyClass + and its subclasses (the second argument in the call). An Extent is useful where you want to restrict a + Query to query over just that set of objects. It can also be used where you just want to retrieve + all persisted objects of a type (as an alternative to using a Query). +

+
+ +
Modified: websites/production/db/content/jdo/faq.html ============================================================================== --- websites/production/db/content/jdo/faq.html (original) +++ websites/production/db/content/jdo/faq.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -12,7 +12,7 @@ - + @@ -210,69 +210,69 @@
- - - -

General

- -

- What is JDO? - - JDO is Java Data Objects, a datastore-agnostic interface - for storing Java objects in transactional datastores. - -

- -

- I'd like to find out more about the project and possibly contribute. What do I do next? - Participation on the project is via the mailing - list and the source code repository. You join by subscribing - to the mailing list and participating in discussions. You - can help by contributing your ideas, enthusiasm, code, - documentation, and tests. The fundamental tenet of the Apache - Software Foundation is that great communities build great - code. The emphasis is on community; the code comes from that. - If you want to help, just join the mailing list, see what - needs to be done, and do it. Welcome! - -

- -

- Where is the mailing list, and how can I subscribe? - - The developers mailing list is jdo-dev@db.apache.org, a - high-volume list currently receiving from 100 to 300 messages - a month. -
- The users mailing list is jdo-user@db.apache.org. -
-

- -

- Does this project use a wiki? - - It does - the - JDO wiki - complements the work taking place on the mailing list and provides - additional information on the project. - -

-
- - + + + +

General

+ +

+ What is JDO? + + JDO is Java Data Objects, a datastore-agnostic interface + for storing Java objects in transactional datastores. + +

+ +

+ I'd like to find out more about the project and possibly contribute. What do I do next? + Participation on the project is via the mailing + list and the source code repository. You join by subscribing + to the mailing list and participating in discussions. You + can help by contributing your ideas, enthusiasm, code, + documentation, and tests. The fundamental tenet of the Apache + Software Foundation is that great communities build great + code. The emphasis is on community; the code comes from that. + If you want to help, just join the mailing list, see what + needs to be done, and do it. Welcome! + +

+ +

+ Where is the mailing list, and how can I subscribe? + + The developers mailing list is jdo-dev@db.apache.org, a + high-volume list currently receiving from 100 to 300 messages + a month. +
+ The users mailing list is jdo-user@db.apache.org. +
+

+ +

+ Does this project use a wiki? + + It does - the + JDO wiki + complements the work taking place on the mailing list and provides + additional information on the project. + +

+
+ +
Modified: websites/production/db/content/jdo/fetchgroups.html ============================================================================== --- websites/production/db/content/jdo/fetchgroups.html (original) +++ websites/production/db/content/jdo/fetchgroups.html Sat Feb 23 14:12:18 2013 @@ -1,5 +1,5 @@ - + @@ -11,7 +11,7 @@ @import url("./css/site.css"); - + @@ -209,265 +209,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();
-
- - -

Default Fetch Group

-

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

-
-<class name="MyClass">
-    ...
-    <field name="fieldX" default-fetch-group="true"/>
-</class>
-

or using annotations

-
-@Persistent(defaultFetchGroup="true")
-SomeType fieldX;
-

- 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);
-
-
- - -

Named Fetch Groups

-

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

-
-<package name="mydomain">
-    <class name="MyClass">
-        <field name="name">
-            <column length="100" jdbc-type="VARCHAR"/>
-        </field>
-        <field name="coll" persistence-modifier="persistent">
-            <collection element-type="mydomain.Address"/>
-            <join/>
-        </field>
-        <field name="other" persistence-modifier="persistent"/>
-        <fetch-group name="otherfield">
-            <field name="other"/>
-        </fetch-group>
-    </class>
-</package>
-

or using annotations

-
-@PersistenceCapable
-@FetchGroup(name="otherfield", members={@Persistent(name="other")})
-public class MyClass
-{
-    ...
-}
-

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

-
- - -

Dynamic Fetch Groups

-

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

-
-
- -

Fetch Depth

-

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

-
-public class MyClass1
-{
-    MyClass2 field1;
-    ...
-}
-
-public class MyClass2
-{
-    MyClass3 field2;
-    ...
-}
-
-public class MyClass3
-{
-    MyClass4 field3;
-    ...
-}
-

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

-
-<class name="MyClass1">
-    ...
-    <fetch-group name="includingField1">
-        <field name="field1"/>
-    </fetch-group>
-</class>
-<class name="MyClass2">
-    ...
-    <fetch-group name="includingField2">
-        <field name="field2"/>
-    </fetch-group>
-</class>
-

- 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;
-    ...
-}
-
-<class name="Directory">
-    <field name="children">
-        <collection element-type="Directory"/>
-    </field>
-
-    <fetch-group name="grandchildren">
-        <field name="children" recursion-depth="2"/>
-    </fetch-group>
-    ...
-</class>
-

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

-
- -

Fetch Size

-

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

-
-
- + + +

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

Default Fetch Group

+

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

+
+<class name="MyClass">
+    ...
+    <field name="fieldX" default-fetch-group="true"/>
+</class>
+

or using annotations

+
+@Persistent(defaultFetchGroup="true")
+SomeType fieldX;
+

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

Named Fetch Groups

+

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

+
+<package name="mydomain">
+    <class name="MyClass">
+        <field name="name">
+            <column length="100" jdbc-type="VARCHAR"/>
+        </field>
+        <field name="coll" persistence-modifier="persistent">
+            <collection element-type="mydomain.Address"/>
+            <join/>
+        </field>
+        <field name="other" persistence-modifier="persistent"/>
+        <fetch-group name="otherfield">
+            <field name="other"/>
+        </fetch-group>
+    </class>
+</package>
+

or using annotations

+
+@PersistenceCapable
+@FetchGroup(name="otherfield", members={@Persistent(name="other")})
+public class MyClass
+{
+    ...
+}
+

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

+
+ + +

Dynamic Fetch Groups

+

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

+
+
+ +

Fetch Depth

+

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

+
+public class MyClass1
+{
+    MyClass2 field1;
+    ...
+}
+
+public class MyClass2
+{
+    MyClass3 field2;
+    ...
+}
+
+public class MyClass3
+{
+    MyClass4 field3;
+    ...
+}
+

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

+
+<class name="MyClass1">
+    ...
+    <fetch-group name="includingField1">
+        <field name="field1"/>
+    </fetch-group>
+</class>
+<class name="MyClass2">
+    ...
+    <fetch-group name="includingField2">
+        <field name="field2"/>
+    </fetch-group>
+</class>
+

+ 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;
+    ...
+}
+
+<class name="Directory">
+    <field name="children">
+        <collection element-type="Directory"/>
+    </field>
+
+    <fetch-group name="grandchildren">
+        <field name="children" recursion-depth="2"/>
+    </fetch-group>
+    ...
+</class>
+

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

+
+ +

Fetch Size

+

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

+
+
+