org.hibernate.annotations.FetchProfile Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of beangle-hibernate-core Show documentation
Hibernate Orm Core Shade,Support Scala Collection
There is a newer version: 6.6.2.Final
Show newest version
/*
 * Hibernate, Relational Persistence for Idiomatic Java
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
 * See the lgpl.txt file in the root directory or .
 */
package org.hibernate.annotations;

import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;

import static java.lang.annotation.ElementType.PACKAGE;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

/**
 * Defines a fetch profile, by specifying its {@link #name}, together
 * with a list of {@linkplain #fetchOverrides fetch strategy overrides}.
 * 
 * A named fetch profile must be explicitly enabled in a given session
 * by calling {@link org.hibernate.Session#enableFetchProfile(String)}
 * for it to have any effect at runtime.
 * 

 * Fetch profiles compete with JPA-defined
 * {@linkplain jakarta.persistence.NamedEntityGraph named entity graphs},
 * and so programs which wish to maintain compatibility with alternative
 * implementations of JPA should prefer {@code @NamedEntityGraph}. The
 * semantics of these two facilities are not quite identical, however,
 * since a fetch profile is a list, not a graph.
 * 

 * Or, if we insist on thinking in terms of graphs:
 * 

 * for a fetch profile, the graph is implicit, determined by
 *     recursively following fetched associations from the root entity,
 *     and each {@link FetchOverride} in the fetch profile applies the
 *     same fetching strategy to the overridden association wherever it
 *     is reached recursively within the graph, whereas
 * 
an entity graph is explicit, and simply specifies that each path
 *     from the root of the graph should be fetched.
 * 
 * 
 * However, a fetch profile is not by nature rooted at any one particular
 * entity, and so {@code @FetchProfile} is not required to annotate the
 * entity classes it affects. It may even occur as a package-level
 * annotation.
 * 

 * Instead, the root entity of a fetch graph is determined by the context
 * in which the fetch profile is active. For example, if a fetch profile
 * is active when {@link org.hibernate.Session#get(Class, Object)} is
 * called, then the root entity is the entity with the given {@link Class}.
 * Given a root entity as input, an active fetch profile contributes to
 * the determination of the fetch graph.
 * 
 * A JPA {@link jakarta.persistence.EntityGraph} may be constructed in
 * Java code at runtime. But this amounts to separate, albeit extremely
 * limited, query facility that competes with JPA's own {@linkplain
 * jakarta.persistence.criteria.CriteriaBuilder criteria queries}.
 * There's no such capability for fetch profiles.
 *
 * @see org.hibernate.Session#enableFetchProfile(String)
 * @see org.hibernate.SessionFactory#containsFetchProfileDefinition(String)
 *
 * @author Hardy Ferentschik
 */
@Target({TYPE, PACKAGE})
@Retention(RUNTIME)
@Repeatable(FetchProfiles.class)
public @interface FetchProfile {
	/**
	 * The name of the fetch profile.
	 */
	String name();

	/**
	 * The list of association fetching strategy overrides.
	 */
	FetchOverride[] fetchOverrides();

	/**
	 * Overrides the fetching strategy pf a particular association
	 * in the named fetch profile being defined.
	 */
	@Target({ TYPE, PACKAGE })
	@Retention(RUNTIME)
	@interface FetchOverride {
		/**
		 * The entity containing the association whose default fetch
		 * strategy is being overridden.
		 */
		Class entity();

		/**
		 * The association whose default fetch strategy is being
		 * overridden.
		 */
		String association();

		/**
		 * The {@linkplain FetchMode fetching strategy} to apply to
		 * the association in the fetch profile being defined.
		 */
		FetchMode mode();
	}
}