Hibernate ORM User Guide

A value type is a piece of data that does not define its own lifecycle. It is, in effect, owned by an entity, which defines its lifecycle.

Looked at another way, all the state of an entity is made up entirely of value types. These state fields or JavaBean properties are termed persistent attributes. The persistent attributes of the Contact class are value types.

Value types are further classified into three sub-categories:

Entities, by nature of their unique identifier, exist independently of other objects whereas values do not. Entities are domain model classes which correlate to rows in a database table, using a unique identifier. Because of the requirement for a unique identifier, entities exist independently and define their own lifecycle. The Contact class itself would be an example of an entity.

Mapping entities is discussed in detail in Entity types.

Strictly speaking, a basic type is denoted by the jakarta.persistence.Basic annotation.

Generally, the @Basic annotation can be ignored as it is assumed by default. Both of the following examples are ultimately the same.

The @Basic annotation defines 2 attributes.

Jakarta Persistence defines rules for implicitly determining the name of tables and columns. For a detailed discussion of implicit naming see Naming strategies.

For basic type attributes, the implicit naming rule is that the column name is the same as the attribute name. If that implicit naming rule does not meet your requirements, you can explicitly tell Hibernate (and other providers) the column name to use.

Here we use @Column to explicitly map the description attribute to the NOTES column, as opposed to the implicit column name description. See Naming strategies for additional details.

The @Column annotation defines other mapping information as well. See its Javadocs for details.

@Formula allows mapping any database computed value as a virtual read-only column.

When loading the Account entity, Hibernate is going to calculate the interest property using the configured @Formula:

To deal with values of basic type, Hibernate needs to understand a few things about the mapping:

This section covers how Hibernate determines these pieces and how to influence that determination process.

Looking at this example, how does Hibernate know what mapping to use for these attributes? The annotations do not really provide much information.

This is an illustration of Hibernate’s implicit basic-type resolution, which is a series of checks to determine the appropriate mapping to use. Describing the complete process for implicit resolution is beyond the scope of this documentation^[2].

This is primarily driven by the Java type defined for the basic type, which can generally be determined through reflection. Is the Java type an enum? Is it temporal? These answers can indicate certain mappings be used.

The fallback is to map the value to the "recommended" JDBC type.

Worst case, if the Java type is Serializable Hibernate will try to handle it via binary serialization.

For cases where the Java type is not a standard type or if some specialized handling is desired, Hibernate provides 2 main approaches to influence this mapping resolution:

These 2 approaches should be considered mutually exclusive. A custom UserType will always take precedence over compositional annotations.

The next few sections look at common, standard Java types and discusses various ways to map them. See Case Study : BitSet for examples of mapping BitSet as a basic type using all of these approaches.

Hibernate supports the mapping of Java enums as basic value types in a number of different ways.

By default, Boolean attributes map to BOOLEAN columns, at least when the database has a dedicated BOOLEAN type. On databases which don’t, Hibernate uses whatever else is available: BIT, TINYINT, or SMALLINT.

However, it is quite common to find boolean values encoded as a character or as an integer. Such cases are exactly the intention of AttributeConverter. For convenience, Hibernate provides 3 built-in converters for the common boolean mapping cases:

If the boolean value is defined in the database as something other than BOOLEAN, character or integer, the value can also be mapped using a custom AttributeConverter - see AttributeConverters.

A UserType may also be used - see Custom type mapping

By default, Hibernate maps values of Byte / byte to the TINYINT JDBC type.

See Byte array for mapping arrays of bytes.

By default, Hibernate maps values of Short / short to the SMALLINT JDBC type.

By default, Hibernate maps values of Integer / int to the INTEGER JDBC type.

By default, Hibernate maps values of Long / long to the BIGINT JDBC type.

By default, Hibernate maps values of BigInteger to the NUMERIC JDBC type.

By default, Hibernate maps values of Double to the DOUBLE, FLOAT, REAL or NUMERIC JDBC type depending on the capabilities of the database

A specific type can be influenced using any of the JDBC type influencers covered in JdbcType section.

If @JdbcTypeCode is used, the Dialect is still consulted to make sure the database supports the requested type. If not, an appropriate type is selected

By default, Hibernate maps values of Float to the FLOAT, REAL or NUMERIC JDBC type depending on the capabilities of the database.

