All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.hibernate.annotations.Mutability Maven / Gradle / Ivy

The newest version!
/*
 * 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(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy