You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@db.apache.org by mc...@apache.org on 2013/01/21 05:23:18 UTC
svn commit: r847423 [3/14] - in /websites/production/db/content/jdo: ./
guides/ releases/
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 "fetch groups" 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>
-<class name="MyClass">
- ...
- <field name="fieldX" default-fetch-group="true"/>
-</class></pre></div>
- <p>or using annotations</p>
- <div class="source"><pre>
-@Persistent(defaultFetchGroup="true")
-SomeType fieldX;</pre></div>
- <p>
- When a <i>PersistenceManager</i> is created it starts with a FetchPlan of the "default" 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 "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
- </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>
-<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></pre></div>
- <p>or using annotations</p>
- <div class="source"><pre>
-@PersistenceCapable
-@FetchGroup(name="otherfield", members={@Persistent(name="other")})
-public class MyClass
-{
- ...
-}</pre></div>
- <p>
- So we have defined a fetch group called "otherfield" 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("otherfield");
-
-... (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 "otherfield", 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 "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");</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 "field1" <i>MyClass2</i> object, and its "field2" <i>MyClass3</i> instance. So we
- define our fetch-groups like this
- </p>
- <div class="source"><pre>
-<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></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 "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
- </p>
- <div class="source"><pre>
-public class Directory
-{
- Collection children;
- ...
-}</pre></div>
- <div class="source"><pre>
-<class name="Directory">
- <field name="children">
- <collection element-type="Directory"/>
- </field>
-
- <fetch-group name="grandchildren">
- <field name="children" recursion-depth="2"/>
- </fetch-group>
- ...
-</class></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 "fetch groups" 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>
+<class name="MyClass">
+ ...
+ <field name="fieldX" default-fetch-group="true"/>
+</class></pre></div>
+ <p>or using annotations</p>
+ <div class="source"><pre>
+@Persistent(defaultFetchGroup="true")
+SomeType fieldX;</pre></div>
+ <p>
+ When a <i>PersistenceManager</i> is created it starts with a FetchPlan of the "default" 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 "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
+ </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>
+<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></pre></div>
+ <p>or using annotations</p>
+ <div class="source"><pre>
+@PersistenceCapable
+@FetchGroup(name="otherfield", members={@Persistent(name="other")})
+public class MyClass
+{
+ ...
+}</pre></div>
+ <p>
+ So we have defined a fetch group called "otherfield" 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("otherfield");
+
+... (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 "otherfield", 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 "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");</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 "field1" <i>MyClass2</i> object, and its "field2" <i>MyClass3</i> instance. So we
+ define our fetch-groups like this
+ </p>
+ <div class="source"><pre>
+<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></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 "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
+ </p>
+ <div class="source"><pre>
+public class Directory
+{
+ Collection children;
+ ...
+}</pre></div>
+ <div class="source"><pre>
+<class name="Directory">
+ <field name="children">
+ <collection element-type="Directory"/>
+ </field>
+
+ <fetch-group name="grandchildren">
+ <field name="children" recursion-depth="2"/>
+ </fetch-group>
+ ...
+</class></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>