A specific type can be influenced using any of the JDBC type influencers covered in Mapping basic values section.

If @JdbcTypeCode is used, the Dialect is still consulted to make sure the database supports the requested type. If not, an appropriate type is selected

By default, Hibernate maps values of BigDecimal to the NUMERIC JDBC type.

By default, Hibernate maps Character to the CHAR JDBC type.

By default, Hibernate maps String to the VARCHAR JDBC type.

Optionally, you may specify the maximum length of the string using @Column(length=…​), or using the @Size annotation from Hibernate Validator. For very large strings, you can use one of the constant values defined by the class org.hibernate.Length, for example:

Alternatively, you may explicitly specify the JDBC type LONGVARCHAR, which is treated as a VARCHAR mapping with default length=Length.LONG when no length is explicitly specified:

If you use Hibernate for schema generation, Hibernate will generate DDL with a column type that is large enough to accommodate the maximum length you’ve specified.

See Handling LOB data for details on mapping to a database CLOB.

For databases which support nationalized character sets, you can also store strings as nationalized data.

See Handling nationalized character data for details on mapping strings using nationalized character sets.

By default, Hibernate maps char[] to the VARCHAR JDBC type. Since Character[] can contain null elements, it is mapped as basic array type instead. Prior to Hibernate 6.2, also Character[] mapped to VARCHAR, yet disallowed null elements. To continue mapping Character[] to the VARCHAR JDBC type, or for LOBs mapping to the CLOB JDBC type, it is necessary to annotate the persistent attribute with @JavaType( CharacterArrayJavaType.class ).

See Handling LOB data for details on mapping as database LOB.

For databases which support nationalized character sets, you can also store character arrays as nationalized data.

See Handling nationalized character data for details on mapping strings using nationalized character sets.

By default, Hibernate will map the java.sql.Clob Java type to CLOB and java.sql.NClob to NCLOB.

Considering we have the following database table:

Let’s first map this using the @Lob Jakarta Persistence annotation and the java.sql.Clob type:

To persist such an entity, you have to create a Clob using the ClobProxy Hibernate utility:

To retrieve the Clob content, you need to transform the underlying java.io.Reader:

We could also map the CLOB in a materialized form. This way, we can either use a String or a char[].

We might even want the materialized data as a char array.

Just like with CLOB, Hibernate can also deal with NCLOB SQL data types:

Hibernate can map the NCLOB to a java.sql.NClob

To persist such an entity, you have to create an NClob using the NClobProxy Hibernate utility:

To retrieve the NClob content, you need to transform the underlying java.io.Reader:

We could also map the NCLOB in a materialized form. This way, we can either use a String or a char[].

We might even want the materialized data as a char array.

By default, Hibernate maps byte[] to the VARBINARY JDBC type. Since Byte[] can contain null elements, it is mapped as basic array type instead. Prior to Hibernate 6.2, also Byte[] mapped to VARBINARY, yet disallowed null elements. To continue mapping Byte[] to the VARBINARY JDBC type, or for LOBs mapping to the BLOB JDBC type, it is necessary to annotate the persistent attribute with @JavaType( ByteArrayJavaType.class ).

Just like with strings, you may specify the maximum length using @Column(length=…​) or the @Size annotation from Hibernate Validator. For very large arrays, you can use the constants defined by org.hibernate.Length. Alternatively @JdbcTypeCode(Types.LONGVARBINARY) is treated as a VARBINARY mapping with default length=Length.LONG when no length is explicitly specified.

If you use Hibernate for schema generation, Hibernate will generate DDL with a column type that is large enough to accommodate the maximum length you’ve specified.

See Handling LOB data for details on mapping to a database BLOB.

By default, Hibernate will map the java.sql.Blob Java type to BLOB.

Considering we have the following database table:

Let’s first map this using the JDBC java.sql.Blob type.

To persist such an entity, you have to create a Blob using the BlobProxy Hibernate utility:

To retrieve the Blob content, you need to transform the underlying java.io.InputStream:

We could also map the BLOB in a materialized form (e.g. byte[]).

By default, Hibernate maps Duration to the NUMERIC SQL type.

Instant is mapped to the TIMESTAMP_UTC SQL type.

