db-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mcai...@apache.org
Subject svn commit: r847423 [3/14] - in /websites/production/db/content/jdo: ./ guides/ releases/
Date Mon, 21 Jan 2013 04:23:18 GMT
Modified: websites/production/db/content/jdo/fetchgroups.html
==============================================================================
--- websites/production/db/content/jdo/fetchgroups.html (original)
+++ websites/production/db/content/jdo/fetchgroups.html Mon Jan 21 04:23:17 2013
@@ -1,9 +1,9 @@
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 16, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 20, 2013 -->
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-    <title>Maven - 
+    <title>JDO - 
         Fetch-Groups</title>
     <style type="text/css" media="all">
       @import url("./css/maven-base.css");
@@ -11,7 +11,7 @@
       @import url("./css/site.css");
     </style>
     <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
-    <meta name="Date-Revision-yyyymmdd" content="20130116" />
+    <meta name="Date-Revision-yyyymmdd" content="20130120" />
     <meta http-equiv="Content-Language" content="en" />
         
         </head>
@@ -30,7 +30,13 @@
     <div id="breadcrumbs">
             
                     
-                  <div class="xright">                    <a href="http://wiki.apache.org/jdo"
class="externalLink" title="Wiki">Wiki</a>
+                  <div class="xright">                    <a href="https://www.facebook.com/JavaDataObjects"
class="externalLink" title="Facebook">Facebook</a>
+            |
+                        <a href="https://twitter.com/JavaDataObjects" class="externalLink"
title="Twitter">Twitter</a>
+            |
+                        <a href="https://plus.google.com/106584233526334524963" class="externalLink"
title="Google+">Google+</a>
+            |
+                        <a href="http://wiki.apache.org/jdo" class="externalLink" title="Wiki">Wiki</a>
             |
                         <a href="http://issues.apache.org/jira/secure/BrowseProject.jspa?id=10630"
class="externalLink" title="Issue Tracker">Issue Tracker</a>
             |
@@ -203,265 +209,265 @@
     </div>
     <div id="bodyColumn">
       <div id="contentBox">
