From hibernate-commits at lists.jboss.org Wed Nov  4 17:28:47 2009
Content-Type: multipart/mixed; boundary="===============7220653749206412012=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r17915 -
 core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Wed, 04 Nov 2009 17:28:47 -0500
Message-ID: <200911042228.nA4MSlW8025517@svn01.web.mwc.hst.phx2.redhat.com>

--===============7220653749206412012==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: steve.ebersole(a)jboss.com
Date: 2009-11-04 17:28:47 -0500 (Wed, 04 Nov 2009)
New Revision: 17915

Modified:
   core/trunk/documentation/manual/src/main/docbook/en-US/content/performan=
ce.xml
Log:
HHH-4006 - Document fetch profiles


Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/pe=
rformance.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/performa=
nce.xml	2009-11-04 21:21:36 UTC (rev 17914)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/performa=
nce.xml	2009-11-04 22:28:47 UTC (rev 17915)
@@ -589,7 +589,76 @@
             <!-- TODO: Write more about this -->
 =

         </sect2>
-        =

+
+        <sect2 id=3D"performance-fetching-profiles">
+            <title>Fetch profiles</title>
+
+            <para>
+                Another way to affect the fetching strategy for loading as=
sociated objects is through something
+                called a fetch profile, which is a named configuration ass=
ociated with the
+                <interfacename>org.hibernate.SessionFactory</interfacename=
> but enabled, by name, on the
+                <interfacename>org.hibernate.Session</interfacename>.  Onc=
e enabled on a
+                <interfacename>org.hibernate.Session</interfacename>, the =
fetch profile wull be in affect for
+                that <interfacename>org.hibernate.Session</interfacename> =
until it is explicitly disabled.
+            </para>
+            <para>
+                So what does that mean?  Well lets explain that by way of =
an example.  Say we have
+                the following mappings:
+            </para>
+            <programlisting><![CDATA[<hibernate-mapping>
+    <class name=3D"Customer">
+        ...
+        <set name=3D"orders" inverse=3D"true">
+            <key column=3D"cust_id"/>
+            <one-to-many class=3D"Order"/>
+        </set>
+    </class>
+    <class name=3D"Order">
+        ...
+    </class>
+</hibernate-mapping>]]></programlisting>
+            <para>
+                Now normally when you get a reference to a particular cust=
omer, that customer's set of
+                orders will be lazy meaning we will not yet have loaded th=
ose orders from the database.
+                Normally this is a good thing.  Now lets say that you have=
 a certain use case where
+                it is more efficient to load the customer and their orders=
 together.  One way certainly is
+                to use "dynamic fetching" strategies via an HQL or criteri=
a queries.  But another option is
+                to use a fetch profile to achieve that.  Just add the foll=
owing to your mapping:
+            </para>
+            <programlisting><![CDATA[<hibernate-mapping>
+    ...
+    <fetch-profile name=3D"customer-with-orders">
+        <fetch entity=3D"Customer" association=3D"orders" style=3D"join"/>
+    </fetch-profile>
+</hibernate-mapping>]]></programlisting>
+            <para>
+                or even:
+            </para>
+            <programlisting><![CDATA[<hibernate-mapping>
+    <class name=3D"Customer">
+        ...
+        <fetch-profile name=3D"customer-with-orders">
+            <fetch association=3D"orders" style=3D"join"/>
+        </fetch-profile>
+    </class>
+    ...
+</hibernate-mapping>]]></programlisting>
+            <para>
+                Now the following code will actually load both the custome=
r <emphasis>and their orders</emphasis>:
+            </para>
+            <programlisting><![CDATA[
+    Session session =3D ...;
+    session.enableFetchProfile( "customer-with-orders" );  // name matches=
 from mapping
+    Customer customer =3D (Customer) session.get( Customer.class, customer=
Id );
+
+]]></programlisting>
+            <para>
+                Currently only join style fetch profiles are supported, bu=
t they plan is to support additional
+                styles.  See <ulink url=3D"http://opensource.atlassian.com=
/projects/hibernate/browse/HHH-3414">HHH-3414</ulink>
+                for details.
+            </para>
+        </sect2>
+
         <sect2 id=3D"performance-fetching-lazyproperties">
             <title>Using lazy property fetching</title>
 =

@@ -653,7 +722,6 @@
             </para>
 =

         </sect2>
-
     </sect1>
 =

     <sect1 id=3D"performance-cache" revision=3D"1">


--===============7220653749206412012==--