db-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From an...@apache.org
Subject svn commit: r892842 [4/15] - in /websites/production/db/content/jdo: ./ guides/ releases/
Date Sun, 05 Jan 2014 10:08:46 GMT
Modified: websites/production/db/content/jdo/exceptions.html
==============================================================================
--- websites/production/db/content/jdo/exceptions.html (original)
+++ websites/production/db/content/jdo/exceptions.html Sun Jan  5 10:08:45 2014
@@ -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 Nov 4, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 5, 2014 -->
 <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="20131104" />
+    <meta name="Date-Revision-yyyymmdd" content="20140105" />
     <meta http-equiv="Content-Language" content="en" />
         
         </head>
@@ -101,7 +101,7 @@
                   <li class="none">
                           <a href="field_types.html" title="Types of Fields">Types of Fields</a>
             </li>
-                                                                                                                          <li class="collapsed">
+                                                                                                                                            <li class="collapsed">
                           <a href="metadata.html" title="MetaData">MetaData</a>
                   </li>
                   <li class="none">
@@ -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>
@@ -313,7 +313,7 @@
     </div>
     <div id="footer">
       <div class="xright">
-              Copyright &#169;                   2005-2013.
+              Copyright &#169;                   2005-2014.
           All Rights Reserved.      
                     
                   </div>

Modified: websites/production/db/content/jdo/extents.html
==============================================================================
--- websites/production/db/content/jdo/extents.html (original)
+++ websites/production/db/content/jdo/extents.html Sun Jan  5 10:08:45 2014
@@ -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 Nov 4, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 5, 2014 -->
 <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="20131104" />
+    <meta name="Date-Revision-yyyymmdd" content="20140105" />
     <meta http-equiv="Content-Language" content="en" />
         
         </head>
@@ -101,7 +101,7 @@
                   <li class="none">
                           <a href="field_types.html" title="Types of Fields">Types of Fields</a>
             </li>
-                                                                                                                          <li class="collapsed">
+                                                                                                                                            <li class="collapsed">
                           <a href="metadata.html" title="MetaData">MetaData</a>
                   </li>
                   <li class="none">
