diff --git a/hibernate-core/src/main/java/org/hibernate/FetchMode.java b/hibernate-core/src/main/java/org/hibernate/FetchMode.java index 3a11160092..5f3606d7c7 100644 --- a/hibernate-core/src/main/java/org/hibernate/FetchMode.java +++ b/hibernate-core/src/main/java/org/hibernate/FetchMode.java @@ -7,13 +7,7 @@ package org.hibernate; /** - * Represents an association fetching strategy. This is used - * together with the {@code Criteria} API to specify runtime - * fetching strategies. - *

- * For HQL queries, use the {@code FETCH} keyword instead. - * - * @see Criteria#setFetchMode(String, FetchMode) + * Represents an association fetching strategy. * * @author Gavin King */ diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java b/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java index c4cfac9bd4..8f917eb0b5 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Fetch.java @@ -12,15 +12,17 @@ import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; /** - * Define the fetching strategy used for the given association. + * Specify the fetching strategy used for the annotated association. * * @author Emmanuel Bernard + * + * @see FetchMode */ @Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface Fetch { /** - * The style of fetch to use. + * The method that should be used to fetch the association. */ FetchMode value(); } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java b/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java index 46014d4bbd..99afb9a367 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FetchMode.java @@ -7,22 +7,27 @@ package org.hibernate.annotations; /** - * Fetch options on associations. Defines more of the "how" of fetching, whereas JPA {@link jakarta.persistence.FetchType} - * focuses on the "when". + * Enumerates the association fetching strategies available in Hibernate. + *

+ * Whereas the JPA {@link jakarta.persistence.FetchType} enumeration provides a way to + * specify when an association should be fetched, this enumeration provides a + * way to express how it should be fetched. * * @author Emmanuel Bernard */ public enum FetchMode { /** - * Use a secondary select for each individual entity, collection, or join load. + * The association or collection is fetched with a separate subsequent SQL select. */ SELECT, /** - * Use an outer join to load the related entities, collections or joins. + * The association or collection is fetched using an outer join clause added to + * the initial SQL select. */ JOIN, /** - * Available for collections only.  When accessing a non-initialized collection, this fetch mode will trigger loading all elements of all collections of the same role for all owners associated with the persistence context using a single secondary select. + * For collections and many-valued associations only. After the initial SQL select, + * all associated collections are fetched together in a single subsequent select. */ SUBSELECT } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java b/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java index a26c6a477c..95b924934d 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/FlushModeType.java @@ -7,9 +7,15 @@ package org.hibernate.annotations; /** - * Enumeration extending jakarta.persistence flush modes. + * Enumeration extending {@link jakarta.persistence.FlushModeType JPA flush modes} with + * flush modes specific to Hibernate, and a "null" flush mode, {@link #PERSISTENCE_CONTEXT} + * for use as a default annotation value. Except for the null value, this enumeration is + * isomorphic to {@link org.hibernate.FlushMode}. * * @author Carlos Gonzalez-Cadenas + * + * @see NamedQuery + * @see NamedNativeQuery */ public enum FlushModeType { /** diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java b/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java index 078fc5afb6..1c40084012 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java @@ -5,28 +5,35 @@ * See the lgpl.txt file in the root directory or . */ package org.hibernate.annotations; -import java.lang.annotation.ElementType; + +import java.lang.annotation.Target; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; +import static java.lang.annotation.ElementType.*; + /** - * Mark an Entity, a Collection, or an Attribute type as immutable. No annotation means the element is mutable. - *

- * An immutable entity may not be updated by the application. Updates to an immutable - * entity will be ignored, but no exception is thrown. @Immutable must be used on root entities only. - *

- *

- * @Immutable placed on a collection makes the collection immutable, meaning additions and - * deletions to and from the collection are not allowed. A HibernateException is thrown in this case. - *

- *

- * An immutable attribute type will not be copied in the currently running Persistence Context in order to detect if the underlying value is dirty. As a result loading the entity will require less memory - * and checking changes will be much faster. - *

+ * Marks an entity, collection, or attribute as immutable. The absence of this annotation + * means the element is mutable. + * * * @author Emmanuel Bernard */ -@java.lang.annotation.Target({ElementType.TYPE, ElementType.METHOD, ElementType.FIELD}) +@Target({TYPE, METHOD, FIELD}) @Retention( RetentionPolicy.RUNTIME ) public @interface Immutable { } diff --git a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java index 95b5b835f8..dbb2042022 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/NamedQuery.java @@ -21,7 +21,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME; * * @see org.hibernate.query.Query */ -@Target( { TYPE, PACKAGE }) +@Target({TYPE, PACKAGE}) @Retention(RUNTIME) @Repeatable(NamedQueries.class) public @interface NamedQuery {