See Handling temporal data for basics of temporal mapping

LocalDate is mapped to the DATE JDBC type.

See Handling temporal data for basics of temporal mapping

LocalDateTime is mapped to the TIMESTAMP JDBC type.

See Handling temporal data for basics of temporal mapping

LocalTime is mapped to the TIME JDBC type.

See Handling temporal data for basics of temporal mapping

OffsetDateTime is mapped to the TIMESTAMP or TIMESTAMP_WITH_TIMEZONE JDBC type depending on the database.

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

OffsetTime is mapped to the TIME or TIME_WITH_TIMEZONE JDBC type depending on the database.

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

TimeZone is mapped to VARCHAR JDBC type.

ZonedDateTime is mapped to the TIMESTAMP or TIMESTAMP_WITH_TIMEZONE JDBC type depending on the database.

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

ZoneOffset is mapped to VARCHAR JDBC type.

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

See Handling temporal data for basics of temporal mapping See Using a specific time zone for basics of time-zone handling

Hibernate maps Class references to VARCHAR JDBC type

Hibernate maps Currency references to VARCHAR JDBC type

Hibernate maps Locale references to VARCHAR JDBC type

Hibernate allows mapping UUID values in a number of ways. By default, Hibernate will store UUID values in the native form by using the SQL type UUID or in binary form with the BINARY JDBC type if the database does not have a native UUID type.

By default, Hibernate will map InetAddress to the INET SQL type and fallback to BINARY if necessary.

Hibernate will only use the JSON type if explicitly configured through @JdbcTypeCode( SqlTypes.JSON ). The JSON library used for serialization/deserialization is detected automatically, but can be overridden by setting hibernate.type.json_format_mapper as can be read in the Configurations section.

Hibernate will only use the XML type if explicitly configured through @JdbcTypeCode( SqlTypes.SQLXML ). The XML library used for serialization/deserialization is detected automatically, but can be overridden by setting hibernate.type.xml_format_mapper as can be read in the Configurations section.

Basic arrays, other than byte[]/Byte[] and char[]/Character[], map to the type code SqlTypes.ARRAY by default, which maps to the SQL standard array type if possible, as determined via the new methods getArrayTypeName and supportsStandardArrays of org.hibernate.dialect.Dialect. If SQL standard array types are not available, data will be modeled as SqlTypes.JSON, SqlTypes.XML or SqlTypes.VARBINARY, depending on the database support as determined via the new method org.hibernate.dialect.Dialect.getPreferredSqlTypeCodeForArray.

Basic collections (only subtypes of Collection), which are not annotated with @ElementCollection, map to the type code SqlTypes.ARRAY by default, which maps to the SQL standard array type if possible, as determined via the new methods getArrayTypeName and supportsStandardArrays of org.hibernate.dialect.Dialect. If SQL standard array types are not available, data will be modeled as SqlTypes.JSON, SqlTypes.XML or SqlTypes.VARBINARY, depending on the database support as determined via the new method org.hibernate.dialect.Dialect.getPreferredSqlTypeCodeForArray.

The compositional approach allows defining how the mapping should work in terms of influencing individual parts that make up a basic-value mapping. This section will look at these individual parts and the specifics of influencing each.

Another approach is to supply the implementation of the org.hibernate.usertype.UserType contract using @Type.

There are also corresponding, specialized forms of @Type for specific model parts:

@Type allows for more complex mapping concerns; but, AttributeConverter and Compositional basic mapping should generally be preferred as simpler solutions

How nationalized character data is handled and stored depends on the underlying database.

Most databases support storing nationalized character data through the standardized SQL NCHAR, NVARCHAR, LONGNVARCHAR and NCLOB variants.

Others support storing nationalized data as part of CHAR, VARCHAR, LONGVARCHAR and CLOB. Generally these databases do not support NCHAR, NVARCHAR, LONGNVARCHAR and NCLOB, even as aliased types.

Ultimately Hibernate understands this through Dialect#getNationalizationSupport()

To ensure nationalized character data gets stored and accessed correctly, @Nationalized can be used locally or hibernate.use_nationalized_character_data can be set globally.

Considering we have the following database table:

To map a specific attribute to a nationalized variant data type, Hibernate defines the @Nationalized annotation.

