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 86faf0403e..7722297d37 100644 --- a/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java +++ b/hibernate-core/src/main/java/org/hibernate/annotations/Immutable.java @@ -32,6 +32,10 @@ import static java.lang.annotation.ElementType.*; * context does not need to keep track of its state. This may help reduce memory allocation. * * + *

+ * This annotation may also be used to mark a Java type handled by a JPA + * {@link jakarta.persistence.AttributeConverter} as immutable, circumventing the need to treat + * it as mutable. * * @author Emmanuel Bernard */ diff --git a/hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/internal/JpaAttributeConverterImpl.java b/hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/internal/JpaAttributeConverterImpl.java index 96fcfe1abe..4999a09f40 100644 --- a/hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/internal/JpaAttributeConverterImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/metamodel/model/convert/internal/JpaAttributeConverterImpl.java @@ -22,7 +22,9 @@ import org.hibernate.type.descriptor.java.spi.RegistryHelper; import org.hibernate.type.descriptor.jdbc.JdbcType; /** - * Standard implementation of JpaAttributeConverter + * Standard implementation of {@link JpaAttributeConverter}. + * + * @see AttributeConverterMutabilityPlanImpl * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/AttributeConverterMutabilityPlanImpl.java b/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/AttributeConverterMutabilityPlanImpl.java index 54bf247afd..015149a01f 100644 --- a/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/AttributeConverterMutabilityPlanImpl.java +++ b/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/AttributeConverterMutabilityPlanImpl.java @@ -7,19 +7,38 @@ package org.hibernate.type.descriptor.converter; import java.io.Serializable; +import java.lang.reflect.Type; import org.hibernate.SharedSessionContract; import org.hibernate.metamodel.model.convert.spi.JpaAttributeConverter; import org.hibernate.type.descriptor.java.MutableMutabilityPlan; +import org.hibernate.type.spi.TypeConfiguration; /** - * The standard approach for defining a MutabilityPlan for converted (AttributeConverter) - * values is to always assume that they are immutable to make sure that dirty checking, - * deep copying and second-level caching all work properly no matter what. That was work - * done under https://hibernate.atlassian.net/browse/HHH-10111 + * The default {@link org.hibernate.type.descriptor.java.MutabilityPlan} for a + * {@linkplain jakarta.persistence.AttributeConverter converted value} assumes, + * in the absence of additional evidence, that the value is mutable, so + * that dirty checking, deep copying, and second-level caching all work correctly + * in the case where it really is mutable. + *

+ * As an exception to this, Java primitive types and {@code enum}s are inferred + * to be immutable. + *

+ * To explicitly mark a converted value is immutable and avoid the extra processing + * required for a mutable value, either: + *

* - * However a series of approaches to tell Hibernate that the values are immutable were - * documented as part of https://hibernate.atlassian.net/browse/HHH-10127 + * @see HHH-10111 + * @see HHH-10127 + * + * @see org.hibernate.type.descriptor.java.spi.RegistryHelper#determineMutabilityPlan(Type, TypeConfiguration) * * @author Steve Ebersole */ diff --git a/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/package-info.java b/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/package-info.java index 9650723dfe..13d5d27c45 100644 --- a/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/type/descriptor/converter/package-info.java @@ -8,5 +8,7 @@ /** * Support for handling JPA {@link jakarta.persistence.AttributeConverter} * instances as part of the Hibernate {@link org.hibernate.type.Type} system. + * + * @see org.hibernate.type.descriptor.converter.AttributeConverterMutabilityPlanImpl */ package org.hibernate.type.descriptor.converter; diff --git a/hibernate-core/src/main/java/org/hibernate/type/descriptor/package-info.java b/hibernate-core/src/main/java/org/hibernate/type/descriptor/package-info.java index 28956dd4ad..30ad9b90b5 100644 --- a/hibernate-core/src/main/java/org/hibernate/type/descriptor/package-info.java +++ b/hibernate-core/src/main/java/org/hibernate/type/descriptor/package-info.java @@ -8,7 +8,9 @@ /** * Contracts for reading and writing values to and from JDBC. *

- * Used by implementations of - * {@link org.hibernate.type.descriptor.jdbc.JdbcType} + * Used by implementations of {@link org.hibernate.type.descriptor.jdbc.JdbcType} + * + * @see org.hibernate.type.descriptor.ValueBinder + * @see org.hibernate.type.descriptor.ValueExtractor */ package org.hibernate.type.descriptor;