| <!DOCTYPE html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <!-- No caching headers --> |
| <meta http-equiv="cache-control" content="no-cache"/> |
| <meta http-equiv="pragma" content="no-cache"/> |
| <meta http-equiv="expires" content="-1"/> |
| <meta name="keywords" content="JDO, Apache, Java, Data, Objects"/> |
| <meta name="description" content="Apache JDO - Java Data Objects"/> |
| |
| <title>Fetch Groups</title> |
| |
| <link rel="icon" type="image/png" href="https://apache.github.io/db-jdo-site/images/JDO_32x32.png"/> |
| |
| <!-- |
| Apache JDO Documentation Template |
| ================================== |
| This template derived various aspects from Apache Deltaspike template, the Apache ISIS template and the Datanucleus template. |
| This template uses |
| * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar. |
| * Asciidoctor "foundation" CSS |
| * Bootswatch "cosmo" theme for Bootstrap (https://bootswatch.com/cosmo). |
| * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/) for the table of contents. |
| * jQuery (necessary for Bootstrap's JavaScript plugins) |
| * Font-Awesome for some icons used by Asciidoctor |
| NOTE: tried using Font-Awesome CSS hosted locally but then fails to work! |
| --> |
| <link href="css/bootswatch/3.3.7/bootstrap-cosmo.css" rel="stylesheet"/> |
| <link href="css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet"/> |
| |
| <link href="css/asciidoctor/foundation.css" rel="stylesheet"/> |
| <link href="css/datanucleus_theme.css" rel="stylesheet"/> |
| <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet"> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script> |
| <script src="js/bootstrap/3.3.7/bootstrap.min.js"></script> |
| <script src="js/bootstrap-toc/0.4.1/bootstrap-toc.min.js"></script> |
| |
| <!-- Coderay syntax formatter --> |
| <style type="text/css"> |
| /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */ |
| /*pre.CodeRay {background-color:#f7f7f8;}*/ |
| .CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em} |
| .CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)} |
| .CodeRay .line-numbers strong{color:rgba(0,0,0,.4)} |
| table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none} |
| table.CodeRay td{vertical-align: top;line-height:1.45} |
| table.CodeRay td.line-numbers{text-align:right} |
| table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)} |
| table.CodeRay td.code{padding:0 0 0 .5em} |
| table.CodeRay td.code>pre{padding:0} |
| .CodeRay .debug{color:#fff !important;background:#000080 !important} |
| .CodeRay .annotation{color:#007} |
| .CodeRay .attribute-name{color:#000080} |
| .CodeRay .attribute-value{color:#700} |
| .CodeRay .binary{color:#509} |
| .CodeRay .comment{color:#998;font-style:italic} |
| .CodeRay .char{color:#04d} |
| .CodeRay .char .content{color:#04d} |
| .CodeRay .char .delimiter{color:#039} |
| .CodeRay .class{color:#458;font-weight:bold} |
| .CodeRay .complex{color:#a08} |
| .CodeRay .constant,.CodeRay .predefined-constant{color:#008080} |
| .CodeRay .color{color:#099} |
| .CodeRay .class-variable{color:#369} |
| .CodeRay .decorator{color:#b0b} |
| .CodeRay .definition{color:#099} |
| .CodeRay .delimiter{color:#000} |
| .CodeRay .doc{color:#970} |
| .CodeRay .doctype{color:#34b} |
| .CodeRay .doc-string{color:#d42} |
| .CodeRay .escape{color:#666} |
| .CodeRay .entity{color:#800} |
| .CodeRay .error{color:#808} |
| .CodeRay .exception{color:inherit} |
| .CodeRay .filename{color:#099} |
| .CodeRay .function{color:#900;font-weight:bold} |
| .CodeRay .global-variable{color:#008080} |
| .CodeRay .hex{color:#058} |
| .CodeRay .integer,.CodeRay .float{color:#099} |
| .CodeRay .include{color:#555} |
| .CodeRay .inline{color:#000} |
| .CodeRay .inline .inline{background:#ccc} |
| .CodeRay .inline .inline .inline{background:#bbb} |
| .CodeRay .inline .inline-delimiter{color:#d14} |
| .CodeRay .inline-delimiter{color:#d14} |
| .CodeRay .important{color:#555;font-weight:bold} |
| .CodeRay .interpreted{color:#b2b} |
| .CodeRay .instance-variable{color:#008080} |
| .CodeRay .label{color:#970} |
| .CodeRay .local-variable{color:#963} |
| .CodeRay .octal{color:#40e} |
| .CodeRay .predefined{color:#369} |
| .CodeRay .preprocessor{color:#579} |
| .CodeRay .pseudo-class{color:#555} |
| .CodeRay .directive{font-weight:bold} |
| .CodeRay .type{font-weight:bold} |
| .CodeRay .predefined-type{color:inherit} |
| .CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold} |
| .CodeRay .key{color:#808} |
| .CodeRay .key .delimiter{color:#606} |
| .CodeRay .key .char{color:#80f} |
| .CodeRay .value{color:#088} |
| .CodeRay .regexp .delimiter{color:#808} |
| .CodeRay .regexp .content{color:#808} |
| .CodeRay .regexp .modifier{color:#808} |
| .CodeRay .regexp .char{color:#d14} |
| .CodeRay .regexp .function{color:#404;font-weight:bold} |
| .CodeRay .string{color:#d20} |
| .CodeRay .string .string .string{background:#ffd0d0} |
| .CodeRay .string .content{color:#d14} |
| .CodeRay .string .char{color:#d14} |
| .CodeRay .string .delimiter{color:#d14} |
| .CodeRay .shell{color:#d14} |
| .CodeRay .shell .delimiter{color:#d14} |
| .CodeRay .symbol{color:#990073} |
| .CodeRay .symbol .content{color:#a60} |
| .CodeRay .symbol .delimiter{color:#630} |
| .CodeRay .tag{color:#008080} |
| .CodeRay .tag-special{color:#d70} |
| .CodeRay .variable{color:#036} |
| .CodeRay .insert{background:#afa} |
| .CodeRay .delete{background:#faa} |
| .CodeRay .change{color:#aaf;background:#007} |
| .CodeRay .head{color:#f8f;background:#505} |
| .CodeRay .insert .insert{color:#080} |
| .CodeRay .delete .delete{color:#800} |
| .CodeRay .change .change{color:#66f} |
| .CodeRay .head .head{color:#f4f} |
| </style> |
| </head> |
| <body data-spy="scroll" data-target="#toc"> |
| <!-- Navbar --> |
| <nav class="navbar navbar-default navbar-static-top"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <!-- Three line menu button for use on mobile screens --> |
| <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <!-- 'style' added to align image with navbar. FIX THIS --> |
| <a class="navbar-brand" href="https://db.apache.org/jdo/"> |
| <img style="margin-top: -12px;" alt="Brand" src="images/JDO_44x44.png"/> |
| </a> |
| <!-- TODO Any way to abstract the version from Maven? --> |
| <a class="navbar-brand" href="index.html">Apache JDO</a> |
| </div> |
| <!-- Navbar that will collapse on mobile screens --> |
| <div id="navbar" class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li class="dropdown"> |
| |
| <!-- menu item General --> |
| |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">General<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="why_jdo.html">Why JDO?</a></li> |
| <li><a href="getting-started.html">Getting Started</a></li> |
| <li><a href="specifications.html">Specifications</a></li> |
| <li><a href="tck.html">TCK</a></li> |
| <li><a href="javadoc.html">API Javadoc</a></li> |
| <li role="separator" class="divider"></li> |
| <li><a href="jdo_v_jpa.html">JDO v JPA</a></li> |
| <li><a href="jdo_v_jpa_api.html">JDO v JPA : API</a></li> |
| <li><a href="jdo_v_jpa_orm.html">JDO v JPA : ORM</a></li> |
| <li role="separator" class="divider"></li> |
| <li><a href="license.html">License</a></li> |
| <li><a href="impls.html">Implementations</a></li> |
| <li><a href="jdo_3_0_overview.html">JDO 3.0 Overview</a></li> |
| <li><a href="references.html">References</a></li> |
| <li><a href="glossary.html">Glossary</a></li> |
| </ul> |
| </li> |
| |
| <!-- menu item API Usage --> |
| |
| <li class="dropdown"> |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false" style="background-color:#2385c6">API Usage<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="jdohelper.html">JDO Helper</a></li> |
| <li><a href="pmf.html">PersistenceManagerFactory</a></li> |
| <li><a href="pm.html">PersistenceManager</a></li> |
| <li><a href="transactions.html">Transactions</a></li> |
| <li><a href="attach_detach.html">Attach-Detach</a></li> |
| <li><a href="fetchgroups.html">Fetch Groups</a></li> |
| <li><a href="state_transition.html">Object States</a></li> |
| <li><a href="object_retrieval.html">Object Retrieval</a></li> |
| <li><a href="exceptions.html">Exceptions</a></li> |
| <li role="separator" class="divider"></li> |
| <li><a href="guides-replication.html">Data Replication</a></li> |
| </ul> |
| </li> |
| |
| <!-- menu item Types & Metadata --> |
| |
| <li class="dropdown"> |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Types & Metadata<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="class_types.html">Types of Classes</a></li> |
| <li><a href="field_types.html">Types of Fields</a></li> |
| <li role="separator" class="divider"></li> |
| <!-- <li class="dropdown-header">Metadata</li> --> |
| <li><a href="metadata.html">MetaData</a></li> |
| <li><a href="annotations.html">Annotations</a></li> |
| <li><a href="jdo_dtd.html">jdo DTD/XSD</a></li> |
| <li><a href="orm_dtd.html">orm DTD/XSD</a></li> |
| <li><a href="jdoquery_dtd.html">jdoquery DTD/XSD</a></li> |
| <li><a href="jdoconfig_dtd.html">jdoconfig DTD/XSD</a></li> |
| <li role="separator" class="divider"></li> |
| <li><a href="enhancement.html">Bytecode Enhancement</a></li> |
| </ul> |
| </li> |
| |
| <!-- menu item Query --> |
| |
| <li class="dropdown"> |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Query<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="jdoql.html">JDOQL</a></li> |
| <li><a href="jdoql_result.html">Result</a></li> |
| <li><a href="jdoql_methods.html">Methods</a></li> |
| <li><a href="jdoql_quickref.pdf">Quick Ref PDF</a></li> |
| <li role="separator" class="divider"></li> |
| <li><a href="extents.html">Extents</a></li> |
| </ul> |
| </li> |
| |
| <!-- menu item Community --> |
| |
| <li class="dropdown"> |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Community<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="get-involved.html">Get Involved</a></li> |
| <li><a href="team-list.html">Project Team</a></li> |
| <li><a href="mail-lists.html">Mailing Lists</a></li> |
| <li><a href="faq.html">FAQ</a></li> |
| </ul> |
| </li> |
| |
| <!-- menu item Development --> |
| |
| <li class="dropdown"> |
| |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Development<span class="caret"></span></a> |
| |
| <ul class="dropdown-menu"> |
| <li><a href="roadmap.html">RoadMap / TODO</a></li> |
| <li><a href="downloads.html">Downloads</a></li> |
| <li><a href="source-code.html">Source Code</a></li> |
| <li><a href="coding-standards.html">Coding Standards</a></li> |
| <li><a href="issuetracking.html">Issue Tracking</a></li> |
| </ul> |
| </li> |
| </ul> |
| <!-- 'style' added to fix height of input box. FIX THIS --> |
| <form class="navbar-form navbar-left" role="search" id="search-form" action="https://www.google.com/search" method="get" style="padding: 1px 15px;"> |
| <div class="form-group"> |
| <input name="sitesearch" value="db.apache.org/jdo" type="hidden"> |
| <input name="q" type="text" class="form-control" placeholder="Search" style="margin-top: 7px; padding: 1px; border-radius: 5px; height: 30px; vertical-align: middle;"> |
| </div> |
| </form> |
| </div> |
| </div> |
| </nav> |
| <div class="container"> |
| |
| <div class="row-fluid"> |
| <div class="col-sm-9"> |
| <!-- <div class="page-title"> |
| <h3>Fetch Groups<a id="Fetch_Groups"></a></h3> |
| </div> |
| --> |
| <div id="doc-content"> |
| <div class="sect1"> |
| <h2 id="index">Fetch Groups<a id="Fetch_Groups"></a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <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 <strong>fetch |
| group</strong>. There are 3 types of "fetch groups" to consider</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><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).</p> |
| </li> |
| <li> |
| <p><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 <em>static</em></p> |
| </li> |
| <li> |
| <p><a href="#dynamic">Dynamic Fetch Groups</a> : Programmatic definition of fetch |
| groups at runtime via an API</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The <strong>fetch group</strong> in use for a class is controled via the <em>FetchPlan</em> |
| <a href="http://db.apache.org/jdo/api20/apidocs/javax/jdo/FetchPlan.html"><span class="image"><img src="images/javadoc.png" alt="image"></span></a> |
| interface. To get a handle on the current <em>FetchPlan</em> we do</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>FetchPlan fp = pm.getFetchPlan();</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><br></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="dfg"></a></p> |
| </div> |
| <div class="sect2"> |
| <h3 id="_default_fetch_group_a_id_default_fetch_group_a">Default Fetch Group<a id="Default_Fetch_Group"></a></h3> |
| <div class="paragraph"> |
| <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 <em>default fetch group</em> comprises |
| all fields of the following types :</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>primitives : boolean, byte, char, double, float, int, long, short</p> |
| </li> |
| <li> |
| <p>Object wrappers of primitives : Boolean, Byte, Character, Double, |
| Float, Integer, Long, Short</p> |
| </li> |
| <li> |
| <p>java.lang.String, java.lang.Number, java.lang.Enum</p> |
| </li> |
| <li> |
| <p>java.math.BigDecimal, java.math.BigInteger</p> |
| </li> |
| <li> |
| <p>java.util.Date</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>If you wish to change the <strong>Default Fetch Group</strong> for a class you can |
| update the Meta-Data for the class as follows (for XML)</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre><class name="MyClass"> |
| ... |
| <field name="fieldX" default-fetch-group="true"/> |
| </class></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or using annotations</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>@Persistent(defaultFetchGroup="true") |
| SomeType fieldX;</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When a <em>PersistenceManager</em> is created it starts with a FetchPlan of the |
| "default" fetch group. That is, if we call</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>Collection fetchGroups = fp.getGroups();</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <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> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>fp.setGroup(FetchPlan.DEFAULT);</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><br></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="static"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_named_fetch_groups_a_id_named_fetch_groups_a">Named Fetch Groups<a id="Named_Fetch_Groups"></a></h3> |
| <div class="paragraph"> |
| <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> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>class MyClass |
| { |
| String name; |
| HashSet coll; |
| MyOtherClass other; |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>and we want to have the <span class="underline">other</span> field loaded whenever we |
| load objects of this class, we define our MetaData as</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p>or using annotations</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>@PersistenceCapable |
| @FetchGroup(name="otherfield", members={@Persistent(name="other")}) |
| public class MyClass |
| { |
| ... |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>So we have defined a fetch group called "otherfield" that just includes |
| the field with name <em>other</em>. We can then use this at runtime in our |
| persistence code.</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>PersistenceManager pm = pmf.getPersistenceManager(); |
| pm.getFetchPlan().addGroup("otherfield"); |
| |
| ... (load MyClass object)</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>By default the <em>FetchPlan</em> will include the default fetch group. We have |
| changed this above by <span class="underline">adding</span> the fetch group "otherfield", |
| so when we retrieve an object using this <em>PersistenceManager</em> we will be |
| retrieving the fields <em>name</em> AND <em>other</em> since they are both in the |
| current <em>FetchPlan</em>. 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 <em>FetchPlan</em> just before any <em>PersistenceManager</em> |
| operation to control what is fetched during that operation. The user has |
| full flexibility to add many groups to the current <strong>Fetch Plan</strong>. This |
| gives much power and control over what will be loaded and when.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The <em>FetchPlan</em> applies not just to calls to |
| <em>PersistenceManager.getObjectById()</em>, but also to |
| <em>PersistenceManager.newQuery()</em>, <em>PersistenceManager.getExtent()</em>, |
| <em>PersistenceManager.detachCopy</em> and much more besides.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You can read more about <strong>named fetch-groups</strong> and how to use it with |
| <a href="attach_detach.html"><strong>attach/detach</strong></a></p> |
| </div> |
| <div class="paragraph"> |
| <p><a id="dynamic"></a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_dynamic_fetch_groups_a_id_dynamic_fetch_groups_a">Dynamic Fetch Groups<a id="Dynamic_Fetch_Groups"></a></h3> |
| <div class="paragraph"> |
| <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> |
| <div class="literalblock"> |
| <div class="content"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p><br></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_fetch_depth_a_id_fetch_depth_a">Fetch Depth<a id="Fetch_Depth"></a></h3> |
| <div class="paragraph"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p>The first is to set the <strong>maxFetchDepth</strong> for the <em>FetchPlan</em>. 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> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>public class MyClass1 |
| { |
| MyClass2 field1; |
| ... |
| } |
| |
| public class MyClass2 |
| { |
| MyClass3 field2; |
| ... |
| } |
| |
| public class MyClass3 |
| { |
| MyClass4 field3; |
| ... |
| }</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>and we want to detach <em>field1</em> of instances of <em>MyClass1</em>, down 2 levels |
| - so detaching the initial "field1" <em>MyClass2</em> object, and its "field2" |
| <em>MyClass3</em> instance. So we define our fetch-groups like this</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p>and we then define the <strong>maxFetchDepth</strong> as 2, like this</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>pm.getFetchPlan().setMaxFetchDepth(2);</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <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> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>public class Directory |
| { |
| Collection children; |
| ... |
| }</pre> |
| </div> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <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> |
| </div> |
| <div class="paragraph"> |
| <p>So when we fetch a Directory, it will fetch 2 levels of the <em>children</em> |
| field, hence fetching the children and the grandchildren.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_fetch_size_a_id_fetch_size_a">Fetch Size<a id="Fetch_Size"></a></h3> |
| <div class="paragraph"> |
| <p>A FetchPlan can also be used for defining the fetching policy when using |
| queries. This can be set using</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>pm.getFetchPlan().setFetchSize(value);</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The default is <em>FetchPlan.FETCH_SIZE_OPTIMAL</em> which leaves it to |
| DataNucleus to optimise the fetching of instances. A positive value |
| defines the number of instances to be fetched. Using |
| <em>FetchPlan.FETCH_SIZE_GREEDY</em> means that all instances will be fetched |
| immediately.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="col-sm-3"> |
| <nav id="toc" data-spy="affix" data-toggle="toc"></nav> |
| </div> |
| </div> |
| |
| </div> |
| |
| <footer style="color:#fff; background-color:#222222; padding: 5px;"> |
| <div class="container"> |
| <div class="row" style="margin-top:25px"> |
| <div class="col-sm" align="center"> |
| <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="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> |
| | |
| <a href="mail-lists.html" title="Mailing Lists">Mailing Lists</a> |
| | |
| <a href="api31/apidocs/index.html" title="Latest Javadocs">Latest Javadocs</a> |
| </div> |
| </div> |
| <p class="text-center" style="margin-top:16px">© 2005-2020 Apache Software Foundation. All Rights Reserved.</p> |
| </div> |
| </footer> |
| |
| </body> |
| </html> |