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
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
Dynamic Fetch Groups : Programmatic definition of fetch groups at
runtime via an API
in use for a class is controled via the
interface. To get a handle on the current
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
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
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)
<field name="fieldX" default-fetch-group="true"/>
or using annotations
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
As mentioned above, JDO2 allows specification of users own fetch groups. These are specified in the
MetaData of the class. For example, if we have the following class
and we want to have the
field loaded whenever we load objects of this class, we define
our MetaData as
<column length="100" jdbc-type="VARCHAR"/>
<field name="coll" persistence-modifier="persistent">
<field name="other" persistence-modifier="persistent"/>
or using annotations
public class MyClass
So we have defined a fetch group called "otherfield" that just includes the field with name
. We can then use this at runtime in our persistence code.
PersistenceManager pm = pmf.getPersistenceManager();
... (load MyClass object)
By default the
will include the default fetch group. We have changed this above by
the fetch group "otherfield", so when we retrieve an object using this
we will be retrieving the fields
are both in the current
. 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
operation to control what is fetched during that operation.
The user has full flexibility to add many groups to the current
This gives much power and control over what will be loaded and when. A big improvement over JDO 1.0
applies not just to calls to
, but also
and much more besides.
To read more about
and how to use it with
you can look at our
Tutorial on DAO Layer design.
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
(was previously a DataNucleus extension). It operates as follows
// Create a FetchGroup on the PMF called "TestGroup" for MyClass
FetchGroup grp = myPMF.getFetchGroup("TestGroup", MyClass.class);
// Add this group to the fetch plan (using its name)
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
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. JDO2 provides two ways of controlling this.
The first is to set the
. 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
public class MyClass2
public class MyClass3
and we want to detach
of instances of
, down 2 levels - so detaching
the initial "field1"
object, and its "field2"
instance. So we
define our fetch-groups like this
and we then define the
as 2, like this
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
<field name="children" recursion-depth="2"/>
So when we fetch a Directory, it will fetch 2 levels of the
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
The default is
which leaves it to DataNucleus to optimise the fetching
of instances. A positive value defines the number of instances to be fetched. Using
means that all instances will be fetched immediately.