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 © 2005-2013. + Copyright © 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 © 2005-2013. + Copyright © 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-...@db.apache.org, a - high-volume list currently receiving from 100 to 300 messages - a month. - <br /> - The users mailing list is jdo-u...@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-...@db.apache.org, a + high-volume list currently receiving from 100 to 300 messages + a month. + <br /> + The users mailing list is jdo-u...@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 © 2005-2013. + Copyright © 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 "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> @@ -476,7 +476,7 @@ public class Directory </div> <div id="footer"> <div class="xright"> - Copyright © 2005-2013. + Copyright © 2005-2014. All Rights Reserved. </div>
