[hibernate-commits] Hibernate SVN: r18926 - core/trunk/annotations/src/main/docbook/en/modules.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Fri Mar 5 10:23:34 EST 2010
Author: hardy.ferentschik
Date: 2010-03-05 10:23:34 -0500 (Fri, 05 Mar 2010)
New Revision: 18926
Modified:
core/trunk/annotations/src/main/docbook/en/modules/entity.xml
core/trunk/annotations/src/main/docbook/en/modules/setup.xml
Log:
HHH-4812 documentation
Modified: core/trunk/annotations/src/main/docbook/en/modules/entity.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-03-05 00:56:10 UTC (rev 18925)
+++ core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-03-05 15:23:34 UTC (rev 18926)
@@ -3207,7 +3207,7 @@
@Where(clause="1=1")
@org.hibernate.annotations.Table(name="Forest", indexes = { @Index(name="idx", columnNames = { "name", "length" } ) } )
@Persister(impl=MyEntityPersister.class)
-public class Forest { ... }</programlisting><programlisting>@Entity
+public class Forest { ... }</programlisting> <programlisting>@Entity
@Inheritance(
strategy=InheritanceType.JOINED
)
@@ -3614,7 +3614,8 @@
alter table Child add constraint FK_PARENT foreign key (parent_id) references Parent</programlisting>
<section id="entity-hibspec-singleassoc-fetching">
- <title>Lazy options and fetching modes</title>
+ <title id="section-lazy-options-fetching-modes">Lazy options and
+ fetching modes</title>
<para>JPA comes with the <literal>fetch</literal> option to define
lazy loading and fetching modes, however Hibernate has a much more
@@ -4301,5 +4302,63 @@
public void setCountry(Country country);
}</programlisting>
</section>
+
+ <section>
+ <title>Fetch profiles</title>
+
+ <para>In <xref linkend="section-lazy-options-fetching-modes" /> we have
+ seen how to affect the fetching strategy for associated objects using
+ the <classname>@Fetch</classname> annotation. An alternative approach is
+ a so called fetch profile. A fetch profile is a named configuration
+ associated with the <classname>org.hibernate.SessionFactory</classname>
+ which gets enabled on the <classname>org.hibernate.Session.</classname>
+ Once enabled on a <classname>org.hibernate.Session</classname>, the
+ fetch profile will be in affect for that session until it is explicitly
+ disabled. Lets look at an example:</para>
+
+ <para><programlisting>@Entity
+<emphasis role="bold">@FetchProfile(name = "customer-with-orders", fetchOverrides = {
+ @FetchProfile.FetchOverride(entity = Customer.class, association = "orders", mode = FetchMode.JOIN)
+})</emphasis>
+public class Customer {
+ @Id
+ @GeneratedValue
+ private long id;
+
+ private String name;
+
+ private long customerNumber;
+
+ @OneToMany
+ private Set<Order> orders;
+
+ // standard getter/setter
+ ...
+}</programlisting>In the normal case the orders association would be lazy
+ loaded by Hibernate, but in a usecase where it is more efficient to load
+ the customer and their orders together you could do something like
+ this:</para>
+
+ <programlisting>Session session = ...;
+session.enableFetchProfile( "customer-with-orders" ); // name matches @FetchProfile name
+Customer customer = (Customer) session.get( Customer.class, customerId );
+session.disableFetchProfile( "customer-with-orders" ); // or just close the session
+...</programlisting>
+
+ <note>
+ <para>Fetch profile definitions are global and it does not matter on
+ which class you place them. You can place the
+ <classname>@FetchProfile</classname> annotation either onto a class or
+ package (package-info.java). In order to define multiple fetch
+ profiles for the same class or package
+ <classname>@FetchProfiles</classname> can be used.</para>
+ </note>
+
+ <para>Currently only join style fetch profiles are supported, but they
+ plan is to support additional styles. See <ulink
+ url="http://opensource.atlassian.com/projects/hibernate/browse/HHH-3414">HHH-3414</ulink>
+ for details. Refer also to the discussion about fetch profiles in the
+ Hibernate Core documentation.</para>
+ </section>
</section>
</chapter>
Modified: core/trunk/annotations/src/main/docbook/en/modules/setup.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-05 00:56:10 UTC (rev 18925)
+++ core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-05 15:23:34 UTC (rev 18926)
@@ -51,7 +51,7 @@
<dependencies>
<dependency>
<groupId>org.hibernate</groupId>
- <artifactId>hibernate-annotations</artifactId>
+ <artifactId>hibernate-core</artifactId>
<version>${hibernate-core-version}</version>
</dependency>
</dependencies>
@@ -66,8 +66,8 @@
<para>First, set up your classpath (after you have created a new project
in your favorite IDE): <itemizedlist>
<listitem>
- <para>Copy <filename>hibernate-core.jar</filename> and required 3rd
- party library files.</para>
+ <para>Copy all Hibernate3 core and required 3rd party library
+ files.</para>
</listitem>
<listitem>
@@ -97,7 +97,7 @@
<filename>hibernate-validator.jar</filename> and
<filename>validation-api.jar</filename> in your classpath. Alternatively
add the following dependency in your
- <filename>pom.xml</filename>.<programlisting><project ...>
+ <filename>pom.xml</filename>.<programlisting><project>
...
<dependencies>
<dependency>
@@ -105,7 +105,9 @@
<artifactId>hibernate-validator</artifactId>
<version>${hibernate-validator-version}</version>
</dependency>
+ ...
</dependencies>
+ ...
</project></programlisting></para>
<para>If you wish to use <ulink
@@ -114,7 +116,7 @@
<filename>hibernate-search.jar</filename> and
<filename>lucene-core-x.y.z.jar</filename> in your classpath.
Alternatively add the following dependency in your
- <filename>pom.xml</filename>.<programlisting><project ...>
+ <filename>pom.xml</filename>.<programlisting><project>
...
<dependencies>
<dependency>
@@ -122,7 +124,9 @@
<artifactId>hibernate-search</artifactId>
<version>${hibernate-search-version}</version>
</dependency>
+ ...
</dependencies>
+ ...
</project></programlisting></para>
<para>We recommend you use the JPA 2 APIs to bootstrap Hibernate (see the
@@ -198,7 +202,7 @@
.addAnnotatedClass(Dog.class)</emphasis>
<emphasis role="bold"> .addResource("test/animals/orm.xml")</emphasis>
.configure()
- .buildSessionFactory();</programlisting>
+ .buildSessionFactory();</programlisting>
<para>There is no other difference in the way you use Hibernate APIs with
annotations, except for this startup routine change or in the
More information about the hibernate-commits
mailing list