diff --git a/documentation/src/main/asciidoc/introduction/Advanced.adoc b/documentation/src/main/asciidoc/introduction/Advanced.adoc index 8bc5921f026c..a4f59b0cb8d0 100644 --- a/documentation/src/main/asciidoc/introduction/Advanced.adoc +++ b/documentation/src/main/asciidoc/introduction/Advanced.adoc @@ -1144,10 +1144,17 @@ A fetch profile must be explicitly enabled for a given session by calling link:{ [source,java] ---- -session.enableFetchProfile(Book_.PROFILE_EAGER_BOOK); +session.enableFetchProfile(Book_._EagerBook); Book eagerBook = session.find(Book.class, bookId); ---- +Alternatively, a profile may be passed as a `FindOption`: + +[source,java] +---- +Book eagerBook = session.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/Session.java b/hibernate-core/src/main/java/org/hibernate/Session.java index d48ca8d3094e..8a7402b3d890 100644 --- a/hibernate-core/src/main/java/org/hibernate/Session.java +++ b/hibernate-core/src/main/java/org/hibernate/Session.java @@ -1275,7 +1275,7 @@ public interface Session extends SharedSessionContract, EntityManager { boolean isFetchProfileEnabled(String name) throws UnknownProfileException; /** - * Enable the {@link org.hibernate.annotations.FetchProfile fetch profile} + * Enable the {@linkplain org.hibernate.annotations.FetchProfile fetch profile} * with the given name in this session. If the requested fetch profile is * already enabled, the call has no effect. * @@ -1288,6 +1288,26 @@ public interface Session extends SharedSessionContract, EntityManager { */ void enableFetchProfile(String name) throws UnknownProfileException; + /** + * Enable the {@linkplain org.hibernate.annotations.FetchProfile fetch profile} + * represented by the given instance of {@link EnabledFetchProfile}. If + * the requested fetch profile is already enabled, the call has no effect. + *

+ * An instance of {@link EnabledFetchProfile} may be obtained in a typesafe + * way from the static metamodel. + * + * @param fetchProfile the {@link EnabledFetchProfile} + * + * @throws UnknownProfileException Indicates that the given object has + * a profile name which does not match + * any known fetch profile names + * + * @see org.hibernate.annotations.FetchProfile + * + * @since 7 + */ + void enableFetchProfile(EnabledFetchProfile fetchProfile) throws UnknownProfileException; + /** * Disable the {@link org.hibernate.annotations.FetchProfile fetch profile} * with the given name in this session. If the requested fetch profile is diff --git a/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionDelegatorBaseImpl.java b/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionDelegatorBaseImpl.java index 5b73af08a162..121fd85ff51b 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionDelegatorBaseImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionDelegatorBaseImpl.java @@ -22,6 +22,7 @@ import jakarta.persistence.metamodel.Metamodel; import org.checkerframework.checker.nullness.qual.Nullable; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.Filter; import org.hibernate.FlushMode; import org.hibernate.HibernateException; @@ -1102,6 +1103,11 @@ public void enableFetchProfile(String name) throws UnknownProfileException { delegate.enableFetchProfile( name ); } + @Override + public void enableFetchProfile(EnabledFetchProfile fetchProfile) { + delegate.enableFetchProfile( fetchProfile ); + } + @Override public void disableFetchProfile(String name) throws UnknownProfileException { delegate.disableFetchProfile( name ); diff --git a/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionLazyDelegator.java b/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionLazyDelegator.java index 9223479b476a..719020f5bd7b 100644 --- a/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionLazyDelegator.java +++ b/hibernate-core/src/main/java/org/hibernate/engine/spi/SessionLazyDelegator.java @@ -25,6 +25,7 @@ import jakarta.persistence.metamodel.Metamodel; import org.checkerframework.checker.nullness.qual.Nullable; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.Filter; import org.hibernate.FlushMode; import org.hibernate.HibernateException; @@ -416,6 +417,11 @@ public void enableFetchProfile(String name) throws UnknownProfileException { this.lazySession.get().enableFetchProfile( name ); } + @Override + public void enableFetchProfile(EnabledFetchProfile fetchProfile) { + this.lazySession.get().enableFetchProfile( fetchProfile ); + } + @Override public void disableFetchProfile(String name) throws UnknownProfileException { this.lazySession.get().disableFetchProfile( name ); diff --git a/hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java b/hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java index 9f54ecb571d1..28a5c43daf3d 100644 --- a/hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/internal/SessionImpl.java @@ -1979,6 +1979,11 @@ public void enableFetchProfile(String name) throws UnknownProfileException { loadQueryInfluencers.enableFetchProfile( name ); } + @Override + public void enableFetchProfile(EnabledFetchProfile fetchProfile) { + enableFetchProfile( fetchProfile.profileName() ); + } + @Override public void disableFetchProfile(String name) throws UnknownProfileException { loadQueryInfluencers.disableFetchProfile( name ); diff --git a/hibernate-core/src/main/java/org/hibernate/query/Query.java b/hibernate-core/src/main/java/org/hibernate/query/Query.java index 97e43e224d98..182127797ce3 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/Query.java +++ b/hibernate-core/src/main/java/org/hibernate/query/Query.java @@ -17,6 +17,7 @@ import jakarta.persistence.PessimisticLockScope; import jakarta.persistence.Timeout; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.Incubating; import org.hibernate.LockMode; @@ -946,6 +947,9 @@ default Query setPage(Page page) { @Override Query setEntityGraph(EntityGraph graph, GraphSemantic semantic); + @Override + Query enableFetchProfile(EnabledFetchProfile fetchProfile); + @Override Query enableFetchProfile(String profileName); diff --git a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java index 1315993df830..021084d799cd 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/query/SelectionQuery.java @@ -18,6 +18,7 @@ import jakarta.persistence.EntityGraph; import jakarta.persistence.PessimisticLockScope; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.Incubating; import org.hibernate.LockMode; @@ -286,6 +287,30 @@ default Stream stream() { */ SelectionQuery setEntityGraph(EntityGraph graph, GraphSemantic semantic); + /** + * Enable the {@linkplain org.hibernate.annotations.FetchProfile fetch + * profile} represented by the given instance of {@link EnabledFetchProfile} + * during execution of this query. If the requested fetch profile is already + * enabled, the call has no effect. + *

+ * This is an alternative way to specify the associations which + * should be fetched as part of the initial query. + *

+ * An instance of {@link EnabledFetchProfile} may be obtained in a typesafe + * way from the static metamodel. + * + * @param fetchProfile the {@link EnabledFetchProfile} + * + * @throws UnknownProfileException Indicates that the given object has + * a profile name which does not match + * any known fetch profile names + * + * @see org.hibernate.annotations.FetchProfile + * + * @since 7 + */ + SelectionQuery enableFetchProfile(EnabledFetchProfile fetchProfile); + /** * Enable the {@linkplain org.hibernate.annotations.FetchProfile fetch * profile} with the given name during execution of this query. If the diff --git a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java index e1b609b12f6a..8f7cdd6a8d53 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractQuery.java @@ -24,6 +24,7 @@ import jakarta.persistence.Timeout; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.query.QueryFlushMode; import org.hibernate.HibernateException; @@ -127,6 +128,12 @@ public QueryImplementor setEntityGraph(EntityGraph graph, GraphSem return this; } + @Override + public QueryImplementor enableFetchProfile(EnabledFetchProfile fetchProfile) { + super.enableFetchProfile( fetchProfile ); + return this; + } + @Override public QueryImplementor enableFetchProfile(String profileName) { super.enableFetchProfile( profileName ); diff --git a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java index 5db77c4985e8..9cb2a7b79b32 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/query/spi/AbstractSelectionQuery.java @@ -19,6 +19,7 @@ import jakarta.persistence.PessimisticLockScope; import jakarta.persistence.Timeout; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.ScrollableResults; import org.hibernate.engine.spi.SessionImplementor; @@ -380,6 +381,11 @@ public SelectionQuery setEntityGraph(EntityGraph graph, GraphSeman return this; } + @Override + public SelectionQuery enableFetchProfile(EnabledFetchProfile fetchProfile) { + return enableFetchProfile( fetchProfile.profileName() ); + } + @Override public SelectionQuery enableFetchProfile(String profileName) { if ( this.getSessionFactory().containsFetchProfileDefinition( profileName ) ) { diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java index 397e9d0f96be..9a0b6f9a3a48 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/internal/QuerySqmImpl.java @@ -17,6 +17,7 @@ import jakarta.persistence.metamodel.Type; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.HibernateException; import org.hibernate.LockMode; @@ -847,6 +848,12 @@ public Query setEntityGraph(EntityGraph graph, GraphSemantic seman return this; } + @Override + public Query enableFetchProfile(EnabledFetchProfile fetchProfile) { + super.enableFetchProfile( fetchProfile ); + return this; + } + @Override public Query enableFetchProfile(String profileName) { super.enableFetchProfile( profileName ); diff --git a/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java b/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java index d20e399f7e2d..4d07a964571c 100644 --- a/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java +++ b/hibernate-core/src/main/java/org/hibernate/query/sqm/spi/DelegatingSqmSelectionQueryImplementor.java @@ -14,6 +14,7 @@ import java.util.stream.Stream; import org.hibernate.CacheMode; +import org.hibernate.EnabledFetchProfile; import org.hibernate.FlushMode; import org.hibernate.Incubating; import org.hibernate.LockMode; @@ -28,6 +29,7 @@ import org.hibernate.query.QueryFlushMode; import org.hibernate.query.QueryParameter; import org.hibernate.query.ResultListTransformer; +import org.hibernate.query.SelectionQuery; import org.hibernate.query.TupleTransformer; import org.hibernate.query.spi.QueryOptions; import org.hibernate.query.sqm.SqmSelectionQuery; @@ -164,6 +166,12 @@ public SqmSelectionQueryImplementor setEntityGraph(EntityGraph gra return this; } + @Override + public SelectionQuery enableFetchProfile(EnabledFetchProfile fetchProfile) { + getDelegate().enableFetchProfile( fetchProfile ); + return this; + } + @Override public SqmSelectionQueryImplementor enableFetchProfile(String profileName) { getDelegate().enableFetchProfile( profileName );