@@ -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>
@@ -238,7 +238,7 @@ Extent e = pm.getExtent(MyClass.class, t
     </div>
     <div id="footer">
       <div class="xright">
-              Copyright &#169;                   2005-2013.
+              Copyright &#169;                   2005-2014.
           All Rights Reserved.      
                     
                   </div>

Modified: websites/production/db/content/jdo/faq.html
==============================================================================
--- websites/production/db/content/jdo/faq.html (original)
+++ websites/production/db/content/jdo/faq.html Sun Jan  5 10:08:45 2014
@@ -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 Nov 4, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 5, 2014 -->
 <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="20131104" />
+    <meta name="Date-Revision-yyyymmdd" content="20140105" />
     <meta http-equiv="Content-Language" content="en" />
         
         </head>
@@ -102,7 +102,7 @@
                   <li class="none">
                           <a href="field_types.html" title="Types of Fields">Types of Fields</a>
             </li>
-                                                                                                                          <li class="collapsed">
+                                                                                                                                            <li class="collapsed">
                           <a href="metadata.html" title="MetaData">MetaData</a>
                   </li>
                   <li class="none">
@@ -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>
@@ -281,7 +281,7 @@ limitations under the License. -->
     </div>
     <div id="footer">
       <div class="xright">
-              Copyright &#169;                   2005-2013.
+              Copyright &#169;                   2005-2014.
           All Rights Reserved.      
                     
                   </div>

Modified: websites/production/db/content/jdo/fetchgroups.html
==============================================================================
--- websites/production/db/content/jdo/fetchgroups.html (original)
+++ websites/production/db/content/jdo/fetchgroups.html Sun Jan  5 10:08:45 2014
@@ -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 Nov 4, 2013 -->
+<!-- Generated by Apache Maven Doxia Site Renderer 1.3 at Jan 5, 2014 -->
 <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="20131104" />
+    <meta name="Date-Revision-yyyymmdd" content="20140105" />
     <meta http-equiv="Content-Language" content="en" />
         
         </head>
@@ -101,7 +101,7 @@
                   <li class="none">
                           <a href="field_types.html" title="Types of Fields">Types of Fields</a>
             </li>
-                                                                                                                          <li class="collapsed">
+                                                                                                                                            <li class="collapsed">
                           <a href="metadata.html" title="MetaData">MetaData</a>
                   </li>
                   <li class="none">
@@ -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 &quot;fetch groups&quot; 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>
-&lt;class name=&quot;MyClass&quot;&gt;
-    ...
-    &lt;field name=&quot;fieldX&quot; default-fetch-group=&quot;true&quot;/&gt;
-&lt;/class&gt;</pre></div>
-                <p>or using annotations</p>
-                <div class="source"><pre>
-@Persistent(defaultFetchGroup=&quot;true&quot;)
-SomeType fieldX;</pre></div>
-                <p>
-                    When a <i>PersistenceManager</i> is created it starts with a FetchPlan of the &quot;default&quot; 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 &quot;default&quot;. 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>
-&lt;package name=&quot;mydomain&quot;&gt;
-    &lt;class name=&quot;MyClass&quot;&gt;
-        &lt;field name=&quot;name&quot;&gt;
-            &lt;column length=&quot;100&quot; jdbc-type=&quot;VARCHAR&quot;/&gt;
-        &lt;/field&gt;
-        &lt;field name=&quot;coll&quot; persistence-modifier=&quot;persistent&quot;&gt;
-            &lt;collection element-type=&quot;mydomain.Address&quot;/&gt;
-            &lt;join/&gt;
-        &lt;/field&gt;
-        &lt;field name=&quot;other&quot; persistence-modifier=&quot;persistent&quot;/&gt;
-        &lt;fetch-group name=&quot;otherfield&quot;&gt;
-            &lt;field name=&quot;other&quot;/&gt;
-        &lt;/fetch-group&gt;
-    &lt;/class&gt;
-&lt;/package&gt;</pre></div>
-                <p>or using annotations</p>
-                <div class="source"><pre>
-@PersistenceCapable
-@FetchGroup(name=&quot;otherfield&quot;, members={@Persistent(name=&quot;other&quot;)})
-public class MyClass
-{
-    ...
-}</pre></div>
-                <p>
-                    So we have defined a fetch group called &quot;otherfield&quot; 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(&quot;otherfield&quot;);
-
-... (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 &quot;otherfield&quot;, 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 &quot;TestGroup&quot; for MyClass
-FetchGroup grp = myPMF.getFetchGroup(&quot;TestGroup&quot;, MyClass.class);
-grp.addMember(&quot;field1&quot;).addMember(&quot;field2&quot;);
-
-// Add this group to the fetch plan (using its name)
-fp.addGroup(&quot;TestGroup&quot;);</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 &quot;field1&quot; <i>MyClass2</i> object, and its &quot;field2&quot; <i>MyClass3</i> instance. So we 
-                    define our fetch-groups like this
-                </p>
-                <div class="source"><pre>
-&lt;class name=&quot;MyClass1&quot;&gt;
-    ...
-    &lt;fetch-group name=&quot;includingField1&quot;&gt;
-        &lt;field name=&quot;field1&quot;/&gt;
-    &lt;/fetch-group&gt;
-&lt;/class&gt;
-&lt;class name=&quot;MyClass2&quot;&gt;
-    ...
-    &lt;fetch-group name=&quot;includingField2&quot;&gt;
-        &lt;field name=&quot;field2&quot;/&gt;
-    &lt;/fetch-group&gt;
-&lt;/class&gt;</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 &quot;recursion-depth&quot;. 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>
-&lt;class name=&quot;Directory&quot;&gt;
-    &lt;field name=&quot;children&quot;&gt;
-        &lt;collection element-type=&quot;Directory&quot;/&gt;
-    &lt;/field&gt;
-
-    &lt;fetch-group name=&quot;grandchildren&quot;&gt;
-        &lt;field name=&quot;children&quot; recursion-depth=&quot;2&quot;/&gt;
-    &lt;/fetch-group&gt;
-    ...
-&lt;/class&gt;</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 &quot;fetch groups&quot; 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>
+&lt;class name=&quot;MyClass&quot;&gt;
+    ...
+    &lt;field name=&quot;fieldX&quot; default-fetch-group=&quot;true&quot;/&gt;
+&lt;/class&gt;</pre></div>
+                <p>or using annotations</p>
+                <div class="source"><pre>
+@Persistent(defaultFetchGroup=&quot;true&quot;)
+SomeType fieldX;</pre></div>
+                <p>
+                    When a <i>PersistenceManager</i> is created it starts with a FetchPlan of the &quot;default&quot; 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 &quot;default&quot;. 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>
+&lt;package name=&quot;mydomain&quot;&gt;
+    &lt;class name=&quot;MyClass&quot;&gt;
+        &lt;field name=&quot;name&quot;&gt;
+            &lt;column length=&quot;100&quot; jdbc-type=&quot;VARCHAR&quot;/&gt;
+        &lt;/field&gt;
+        &lt;field name=&quot;coll&quot; persistence-modifier=&quot;persistent&quot;&gt;
+            &lt;collection element-type=&quot;mydomain.Address&quot;/&gt;
+            &lt;join/&gt;
+        &lt;/field&gt;
+        &lt;field name=&quot;other&quot; persistence-modifier=&quot;persistent&quot;/&gt;
+        &lt;fetch-group name=&quot;otherfield&quot;&gt;
+            &lt;field name=&quot;other&quot;/&gt;
+        &lt;/fetch-group&gt;
+    &lt;/class&gt;
+&lt;/package&gt;</pre></div>
+                <p>or using annotations</p>
+                <div class="source"><pre>
+@PersistenceCapable
+@FetchGroup(name=&quot;otherfield&quot;, members={@Persistent(name=&quot;other&quot;)})
+public class MyClass
+{
+    ...
+}</pre></div>
+                <p>
+                    So we have defined a fetch group called &quot;otherfield&quot; 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(&quot;otherfield&quot;);
+
+... (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 &quot;otherfield&quot;, 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 &quot;TestGroup&quot; for MyClass
+FetchGroup grp = myPMF.getFetchGroup(&quot;TestGroup&quot;, MyClass.class);
+grp.addMember(&quot;field1&quot;).addMember(&quot;field2&quot;);
+
+// Add this group to the fetch plan (using its name)
+fp.addGroup(&quot;TestGroup&quot;);</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 &quot;field1&quot; <i>MyClass2</i> object, and its &quot;field2&quot; <i>MyClass3</i> instance. So we 
+                    define our fetch-groups like this
+                </p>
+                <div class="source"><pre>
+&lt;class name=&quot;MyClass1&quot;&gt;
+    ...
+    &lt;fetch-group name=&quot;includingField1&quot;&gt;
+        &lt;field name=&quot;field1&quot;/&gt;
+    &lt;/fetch-group&gt;
+&lt;/class&gt;
+&lt;class name=&quot;MyClass2&quot;&gt;
+    ...
+    &lt;fetch-group name=&quot;includingField2&quot;&gt;
+        &lt;field name=&quot;field2&quot;/&gt;
+    &lt;/fetch-group&gt;
+&lt;/class&gt;</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 &quot;recursion-depth&quot;. 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>
+&lt;class name=&quot;Directory&quot;&gt;
+    &lt;field name=&quot;children&quot;&gt;
+        &lt;collection element-type=&quot;Directory&quot;/&gt;
+    &lt;/field&gt;
+
+    &lt;fetch-group name=&quot;grandchildren&quot;&gt;
+        &lt;field name=&quot;children&quot; recursion-depth=&quot;2&quot;/&gt;
+    &lt;/fetch-group&gt;
+    ...
+&lt;/class&gt;</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>
@@ -476,7 +476,7 @@ public class Directory
     </div>
     <div id="footer">
       <div class="xright">
-              Copyright &#169;                   2005-2013.
+              Copyright &#169;                   2005-2014.
           All Rights Reserved.      
                     
                   </div>



Mime
View raw message