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>
