Google Git
Sign in
apache / db-jdo-site / refs/heads/publish / . / content / fetchgroups.html
blob: 62c5753bdf6540dfca494f7705e457948d91ed2d [file] [log] [blame]
<!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 Plan / Groups</title>
<link rel="icon" type="image/png" href="images/JDOx150.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:#f7f7f8}
.CodeRay .line-numbers{border-right:1px solid currentColor;opacity:.35;padding:0 .5em 0 0}
.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
.CodeRay .line-numbers strong{color:#000}
table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.CodeRay td{vertical-align:top;line-height:inherit}
table.CodeRay td.line-numbers{text-align:right}
table.CodeRay td.code{padding:0 0 0 .75em}
.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" width="45.5" height="45.5" src="images/JDOx150.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="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 Plan/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><a href="jdohelper.html">JDO Helper</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 &amp; 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="query_api.html">Query API</a></li>
<li role="separator" class="divider"></li>
<li><a href="jdoql.html">JDOQL</a></li>
<li><a href="jdoql_methods.html">Methods</a></li>
<li><a href="jdoql_result.html">Result</a></li>
<li><a href="jdoql_quickref.pdf">Quick Ref PDF</a></li>
<li><a href="jdoql_typed.html">JDOQL Typed API</a></li>
<li role="separator" class="divider"></li>
<li><a href="query_sql.html">SQL</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 Plan / Groups</h3>
</div>
-->
<div id="doc-content">
<div class="sect1">
<h2 id="Fetch_Groups">Fetch Plan / Groups</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 defined by a <strong>FetchPlan</strong> and is comprised of multiple *fetch group*s.
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 the JDO spec, 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 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>(s) in use for a class is controlled via the <em>FetchPlan</em>
<a href="http://db.apache.org/jdo/api32/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="sect2">
<h3 id="dfg">Default Fetch Group</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 (using XML)</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MyClass</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
...
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">fieldX</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">default-fetch-group</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/class&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>or using annotations</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@Persistent</span>(defaultFetchGroup=<span class="string"><span class="delimiter">&quot;</span><span class="content">true</span><span class="delimiter">&quot;</span></span>)
SomeType fieldX;</code></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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="predefined-type">Collection</span> fetchGroups = fp.getGroups();</code></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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">fp.setGroup(FetchPlan.DEFAULT);</code></pre>
</div>
</div>
<div class="paragraph">
<p><br></p>
</div>
</div>
<div class="sect2">
<h3 id="static">Named Fetch Groups</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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="type">class</span> <span class="class">MyClass</span>
{
<span class="predefined-type">String</span> name;
<span class="predefined-type">HashSet</span> coll;
MyOtherClass other;
}</code></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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;package</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mydomain</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MyClass</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">name</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;column</span> <span class="attribute-name">length</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">100</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">jdbc-type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">VARCHAR</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/field&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">coll</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">persistence-modifier</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">persistent</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;collection</span> <span class="attribute-name">element-type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">mydomain.Address</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;join</span><span class="tag">/&gt;</span>
<span class="tag">&lt;/field&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">persistence-modifier</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">persistent</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;fetch-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">otherfield</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">other</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/fetch-group&gt;</span>
<span class="tag">&lt;/class&gt;</span>
<span class="tag">&lt;/package&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>or using annotations</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="annotation">@PersistenceCapable</span>
<span class="annotation">@FetchGroup</span>(name=<span class="string"><span class="delimiter">&quot;</span><span class="content">otherfield</span><span class="delimiter">&quot;</span></span>, members={<span class="annotation">@Persistent</span>(name=<span class="string"><span class="delimiter">&quot;</span><span class="content">other</span><span class="delimiter">&quot;</span></span>)})
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClass</span>
{
...
}</code></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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">PersistenceManager pm = pmf.getPersistenceManager();
pm.getFetchPlan().addGroup(<span class="string"><span class="delimiter">&quot;</span><span class="content">otherfield</span><span class="delimiter">&quot;</span></span>);
... (load MyClass object)</code></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>
<div class="sect2">
<h3 id="dynamic">Dynamic Fetch Groups</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.
It operates as follows</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="keyword">import</span> <span class="include">org.datanucleus.FetchGroup</span>;
<span class="comment">// Create a FetchGroup on the PMF called &quot;TestGroup&quot; for MyClass</span>
FetchGroup grp = myPMF.getFetchGroup(<span class="string"><span class="delimiter">&quot;</span><span class="content">TestGroup</span><span class="delimiter">&quot;</span></span>, MyClass.class);
grp.addMember(<span class="string"><span class="delimiter">&quot;</span><span class="content">field1</span><span class="delimiter">&quot;</span></span>).addMember(<span class="string"><span class="delimiter">&quot;</span><span class="content">field2</span><span class="delimiter">&quot;</span></span>);
<span class="comment">// Add this group to the fetch plan (using its name)</span>
fp.addGroup(<span class="string"><span class="delimiter">&quot;</span><span class="content">TestGroup</span><span class="delimiter">&quot;</span></span>);</code></pre>
</div>
</div>
<div class="paragraph">
<p>So we use the 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">Fetch Depth</h3>
<div class="paragraph">
<p>The basic fetch group defines which fields are to be fetched.
It doesn&#8217;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&#8217;s take an example</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">MyClass1</span>
{
MyClass2 field1;
...
}
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClass2</span>
{
MyClass3 field2;
...
}
<span class="directive">public</span> <span class="type">class</span> <span class="class">MyClass3</span>
{
MyClass4 field3;
...
}</code></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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MyClass1</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
...
<span class="tag">&lt;fetch-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">includingField1</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">field1</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/fetch-group&gt;</span>
<span class="tag">&lt;/class&gt;</span>
<span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">MyClass2</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
...
<span class="tag">&lt;fetch-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">includingField2</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">field2</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/fetch-group&gt;</span>
<span class="tag">&lt;/class&gt;</span></code></pre>
</div>
</div>
<div class="paragraph">
<p>and we then define the <strong>maxFetchDepth</strong> as 2, like this</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">pm.getFetchPlan().setMaxFetchDepth(<span class="integer">2</span>);</code></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&#8217;s take an example</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Directory</span>
{
<span class="predefined-type">Collection</span> children;
...
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="xml"><span class="tag">&lt;class</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Directory</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">children</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;collection</span> <span class="attribute-name">element-type</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">Directory</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/field&gt;</span>
<span class="tag">&lt;fetch-group</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">grandchildren</span><span class="delimiter">&quot;</span></span><span class="tag">&gt;</span>
<span class="tag">&lt;field</span> <span class="attribute-name">name</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">children</span><span class="delimiter">&quot;</span></span> <span class="attribute-name">recursion-depth</span>=<span class="string"><span class="delimiter">&quot;</span><span class="content">2</span><span class="delimiter">&quot;</span></span><span class="tag">/&gt;</span>
<span class="tag">&lt;/fetch-group&gt;</span>
...
<span class="tag">&lt;/class&gt;</span></code></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">Fetch Size</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="listingblock">
<div class="content">
<pre class="CodeRay highlight"><code data-lang="java">pm.getFetchPlan().setFetchSize(value);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The default is <em>FetchPlan.FETCH_SIZE_OPTIMAL</em> which leaves it to the JDO provider 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>
|
<a href="https://privacy.apache.org/policies/privacy-policy-public.html" title="Privacy Policy">Privacy Policy</a>
</div>
</div>
<p class="text-center" style="margin-top:16px">&copy; 2005-2022 Apache Software Foundation. All Rights Reserved.</p>
</div>
</footer>
</body>
</html>