-        
-    
-        <div class="section"><h2>Fetch Groups<a name="Fetch_Groups"></a></h2>
-            <p>
-                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 <b>fetch group</b>.
-                There are 3 types of &quot;fetch groups&quot; to consider
-            </p>
-            <ul>
-                <li><a href="#dfg">Default Fetch Group</a> : defined in
all JDO specs, containing the fields 
-                    of a class that will be retrieved by default (with no user specification).</li>
-                <li><a href="#static">Named Fetch Groups</a> : 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 <i>static</i></li>
-                <li><a href="#dynamic">Dynamic Fetch Groups</a> : Programmatic
definition of fetch groups at 
-                    runtime via an API</li>
-            </ul>
-            <p>
-                The <b>fetch group</b> in use for a class is controled via the
<i>FetchPlan</i>
-                <a class="externalLink" href="http://db.apache.org/jdo/api20/apidocs/javax/jdo/FetchPlan.html"
target="_blank"><img src="images/javadoc.gif" alt="" /></a>
-                interface. To get a handle on the current <i>FetchPlan</i> we
do
-            </p>
-            <div class="source"><pre>FetchPlan fp = pm.getFetchPlan();</pre></div>
-            <br />
-
-            <a name="dfg"></a>
-            <div class="section"><h3>Default Fetch Group<a name="Default_Fetch_Group"></a></h3>
-                <p>
-                    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 <i>default 
-                    fetch group</i> comprises all fields of the following types :-
-                </p>
-                <ul>
-                    <li>primitives : boolean, byte, char, double, float, int, long,
short</li>
-                    <li>Object wrappers of primitives : Boolean, Byte, Character, Double,
Float, Integer, Long, Short</li>
-                    <li>java.lang.String, java.lang.Number, java.lang.Enum</li>
-                    <li>java.math.BigDecimal, java.math.BigInteger</li>
-                    <li>java.util.Date</li>
-                </ul>
-                <p>
-                    If you wish to change the <b>Default Fetch Group</b> for
a class you can update the Meta-Data 
-                    for the class as follows (for XML)
-                </p>
-                <div class="source"><pre>
-&lt;class name=&quot;MyClass&quot;&gt;
-    ...
-    &lt;field name=&quot;fieldX&quot; default-fetch-group=&quot;true&quot;/&gt;
-&lt;/class&gt;</pre></div>
-                <p>or using annotations</p>
-                <div class="source"><pre>
-@Persistent(defaultFetchGroup=&quot;true&quot;)
-SomeType fieldX;</pre></div>
-                <p>
-                    When a <i>PersistenceManager</i> is created it starts with
a FetchPlan of the &quot;default&quot; fetch group. 
-                    That is, if we call
-                </p>
-                <div class="source"><pre>Collection fetchGroups = fp.getGroups();</pre></div>
-                <p>
-                    this will have one group, called &quot;default&quot;. 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
-                </p>
-                <div class="source"><pre>fp.setGroup(FetchPlan.DEFAULT);</pre></div>
-                <br />
-            </div>
-
-            <a name="static"></a>
-            <div class="section"><h3>Named Fetch Groups<a name="Named_Fetch_Groups"></a></h3>
-                <p>
-                    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
-                </p>
-                <div class="source"><pre>
-class MyClass
-{
-    String name;
-    HashSet coll;
-    MyOtherClass other;
-}</pre></div>
-                <p>
-                    and we want to have the <u>other</u> field loaded whenever
we load objects of this class, we define 
-                    our MetaData as
-                </p>
-                <div class="source"><pre>
-&lt;package name=&quot;mydomain&quot;&gt;
-    &lt;class name=&quot;MyClass&quot;&gt;
-        &lt;field name=&quot;name&quot;&gt;
-            &lt;column length=&quot;100&quot; jdbc-type=&quot;VARCHAR&quot;/&gt;
-        &lt;/field&gt;
-        &lt;field name=&quot;coll&quot; persistence-modifier=&quot;persistent&quot;&gt;
-            &lt;collection element-type=&quot;mydomain.Address&quot;/&gt;
-            &lt;join/&gt;
-        &lt;/field&gt;
-        &lt;field name=&quot;other&quot; persistence-modifier=&quot;persistent&quot;/&gt;
-        &lt;fetch-group name=&quot;otherfield&quot;&gt;
-            &lt;field name=&quot;other&quot;/&gt;
-        &lt;/fetch-group&gt;
-    &lt;/class&gt;
-&lt;/package&gt;</pre></div>
-                <p>or using annotations</p>
-                <div class="source"><pre>
-@PersistenceCapable
-@FetchGroup(name=&quot;otherfield&quot;, members={@Persistent(name=&quot;other&quot;)})
-public class MyClass
-{
-    ...
-}</pre></div>
-                <p>
-                    So we have defined a fetch group called &quot;otherfield&quot;
that just includes the field with name 
-                    <i>other</i>. We can then use this at runtime in our persistence
code.
-                </p>
-                <div class="source"><pre>
-PersistenceManager pm = pmf.getPersistenceManager();
-pm.getFetchPlan().addGroup(&quot;otherfield&quot;);
-
-... (load MyClass object)</pre></div>
-                <p>
-                    By default the <i>FetchPlan</i> will include the default
fetch group. We have changed this above by
-                    <u>adding</u> the fetch group &quot;otherfield&quot;,
so when we retrieve an object using this 
-                    <i>PersistenceManager</i> we will be retrieving the fields
<i>name</i> AND <i>other</i> since they
-                    are both in the current <i>FetchPlan</i>. 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 <i>FetchPlan</i> just
-                    before any <i>PersistenceManager</i> operation to control
what is fetched during that operation.
-                    The user has full flexibility to add many groups to the current <b>Fetch
Plan</b>.
-                    This gives much power and control over what will be loaded and when.
-                </p>
-                <p>
-                    The <i>FetchPlan</i> applies not just to calls to <i>PersistenceManager.getObjectById()</i>,
but also
-                    to <i>PersistenceManager.newQuery()</i>, <i>PersistenceManager.getExtent()</i>,