The @Lob annotation specifies that character or binary data should be written to the database using the special JDBC APIs for handling database LOB (Large OBject) types.

There’s two ways a LOB may be represented in the Java domain model:

Hibernate supports mapping temporal values in numerous ways, though ultimately these strategies boil down to the 3 main Date/Time types defined by the SQL specification:

The mapping of java.time temporal types to the specific SQL Date/Time types is implied as follows:

Although Hibernate recommends the use of the java.time package for representing temporal values, it does support using java.sql.Date, java.sql.Time, java.sql.Timestamp, java.util.Date and java.util.Calendar.

The mappings for java.sql.Date, java.sql.Time, java.sql.Timestamp are implicit:

When using java.util.Date or java.util.Calendar, Hibernate assumes TIMESTAMP. To alter that, use @Temporal.

Hibernate supports defining the storage to use for time zone information for individual properties via the @TimeZoneStorage and @TimeZoneColumn annotations. The storage type can be specified via the @TimeZoneStorage by specifying a org.hibernate.annotations.TimeZoneStorageType. The default storage type is AUTO which will ensure that the time zone information is retained. The @TimeZoneColumn annotation can be used in conjunction with AUTO or COLUMN and allows to define the column details for the time zone information storage.

With a custom AttributeConverter, the application developer can map a given JDBC type to an entity basic type.

In the following example, the java.time.Period is going to be mapped to a VARCHAR database column.

To make use of this custom converter, the @Convert annotation must decorate the entity attribute.

When persisting such entity, Hibernate will do the type conversion based on the AttributeConverter logic:

An AttributeConverter can be applied globally for (@Converter( autoApply=true )) or locally.

We’ve covered JavaTypeRegistry and JdbcTypeRegistry a few times now, mainly in regards to mapping resolution as discussed in Resolving the composition. But they each also serve additional important roles.

The JavaTypeRegistry is a registry of JavaType references keyed by Java type. In addition to mapping resolution, this registry is used to handle Class references exposed in various APIs such as Query parameter types. JavaType references can be registered through @JavaTypeRegistration.

The JdbcTypeRegistry is a registry of JdbcType references keyed by an integer code. As discussed in JdbcType, these type-codes typically match with the corresponding code from java.sql.Types, but that is not a requirement - integers other than those defined by java.sql.Types can be used. This might be useful for mapping JDBC User Data Types (UDTs) or other specialized database-specific types (PostgreSQL’s UUID type, e.g.). In addition to its use in mapping resolution, this registry is also used as the primary source for resolving "discovered" values in a JDBC ResultSet. JdbcType references can be registered through @JdbcTypeRegistration.

See TypeContributor for an alternative to @JavaTypeRegistration and @JdbcTypeRegistration for registration.

org.hibernate.boot.model.TypeContributor is a contract for overriding or extending parts of the Hibernate type system.

There are many ways to integrate a TypeContributor. The most common is to define the TypeContributor as a Java service (see java.util.ServiceLoader).

TypeContributor is passed a TypeContributions reference, which allows registration of custom JavaType, JdbcType and BasicType references.

We’ve covered many ways to specify basic value mappings so far. This section will look at mapping the java.util.BitSet type by applying the different techniques covered so far.

As mentioned previously, the worst-case fallback for Hibernate mapping a basic type which implements Serializable is to simply serialize it to the database. BitSet does implement Serializable, so by default Hibernate would handle this mapping by serialization.

That is not an ideal mapping. In the following sections we will look at approaches to change various aspects of how the BitSet gets mapped to the database.

You can force Hibernate to quote an identifier in the generated SQL by enclosing the table or column name in backticks in the mapping document. While traditionally, Hibernate used backticks for escaping SQL reserved keywords, Jakarta Persistence uses double quotes instead.

Once the reserved keywords are escaped, Hibernate will use the correct quotation style for the SQL Dialect. This is usually double quotes, but SQL Server uses brackets and MySQL uses backticks.

Because name and number are reserved words, the Product entity mapping uses backticks to quote these column names.

When saving the following Product entity, Hibernate generates the following SQL insert statement:

Generated attributes have their values generated as part of performing a SQL INSERT or UPDATE. Applications can generate these values in any number of ways (SQL DEFAULT value, trigger, etc). Typically, the application needs to refresh objects that contain any properties for which the database was generating values, which is a major drawback.

