Package org.hibernate.annotations

Annotation Interface Immutable

@Target({TYPE,METHOD,FIELD}) @Retention(RUNTIME) public @interface Immutable
Marks an entity, collection, or attribute of an entity as immutable. The absence of this annotation means the element is mutable.

Immutable entities

Changes made in memory to the state of an immutable entity are never synchronized to the database. The changes are ignored, with no exception thrown.

An immutable entity need not be dirty-checked, and so Hibernate does not need to maintain a snapshot of its state. This may help reduce memory allocation. Note that it's also possible to obtain an entity in read-only mode in a given session, and this has similar benefits.

In a mapped inheritance hierarchy, @Immutable may be applied only to the root entity, and is inherited by entity subclasses. To make just one entity in the hierarchy immutable, annotate its attributes individually.

Immutable basic-valued attributes

A mutable entity may have an immutable field or property.

An immutable attribute is ignored by the dirty-checking process, and so the persistence context does not need to keep track of its state. This may help reduce memory allocation.

Immutable collections

An immutable collection may not be modified.

A HibernateException is thrown if an element is added to or removed from the collection.

Immutable for converters

@Immutable may also be used to mark a Java type handled by a JPA AttributeConverter as immutable, circumventing the need to treat it as mutable.

Either:

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

This is not the same as marking the attribute @Immutable. A mutable attribute may have a type whose values are immutable.

See Also: