You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@db.apache.org by an...@apache.org on 2013/02/23 15:12:19 UTC
svn commit: r851672 [2/12] - in /websites/production/db/content/jdo: ./
guides/ releases/
Modified: websites/production/db/content/jdo/exceptions.html
==============================================================================
--- websites/production/db/content/jdo/exceptions.html (original)
+++ websites/production/db/content/jdo/exceptions.html Sat Feb 23 14:12:18 2013
@@ -1,5 +1,5 @@
<!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 20, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Feb 23, 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" />
@@ -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="20130120" />
+ <meta name="Date-Revision-yyyymmdd" content="20130223" />
<meta http-equiv="Content-Language" content="en" />
</head>
@@ -209,102 +209,102 @@
</div>
<div id="bodyColumn">
<div id="contentBox">
-
-
- <div class="section"><h2>JDO Exceptions<a name="JDO_Exceptions"></a></h2>
- <p>
- All exceptions raised by a JDO implementation are runtime exceptions which means that you can choose to catch
- the exceptions or not. The reason for JDO using <i>unchecked</i> exceptions is that JDO tries to provide transparent
- persistence, and so needs to present the same interface and exceptions whatever the state an object has.
- </p>
-
- <div class="section"><h3>JDOException<a name="JDOException"></a></h3>
- <p>
- This is the base class for all JDO exceptions. It is a subclass of RuntimeException, and need not be declared or caught.
- </p>
- <br />
- </div>
-
- <div class="section"><h3>Can Retry Exceptions<a name="Can_Retry_Exceptions"></a></h3>
- <center>
- <img src="images/jdo_exception_canretry.jpg" border="0" alt="JDO Can Retry Exceptions" />
- </center>
- <table border="0" class="bodyTable">
- <tr class="a">
- <th>Exception</th><th>Description</th>
- </tr>
- <tr class="b">
- <td>JDOCanRetryException</td>
- <td>This is the base class for errors that can be retried.</td>
- </tr>
- <tr class="a">
- <td>JDOUserException</td>
- <td>This is the base class for user errors that can be retried.</td>
- </tr>
- <tr class="b">
- <td>JDODataStoreException</td>
- <td>This is the base class for datastore errors that can be retried.
- Any root SQLException that caused this will typically be nested within this exception.</td>
- </tr>
- <tr class="a">
- <td>JDOObjectNotFoundException</td>
- <td>This exception is to notify the application that an object does not exist in the
- datastore. When this exception is thrown during a transaction, there has been no change
- in the status of the transaction in progress. If this exception is a nested exception
- thrown during commit, then the transaction is rolled back.</td>
- </tr>
- <tr class="b">
- <td>JDOUnsupportedOptionException</td>
- <td>This exception is thrown by an implementation to indicate that it does not implement a
- JDO optional feature.</td>
- </tr>
- </table>
- <br />
- </div>
-
- <div class="section"><h3>Fatal Exceptions<a name="Fatal_Exceptions"></a></h3>
- <center>
- <img src="images/jdo_exception_fatal.jpg" border="0" alt="JDO Fatal Exceptions" />
- </center>
- <table border="0" class="bodyTable">
- <tr class="a">
- <th>Exception</th><th>Description</th>
- </tr>
- <tr class="b">
- <td>JDOFatalException</td>
- <td>This is the base class for errors that cannot be retried. This exception generally
- means that the transaction associated with the PersistenceManager has been rolled back,
- and the transaction should be abandoned.</td>
- </tr>
- <tr class="a">
- <td>JDOFatalUserException</td>
- <td>This is the base class for user errors that cannot be retried.</td>
- </tr>
- <tr class="b">
- <td>JDOFatalInternalException</td>
- <td>This is the base class for JDO implementation failures.</td>
- </tr>
- <tr class="a">
- <td>JDOFatalDataStoreException</td>
- <td>This is the base class for fatal datastore errors. When this exception is thrown, the
- transaction has been rolled back. Any root SQLException that caused this will typically be nested
- within this exception.</td>
- </tr>
- <tr class="b">
- <td>JDOOptimisticVerificationException</td>
- <td>This exception is the result of a user commit operation in an optimistic transaction
- where the verification of new, modified, or deleted instances fails the verification.
- The user will never see this exception except as a result of commit.</td>
- </tr>
- <tr class="a">
- <td>JDODetachedFieldAccessException</td>
- <td>This exception is the result of a user accessing a field of a detached instance, where
- the field was not copied to the detached instance.</td>
- </tr>
- </table>
- </div>
- </div>
-
+
+
+ <div class="section"><h2>JDO Exceptions<a name="JDO_Exceptions"></a></h2>
+ <p>
+ All exceptions raised by a JDO implementation are runtime exceptions which means that you can choose to catch
+ the exceptions or not. The reason for JDO using <i>unchecked</i> exceptions is that JDO tries to provide transparent
+ persistence, and so needs to present the same interface and exceptions whatever the state an object has.
+ </p>
+
+ <div class="section"><h3>JDOException<a name="JDOException"></a></h3>
+ <p>
+ This is the base class for all JDO exceptions. It is a subclass of RuntimeException, and need not be declared or caught.
+ </p>
+ <br />
+ </div>
+
+ <div class="section"><h3>Can Retry Exceptions<a name="Can_Retry_Exceptions"></a></h3>
+ <center>
+ <img src="images/jdo_exception_canretry.jpg" border="0" alt="JDO Can Retry Exceptions" />
+ </center>
+ <table border="0" class="bodyTable">
+ <tr class="a">
+ <th>Exception</th><th>Description</th>
+ </tr>
+ <tr class="b">
+ <td>JDOCanRetryException</td>
+ <td>This is the base class for errors that can be retried.</td>
+ </tr>
+ <tr class="a">
+ <td>JDOUserException</td>
+ <td>This is the base class for user errors that can be retried.</td>
+ </tr>
+ <tr class="b">
+ <td>JDODataStoreException</td>
+ <td>This is the base class for datastore errors that can be retried.
+ Any root SQLException that caused this will typically be nested within this exception.</td>
+ </tr>
+ <tr class="a">
+ <td>JDOObjectNotFoundException</td>
+ <td>This exception is to notify the application that an object does not exist in the
+ datastore. When this exception is thrown during a transaction, there has been no change
+ in the status of the transaction in progress. If this exception is a nested exception
+ thrown during commit, then the transaction is rolled back.</td>
+ </tr>
+ <tr class="b">
+ <td>JDOUnsupportedOptionException</td>
+ <td>This exception is thrown by an implementation to indicate that it does not implement a
+ JDO optional feature.</td>
+ </tr>
+ </table>
+ <br />
+ </div>
+
+ <div class="section"><h3>Fatal Exceptions<a name="Fatal_Exceptions"></a></h3>
+ <center>
+ <img src="images/jdo_exception_fatal.jpg" border="0" alt="JDO Fatal Exceptions" />
+ </center>
+ <table border="0" class="bodyTable">
+ <tr class="a">
+ <th>Exception</th><th>Description</th>
+ </tr>
+ <tr class="b">
+ <td>JDOFatalException</td>
+ <td>This is the base class for errors that cannot be retried. This exception generally
+ means that the transaction associated with the PersistenceManager has been rolled back,
+ and the transaction should be abandoned.</td>
+ </tr>
+ <tr class="a">
+ <td>JDOFatalUserException</td>
+ <td>This is the base class for user errors that cannot be retried.</td>
+ </tr>
+ <tr class="b">
+ <td>JDOFatalInternalException</td>
+ <td>This is the base class for JDO implementation failures.</td>
+ </tr>
+ <tr class="a">
+ <td>JDOFatalDataStoreException</td>
+ <td>This is the base class for fatal datastore errors. When this exception is thrown, the
+ transaction has been rolled back. Any root SQLException that caused this will typically be nested
+ within this exception.</td>
+ </tr>
+ <tr class="b">
+ <td>JDOOptimisticVerificationException</td>
+ <td>This exception is the result of a user commit operation in an optimistic transaction
+ where the verification of new, modified, or deleted instances fails the verification.
+ The user will never see this exception except as a result of commit.</td>
+ </tr>
+ <tr class="a">
+ <td>JDODetachedFieldAccessException</td>
+ <td>This exception is the result of a user accessing a field of a detached instance, where
+ the field was not copied to the detached instance.</td>
+ </tr>
+ </table>
+ </div>
+ </div>
+
</div>
</div>
Modified: websites/production/db/content/jdo/extents.html
==============================================================================
--- websites/production/db/content/jdo/extents.html (original)
+++ websites/production/db/content/jdo/extents.html Sat Feb 23 14:12:18 2013
@@ -1,5 +1,5 @@
<!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 20, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Feb 23, 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" />
@@ -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="20130120" />
+ <meta name="Date-Revision-yyyymmdd" content="20130223" />
<meta http-equiv="Content-Language" content="en" />
</head>
@@ -209,27 +209,27 @@
</div>
<div id="bodyColumn">
<div id="contentBox">
-
-
- <div class="section"><h2>JDO Extents<a name="JDO_Extents"></a></h2>
- <p>
- JDO implementations manage the persistence of objects into the datastore. An <b>Extent</b>
- is a collection of objects of a particular type of object that have been persisted. When you define
- the MetaData for a class you can define if the class requires an Extent. The default is true.
- You access the Extent as follows
- </p>
- <div class="source"><pre>
-Extent e = pm.getExtent(MyClass.class, true);
- </pre></div>
- <p>
- This example will return an Extent that contains all persisted instances of the class <i>MyClass</i>
- and its subclasses (the second argument in the call). An Extent is useful where you want to restrict a
- Query to query over just that set of objects. It can also be used where you just want to retrieve
- all persisted objects of a type (as an alternative to using a Query).
- </p>
- </div>
-
-
+
+
+ <div class="section"><h2>JDO Extents<a name="JDO_Extents"></a></h2>
+ <p>
+ JDO implementations manage the persistence of objects into the datastore. An <b>Extent</b>
+ is a collection of objects of a particular type of object that have been persisted. When you define
+ the MetaData for a class you can define if the class requires an Extent. The default is true.
+ You access the Extent as follows
+ </p>
+ <div class="source"><pre>
+Extent e = pm.getExtent(MyClass.class, true);
+ </pre></div>
+ <p>
+ This example will return an Extent that contains all persisted instances of the class <i>MyClass</i>
+ and its subclasses (the second argument in the call). An Extent is useful where you want to restrict a
+ Query to query over just that set of objects. It can also be used where you just want to retrieve
+ all persisted objects of a type (as an alternative to using a Query).
+ </p>
+ </div>
+
+
</div>
</div>
Modified: websites/production/db/content/jdo/faq.html
==============================================================================
--- websites/production/db/content/jdo/faq.html (original)
+++ websites/production/db/content/jdo/faq.html Sat Feb 23 14:12:18 2013
@@ -1,5 +1,5 @@
<!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 20, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Feb 23, 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" />
@@ -12,7 +12,7 @@
</style>
<link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
<meta name="author" content="JDO Documentation Team" />
- <meta name="Date-Revision-yyyymmdd" content="20130120" />
+ <meta name="Date-Revision-yyyymmdd" content="20130223" />
<meta http-equiv="Content-Language" content="en" />
</head>
@@ -210,69 +210,69 @@
</div>
<div id="bodyColumn">
<div id="contentBox">
- <!-- Licensed to the Apache Software Foundation (ASF) under one or more
-contributor license agreements. See the NOTICE file distributed with
-this work for additional information regarding copyright ownership.
-The ASF licenses this file to You under the Apache License, Version 2.0
-(the "License"); you may not use this file except in compliance with
-the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License. -->
-
-
- <div class="section"><h2>General<a name="General"></a></h2>
-
- <p>
- <b>What is JDO?</b>
- <cite>
- JDO is Java Data Objects, a datastore-agnostic interface
- for storing Java objects in transactional datastores.
- </cite>
- </p>
-
- <p>
- <b>I'd like to find out more about the project and possibly contribute. What do I do next?</b>
- <cite>Participation on the project is via the mailing
- list and the source code repository. You join by subscribing
- to the mailing list and participating in discussions. You
- can help by contributing your ideas, enthusiasm, code,
- documentation, and tests. The fundamental tenet of the Apache
- Software Foundation is that great communities build great
- code. The emphasis is on community; the code comes from that.
- If you want to help, just join the mailing list, see what
- needs to be done, and do it. Welcome!
- </cite>
- </p>
-
- <p>
- <b>Where is the mailing list, and how can I subscribe?</b>
- <cite>
- The developers mailing list is jdo-dev@db.apache.org, a
- high-volume list currently receiving from 100 to 300 messages
- a month.
- <br />
- The users mailing list is jdo-user@db.apache.org.
- </cite>
- </p>
-
-<p>
- <b>Does this project use a wiki?</b>
- <cite>
- It does - the
- <a class="externalLink" href="http://wiki.apache.org/jdo">JDO wiki</a>
- complements the work taking place on the mailing list and provides
- additional information on the project.
- </cite>
-</p>
-</div>
-
-
+ <!-- Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License. -->
+
+
+ <div class="section"><h2>General<a name="General"></a></h2>
+
+ <p>
+ <b>What is JDO?</b>
+ <cite>
+ JDO is Java Data Objects, a datastore-agnostic interface
+ for storing Java objects in transactional datastores.
+ </cite>
+ </p>
+
+ <p>
+ <b>I'd like to find out more about the project and possibly contribute. What do I do next?</b>
+ <cite>Participation on the project is via the mailing
+ list and the source code repository. You join by subscribing
+ to the mailing list and participating in discussions. You
+ can help by contributing your ideas, enthusiasm, code,
+ documentation, and tests. The fundamental tenet of the Apache
+ Software Foundation is that great communities build great
+ code. The emphasis is on community; the code comes from that.
+ If you want to help, just join the mailing list, see what
+ needs to be done, and do it. Welcome!
+ </cite>
+ </p>
+
+ <p>
+ <b>Where is the mailing list, and how can I subscribe?</b>
+ <cite>
+ The developers mailing list is jdo-dev@db.apache.org, a
+ high-volume list currently receiving from 100 to 300 messages
+ a month.
+ <br />
+ The users mailing list is jdo-user@db.apache.org.
+ </cite>
+ </p>
+
+<p>
+ <b>Does this project use a wiki?</b>
+ <cite>
+ It does - the
+ <a class="externalLink" href="http://wiki.apache.org/jdo">JDO wiki</a>
+ complements the work taking place on the mailing list and provides
+ additional information on the project.
+ </cite>
+</p>
+</div>
+
+
</div>
</div>
Modified: websites/production/db/content/jdo/fetchgroups.html
==============================================================================
--- websites/production/db/content/jdo/fetchgroups.html (original)
+++ websites/production/db/content/jdo/fetchgroups.html Sat Feb 23 14:12:18 2013
@@ -1,5 +1,5 @@
<!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 20, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Feb 23, 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" />
@@ -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="20130120" />
+ <meta name="Date-Revision-yyyymmdd" content="20130223" />
<meta http-equiv="Content-Language" content="en" />
</head>
@@ -209,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>