Applications can also delegate generation to Hibernate, in which case Hibernate will manage the value generation and (potential^[3]) state refresh itself.

Hibernate supports both in-VM and in-DB generation. A generation that uses the current JVM timestamp as the generated value is an example of an in-VM strategy. A generation that uses the database’s current_timestamp function is an example of an in-DB strategy.

Hibernate supports the following timing (when) for generation:

Hibernate supports multiple ways to mark an attribute as generated:

Hibernate allows you to customize the SQL it uses to read and write the values of columns mapped to @Basic types. For example, if your database provides a set of data encryption functions, you can invoke them for individual columns like in the following example.

If a property uses more than one column, you must use the forColumn attribute to specify which column the @ColumnTransformer read and write expressions are targeting.

Hibernate applies the custom expressions automatically whenever the property is referenced in a query. This functionality is similar to a derived-property @Formula with two differences:

The write expression, if specified, must contain exactly one '?' placeholder for the value.

Most often, embeddable types are used to group multiple basic type mappings and reuse them across several entities.

So, the embeddable type is represented by the Publisher class and the parent entity makes use of it through the book#publisher object composition.

The composed values are mapped to the same table as the parent table. Composition is part of good object-oriented data modeling (idiomatic Java). In fact, that table could also be mapped by the following entity type instead.

The composition form is certainly more object-oriented, and that becomes more evident as we work with multiple embeddable types.

Although from an object-oriented perspective, it’s much more convenient to work with embeddable types, when we reuse the same embeddable multiple times on the same class, the Jakarta Persistence specification requires to set the associated column names explicitly.

This requirement is due to how object properties are mapped to database columns. By default, Jakarta Persistence expects a database column having the same name with its associated object property. When including multiple embeddables, the implicit name-based mapping rule doesn’t work anymore because multiple object properties could end-up being mapped to the same database column.

When an embeddable type is used multiple times, Jakarta Persistence defines the @AttributeOverride and @AssociationOverride annotations to handle this scenario to override the default column names defined by the Embeddable.

Considering you have the following Publisher embeddable type which defines a @ManyToOne association with the Country entity:

Now, if you have a Book entity which declares two Publisher embeddable types for the ebook and paperback versions, you cannot use the default Publisher embeddable mapping since there will be a conflict between the two embeddable column mappings.

Therefore, the Book entity needs to override the embeddable type mappings for each Publisher attribute:

Collections of embeddable types are specifically valued collections (as embeddable types are value types). Value collections are covered in detail in Collections of value types.

Embeddable types can also be used as Map keys. This topic is converted in detail in Map - key.

Embeddable types can also be used as entity type identifiers. This usage is covered in detail in Composite identifiers.

The @Target annotation is used to specify the implementation class of a given association that is mapped via an interface. The @ManyToOne, @OneToOne, @OneToMany, and @ManyToMany feature a targetEntity attribute to specify the actual class of the entity association when an interface is used for the mapping.

The @ElementCollection association has a targetClass attribute for the same purpose.

However, for simple embeddable types, there is no such construct and so you need to use the Hibernate-specific @Target annotation instead.

The coordinates embeddable type is mapped as the Coordinates interface. However, Hibernate needs to know the actual implementation tye, which is GPS in this case, hence the @Target annotation is used to provide this information.

Assuming we have persisted the following City entity:

When fetching the City entity, the coordinates property is mapped by the @Target expression:

Therefore, the @Target annotation is used to define a custom join association between the parent-child association.

The Hibernate-specific @Parent annotation allows you to reference the owner entity from within an embeddable.

Assuming we have persisted the following City entity:

When fetching the City entity, the city property of the embeddable type acts as a back reference to the owning parent entity:

Therefore, the @Parent annotation is used to define the association between an embeddable type and the owning entity.

Jakarta Persistence requires embeddable classes to follow Java Bean conventions. Part of this is the definition of a non-arg constructor. However, not all value compositions applications might map as embeddable values follow Java Bean conventions - e.g. a struct or Java 15 record.

Hibernate allows the use of a custom instantiator for creating the embeddable instances through the org.hibernate.metamodel.spi.EmbeddableInstantiator contract. For example, consider the following embeddable:

