HHH-4812 documentation

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18926 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Hardy Ferentschik 2010-03-05 15:23:34 +00:00
parent 153ad753e1
commit 9329e59e86
2 changed files with 71 additions and 8 deletions

View File

@ -3207,7 +3207,7 @@ public class SpaceShip {</programlisting>
@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 @@ public class Child {
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 interface Cuisine {
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&lt;Order&gt; 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>

View File

@ -51,7 +51,7 @@
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.hibernate&lt;/groupId&gt;
&lt;artifactId&gt;hibernate-annotations&lt;/artifactId&gt;
&lt;artifactId&gt;hibernate-core&lt;/artifactId&gt;
&lt;version&gt;${hibernate-core-version}&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
@ -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>&lt;project ...&gt;
<filename>pom.xml</filename>.<programlisting>&lt;project&gt;
...
&lt;dependencies&gt;
&lt;dependency&gt;
@ -105,7 +105,9 @@
&lt;artifactId&gt;hibernate-validator&lt;/artifactId&gt;
&lt;version&gt;${hibernate-validator-version}&lt;/version&gt;
&lt;/dependency&gt;
...
&lt;/dependencies&gt;
...
&lt;/project&gt;</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>&lt;project ...&gt;
<filename>pom.xml</filename>.<programlisting>&lt;project&gt;
...
&lt;dependencies&gt;
&lt;dependency&gt;
@ -122,7 +124,9 @@
&lt;artifactId&gt;hibernate-search&lt;/artifactId&gt;
&lt;version&gt;${hibernate-search-version}&lt;/version&gt;
&lt;/dependency&gt;
...
&lt;/dependencies&gt;
...
&lt;/project&gt;</programlisting></para>
<para>We recommend you use the JPA 2 APIs to bootstrap Hibernate (see the
@ -198,7 +202,7 @@ private static final SessionFactory sessionFactory;
.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