-                    <i>PersistenceManager.detachCopy</i> and much more besides.
-                </p>
-                <p>
-                    You can read more about <b>named fetch-groups</b> and how
to use it with 
-                    <a href="attach_detach.html"><b>attach/detach</b></a>
-                </p>
-            </div>
-
-            <a name="dynamic"></a>
-            <div class="section"><h3>Dynamic Fetch Groups<a name="Dynamic_Fetch_Groups"></a></h3>
-                <p>
-                    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
-                </p>
-                <div class="source"><pre>
-import org.datanucleus.FetchGroup;
-
-// Create a FetchGroup on the PMF called &quot;TestGroup&quot; for MyClass
-FetchGroup grp = myPMF.getFetchGroup(&quot;TestGroup&quot;, MyClass.class);
-grp.addMember(&quot;field1&quot;).addMember(&quot;field2&quot;);
-
-// Add this group to the fetch plan (using its name)
-fp.addGroup(&quot;TestGroup&quot;);</pre></div>
-                <p>
-                    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.
-                </p>
-                <br />
-            </div>
-
-            <div class="section"><h3>Fetch Depth<a name="Fetch_Depth"></a></h3>
-                <p>
-                    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.
-                </p>
-                <p>
-                    The first is to set the <b>maxFetchDepth</b> for the <i>FetchPlan</i>.
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
-                </p>
-                <div class="source"><pre>
-public class MyClass1
-{
-    MyClass2 field1;
-    ...
-}
-
-public class MyClass2
-{
-    MyClass3 field2;
-    ...
-}
-
-public class MyClass3
-{
-    MyClass4 field3;
-    ...
-}</pre></div>
-                <p>
-                    and we want to detach <i>field1</i> of instances of <i>MyClass1</i>,
down 2 levels - so detaching 
-                    the initial &quot;field1&quot; <i>MyClass2</i> object,
and its &quot;field2&quot; <i>MyClass3</i> instance. So we 
-                    define our fetch-groups like this
-                </p>
-                <div class="source"><pre>
-&lt;class name=&quot;MyClass1&quot;&gt;
-    ...
-    &lt;fetch-group name=&quot;includingField1&quot;&gt;
-        &lt;field name=&quot;field1&quot;/&gt;
-    &lt;/fetch-group&gt;
-&lt;/class&gt;
-&lt;class name=&quot;MyClass2&quot;&gt;
-    ...
-    &lt;fetch-group name=&quot;includingField2&quot;&gt;
-        &lt;field name=&quot;field2&quot;/&gt;
-    &lt;/fetch-group&gt;
-&lt;/class&gt;</pre></div>
-                <p>
-                    and we then define the <b>maxFetchDepth</b> as 2, like this
-                </p>
-                <div class="source"><pre>pm.getFetchPlan().setMaxFetchDepth(2);</pre></div>
-                <p>
-                    A further refinement to this global fetch depth setting is to control
the fetching of recursive 
-                    fields. This is performed via a MetaData setting &quot;recursion-depth&quot;.
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
-                </p>
-                <div class="source"><pre>
-public class Directory
-{
-    Collection children;
-    ...
-}</pre></div>
-                <div class="source"><pre>
-&lt;class name=&quot;Directory&quot;&gt;
-    &lt;field name=&quot;children&quot;&gt;
-        &lt;collection element-type=&quot;Directory&quot;/&gt;
-    &lt;/field&gt;
-
-    &lt;fetch-group name=&quot;grandchildren&quot;&gt;
-        &lt;field name=&quot;children&quot; recursion-depth=&quot;2&quot;/&gt;
-    &lt;/fetch-group&gt;
-    ...
-&lt;/class&gt;</pre></div>
-                <p>
-                    So when we fetch a Directory, it will fetch 2 levels of the <i>children</i>
field, hence fetching 
-                    the children and the grandchildren.
-                </p>
-            </div>
-
-            <div class="section"><h3>Fetch Size<a name="Fetch_Size"></a></h3>
-                <p>
-                    A FetchPlan can also be used for defining the fetching policy when using
queries. This can be 
-                    set using
-                </p>
-                <div class="source"><pre>pm.getFetchPlan().setFetchSize(value);</pre></div>
-                <p>
-                    The default is <i>FetchPlan.FETCH_SIZE_OPTIMAL</i> which
leaves it to DataNucleus to optimise the fetching
-                    of instances. A positive value defines the number of instances to be
fetched. Using 
-                    <i>FetchPlan.FETCH_SIZE_GREEDY</i> means that all instances
will be fetched immediately.
-                </p>
-            </div>
-        </div>
-    
+        
+    
+        <div class="section"><h2>Fetch Groups<a name="Fetch_Groups"></a></h2>
+            <p>
+                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 <b>fetch group</b>.
+                There are 3 types of &quot;fetch groups&quot; to consider
+            </p>
+            <ul>
+                <li><a href="#dfg">Default Fetch Group</a> : defined in
all JDO specs, containing the fields 
+                    of a class that will be retrieved by default (with no user specification).</li>
+                <li><a href="#static">Named Fetch Groups</a> : 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 <i>static</i></li>
+                <li><a href="#dynamic">Dynamic Fetch Groups</a> : Programmatic
definition of fetch groups at 
+                    runtime via an API</li>
+            </ul>
+            <p>
+                The <b>fetch group</b> in use for a class is controled via the
<i>FetchPlan</i>
+                <a class="externalLink" href="http://db.apache.org/jdo/api20/apidocs/javax/jdo/FetchPlan.html"
target="_blank"><img src="images/javadoc.gif" alt="" /></a>
+                interface. To get a handle on the current <i>FetchPlan</i> we
do
+            </p>
+            <div class="source"><pre>FetchPlan fp = pm.getFetchPlan();</pre></div>
+            <br />
+
+            <a name="dfg"></a>
+            <div class="section"><h3>Default Fetch Group<a name="Default_Fetch_Group"></a></h3>
+                <p>
+                    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 <i>default 
+                    fetch group</i> comprises all fields of the following types :-
+                </p>
+                <ul>
+                    <li>primitives : boolean, byte, char, double, float, int, long,
short</li>
+                    <li>Object wrappers of primitives : Boolean, Byte, Character, Double,
Float, Integer, Long, Short</li>
+                    <li>java.lang.String, java.lang.Number, java.lang.Enum</li>
+                    <li>java.math.BigDecimal, java.math.BigInteger</li>
+                    <li>java.util.Date</li>
+                </ul>
+                <p>
+                    If you wish to change the <b>Default Fetch Group</b> for
a class you can update the Meta-Data 
+                    for the class as follows (for XML)
+                </p>
+                <div class="source"><pre>
+&lt;class name=&quot;MyClass&quot;&gt;
+    ...
+    &lt;field name=&quot;fieldX&quot; default-fetch-group=&quot;true&quot;/&gt;
+&lt;/class&gt;</pre></div>
+                <p>or using annotations</p>
+                <div class="source"><pre>
+@Persistent(defaultFetchGroup=&quot;true&quot;)
+SomeType fieldX;</pre></div>
+                <p>
+                    When a <i>PersistenceManager</i> is created it starts with
a FetchPlan of the &quot;default&quot; fetch group. 
+                    That is, if we call
+                </p>
+                <div class="source"><pre>Collection fetchGroups = fp.getGroups();</pre></div>
+                <p>
+                    this will have one group, called &quot;default&quot;. 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
+                </p>
+                <div class="source"><pre>fp.setGroup(FetchPlan.DEFAULT);</pre></div>
+                <br />
+            </div>
+
+            <a name="static"></a>
+            <div class="section"><h3>Named Fetch Groups<a name="Named_Fetch_Groups"></a></h3>
+                <p>
+                    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
+                </p>
+                <div class="source"><pre>
+class MyClass
+{
+    String name;
+    HashSet coll;
+    MyOtherClass other;
+}</pre></div>
+                <p>
+                    and we want to have the <u>other</u> field loaded whenever
we load objects of this class, we define 
+                    our MetaData as
+                </p>
+                <div class="source"><pre>
+&lt;package name=&quot;mydomain&quot;&gt;
+    &lt;class name=&quot;MyClass&quot;&gt;
+        &lt;field name=&quot;name&quot;&gt;
+            &lt;column length=&quot;100&quot; jdbc-type=&quot;VARCHAR&quot;/&gt;
+        &lt;/field&gt;
+        &lt;field name=&quot;coll&quot; persistence-modifier=&quot;persistent&quot;&gt;
+            &lt;collection element-type=&quot;mydomain.Address&quot;/&gt;
+            &lt;join/&gt;
+        &lt;/field&gt;
+        &lt;field name=&quot;other&quot; persistence-modifier=&quot;persistent&quot;/&gt;
+        &lt;fetch-group name=&quot;otherfield&quot;&gt;
+            &lt;field name=&quot;other&quot;/&gt;
+        &lt;/fetch-group&gt;
+    &lt;/class&gt;
+&lt;/package&gt;</pre></div>
+                <p>or using annotations</p>
+                <div class="source"><pre>
+@PersistenceCapable
+@FetchGroup(name=&quot;otherfield&quot;, members={@Persistent(name=&quot;other&quot;)})
+public class MyClass
+{
+    ...
+}</pre></div>
+                <p>
+                    So we have defined a fetch group called &quot;otherfield&quot;
that just includes the field with name 
+                    <i>other</i>. We can then use this at runtime in our persistence
code.
+                </p>
+                <div class="source"><pre>
+PersistenceManager pm = pmf.getPersistenceManager();
+pm.getFetchPlan().addGroup(&quot;otherfield&quot;);
+
+... (load MyClass object)</pre></div>
+                <p>
+                    By default the <i>FetchPlan</i> will include the default
fetch group. We have changed this above by
+                    <u>adding</u> the fetch group &quot;otherfield&quot;,
so when we retrieve an object using this 
+                    <i>PersistenceManager</i> we will be retrieving the fields
<i>name</i> AND <i>other</i> since they
+                    are both in the current <i>FetchPlan</i>. 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 <i>FetchPlan</i> just
+                    before any <i>PersistenceManager</i> operation to control
what is fetched during that operation.
+                    The user has full flexibility to add many groups to the current <b>Fetch
Plan</b>.
+                    This gives much power and control over what will be loaded and when.
+                </p>
+                <p>
+                    The <i>FetchPlan</i> applies not just to calls to <i>PersistenceManager.getObjectById()</i>,
but also
+                    to <i>PersistenceManager.newQuery()</i>, <i>PersistenceManager.getExtent()</i>,