Here, Name only allows use of the constructor accepting its state. Because this class does not follow Java Bean conventions, in terms of constructor, a custom strategy for instantiation is needed.

There are a few ways to specify the custom instantiator. The @org.hibernate.annotations.EmbeddableInstantiator annotation can be used on the embedded attribute:

@EmbeddableInstantiator may also be specified on the embeddable class:

Lastly, @org.hibernate.annotations.EmbeddableInstantiatorRegistration may be used, which is useful when the application developer does not control the embeddable to be able to apply the instantiator on the embeddable.

Another approach is to supply the implementation of the org.hibernate.usertype.CompositeUserType contract using @CompositeType, which is an extension to the org.hibernate.metamodel.spi.EmbeddableInstantiator contract.

There are also corresponding, specialized forms of @CompositeType for specific model parts:

For example, consider the following custom type:

Here, Name only allows use of the constructor accepting its state. Because this class does not follow Java Bean conventions, a custom user type for instantiation and state access is needed.

A composite user type needs an embeddable mapper class, which represents the embeddable mapping structure of the type i.e. the way the type would look like if you had the option to write a custom @Embeddable class.

In addition to the instantiation logic, a composite user type also has to provide a way to decompose the returned type into the individual components/properties of the embeddable mapper class through getPropertyValue. The property index, just like in the instantiate method, is based on the alphabetical order of the attribute names of the embeddable mapper class.

The composite user type also needs to provide methods to handle the mutability, equals, hashCode and the cache serialization and deserialization of the returned type.

There are a few ways to specify the composite user type. The @org.hibernate.annotations.CompositeType annotation can be used on the embedded and element collection attributes:

Or @org.hibernate.annotations.CompositeTypeRegistration may be used, which is useful when the application developer wants to apply the composite user type for all domain type uses.

Hibernate naming strategies are covered in detail in Naming. However, for the purposes of this discussion, Hibernate has the capability to interpret implicit column names in a way that is safe for use with multiple embeddable types.

To make it work, you need to use the ImplicitNamingStrategyComponentPathImpl naming strategy.

Now the "path" to attributes are used in the implicit column naming:

You could even develop your own naming strategy to do other types of implicit naming strategies.

An embeddable mapping is usually just a way to encapsulate columns of a table into a Java type, but as of Hibernate 6.2, it is also possible to map embeddable types as SQL aggregate types.

Currently, there are three possible SQL aggregate types which can be specified by annotating one of the following annotations on a persistent attribute:

Any read or assignment (in an update statement) expression for an attribute of such an embeddable will resolve to the proper SQL expression to access/update the attribute of the SQL type.

Since object, JSON and XML types are not supported equally on all databases, beware that not every mapping will work on all databases. The following table outlines the current support for the different aggregate types:

Also note that embeddable types that are used in aggregate mappings do not yet support all kinds of attribute mappings, most notably:

Section 2.1 The Entity Class of the Java Persistence 2.1 specification defines its requirements for an entity class. Applications that wish to remain portable across Jakarta Persistence providers should adhere to these requirements:

Hibernate, however, is not as strict in its requirements. The differences from the list above include:

Let’s look at each requirement in detail.

A central feature of Hibernate is the ability to load lazily certain entity instance variables (attributes) via runtime proxies. This feature depends upon the entity class being non-final or else implementing an interface that declares all the attribute getters/setters. You can still persist final classes that do not implement such an interface with Hibernate, but you will not be able to use proxies for fetching lazy associations, therefore limiting your options for performance tuning. For the very same reason, you should also avoid declaring persistent attribute getters and setters as final.

The entity class should have a no-argument constructor. Both Hibernate and Jakarta Persistence require this.

Jakarta Persistence requires that this constructor be defined as public or protected. Hibernate, for the most part, does not care about the constructor visibility, as long as the system SecurityManager allows overriding the visibility setting. That said, the constructor should be defined with at least package visibility if you wish to leverage runtime proxy generation.

The Jakarta Persistence specification requires this, otherwise, the model would prevent accessing the entity persistent state fields directly from outside the entity itself.

Although Hibernate does not require it, it is recommended to follow the JavaBean conventions and define getters and setters for entity persistent attributes. Nevertheless, you can still tell Hibernate to directly access the entity fields.

