Mailing-List: contact jdo-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: jdo-dev@db.apache.org
Received-SPF: pass (asf.osuosl.org: local policy)
Date: Thu, 26 Jan 2006 09:18:35 -0800
From: Craig L Russell <Craig.Russell@Sun.COM>
Subject: Re: [IMPORTANT] Fetch-depth
Sender: Craig.Russell@Sun.COM
To: JDO Expert Group <jdo-experts-ext@Sun.COM>,
        Apache JDO project <jdo-dev@db.apache.org>
Message-id: <72ABA1BC-D2CB-49E3-AFC6-9078CFED1D8C@Sun.COM>
MIME-version: 1.0
Content-type: multipart/signed; protocol="application/pkcs7-signature";
 boundary=Apple-Mail-68--1072557593; micalg=sha1

--Apple-Mail-68--1072557593
Content-Type: multipart/alternative;
	boundary=Apple-Mail-67--1072557992


--Apple-Mail-67--1072557992
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=WINDOWS-1252;
	delsp=yes;
	format=flowed

Javadogs,

Here's the latest work in progress. I've incorporated all the =20
feedback received from the previous discussion.

Craig

Fetch Plan
A fetch plan defines rules for instantiating the loaded state for an =20
object graph. It specifies fields to be loaded for all of the =20
instances in the graph. Using fetch plans, users can control the =20
field fetching behavior of many JDO APIs. A fetch plan can be =20
associated with a PersistenceManager and, independently, with a Query =20=

and with an Extent.
A fetch plan also defines rules for creating the detached object =20
graph for the detach APIs and for automatic detachment at commit with =20=

DetachAllOnCommit set to true.
A fetch plan consists of a number of fetch groups that are combined =20
additively for each affected class; a fetch size that governs the =20
number of instances of multi-valued fields retrieved by queries; a =20
fetch-depth per field that governs the depth of the object graph =20
fetched for that field; and flags that govern the behavior of =20
detachment.
The default fetch plan contains exactly one fetch group, "default". =20
It has a fetch size of 0, and detachment option DETACH_LOAD_FIELDS. =20
The default fetch plan is in effect when the PersistenceManager is =20
first acquired from the PersistenceManagerFactory.
With the default fetch plan in effect, the behavior of JDO 2 is very =20
similar to the behavior of JDO 1. That is, when instances are loaded =20
into memory in response to queries or navigation, fields in the =20
default fetch group are loaded, and the jdoPostLoad callback is =20
executed the first time an instance is fetched from the datastore. =20
The implementation is allowed to load additional fields, as in JDO 1. =20=

Upon detachment, fields that are have been loaded into the detached =20
instances are preserved, regardless of whether they were loaded =20
automatically by the implementation or loaded in response to =20
application access; and fields that have not been loaded are marked =20
in the detached instances as not loaded.
This behavior is sufficient for the most basic use case for =20
detachment, where the detached instances are simply =93data transfer =20
objects=94 containing primitive fields. The detached instances can be =20=

modified in place or serialized and sent to another tier to be =20
changed and sent back. Upon being received back, the instances can be =20=

attached and if there are no version conflicts, the changes can be =20
applied to the datastore.
The most common use case for fetch groups is to restrict the fields =20
loaded for an instance to the primitive values and avoid loading =20
related instances for queries. For more control over the default =20
behavior, the =93default=94 fetch group can simply be redefined for =20
specific classes. For example, a String field that contains a =20
typically large document can be defined as not part of the default =20
fetch group, and the field will be loaded only when accessed by the =20
application. Similarly, the Order field associated with OrderLine =20
might be defined as part of the default fetch group of OrderLine, and =20=

queries on OrderLine will always load the corresponding Order =20
instance as well. This can easily improve the performance of =20
applications that always need the Order whenever OrderLine instances =20
are loaded.
For explicit detachment, the parameters of the detach method are each =20=

treated as roots for the purpose of determining the detached object =20
graph. The fetch plan is applied to each of the roots as if no other =20
roots were also being detached. The roots and their corresponding =20
object graphs are combined and the resulting object graph is detached =20=

in its entirety.
Fetch Groups
Fetch groups are used to identify the list of fields and the =20
associated field recursion-depth for each class for which the fetch =20
plan is applied.
Fetch groups are identified by name and apply to one or more classes. =20=

Names have global scope so the same fetch group name can be used for =20
any number of classes. This makes it possible to specify fetch groups =20=

per PersistenceManager instead of per extent. This greatly simplifies =20=