+                    <i>PersistenceManager.detachCopy</i> and much more besides.
+                </p>
+                <p>
+                    You can read more about <b>named fetch-groups</b> and how
to use it with 
+                    <a href="attach_detach.html"><b>attach/detach</b></a>
+                </p>
+            </div>
+
+            <a name="dynamic"></a>
+            <div class="section"><h3>Dynamic Fetch Groups<a name="Dynamic_Fetch_Groups"></a></h3>
+                <p>
+                    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
+                </p>
+                <div class="source"><pre>
+import org.datanucleus.FetchGroup;
+
+// Create a FetchGroup on the PMF called &quot;TestGroup&quot; for MyClass
+FetchGroup grp = myPMF.getFetchGroup(&quot;TestGroup&quot;, MyClass.class);
+grp.addMember(&quot;field1&quot;).addMember(&quot;field2&quot;);
+
+// Add this group to the fetch plan (using its name)
+fp.addGroup(&quot;TestGroup&quot;);</pre></div>
+                <p>
+                    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.
+                </p>
+                <br />
+            </div>
+
+            <div class="section"><h3>Fetch Depth<a name="Fetch_Depth"></a></h3>
+                <p>
+                    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.
+                </p>
+                <p>
+                    The first is to set the <b>maxFetchDepth</b> for the <i>FetchPlan</i>.
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
+                </p>
+                <div class="source"><pre>
+public class MyClass1
+{
+    MyClass2 field1;
+    ...
+}
+
+public class MyClass2
+{
+    MyClass3 field2;
+    ...
+}
+
+public class MyClass3
+{
+    MyClass4 field3;
+    ...
+}</pre></div>
+                <p>
+                    and we want to detach <i>field1</i> of instances of <i>MyClass1</i>,
down 2 levels - so detaching 
+                    the initial &quot;field1&quot; <i>MyClass2</i> object,
and its &quot;field2&quot; <i>MyClass3</i> instance. So we 
+                    define our fetch-groups like this
+                </p>
+                <div class="source"><pre>
+&lt;class name=&quot;MyClass1&quot;&gt;
+    ...
+    &lt;fetch-group name=&quot;includingField1&quot;&gt;
+        &lt;field name=&quot;field1&quot;/&gt;
+    &lt;/fetch-group&gt;
+&lt;/class&gt;
+&lt;class name=&quot;MyClass2&quot;&gt;
+    ...
+    &lt;fetch-group name=&quot;includingField2&quot;&gt;
+        &lt;field name=&quot;field2&quot;/&gt;
+    &lt;/fetch-group&gt;
+&lt;/class&gt;</pre></div>
+                <p>
+                    and we then define the <b>maxFetchDepth</b> as 2, like this
+                </p>
+                <div class="source"><pre>pm.getFetchPlan().setMaxFetchDepth(2);</pre></div>
+                <p>
+                    A further refinement to this global fetch depth setting is to control
the fetching of recursive 
+                    fields. This is performed via a MetaData setting &quot;recursion-depth&quot;.
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
+                </p>
+                <div class="source"><pre>
+public class Directory
+{
+    Collection children;
+    ...
+}</pre></div>
+                <div class="source"><pre>
+&lt;class name=&quot;Directory&quot;&gt;
+    &lt;field name=&quot;children&quot;&gt;
+        &lt;collection element-type=&quot;Directory&quot;/&gt;
+    &lt;/field&gt;
+
+    &lt;fetch-group name=&quot;grandchildren&quot;&gt;
+        &lt;field name=&quot;children&quot; recursion-depth=&quot;2&quot;/&gt;
+    &lt;/fetch-group&gt;
+    ...
+&lt;/class&gt;</pre></div>
+                <p>
+                    So when we fetch a Directory, it will fetch 2 levels of the <i>children</i>
field, hence fetching 
+                    the children and the grandchildren.
+                </p>
+            </div>
+
+            <div class="section"><h3>Fetch Size<a name="Fetch_Size"></a></h3>
+                <p>
+                    A FetchPlan can also be used for defining the fetching policy when using
queries. This can be 
+                    set using
+                </p>
+                <div class="source"><pre>pm.getFetchPlan().setFetchSize(value);</pre></div>
+                <p>
+                    The default is <i>FetchPlan.FETCH_SIZE_OPTIMAL</i> which
leaves it to DataNucleus to optimise the fetching
+                    of instances. A positive value defines the number of instances to be
fetched. Using 
+                    <i>FetchPlan.FETCH_SIZE_GREEDY</i> means that all instances
will be fetched immediately.
+                </p>
+            </div>
+        </div>
+    
 
       </div>
     </div>



Mime
View raw message