diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index 8bc5921f026c..1b70d14f8a2f 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -1140,7 +1140,7 @@ We may define as many different fetch profiles as we like. | `@FetchProfileOverride` | Specifies the fetch strategy for the annotated association, in a given fetch profile |=== -A fetch profile must be explicitly enabled for a given session by calling link:{doc-javadoc-url}org/hibernate/Session.html#enableFetchProfile(java.lang.String)[`enableFetchProfile()`]: +A fetch profile must be explicitly enabled for a given session by passing the name of the profile to link:{doc-javadoc-url}org/hibernate/Session.html#enableFetchProfile(java.lang.String)[`enableFetchProfile()`]: [source,java] ---- @@ -1148,6 +1148,13 @@ session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK); Book eagerBook = session.find(Book.class, bookId); ---- +Alternatively, an instance of link:{doc-javadoc-url}org/hibernate/EnabledFetchProfile.html[`EnabledFetchProfile`] may be obtained in a type safe way from the static metamodel, and used as a `FindOption`: + +[source,java] +---- +Book eagerBook = entityManager.find(Book.class, bookId, Book_._EagerBook); +---- + So why or when might we prefer named fetch profiles to entity graphs? Well, it's really hard to say. It's nice that this feature _exists_, and if you love it, that's great. diff --git a/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java b/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java index 8e5a780f075a..8b783d8f29a8 100644 --- a/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java +++ b/hibernate-core/src/main/java/org/hibernate/EnabledFetchProfile.java @@ -9,8 +9,41 @@ /** * A {@link jakarta.persistence.FindOption} which requests a named * {@linkplain org.hibernate.annotations.FetchProfile fetch profile}. + *
+ * An instance of this class may be obtained in a type safe way + * from the static metamodel for the class annotated + * {@link org.hibernate.annotations.FetchProfile @FetchProfile} + * and passed as an option to + * {@link Session#find(Class, Object, FindOption...) find()}. + *
+ * For example, this class defines a fetch profile: + *
+ * @Entity + * @FetchProfile(name = "WithAuthors") + * class Book { + * ... * - * @param profileName the {@link org.hibernate.annotations.FetchProfile#name()} + * @ManyToMany + * @FetchProfileOverride(profile = Book_.PROFILE_WITH_AUTHORS) + * Set<Author> authors; + * } + *+ * The fetch profile may be requested like this: + *
+ * Book bookWithAuthors = + * session.find(Book.class, isbn, Book_._WithAuthors) + *+ *
+ * When the static metamodel is not used, an {@code EnabledFetchProfile} + * may be instantiated directly, passing the name of the fetch profile + * as a string. + *
+ * Book bookWithAuthors = + * session.find(Book.class, isbn, + * new EnabledFetchProfile("WithAuthors")) + *+ * + * @param profileName the {@linkplain org.hibernate.annotations.FetchProfile#name profile name} * * @since 7.0 * diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java index 42d203a68b0d..dd4a43bb4f0e 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchProfileOverride.java @@ -54,8 +54,8 @@ FetchType fetch() default EAGER; /** - * The name of the {@link FetchProfile fetch profile} in - * which this fetch mode should be applied. + * The name of the {@linkplain FetchProfile fetch profile} + * in which this fetch mode should be applied. */ String profile(); }