documented fetch=subselect

git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@6097 1b8cb986-b30d-0410-93ca-fae66ebed9b2

reference/en/modules/collection_mapping.xml

@@ -125,7 +125,7 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set
     sort="unsorted|natural|comparatorClass"
     order-by="column_name asc|desc"
     where="arbitrary sql where condition"
-    fetch="join|select"
+    fetch="join|select|subselect"
     batch-size="N"
     access="field|property|ClassName"
     optimistic-lock="true|false"
@@ -194,8 +194,9 @@ kittens = cat.getKittens(); // Okay, kittens collection is a Set
                 <callout arearefs="mappingcollection10">
                     <para>
                         <literal>fetch</literal> (optional, defaults to <literal>select</literal>) Choose
-                        between outer-join fetching and fetching by sequential select. Only one collection 
-                        may be fetched by outer join per SQL <literal>SELECT</literal>.
+                        between outer-join fetching, fetching by sequential select, and fetching by sequential
+                        subselect. Only one collection may be fetched by outer join per SQL 
+                        <literal>SELECT</literal>.
                     </para>
                 </callout>
                 <callout arearefs="mappingcollection11">

reference/en/modules/inheritance_mapping.xml

@@ -288,8 +288,9 @@
             explicitly. Also notice that properties of <literal>Payment</literal> are 
             mapped in each of the subclasses. If you want to avoid duplication, consider
             using XML entities
-            (e.g. <literal>... [ &lt;!ENTITY allproperties SYSTEM "allproperties.xml"&gt; ]&lt;</literal>
-            in the DTD declartion and <literal>&allproperties;</literal> in the mapping).
+            (e.g. <literal>[ &lt;!ENTITY allproperties SYSTEM "allproperties.xml"&gt; ]</literal>
+            in the <literal>DOCTYPE</literal> declartion and 
+            <literal>&amp;allproperties;</literal> in the mapping).
         </para>
         
         <para>

reference/en/modules/performance.xml

@@ -33,6 +33,15 @@
                     association.
                 </para>
             </listitem>
+            <listitem>
+                <para>
+                    <emphasis>Subselect fetching</emphasis> - a second <literal>SELECT</literal>
+                    is used to retrieve the associated collections for all entities retrieved in a
+                    previous query or fetch. Unless you explicitly disable lazy fetching by specifying 
+                    <literal>lazy="false"</literal>, this second select will only be executed when you 
+                    actually access the association.
+                </para>
+            </listitem>
             <listitem>
                 <para>
                     <emphasis>Batch fetching</emphasis> - an optimization strategy
@@ -44,10 +53,15 @@
         </itemizedlist>
 
         <para>
-            By default, Hibernate3 always uses lazy select fetching, which is the best
-            default for most entities and collections in most applications. However,
-            there is one problem to be aware of. Access to a lazy association outside 
-            of the context of an open Hibernate session will result in an exception.
+            By default, Hibernate3 uses lazy select fetching, which is the best choice for most entities 
+            and collections in most applications. If you set 
+            <literal>hibernate.default_batch_fetch_size</literal>, Hibernate will use the batch fetch 
+            optimization to lazy fetching (this optimization may also be enabled at a more granular level).
+        </para>
+        
+        <para>
+            However, there is one problem to be aware of. Access to a lazy association 
+            outside of the context of an open Hibernate session will result in an exception.
             For example:
         </para>
 
@@ -129,8 +143,8 @@ Integer accessLevel = (Integer) permissions.get("accounts");  // Error!]]></prog
         </itemizedlist>
         
         	<para>
-        		<emphasis>The fetch strategy specified in the mapping document does not affect
-        		HQL queries.</emphasis>
+        		<emphasis>Specifying <literal>join</literal> as the fetch strategy in the mapping 
+        		document does not affect HQL queries.</emphasis>
         	</para>
 
             <para>
@@ -167,6 +181,12 @@ Integer accessLevel = (Integer) permissions.get("accounts");  // Error!]]></prog
                 queries.
             </para>
             
+            <para>
+                If you run into this limitation, you should use subselect or batch fetching to
+                achieve acceptable performance. This is common when retrieving a tree of
+                collection-valued associations.
+            </para>
+            
             <para>
                 There are no restrictions to join fetching of single-ended associations.
             </para>