org.hibernate.annotations.Mutability Maven / Gradle / Ivy
Show all versions of beangle-hibernate-core Show documentation
/*
* 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.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
import org.hibernate.type.descriptor.java.MutabilityPlan;
import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.RUNTIME;
/**
* Specifies a {@link MutabilityPlan} for a basic value mapping.
*
* Mutability refers to whether the internal state of a value can change.
* For example, {@linkplain java.util.Date Date} is considered mutable because its
* internal state can be changed using {@link java.util.Date#setTime} whereas
* {@linkplain java.lang.String String} is considered immutable because its internal
* state cannot be changed. Hibernate uses this distinction when it can for internal
* optimizations.
*
* Hibernate understands the inherent mutability of a large number of Java types -
* {@linkplain java.util.Date Date}, {@linkplain java.lang.String String}, etc.
* {@linkplain Mutability} and friends allow plugging in specific strategies.
*
*
*
* Mutability for basic-typed attributes
*
* For basic-valued attributes, {@code @Mutability} specifies the mutability
* of the basic value type.
*
* This is not the same as saying that the attribute itself is mutable
* or immutable. A mutable attribute may have a type whose values are immutable.
*
*
Mutability for values belonging to collections
*
* Even collection elements, indexes, keys, and values have mutability
* plans, and so this annotation may be applied to a collection-valued
* attribute:
*
* -
* When applied to a {@code Map}-valued attribute, it describes
* the values of the map.
* Use {@link MapKeyMutability} to describe the keys of the map.
*
* -
* When mapping an id-bag, it describes the elements of the bag.
* Use {@link CollectionIdMutability} to describe the
* {@link CollectionId}.
*
* -
* For {@code List}-valued attributes, or for any other collection
* mapping, it describes the elements of the collection.
*
* -
* When applied to an array-valued attribute, it describes the
* array element.
*
*
*
* Again, this is not the same as saying that the collection itself is
* mutable or immutable. One may add or remove immutable values to or
* from a mutable collection.
*
*
Discriminated association mappings
*
* For discriminated association mappings ({@link Any} or {@link ManyToAny}),
* this annotation describes the mutability of the discriminator value.
*
* This is not likely to be useful.
*
*
Mutability for converters
*
* {@code @Mutability} may also be used to specify the mutability of a
* Java type handled by a JPA {@link jakarta.persistence.AttributeConverter},
* circumventing the need to treat it as mutable.
*
* Either:
*
* - annotate the Java type itself, or
*
- annotate the {@code AttributeConverter} class.
*
*
* @apiNote Except for the case of converters, this annotation is not
* usually applied to a {@linkplain ElementType#TYPE type}.
*
* @see Immutable
* @see MutabilityPlan
* @see Basic value type mappings
* @see org.hibernate.type
*
* @since 6.0
*
* @author Steve Ebersole
*/
@Target({METHOD, FIELD, ANNOTATION_TYPE, TYPE})
@Inherited
@Retention(RUNTIME)
public @interface Mutability {
/**
* A class implementing {@link MutabilityPlan}.
*/
Class> value();
}