Chapter 3. Hibernate Annotations

3.1. Hibernate Annotations

The org.hibernate.annotations package contains some annotations which are offered by Hibernate, on top of the standard Jakarta Persistence annotations.

Table 3.1. General Annotations

AnnotationDescription

Check

Arbitrary SQL check constraints which can be defined at the class, property or collection level.

Immutable

Mark an Entity or a Collection as immutable. No annotation means the element is mutable.

An immutable entity may not be updated by the application. Updates to an immutable entity will be ignored, but no exception is thrown.

@Immutable placed on a collection makes the collection immutable, meaning additions and deletions to and from the collection are not allowed. A HibernateException is thrown in this case.

Table 3.2. Caching Entities

AnnotationDescription

Cache

Add caching strategy to a root entity or a collection.

Table 3.3. Collection Related Annotations

AnnotationDescription

MapKeyType

Defines the type of key of a persistent map.

ManyToAny

Defines a ToMany association pointing to different entity types. Matching the entity type is done through a metadata discriminator column. This kind of mapping should be only marginal.

OrderBy

Order a collection using SQL ordering (not HQL ordering).

OnDelete

Strategy to use on collections, arrays and on joined subclasses delete. OnDelete of secondary tables is currently not supported.

Persister

Specify a custom persister.

Sort

Collection sort (Java level sorting).

Where

Where clause to add to the element Entity or target entity of a collection. The clause is written in SQL.

WhereJoinTable

Where clause to add to the collection join table. The clause is written in SQL.

Table 3.4. Custom SQL for CRUD Operations

AnnotationDescription

Loader

Overwrites Hibernate default FIND method.

SQLDelete

Overwrites the Hibernate default DELETE method.

SQLDeleteAll

Overwrites the Hibernate default DELETE ALL method.

SQLInsert

Overwrites the Hibernate default INSERT INTO method.

SQLUpdate

Overwrites the Hibernate default UPDATE method.

Subselect

Maps an immutable and read-only entity to a given SQL subselect expression.

Synchronize

Ensures that auto-flush happens correctly and that queries against the derived entity do not return stale data. Mostly used with Subselect.

Table 3.5. Entity

AnnotationDescription

Cascade

Apply a cascade strategy on an association.

Entity

Adds additional metadata that may be needed beyond what is defined in the standard @Entity.

  • mutable: whether this entity is mutable or not
  • dynamicInsert: allow dynamic SQL for inserts
  • dynamicUpdate: allow dynamic SQL for updates
  • selectBeforeUpdate: Specifies that Hibernate should never perform an SQL UPDATE unless it is certain that an object is actually modified.
  • polymorphism: whether the entity polymorphism is of PolymorphismType.IMPLICIT (default) or PolymorphismType.EXPLICIT
  • optimisticLock: optimistic locking strategy (OptimisticLockType.VERSION, OptimisticLockType.NONE, OptimisticLockType.DIRTY or OptimisticLockType.ALL)

    Note

    The annotation "Entity" is deprecated and scheduled for removal in future releases. Its individual attributes or values should become annotations.

Polymorphism

Used to define the type of polymorphism Hibernate will apply to entity hierarchies.

Proxy

Lazy and proxy configuration of a particular class.

Table

Complementary information to a table either primary or secondary.

Tables

Plural annotation of Table.

Target

Defines an explicit target, avoiding reflection and generics resolving.

Tuplizer

Defines a tuplizer for an entity or a component.

Tuplizers

Defines a set of tuplizers for an entity or a component.

Table 3.6. Fetching

AnnotationDescription

BatchSize

Batch size for SQL loading.

FetchProfile

Defines the fetching strategy profile.

FetchProfiles

Plural annotation for @FetchProfile.

LazyGroup

Specifies that an entity attribute should be fetched along with all the other attributes belonging to the same group. In order to load entity attributes lazily, bytecode enhancement is needed. By default, all non-collection attributes are loaded in one group named DEFAULT. This annotation allows defining different groups of attributes to be initialized together when accessing one attribute in the group.

Table 3.7. Filters

AnnotationDescription

Filter

Adds filters to an entity or a target entity of a collection.

FilterDef

Filter definition.

FilterDefs

Array of filter definitions.

FilterJoinTable

Adds filters to a join table collection.

FilterJoinTables

Adds multiple @FilterJoinTable to a collection.

Filters

Adds multiple @Filter.

ParamDef

A parameter definition.

Table 3.8. Primary Keys

AnnotationDescription

Generated

This annotated property is generated by the database.

GenericGenerator

Generator annotation describing any kind of Hibernate generator in a detyped manner.

GenericGenerators

Array of generic generator definitions.

NaturalId

Specifies that a property is part of the natural id of the entity.

Parameter

Key/value pattern.

RowId

Support for ROWID mapping feature of Hibernate.

Table 3.9. Inheritance

AnnotationDescription

DiscriminatorFormula

Discriminator formula to be placed at the root entity.

DiscriminatorOptions

Optional annotation to express Hibernate specific discriminator properties.

MetaValue

Maps a given discriminator value to the corresponding entity type.

Table 3.10. Mapping JP-QL/HQL Queries

AnnotationDescription

NamedNativeQueries

Extends NamedNativeQueries to hold Hibernate NamedNativeQuery objects.

NamedNativeQuery

Extends NamedNativeQuery with Hibernate features.

NamedQueries

Extends NamedQueries to hold Hibernate NamedQuery objects.

NamedQuery

Extends NamedQuery with Hibernate features.

Table 3.11. Mapping Simple Properties

AnnotationDescription

AccessType

Property access type.

Columns

Support an array of columns. Useful for component user type mappings.

ColumnTransformer

Custom SQL expression used to read the value from and write a value to a column. Use for direct object loading/saving as well as queries. The write expression must contain exactly one '?' placeholder for the value.

ColumnTransformers

Plural annotation for @ColumnTransformer. Useful when more than one column is using this behavior.

Table 3.12. Property

AnnotationDescription

Formula

To be used as a replacement for @Column in most places. The formula has to be a valid SQL fragment.

Index

Defines a database index.

JoinFormula

To be used as a replacement for @JoinColumn in most places. The formula has to be a valid SQL fragment.

Parent

Reference the property as a pointer back to the owner (generally the owning entity).

Type

Hibernate type.

TypeDef

Hibernate type definition.

TypeDefs

Hibernate type definition array.

Table 3.13. Single Association Related Annotations

AnnotationDescription

Any

Defines a ToOne association pointing to several entity types. Matching the according entity type is done through a metadata discriminator column. This kind of mapping should be only marginal.

AnyMetaDef

Defines @Any and @ManyToAny metadata.

AnyMetaDefs

Defines @Any and @ManyToAny set of metadata. Can be defined at the entity level or the package level.

Fetch

Defines the fetching strategy used for the given association.

LazyCollection

Defines the lazy status of a collection.

LazyToOne

Defines the lazy status of a ToOne association (i.e. OneToOne or ManyToOne).

NotFound

Action to do when an element is not found on an association.

Table 3.14. Optimistic Locking

AnnotationDescription

OptimisticLock

Whether or not a change of the annotated property will trigger an entity version increment. If the annotation is not present, the property is involved in the optimistic lock strategy (default).

OptimisticLocking

Used to define the style of optimistic locking to be applied to an entity. In a hierarchy, only valid on the root entity.

Source

Optional annotation in conjunction with Version and timestamp version properties. The annotation value decides where the timestamp is generated.