From 9329e59e8679746dcdc74a213c8b359237f70ca6 Mon Sep 17 00:00:00 2001 From: Hardy Ferentschik Date: Fri, 5 Mar 2010 15:23:34 +0000 Subject: [PATCH] HHH-4812 documentation git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18926 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- .../src/main/docbook/en/modules/entity.xml | 63 ++++++++++++++++++- .../src/main/docbook/en/modules/setup.xml | 16 +++-- 2 files changed, 71 insertions(+), 8 deletions(-) diff --git a/annotations/src/main/docbook/en/modules/entity.xml b/annotations/src/main/docbook/en/modules/entity.xml index 8435fd9d22..8df8983a75 100644 --- a/annotations/src/main/docbook/en/modules/entity.xml +++ b/annotations/src/main/docbook/en/modules/entity.xml @@ -3207,7 +3207,7 @@ public class SpaceShip { @Where(clause="1=1") @org.hibernate.annotations.Table(name="Forest", indexes = { @Index(name="idx", columnNames = { "name", "length" } ) } ) @Persister(impl=MyEntityPersister.class) -public class Forest { ... }@Entity +public class Forest { ... } @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
- Lazy options and fetching modes + Lazy options and + fetching modes JPA comes with the fetch 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); }
+ +
+ Fetch profiles + + In we have + seen how to affect the fetching strategy for associated objects using + the @Fetch annotation. An alternative approach is + a so called fetch profile. A fetch profile is a named configuration + associated with the org.hibernate.SessionFactory + which gets enabled on the org.hibernate.Session. + Once enabled on a org.hibernate.Session, the + fetch profile will be in affect for that session until it is explicitly + disabled. Lets look at an example: + + @Entity +@FetchProfile(name = "customer-with-orders", fetchOverrides = { + @FetchProfile.FetchOverride(entity = Customer.class, association = "orders", mode = FetchMode.JOIN) +}) +public class Customer { + @Id + @GeneratedValue + private long id; + + private String name; + + private long customerNumber; + + @OneToMany + private Set<Order> orders; + + // standard getter/setter + ... +}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: + + 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 +... + + + Fetch profile definitions are global and it does not matter on + which class you place them. You can place the + @FetchProfile annotation either onto a class or + package (package-info.java). In order to define multiple fetch + profiles for the same class or package + @FetchProfiles can be used. + + + Currently only join style fetch profiles are supported, but they + plan is to support additional styles. See HHH-3414 + for details. Refer also to the discussion about fetch profiles in the + Hibernate Core documentation. +
diff --git a/annotations/src/main/docbook/en/modules/setup.xml b/annotations/src/main/docbook/en/modules/setup.xml index 6d54edd7b5..00b6f7dec6 100644 --- a/annotations/src/main/docbook/en/modules/setup.xml +++ b/annotations/src/main/docbook/en/modules/setup.xml @@ -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 @@ First, set up your classpath (after you have created a new project in your favorite IDE): - Copy hibernate-core.jar and required 3rd - party library files. + Copy all Hibernate3 core and required 3rd party library + files. @@ -97,7 +97,7 @@ hibernate-validator.jar and validation-api.jar in your classpath. Alternatively add the following dependency in your - pom.xml.<project ...> + pom.xml.<project> ... <dependencies> <dependency> @@ -105,7 +105,9 @@ <artifactId>hibernate-validator</artifactId> <version>${hibernate-validator-version}</version> </dependency> + ... </dependencies> + ... </project> If you wish to use hibernate-search.jar and lucene-core-x.y.z.jar in your classpath. Alternatively add the following dependency in your - pom.xml.<project ...> + pom.xml.<project> ... <dependencies> <dependency> @@ -122,7 +124,9 @@ <artifactId>hibernate-search</artifactId> <version>${hibernate-search-version}</version> </dependency> + ... </dependencies> + ... </project> 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) .addResource("test/animals/orm.xml") .configure() - .buildSessionFactory(); + .buildSessionFactory(); There is no other difference in the way you use Hibernate APIs with annotations, except for this startup routine change or in the