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 Annotation Description 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 Annotation Description Cache Add caching strategy to a root entity or a collection. Table 3.3. Collection Related Annotations Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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 Annotation Description 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.

Commands: