org.hibernate.annotations.Immutable 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.Target;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import static java.lang.annotation.ElementType.*;
/**
* 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, {@code @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 {@link org.hibernate.HibernateException} is thrown if an element is added to or
* removed from the collection.
*
*
Immutable for converters
*
* {@code @Immutable} 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.
*
* Either:
*
* - annotate the Java type itself, or
*
- annotate the {@code AttributeConverter} class.
*
*
* This is not the same as marking the attribute {@code @Immutable}. A mutable attribute may
* have a type whose values are immutable.
*
* @author Emmanuel Bernard
*
* @see org.hibernate.Session#setDefaultReadOnly(boolean)
* @see org.hibernate.Session#setReadOnly(Object, boolean)
* @see org.hibernate.query.Query#setReadOnly(boolean)
*/
@Target({TYPE, METHOD, FIELD})
@Retention( RetentionPolicy.RUNTIME )
public @interface Immutable {
}