the use of fetch groups in an application.
The default fetch group (named "default") for each class is created =20
by the JDO implementation according to the rules in the JDO 1.0.1 =20
specification. That is, it includes all fields that by default belong =20=

to the default fetch group (i.e. single-valued fields), and causes =20
the jdoPostLoad method to be called the first time fields are loaded. =20=

It may also be defined by the user in the metadata like any other =20
fetch group, in order to make use of JDO 2 features.
The implementation must also define another fetch group named "all" =20
for each class. The "all" group contains all fields in the class, but =20=

can be redefined by the user, for example to add fetch-depth to =20
certain fields, or to exclude some fields from being loaded.
If a fetch plan other than the default fetch plan is active for a =20
PersistenceManager, the behavior of several APIs changes:
For detachCopy the JDO implementation must ensure that the graph =20
specified by the active fetch groups is copied, based on the =20
DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS flags.
For refresh, after clearing fields in the instances, the JDO =20
implementation uses the fetch plan to determine which fields to load =20
from the datastore.
For retrieve with FGonly true, the implementation uses the fetch plan =20=

to determine which fields are loaded from the datastore. With FGonly =20
false, the implementation reverts to JDO 1 behavior, which loads all =20
fields from the datastore; in this case, no related instances are =20
loaded.
When executing a query the JDO implementation loads the fields as =20
specified in the fetch plan associated with the Query instance.
When the application dereferences an unloaded field, the JDO =20
implementation uses the current fetch plan and the load-fetch-group =20
of the field to create the fetch strategy for the field. The specific =20=

behavior depends on whether the unloaded field is a relation to =20
another persistence-capable class.
for non-relation fields, the current fetch plan is applied to the =20
field=92s owning instance, and the fields in the field=92s load-fetch-=20=

group, plus the field itself are added to the list of fields.
for relation fields, the fields in the owning instance are fetched as =20=

immediately above, and additionally the instances referred by the =20
field are loaded using the current fetch plan plus the field=92s load-=20=

fetch-group.
A12.7-3 [FetchPlan getFetchPlan();
This method retrieves the fetch plan associated with the =20
PersistenceManager. It always returns the identical instance for the =20
same PersistenceManager.]
MaxFetchDepth
When relationship fields are included in the active fetch plan, it =20
may be possible to retrieve the entire contents of the datastore, =20
which might not be the desired effect. To avoid this behavior, and to =20=

allow the application to control the amount of data retrieved from =20
the datastore, the MaxFetchDepth property of the fetch plan is used. =20
The MaxFetchDepth is the depth of references (fields of relationship =20
types) to instantiate, starting with the root instances.
Setting MaxFetchDepth to 1 limits the instances retrieved to the root =20=

instances and instances directly reachable from the root instances =20
through a field in the fetch plan for the root class(es). Setting =20
MaxFetchDepth to 0 has no meaning, and JDOUserException will be =20
thrown. Setting MaxFetchDepth to -1 does not limit the instances =20
retrieved via relationship fields in the fetch plan. Caution should =20
be exercised to avoid retrieving more instances than desired.
For example, assume the class Employee defines field dept of type =20
Department, and class Department defines field comp of type Company. =20
When a query for Employee is executed, with a fetch plan that =20
includes Employee.dept and Department.comp and with MaxFetchDepth set =20=

to 1, the Departments referenced by Employees returned from the query =20=

are instantiated, but the Company field is not instantiated. With the =20=

MaxFetchDepth set to 2, Departments and their corresponding Companys =20
are instantiated for the Employee instances returned by the query.
Root instances
Root instances are parameter instances for retrieve, detachCopy, and =20
refresh; result instances for queries. Root instances for =20
DetachAllOnCommit are defined explicitly by the user via the =20
FetchPlan property DetachmentRoots or DetachmentRootClasses. If not =20
set explicitly, the detachment roots consist of the union of all root =20=

instances of methods executed since the last commit or rollback. Once =20=

set explicitly, the detachment roots will not be changed until =20
commit, at which time the detachment roots will be set to the empty =20
collection.
Recursion-depth
For object models with bidirectional relationships or self-=20
referencing relationships, it is useful to limit the depth of the =20
object graph retrieved through these relationships recursively. The =20
recursion-depth attribute of the field element is used for this =20
purpose. The recursion-depth for a relationship field specifies the =20
number of times an instance of the same class, subclass, or =20
superclass can be fetched via traversing this field.
A value of -1 means that the recursion-depth is not limited by =20
traversing this field. If a field is defined in multiple fetch =20
groups, the recursion-depth is the largest of the values specified, =20
treating -1 as a very large positive number. If not specified in any =20
fetch group or in the base field definition, the default is 1.
For example, assume a class Directory with a field parent of type =20
Directory and a field children of type Set<Directory>, and assume the =20=

