Specifies a MutabilityPlan for a basic value mapping. Mutability refers to whether the internal state of a value can change. For example, Date is considered mutable because its internal state can be changed using java.util.Date#setTime whereas 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 - Date, String, etc. Mutability and friends allow plugging in specific strategies.

Mutability for basic-typed attributes

For basic-valued attributes, @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 Map-valued attribute, it describes the values of the map. Use MapKeyMutability to describe the keys of the map.
• When mapping an id-bag, it describes the elements of the bag. Use CollectionIdMutability to describe the CollectionId.
• For 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 (Any or ManyToAny), this annotation describes the mutability of the discriminator value.

This is not likely to be useful.

Mutability for converters

@Mutability may also be used to specify the mutability of a Java type handled by a JPA jakarta.persistence.AttributeConverter, circumventing the need to treat it as mutable.

Either:

• annotate the Java type itself, or
• annotate the AttributeConverter class.