Attributes (whether fields or getters/setters) need not be declared public. Hibernate can deal with attributes declared with the public, protected, package or private visibility. Again, if wanting to use runtime proxy generation for lazy loading, the getter/setter should grant access to at least package visibility.

The identifier attribute does not necessarily need to be mapped to the column(s) that physically define the primary key. However, it should map to column(s) that can uniquely identify each row.

The placement of the @Id annotation marks the persistence state access strategy.

Hibernate offers multiple identifier generation strategies, see the Identifier Generators chapter for more about this topic.

The main piece in mapping the entity is the jakarta.persistence.Entity annotation.

The @Entity annotation defines just the name attribute which is used to give a specific entity name for use in JPQL queries.

By default, if the name attribute of the @Entity annotation is missing, the unqualified name of the entity class itself will be used as the entity name.

In the following example, the entity name (e.g. Book) is given by the unqualified name of the entity class name.

However, the entity name can also be set explicitly as illustrated by the following example.

An entity models a database table. The identifier uniquely identifies each row in that table. By default, the name of the table is assumed to be the same as the name of the entity. To explicitly give the name of the table or to specify other information about the table, we would use the jakarta.persistence.Table annotation.

Whether to implement equals() and hashCode() methods in your domain model, let alone how to implement them, is a surprisingly tricky discussion when it comes to ORM.

There is really just one absolute case: a class that acts as an identifier must implement equals/hashCode based on the id value(s). Generally, this is pertinent for user-defined classes used as composite identifiers. Beyond this one very specific use case and few others we will discuss below, you may want to consider not implementing equals/hashCode altogether.

So what’s all the fuss? Normally, most Java objects provide a built-in equals() and hashCode() based on the object’s identity, so each new object will be different from all others. This is generally what you want in ordinary Java programming. Conceptually, however, this starts to break down when you start to think about the possibility of multiple instances of a class representing the same data.

This is, in fact, exactly the case when dealing with data coming from a database. Every time we load a specific Person from the database we would naturally get a unique instance. Hibernate, however, works hard to make sure that does not happen within a given Session. In fact, Hibernate guarantees equivalence of persistent identity (database row) and Java identity inside a particular session scope. So if we ask a Hibernate Session to load that specific Person multiple times we will actually get back the same instance:

Consider we have a Library parent entity which contains a java.util.Set of Book entities:

However, the semantic changes when we mix instances loaded from different Sessions:

Specifically, the outcome in this last example will depend on whether the Book class implemented equals/hashCode, and, if so, how.

If the Book class did not override the default equals/hashCode, then the two Book object references are not going to be equal since their references are different.

Consider yet another case:

In cases where you will be dealing with entities outside of a Session (whether they be transient or detached), especially in cases where you will be using them in Java collections, you should consider implementing equals/hashCode.

A common initial approach is to use the entity’s identifier attribute as the basis for equals/hashCode calculations:

It turns out that this still breaks when adding transient instance of Book to a set as we saw in the last example:

The issue here is a conflict between the use of the generated identifier, the contract of Set, and the equals/hashCode implementations. Set says that the equals/hashCode value for an object should not change while the object is part of the Set. But that is exactly what happened here because the equals/hasCode are based on the (generated) id, which was not set until the Jakarta Persistence transaction is committed.

Note that this is just a concern when using generated identifiers. If you are using assigned identifiers this will not be a problem, assuming the identifier value is assigned prior to adding to the Set.

Another option is to force the identifier to be generated and set prior to adding to the Set:

But this is often not feasible.

The final approach is to use a "better" equals/hashCode implementation, making use of a natural-id or business-key.

This time, when adding a Book to the Library Set, you can retrieve the Book even after it’s being persisted:

As you can see the question of equals/hashCode is not trivial, nor is there a one-size-fits-all solution.

For details on mapping the identifier, see the Identifiers chapter.

You can map an entity to a SQL query using the @Subselect annotation.

In the example above, the Account entity does not retain any balance since every account operation is registered as an AccountTransaction. To find the Account balance, we need to query the AccountSummary which shares the same identifier with the Account entity.

However, the AccountSummary is not mapped to a physical table, but to an SQL query.

So, if we have the following AccountTransaction record, the AccountSummary balance will match the proper amount of money in this Account.