recursion-depth of the parent field is set to -1 and the recursion-=20
depth of the children field is set to 2. When a query for a Directory =20=

is executed, all parents of the selected Directory instances will be =20
retrieved, and all of the parents=92 parents until a parent is found =20
with a null parent. Additionally, all children of the selected =20
Directory will be retrieved and all children of the children of the =20
selected Directory.
The FetchPlan interface
Fetch groups are activated using methods on the interface FetchPlan. =20
PersistenceManager and Query have getFetchPlan() methods.  When a =20
Query is retrieved from a PersistenceManager, its FetchPlan is =20
initialized to the same settings as that of the PersistenceManager.  =20
Subsequent modifications of the Query FetchPlan are not reflected in =20
the FetchPlan of the PersistenceManager. When an Extent is created, =20
the FetchPlan of the PersistenceManager initializes the FetchPlan for =20=

the Extent.
Mutating FetchPlan methods return the FetchPlan instance to allow =20
method chaining.
package javax.jdo;
public interface FetchPlan {
String DEFAULT =3D =93default=94;
String ALL =3D =93all=94;
int FETCH_SIZE_GREEDY =3D -1;
int FETCH_SIZE_OPTIMAL =3D 0;
int DETACH_LOAD_FIELDS =3D 1;
int DETACH_UNLOAD_FIELDS =3D 2;
A12.7.1-1 [/** Add the fetchgroup to the set of active fetch groups. =20
Duplicate names will be removed.*/
FetchPlan addGroup(String fetchGroupName);
/** Remove the fetch group from the set active fetch groups. */
FetchPlan removeGroup(String fetchGroupName);
/** Remove all active groups, including the default fetch group. */
FetchPlan clearGroups();
/** Return an immutable Set of the names of all active fetch groups. */
Set getGroups();
/** Set a Collection of group names to replace the current groups. =20
Duplicate names will be removed.*/
FetchPlan setGroups(Collection fetchGroupNames);
/** Set an array of group names to replace the current groups. =20
Duplicate names will be removed.*/
FetchPlan setGroups(String[] fetchGroupNames);
/** Set a single group to replace the current groups. */
FetchPlan setGroup(String fetchGroupName);]
/** Set the roots for DetachAllOnCommit */
FetchPlan setDetachmentRoots(Collection roots);
/** Get the roots for DetachAllOnCommit */
Collection getDetachmentRoots();
/** Set the roots for DetachAllOnCommit */
FetchPlan setDetachmentRootClasses(Class[] rootClasses);
/** Get the roots for DetachAllOnCommit */
Class[] getDetachmentRootClasses();
A12.7.1-2 [/** Set the fetch size for large result set support. */
FetchPlan setFetchSize(int fetchSize);
/** Return the fetch size; 0 if not set; -1 for greedy fetching. */
int getFetchSize();]
A12.7.1-3 [/** Set detachment options */
FetchPlan setDetachmentOptions(int options);
/** Return the detachment options */
int getDetachmentOptions();]
The getGroups method returns a collection of names. After a call to =20
clearGroups() this method returns an empty Set. It is legal to remove =20=

the default fetch group explicitly via pm.getFetchPlan().removeGroup=20
("default"), or to use setGroups() with a collection that does not =20
contain "default". This makes it possible to have only a given fetch =20
group active without the default fetch group. If no fetch groups are =20
active then a Set with no elements is returned. In this case, loading =20=

an instance might not result in loading the default fetch group =20
fields and the jdoPostLoad method will only be called if there is an =20
active fetch group that declares post-load=3D=94true=94.
The fetch size allows users to explicitly control the number of =20
instances retrieved from queries. A positive value is the number of =20
result instances to be fetched. A value of FETCH_SIZE_GREEDY =20
indicates that all results should be obtained immediately. A value of =20=

FETCH_SIZE_OPTIMAL indicates that the JDO implementation should try =20
to optimize the fetching of results.
Note that the graph and fields specified by a FetchPlan is strictly =20
the union of all the active fetch groups not based on any complicated =20=

set mathematics. So, if a field f1 is in fetch groups A and B, and =20
both A and B are added to the FetchPlan,and subsequently B is removed =20=

from the active fetch groups and the instance is loaded, then the =20
field f1 will be loaded, because it is in fetch group A.

Craig Russell
Architect, Sun Java Enterprise System http://java.sun.com/products/jdo
408 276-5638 mailto:Craig.Russell@sun.com
P.S. A good JDO? O, Gasp!


--Apple-Mail-67--1072557992
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=WINDOWS-1252

<HTML><BODY style=3D"word-wrap: break-word; -khtml-nbsp-mode: space; =
-khtml-line-break: after-white-space; "><DIV>Javadogs,</DIV><DIV><BR =
class=3D"khtml-block-placeholder"></DIV><DIV>Here's the latest work in =
progress. I've incorporated all the feedback received from the previous =
discussion.</DIV><DIV><BR =
class=3D"khtml-block-placeholder"></DIV><DIV>Craig</DIV><DIV><BR =
class=3D"khtml-block-placeholder"></DIV><DIV>Fetch Plan</DIV><DIV>A =
fetch plan defines rules for instantiating the loaded state for an =
object graph. It specifies fields to be loaded for all of the instances =
in the graph. Using fetch plans, users can control the field fetching =
behavior of many JDO APIs. A fetch plan can be associated with a =
PersistenceManager and, independently, with a Query and with an =
Extent.</DIV><DIV>A fetch plan also defines rules for creating the =
detached object graph for the detach APIs and for automatic detachment =
at commit with DetachAllOnCommit set to true.</DIV><DIV>A fetch plan =
consists of a number of fetch groups that are combined additively for =
each affected class; a fetch size that governs the number of instances =
of multi-valued fields retrieved by queries; a fetch-depth per field =
that governs the depth of the object graph fetched for that field; and =
flags that govern the behavior of detachment.</DIV><DIV>The default =
fetch plan contains exactly one fetch group, "default". It has a fetch =
size of 0, and detachment option DETACH_LOAD_FIELDS. The default fetch =
plan is in effect when the PersistenceManager is first acquired from the =
PersistenceManagerFactory.</DIV><DIV>With the default fetch plan in =
effect, the behavior of JDO 2 is very similar to the behavior of JDO 1. =
That is, when instances are loaded into memory in response to queries or =
navigation, fields in the default fetch group are loaded, and the =
jdoPostLoad callback is executed the first time an instance is fetched =
from the datastore. The implementation is allowed to load additional =
fields, as in JDO 1. Upon detachment, fields that are have been loaded =
into the detached instances are preserved, regardless of whether they =
were loaded automatically by the implementation or loaded in response to =
application access; and fields that have not been loaded are marked in =
the detached instances as not loaded. </DIV><DIV>This behavior is =
sufficient for the most basic use case for detachment, where the =
detached instances are simply =93data transfer objects=94 containing =
primitive fields. The detached instances can be modified in place or =
serialized and sent to another tier to be changed and sent back. Upon =
being received back, the instances can be attached and if there are no =
version conflicts, the changes can be applied to the =
datastore.</DIV><DIV>The most common use case for fetch groups is to =
restrict the fields loaded for an instance to the primitive values and =
avoid loading related instances for queries. For more control over the =
default behavior, the =93default=94 fetch group can simply be redefined =
for specific classes. For example, a String field that contains a =
typically large document can be defined as not part of the default fetch =
group, and the field will be loaded only when accessed by the =
application. Similarly, the Order field associated with OrderLine might =
be defined as part of the default fetch group of OrderLine, and queries =
on OrderLine will always load the corresponding Order instance as well. =
This can easily improve the performance of applications that always need =
the Order whenever OrderLine instances are loaded.</DIV><DIV>For =
explicit detachment, the parameters of the detach method are each =
treated as roots for the purpose of determining the detached object =
graph. The fetch plan is applied to each of the roots as if no other =
roots were also being detached. The roots and their corresponding object =
graphs are combined and the resulting object graph is detached in its =
entirety.</DIV><DIV>Fetch Groups</DIV><DIV>Fetch groups are used to =
identify the list of fields and the associated field recursion-depth for =
each class for which the fetch plan is applied. </DIV><DIV>Fetch groups =
are identified by name and apply to one or more classes. Names have =
global scope so the same fetch group name can be used for any number of =
classes. This makes it possible to specify fetch groups per =
PersistenceManager instead of per extent. This greatly simplifies the =
use of fetch groups in an application.</DIV><DIV>The default fetch group =
(named "default") for each class is created by the JDO implementation =
according to the rules in the JDO 1.0.1 specification. That is, it =
includes all fields that by default belong to the default fetch group =
(i.e. single-valued fields), and causes the jdoPostLoad method to be =
called the first time fields are loaded. It may also be defined by the =
user in the metadata like any other fetch group, in order to make use of =
JDO 2 features.</DIV><DIV>The implementation must also define another =
fetch group named "all" for each class. The "all" group contains all =
fields in the class, but can be redefined by the user, for example to =
add fetch-depth to certain fields, or to exclude some fields from being =
loaded.</DIV><DIV>If a fetch plan other than the default fetch plan is =
active for a PersistenceManager, the behavior of several APIs =
changes:</DIV><DIV>For detachCopy the JDO implementation must ensure =
that the graph specified by the active fetch groups is copied, based on =
the DETACH_LOAD_FIELDS and DETACH_UNLOAD_FIELDS flags. </DIV><DIV>For =
refresh, after clearing fields in the instances, the JDO implementation =
uses the fetch plan to determine which fields to load from the =
datastore. </DIV><DIV>For retrieve with FGonly true, the implementation =
uses the fetch plan to determine which fields are loaded from the =
datastore. With FGonly false, the implementation reverts to JDO 1 =
behavior, which loads all fields from the datastore; in this case, no =
related instances are loaded.</DIV><DIV>When executing a query the JDO =
implementation loads the fields as specified in the fetch plan =
associated with the Query instance.</DIV><DIV>When the application =
dereferences an unloaded field, the JDO implementation uses the current =
fetch plan and the load-fetch-group of the field to create the fetch =
strategy for the field. The specific behavior depends on whether the =
unloaded field is a relation to another persistence-capable =
class.</DIV><DIV>for non-relation fields, the current fetch plan is =
applied to the field=92s owning instance, and the fields in the field=92s =
load-fetch-group, plus the field itself are added to the list of =
fields.</DIV><DIV>for relation fields, the fields in the owning instance =
are fetched as immediately above, and additionally the instances =
referred by the field are loaded using the current fetch plan plus the =
field=92s load-fetch-group.</DIV><DIV>A12.7-3 [FetchPlan =
getFetchPlan();</DIV><DIV>This method retrieves the fetch plan =
associated with the PersistenceManager. It always returns the identical =
instance for the same =
PersistenceManager.]</DIV><DIV>MaxFetchDepth</DIV><DIV>When relationship =
fields are included in the active fetch plan, it may be possible to =
retrieve the entire contents of the datastore, which might not be the =
desired effect. To avoid this behavior, and to allow the application to =
control the amount of data retrieved from the datastore, the =
MaxFetchDepth property of the fetch plan is used. The MaxFetchDepth is =
the depth of references (fields of relationship types) to instantiate, =
starting with the root instances. </DIV><DIV>Setting MaxFetchDepth to 1 =
limits the instances retrieved to the root instances and instances =
directly reachable from the root instances through a field in the fetch =
plan for the root class(es). Setting MaxFetchDepth to 0 has no meaning, =
and JDOUserException will be thrown. Setting MaxFetchDepth to -1 does =
not limit the instances retrieved via relationship fields in the fetch =
plan. Caution should be exercised to avoid retrieving more instances =
than desired.</DIV><DIV>For example, assume the class Employee defines =
field dept of type Department, and class Department defines field comp =
of type Company. When a query for Employee is executed, with a fetch =
plan that includes Employee.dept and Department.comp and with =
MaxFetchDepth set to 1, the Departments referenced by Employees returned =
from the query are instantiated, but the Company field is not =
instantiated. With the MaxFetchDepth set to 2, Departments and their =
corresponding Companys are instantiated for the Employee instances =
returned by the query.</DIV><DIV>Root instances</DIV><DIV>Root instances =
are parameter instances for retrieve, detachCopy, and refresh; result =
instances for queries. Root instances for DetachAllOnCommit are defined =
explicitly by the user via the FetchPlan property DetachmentRoots or =
DetachmentRootClasses. If not set explicitly, the detachment roots =
consist of the union of all root instances of methods executed since the =
last commit or rollback. Once set explicitly, the detachment roots will =
not be changed until commit, at which time the detachment roots will be =
set to the empty collection. </DIV><DIV>Recursion-depth</DIV><DIV>For =
object models with bidirectional relationships or self-referencing =
relationships, it is useful to limit the depth of the object graph =
retrieved through these relationships recursively. The recursion-depth =
attribute of the field element is used for this purpose. The =
recursion-depth for a relationship field specifies the number of times =
an instance of the same class, subclass, or superclass can be fetched =
via traversing this field.</DIV><DIV>A value of -1 means that the =
recursion-depth is not limited by traversing this field. If a field is =
defined in multiple fetch groups, the recursion-depth is the largest of =
the values specified, treating -1 as a very large positive number. If =
not specified in any fetch group or in the base field definition, the =
default is 1. </DIV><DIV>For example, assume a class Directory with a =
field parent of type Directory and a field children of type =
Set&lt;Directory&gt;, and assume the recursion-depth of the parent field =
is set to -1 and the recursion-depth of the children field is set to 2. =
When a query for a Directory is executed, all parents of the selected =
Directory instances will be retrieved, and all of the parents=92 parents =
until a parent is found with a null parent. Additionally, all children =
of the selected Directory will be retrieved and all children of the =
children of the selected Directory.</DIV><DIV>The FetchPlan =
interface</DIV><DIV>Fetch groups are activated using methods on the =
interface FetchPlan. PersistenceManager and Query have getFetchPlan() =
methods.=A0 When a Query is retrieved from a PersistenceManager, its =
FetchPlan is initialized to the same settings as that of the =
PersistenceManager.=A0 Subsequent modifications of the Query FetchPlan =
are not reflected in the FetchPlan of the PersistenceManager. When an =
Extent is created, the FetchPlan of the PersistenceManager initializes =
the FetchPlan for the Extent.</DIV><DIV>Mutating FetchPlan methods =
return the FetchPlan instance to allow method =
chaining.</DIV><DIV>package javax.jdo;</DIV><DIV>public interface =
FetchPlan {</DIV><DIV>String DEFAULT =3D =93default=94;</DIV><DIV>String =
ALL =3D =93all=94;</DIV><DIV>int FETCH_SIZE_GREEDY =3D -1;</DIV><DIV>int =
FETCH_SIZE_OPTIMAL =3D 0;</DIV><DIV>int DETACH_LOAD_FIELDS =3D =
1;</DIV><DIV>int DETACH_UNLOAD_FIELDS =3D 2;</DIV><DIV>A12.7.1-1 [/** =
Add the fetchgroup to the set of active fetch groups. Duplicate names =
will be removed.*/</DIV><DIV>FetchPlan addGroup(String =
fetchGroupName);</DIV><DIV>/** Remove the fetch group from the set =
active fetch groups. */</DIV><DIV>FetchPlan removeGroup(String =
fetchGroupName);</DIV><DIV>/** Remove all active groups, including the =
default fetch group. */</DIV><DIV>FetchPlan clearGroups();</DIV><DIV>/** =
Return an immutable Set of the names of all active fetch groups. =
*/</DIV><DIV>Set getGroups();</DIV><DIV>/** Set a Collection of group =
names to replace the current groups. Duplicate names will be =
removed.*/</DIV><DIV>FetchPlan setGroups(Collection =
fetchGroupNames);</DIV><DIV>/** Set an array of group names to replace =
the current groups. Duplicate names will be =
removed.*/</DIV><DIV>FetchPlan setGroups(String[] =
fetchGroupNames);</DIV><DIV>/** Set a single group to replace the =
current groups. */</DIV><DIV>FetchPlan setGroup(String fetchGroupName);] =
</DIV><DIV>/** Set the roots for DetachAllOnCommit =
*/</DIV><DIV>FetchPlan setDetachmentRoots(Collection =
roots);</DIV><DIV>/** Get the roots for DetachAllOnCommit =
*/</DIV><DIV>Collection getDetachmentRoots();</DIV><DIV>/** Set the =
roots for DetachAllOnCommit */</DIV><DIV>FetchPlan =
setDetachmentRootClasses(Class[] rootClasses);</DIV><DIV>/** Get the =
roots for DetachAllOnCommit */</DIV><DIV>Class[] =
getDetachmentRootClasses();</DIV><DIV>A12.7.1-2 [/** Set the fetch size =
for large result set support. */</DIV><DIV>FetchPlan setFetchSize(int =
fetchSize);</DIV><DIV>/** Return the fetch size; 0 if not set; -1 for =
greedy fetching. */</DIV><DIV>int getFetchSize();]</DIV><DIV>A12.7.1-3 =
[/** Set detachment options */</DIV><DIV>FetchPlan =
setDetachmentOptions(int options);</DIV><DIV>/** Return the detachment =
options */</DIV><DIV>int getDetachmentOptions();]</DIV><DIV>The =
getGroups method returns a collection of names. After a call to =
clearGroups() this method returns an empty Set. It is legal to remove =
the default fetch group explicitly via =
pm.getFetchPlan().removeGroup("default"), or to use setGroups() with a =
collection that does not contain "default". This makes it possible to =
have only a given fetch group active without the default fetch group. If =
no fetch groups are active then a Set with no elements is returned. In =
this case, loading an instance might not result in loading the default =
fetch group fields and the jdoPostLoad method will only be called if =
there is an active fetch group that declares =
post-load=3D=94true=94.</DIV><DIV>The fetch size allows users to =
explicitly control the number of instances retrieved from queries. A =
positive value is the number of result instances to be fetched. A value =
of FETCH_SIZE_GREEDY indicates that all results should be obtained =
immediately. A value of FETCH_SIZE_OPTIMAL indicates that the JDO =
implementation should try to optimize the fetching of =
results.</DIV><DIV>Note that the graph and fields specified by a =
FetchPlan is strictly the union of all the active fetch groups not based =
on any complicated set mathematics. So, if a field f1 is in fetch groups =
A and B, and both A and B are added to the FetchPlan,and subsequently B =
is removed from the active fetch groups and the instance is loaded, then =
the field f1 will be loaded, because it is in fetch group =
A.</DIV><BR><DIV> <P style=3D"margin: 0.0px 0.0px 0.0px 0.0px"><FONT =
face=3D"Helvetica" size=3D"3" style=3D"font: 12.0px Helvetica">Craig =
Russell</FONT></P> <P style=3D"margin: 0.0px 0.0px 0.0px 0.0px"><FONT =
face=3D"Helvetica" size=3D"3" style=3D"font: 12.0px =
Helvetica">Architect, Sun Java Enterprise System <A =
href=3D"http://java.sun.com/products/jdo">http://java.sun.com/products/jdo=
</A></FONT></P> <P style=3D"margin: 0.0px 0.0px 0.0px 0.0px"><FONT =
face=3D"Helvetica" size=3D"3" style=3D"font: 12.0px Helvetica">408 =
276-5638 <A =
href=3D"mailto:Craig.Russell@sun.com">mailto:Craig.Russell@sun.com</A></FO=
NT></P> <P style=3D"margin: 0.0px 0.0px 0.0px 0.0px"><FONT =
face=3D"Helvetica" size=3D"3" style=3D"font: 12.0px Helvetica">P.S. A =
good JDO? O, Gasp!</FONT></P>  </DIV><BR></BODY></HTML>=

--Apple-Mail-67--1072557992--

--Apple-Mail-68--1072557593
Content-Transfer-Encoding: base64
Content-Type: application/pkcs7-signature;
	name=smime.p7s
Content-Disposition: attachment;
	filename=smime.p7s

MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIGUDCCAwkw
ggJyoAMCAQICEB7Y7fLHmKoeHTUdbtYrvpAwDQYJKoZIhvcNAQEEBQAwYjELMAkGA1UEBhMCWkEx
JTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQ
ZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBMB4XDTA1MTIxNTIxNDc0NFoXDTA2MTIxNTIxNDc0
NFowbDEQMA4GA1UEBBMHUnVzc2VsbDEUMBIGA1UEKhMLQ3JhaWcgTGFpcmQxHDAaBgNVBAMTE0Ny
YWlnIExhaXJkIFJ1c3NlbGwxJDAiBgkqhkiG9w0BCQEWFUNyYWlnLlJ1c3NlbGxAU3VuLkNPTTCC
ASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAMXXgEAm88nu8cFbxXSWqTq+GaYpCx/0QSom
8kBbVxpJIURuO4ErLDupeXu6y9+5e7ZKLbeSQE5xbfYPcQR/IhqmYKy5YqRcuzPXREBj2zKEkZph
pNXWpHgMdx9W8dq0Cu2i9Ux/S6c2MuEHrP6gfGGll+b/mzLoO280QHTuE4pcpKntRnwZdGxQ/5l8
IL+eLP+jpJAbYW9C+KNKofZtS6V6R0uzlqTOsEdZvwxZQ4mmPgHoz1+Gjwme/PC5sKvF09MaJDiI
pj9SvZ4CTCgcDZV78J086YwlVbMC0VQotjhu1p42lr8CS33IXLz3OWNrDETCAepah/Dgw2ZZApQ9
9L0CAwEAAaMyMDAwIAYDVR0RBBkwF4EVQ3JhaWcuUnVzc2VsbEBTdW4uQ09NMAwGA1UdEwEB/wQC
MAAwDQYJKoZIhvcNAQEEBQADgYEAKdIkgAWCg2Bi7ocnstfJA4iymTRI2/L4oQx9zvllM9bNJ2cR
cecJIx3HuoHbhPvemh1GExEPgHU+dXSxDmD0BEmPnhSReKCURyslnbMphPZ5kR6USzQFrRa+v0ii
J+SBO9VQYTQWT+xEjmRLM76MfkBFw3IOC9CUkRoYZ88pOoUwggM/MIICqKADAgECAgENMA0GCSqG
SIb3DQEBBQUAMIHRMQswCQYDVQQGEwJaQTEVMBMGA1UECBMMV2VzdGVybiBDYXBlMRIwEAYDVQQH
EwlDYXBlIFRvd24xGjAYBgNVBAoTEVRoYXd0ZSBDb25zdWx0aW5nMSgwJgYDVQQLEx9DZXJ0aWZp
Y2F0aW9uIFNlcnZpY2VzIERpdmlzaW9uMSQwIgYDVQQDExtUaGF3dGUgUGVyc29uYWwgRnJlZW1h
aWwgQ0ExKzApBgkqhkiG9w0BCQEWHHBlcnNvbmFsLWZyZWVtYWlsQHRoYXd0ZS5jb20wHhcNMDMw
NzE3MDAwMDAwWhcNMTMwNzE2MjM1OTU5WjBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3Rl
IENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWls
IElzc3VpbmcgQ0EwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMSmPFVzVftOucqZWh5owHUE
cJ3f6f+jHuy9zfVb8hp2vX8MOmHyv1HOAdTlUAow1wJjWiyJFXCO3cnwK4Vaqj9xVsuvPAsH5/Ef
kTYkKhPPK9Xzgnc9A74r/rsYPge/QIACZNenprufZdHFKlSFD0gEf6e20TxhBEAeZBlyYLf7AgMB
AAGjgZQwgZEwEgYDVR0TAQH/BAgwBgEB/wIBADBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3Js
LnRoYXd0ZS5jb20vVGhhd3RlUGVyc29uYWxGcmVlbWFpbENBLmNybDALBgNVHQ8EBAMCAQYwKQYD
VR0RBCIwIKQeMBwxGjAYBgNVBAMTEVByaXZhdGVMYWJlbDItMTM4MA0GCSqGSIb3DQEBBQUAA4GB
AEiM0VCD6gsuzA2jZqxnD3+vrL7CF6FDlpSdf0whuPg2H6otnzYvwPQcUCCTcDz9reFhYsPZOhl+
hLGZGwDFGguCdJ4lUJRix9sncVcljd2pnDmOjCBPZV+V2vf3h9bGCE6u9uo05RAaWzVNd+NWIXiC
3CEZNd4ksdMdRv9dX2VPMYIDEDCCAwwCAQEwdjBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhh
d3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVt
YWlsIElzc3VpbmcgQ0ECEB7Y7fLHmKoeHTUdbtYrvpAwCQYFKw4DAhoFAKCCAW8wGAYJKoZIhvcN
AQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUxDxcNMDYwMTI2MTcxODM2WjAjBgkqhkiG9w0B
CQQxFgQUycVLm3eUByWbeO2Xqm4F0FB+UZkwgYUGCSsGAQQBgjcQBDF4MHYwYjELMAkGA1UEBhMC
WkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0
ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAhAe2O3yx5iqHh01HW7WK76QMIGHBgsqhkiG
9w0BCRACCzF4oHYwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQ
dHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAhAe
2O3yx5iqHh01HW7WK76QMA0GCSqGSIb3DQEBAQUABIIBAJo7QLyGt/jR6KP3EJV8Cu5MwVMCXkjE
yfc+L6fhiU41C0+BE0lOClOOkkj1TlNaUbIM87KbErkYBLFAqUU/aiY81VBMN1KiC9tkkteZ907t
S9oU5O80Kl9qBcONdEU9ISoM9cSXafABOZmXMlWA90dRpX+fxoIU2NhnGmU/9Oe1E7r/V8K6dG97
AoFf7d1e11+ynTmcUpIPYO/UOPP13RJHnRNVpj5pmnzC8zgjf9NUvFulC+0NDsIx837juylTIrkr
K/CekcrpdCI6m/eNh7sxZzdkPte7fu9f++XyE4eHv1ehMqk2y16IaL1F3Rt5JrhgwSwVni81AblY
F3X1M9wAAAAAAAA=

--Apple-Mail-68--1072557593--