Hibernate was the inspiration behind theJava (nowJakarta)Persistence API, or JPA, and includes a complete implementation of the latest revision ofthis specification.

We can think of the API of Hibernate in terms of three basic elements:

• an implementation of the JPA-defined APIs, most importantly, of the interfacesEntityManagerFactory andEntityManager, and of the JPA-defined O/R mapping annotations,

• anative API exposing the full set of available functionality, centered around the interfacesSessionFactory, which extendsEntityManagerFactory, andSession, which extendsEntityManager, and

• a set ofmapping annotations which augment the O/R mapping annotations defined by JPA, and which may be used with the JPA-defined interfaces, or with the native API.

Hibernate also offers a range of SPIs for frameworks and libraries which extend or integrate with Hibernate, but we’re not interested in any of that stuff here.

As an application developer, you must decide whether to:

• write your program in terms ofSession andSessionFactory, or

• maximize portability to other implementations of JPA by, wherever reasonable, writing code in terms ofEntityManager andEntityManagerFactory, falling back to the native APIs only where necessary.

Whichever path you take, you will use the JPA-defined mapping annotations most of the time, and the Hibernate-defined annotations for more advanced mapping problems.

Since Hibernate existed before JPA, and since JPA was modelled on Hibernate, we unfortunately have some competition and duplication in naming between the standard and native APIs.For example:

Typically, the Hibernate-native APIs offer something a little extra that’s missing in JPA, so this isn’t exactly aflaw.But it’s something to watch out for.

If you’re completely new to Hibernate and JPA, you might already be wondering how the persistence-related code is structured.

Well, typically, our persistence-related code comes in two layers:

1. a representation of our data model in Java, which takes the form of a set of annotated entity classes, and

2. a larger number of functions which interact with Hibernate’s APIs to perform the persistence operations associated with our various transactions.

The first part, the data or "domain" model, is usually easier to write, but doing a great and very clean job of it will strongly affect your success in the second part.

Most people implement the domain model as a set of what we used to call "Plain Old Java Objects", that is, as simple Java classes with no direct dependencies on technical infrastructure, nor on application logic which deals with request processing, transaction management, communications, or interaction with the database.

The second part of the code is much trickier to get right. This code must:

• manage transactions and sessions,

• interact with the database via the Hibernate session,

• publish CDI events and send JMS messages,

• fetch and prepare data needed by the UI, and

• handle failures.

We’re going tocome back soon to the thorny question of how this persistence logic should be organized, and how it should fit into the rest of the system.

Before we get deeper into the weeds, we’ll quickly present a basic example program that will help you get started if you don’t already have Hibernate integrated into your project.

We begin with a simpleGradle build file:

Only the first of these dependencies is absolutelyrequired to run Hibernate.

Next, we’ll add a logging configuration file forlog4j:

Now we need some Java code.We begin with ourentity class:

Finally, let’s see code whichconfigures and instantiates Hibernate and asks it topersist and query the entity.Don’t worry if this makes no sense at all right now.It’s the job of the rest of this Short Guide to make all this crystal clear.

In practice, we never access the database directly from amain() method.So now let’s talk about how to organize persistence logic in a real system.The rest of this chapter is not compulsory.If you’re itching for more details about Hibernate itself, you’re quite welcome to skip straight to thenext chapter, and come back later.

A class in the domain model which directly represents a relational database table is called anentity.Entity classes are central to object persistence and to object/relational mapping.They’re also, typically, central players in the business logic of our application program.Entities represent thethings in our business domain.This makes them very important objects indeed!

Given how much weight an entity already bears due to its very nature, we need to think carefully before weighing it down with too many additional responsibilities.

In keeping with our commitment to anti-dogmatism, we would like to add the following important caveat to the discussion in the previous callout.

For now, we’re going to assume that entities are implemented as plain Java classes.

It should be very clear from the example codeabove, that the session is also a very important object.It exposes basic operations likepersist() andcreateQuery(), and so it’s our first port of call when we want tointeract with the database via Hibernate.In the code we just saw, we’ve used astateful session.

Later, we’ll learn about the idea of apersistence context.Oversimplifying for now, you can think of it as a cache of data which has been read in the current transaction.Thus, in the architecture of Hibernate, it’s sometimes called thefirst-level cache.Each stateful session — that is, every HibernateSession, and every JPAEntityManager — has its own persistence context.

But stateful sessions have never been the only possibility.TheStatelessSession interface offers a way to interact with Hibernatewithout going through a persistence context.However, the programming model is somewhat different.

As of Hibernate 7, a key decision for any new project is which of these programming models to take as a baseline.Fortunately, the two models aren’t mutually exclusive.This is a friendly competition, where the two APIs are designed to complement each other.Even if we decide to useStatefulSession most of the time, we can still use aStatelessSession wherever it’s more convenient.

But now we’ve got just a little bit ahead of ourselves.In the next section taking we’re taking a journey whichmight — but definitely doesn’tnecessarily — end at the idea of a "repository".

In a real program, persistence logic like the code shown above is usually interleaved with other sorts of code, including logic:

• implementing the rules of the business domain, or

• for interacting with the user.

Therefore, many developers quickly—eventoo quickly, in our opinion—reach for ways to isolate the persistence logic into some sort of separate architectural layer.We’re going to ask you to suppress this urge for now.

We prefer abottom-up approach to organizing our code.We like to start thinking about methods and functions, not about architectural layers and container-managed objects.

To illustrate the sort of approach to code organization that we advocate, let’s consider a service which queries the database using HQL or SQL.We might start with something like this, a mix of UI and persistence logic:

Indeed, we might alsofinish with something like that—it’s quite hard to identify anything concretely wrong with the code above, and for such a simple case it seems really difficult to justify making this code more complicated by introducing additional objects.

One very nice aspect of this code, which we wish to draw your attention to, is that session and transaction management is handled by generic "framework" code, just as we already recommended above.In this case, we’re using thefromTransaction() method, which happens to come built in to Hibernate.But you might prefer to use something else, for example:

• in a container environment like Jakarta EE or Quarkus,container-managed transactions andcontainer-managed persistence contexts, or

• something you write yourself.

The important thing is that calls likecreateEntityManager() andgetTransaction().begin() don’t belong in regular program logic, because it’s tricky and tedious to get the error handling correct.

Let’s now consider a slightly more complicated case.

This is fine, and we won’t complain if you prefer to leave the code exactly as it appears above.But there’s one thing we could perhaps improve.We love super-short methods with single responsibilities, and there looks to be an opportunity to introduce one here.Let’s hit the code with our favorite thing, the Extract Method refactoring. We obtain:

This is an example of aquery method, a function which accepts arguments to the parameters of a HQL or SQL query, and executes the query, returning its results to the caller.And that’s all it does; it doesn’t orchestrate additional program logic, and it doesn’t perform transaction or session management.

It’s even better to specify the query string using the@NamedQuery annotation, so that Hibernate can validate the query at startup time, that is, when theSessionFactory is created, instead of when the query is first executed.Indeed, since we includedHibernate Processor in ourGradle build, the query can even be validated atcompile time.

We need a place to put the annotation, so let’s move our query method to a new class:

Notice that our query method doesn’t attempt to hide theEntityManager from its clients.Indeed, the client code is responsible for providing theEntityManager orSession to the query method.

The client code may:

• obtain anEntityManager orSession by callinginTransaction() orfromTransaction(), as we saw above, or,

• in an environment with container-managed transactions, it might obtain it via dependency injection.

Whatever the case, the code which orchestrates a unit of work usually just calls theSession orEntityManager directly, passing it along to helper methods like our query method if necessary.

You might be thinking that our query method looks a bit boilerplatey.That’s true, perhaps, but we’re much more concerned that it’s still not perfectly typesafe.Indeed, for many years, the lack of compile-time checking for HQL queries and code which binds arguments to query parameters was our number one source of discomfort with Hibernate.Here, the@CheckHQL annotation takes care of checking the query itself, but the call tosetParameter() is still not type safe.

Fortunately, there’s now a great solution to both problems. Hibernate Processor is able to fill in the implementation of such query methods for us.This facility is the topic ofa whole chapter of this introduction, so for now we’ll just leave you with one simple example.

Suppose we simplifyQueries to just the following:

Then Hibernate Processor automatically produces an implementation of the method annotated@HQL in a class namedQueries_.We can call it just like we were previously calling our handwritten version:

In this case, the quantity of code eliminated is pretty trivial.The real value is in improved type safety.We now find out about errors in assignments of arguments to query parameters at compile time.

This is all quite nice so far, but at this point you’re probably wondering whether we could use dependency injection to obtain aninstance of theQueries interface, and have this object take care of obtaining its ownSession.Well, indeed we can.What we need to do is indicate the kind of session theQueries interface depends on, by adding a method to retrieve the session.Observe, again, that we’restill not attempting to hide theSession from the client code.

TheQueries interface is now considered arepository, and we may use CDI to inject the repository implementation generated by Hibernate Processor.Also, since I guess we’re now working in some sort of container environment, we’ll let the container manage transactions for us.

Alternatively, if CDI isn’t available, we may directly instantiate the generated repository implementation class usingnew Queries_(entityManager).

Now that we have a rough picture of what our persistence logic might look like, it’s natural to ask how we should test our code.

When we write tests for our persistence logic, we’re going to need:

1. a database, with

2. an instance of the schema mapped by our persistent entities, and

3. a set of test data, in a well-defined state at the beginning of each test.

It might seem obvious that we should test against the same database system that we’re going to use in production, and, indeed, we should certainly have at leastsome tests for this configuration.But on the other hand, tests which perform I/O are much slower than tests which don’t, and most databases can’t be set up to run in-process.

So, since most persistence logic written using Hibernate 6 isextremely portable between databases, it often makes good sense to test against an in-memory Java database.(H2 is the one we recommend.)

Whether we’re testing against our real database, or against an in-memory Java database, we’ll need to export the schema at the beginning of a test suite.Weusually do this when we create the HibernateSessionFactory or JPAEntityManagerFactory, and so traditionally we’ve used aconfiguration property for this.

The JPA-standard property isjakarta.persistence.schema-generation.database.action.For example, if we’re usingPersistenceConfiguration to configure Hibernate, we could write:

Alternatively, we may use the newSchemaManager API to export the schema, just as we didabove.This option is especially convenient when writing tests.

Since executing DDL statements is very slow on many databases, we don’t want to do this before every test.Instead, to ensure that each test begins with the test data in a well-defined state, we need to do two things before each test:

1. clean up any mess left behind by the previous test, and then

2. reinitialize the test data.

We may truncate all the tables, leaving an empty database schema, using theSchemaManager.

After truncating tables, we might need to initialize our test data.We may specify test data in a SQL script, for example:

If we name this fileimport.sql, and place it in the root classpath, that’s all we need to do.

Otherwise, we need to specify the file in theconfiguration propertyjakarta.persistence.sql-load-script-source.If we’re usingPersistenceConfiguration to configure Hibernate, we could write:

The SQL script will be executed every timeexport() ortruncate() is called.

Now, suppose you’ve followed our advice, and written your entities and query methods to minimize dependencies on "infrastructure", that is, on libraries other than JPA and Hibernate, on frameworks, on container-managed objects, and even on bits of your own system which are hard to instantiate from scratch.Then testing persistence logic is now straightforward!

You’ll need to:

• bootstrap Hibernate and create aSessionFactory orEntityManagerFactory at the beginning of your test suite (we’ve already seen how to do that), and

• create a newSession orEntityManager inside each@Test method, usinginTransaction(), for example.

Actually, some tests might require multiple sessions.But be careful not to leak a session between different tests.

It’s now time to begin our journey toward actuallyunderstanding the code we saw earlier.

This introduction will guide you through the basic tasks involved in developing a program that uses Hibernate for persistence:

1. configuring and bootstrapping Hibernate, and obtaining an instance ofSessionFactory orEntityManagerFactory,

2. writing adomain model, that is, a set ofentity classes which represent the persistent types in your program, and which map to tables of your database,

3. customizing these mappings when the model maps to a pre-existing relational schema,

4. using theSession orEntityManager to perform operations which query the database and return entity instances, or which update the data held in the database,

5. using Hibernate Processor to improve compile-time type-safety,

6. writing complex queries using the Hibernate Query Language (HQL) or native SQL, and, finally

7. tuning performance of the data access logic.

Naturally, we’ll start at the top of this list, with the least-interesting topic:configuration.

First, add the following dependency to your project:

Where{version} is the version of Hibernate you’re using,7.0.10.Final, for example.

You’ll also need to add a dependency for the JDBCdriver for your database.

Where{version} is the latest version of the JDBC driver for your database.

Optionally, you might also add any of the following additional features:

You might also add the Hibernatebytecode enhancer to yourGradle build if you want to usefield-level lazy fetching.

Sticking to the JPA-standard approach, we would provide a file namedpersistence.xml, which we usually place in theMETA-INF directory of apersistence archive, that is, of the.jar file or directory which contains our entity classes.

The<persistence-unit> element defines a namedpersistence unit, that is:

• a collection of associated entity types, along with

• a set of default configuration settings, which may be augmented or overridden at runtime.

Each<class> element specifies the fully-qualified name of an entity class.

Each<property> element specifies aconfiguration property and its value.Note that:

• the configuration properties in thejakarta.persistence namespace are standard properties defined by the JPA spec, and

• properties in thehibernate namespace are specific to Hibernate.

We may obtain anEntityManagerFactory by callingPersistence.createEntityManagerFactory():

If necessary, we may override configuration properties specified inpersistence.xml:

The newPersistenceConfiguration class allows full programmatic control over creation of theEntityManagerFactory.

The specification gives JPA implementors like Hibernate explicit permission to extend this class, and so Hibernate offers theHibernatePersistenceConfiguration, which lets us obtain aSessionFactory without any need for a cast.

Alternatively, the venerable classConfiguration offers similar functionality.

If we’re using programmatic configuration, but we don’t want to put certain configuration properties directly in the Java code, we can specify them in a file namedhibernate.properties, and place the file in the root classpath.

ThePersistenceConfiguration class declaresstatic final constants holding the names of all configuration properties defined by the specification itself, for example,JDBC_URL holds the property name"jakarta.persistence.jdbc.driver".

Similarly, the classAvailableSettings enumerates all the configuration properties understood by Hibernate.

Of course, we’re not going to cover every useful configuration setting in this chapter.Instead, we’ll mention the ones you need to get started, and come back to some other important settings later, especially when we talk about performance tuning.

The properties you really do need to get started are these three:

In some environments it’s useful to be able to start Hibernate without accessing the database.In this case, we must explicitly specify not only the database platform, but also the version of the database, using the standard JPA configuration properties.

The product name is the value returned byjava.sql.DatabaseMetaData.getDatabaseProductName(), for example,PostgreSQL,MySQL,H2,Oracle,EnterpriseDB,MariaDB, orMicrosoft SQL Server.

Pooling JDBC connections is an extremely important performance optimization.You can set the size of Hibernate’s built-in connection pool using this property:

This configuration property is also respected when you use Agroal, HikariCP, or c3p0 for connection pooling.

Alternatively, in a container environment, you’ll need at least one of these properties:

In this case, Hibernate obtains pooled JDBC database connections from a container-managedDataSource.

You can have Hibernate infer your database schema from the mappingannotations you’ve specified in your Java code, and export the schema atinitialization time by specifying one or more of the following configurationproperties:

This feature is extremely useful for testing.

As we mentionedearlier, it can also be useful to control schema export programmatically.

To see the generated SQL as it’s sent to the database, you have two options.

One way is to set the propertyhibernate.show_sql totrue, and Hibernate will log SQL directly to the console.You can make the output much more readable by enabling formatting or highlighting.These settings really help when troubleshooting the generated SQL statements.

Alternatively, you can enable debug-level logging for the categoryorg.hibernate.SQL using your preferred SLF4J logging implementation.

For example, if you’re using Log4J 2 (as above inOptional dependencies), add these lines to yourlog4j2.properties file:

SQL logging respects the settingshibernate.format_sql andhibernate.highlight_sql, so we don’t miss out on the pretty formatting and highlighting.

The following properties are very useful for minimizing the amount of information you’ll need to explicitly specify in@Table and@Column annotations, which we’ll discuss below inObject/relational mapping:

By default, Hibernate never quotes a SQL table or column name in generated SQL when the name contains only alphanumeric characters.This behavior is usually much more convenient, especially when working with a legacy schema, since unquoted identifiers aren’t case-sensitive, and so Hibernate doesn’t need to know or care whether a column is namedNAME,name, orName on the database side.On the other hand, any table or column name containing a punctuation character like$ is automatically quoted by default.

The following settings enable additional automatic quoting:

Note thathibernate.globally_quoted_identifiers is a synonym for<delimited-identifiers/> inpersistence.xml.We don’t recommend the use of global identifier quoting, and in fact these settings are rarely used.

By default, SQL Server’schar andvarchar types don’t accommodate Unicode data.But a Java string may contain any Unicode character.So, if you’re working with SQL Server, you might need to force Hibernate to use thenchar andnvarchar column types.

On the other hand, if onlysome columns store nationalized data, use the@Nationalized annotation to indicate fields of your entities which map these columns.

By default, Hibernate handles date and time types defined byjava.time by:

• convertingjava.time types to JDBC date/time types defined injava.sql when sending data to the database, and

• readingjava.sql types from JDBC and then converting them tojava.time types when retrieving data from the database.

This works best when the database server time zone agrees with JVM system time zone.

There are two system configuration properties which influence this behavior:

You may sethibernate.jdbc.time_zone to the time zone of the database server if for some reason the JVM needs to operate in a different time zone.We do not recommend this approach.

On the other hand, we would love to recommend the use ofhibernate.type.java_time_use_direct_jdbc, but this option is still experimental for now, and does result in some subtle differences in behavior which might affect legacy programs using Hibernate.

An entity must:

• be a non-final class,

• with a non-private constructor with no parameters.

On the other hand, the entity class may be either concrete orabstract, and it may have any number of additional constructors.

Every entity class must be annotated@Entity.

Alternatively, the class may be identified as an entity type by providing an XML-based mapping for the class.

We won’t have much more to say about XML-based mappings in this Short Guide, since it’s not our preferred way to do things.

Each entity class has a defaultaccess type, either:

• directfield access, or

• property access.

Hibernate automatically determines the access type from the location of attribute-level annotations.Concretely:

• if a field is annotated@Id, field access is used, or

• if a getter method is annotated@Id, property access is used.

Back when Hibernate was just a baby, property access was quite popular in the Hibernate community.Today, however, field access ismuch more common.

An entity class likeBook, which does not extend any other entity class, is called aroot entity.Every root entity must declare an identifier attribute.

An entity class mayextend another entity class.

A subclass entity inherits every persistent attribute of every entity it extends.

A root entity may also extend another class and inherit mapped attributes from the other class.But in this case, the class which declares the mapped attributes must be annotated@MappedSuperclass.

A root entity class must declare an attribute annotated@Id, or inherit one from a@MappedSuperclass.A subclass entity always inherits the identifier attribute of the root entity.It may not declare its own@Id attribute.

An identifier attribute is usually a field:

But it may be a property:

An identifier attribute must be annotated@Id or@EmbeddedId.

Identifier values may be:

• assigned by the application, that is, by your Java code, or

• generated and assigned by Hibernate.

We’ll discuss the second option first.

An identifier is often system-generated, in which case it should be annotated@GeneratedValue:

JPA defines the following strategies for generating ids, which are enumerated byGenerationType:

For example, this UUID is generated in Java code:

This id maps to a SQLidentity,auto_increment, orbigserial column:

The@SequenceGenerator and@TableGenerator annotations allow further control overSEQUENCE andTABLE generation respectively.

Consider this sequence generator:

Values are generated using a database sequence defined as follows:

Notice that Hibernate doesn’t have to go to the database every time a new identifier is needed.Instead, a given process obtains a block of ids, of sizeallocationSize, and only needs to hit the database each time the block is exhausted.Of course, the downside is that generated identifiers are not contiguous.

Any identifier attribute may now make use of the generator namedbookSeq:

Actually, it’s extremely common to place the@SequenceGenerator annotation on the@Id attribute that makes use of it:

In this case, thename of the@SequenceGenerator should not be specified.

We may even place a@SequenceGenerator or@TableGenerator annotation at the package level:

Then any entity in this package which specifiesstrategy=SEQUENCE orstrategy=TABLE without also explicitly specifying a generatorname will be assigned a generator based on the package-level annotation.

As you can see, JPA provides quite adequate support for the most common strategies for system-generated ids.However, the annotations themselves are a bit more intrusive than they should be, and there’s no well-defined way to extend this framework to support custom strategies for id generation.Nor may@GeneratedValue be used on a property not annotated@Id.Since custom id generation is a rather common requirement, Hibernate provides a very carefully-designed framework for user-definedGenerators, which we’ll discuss inUser-defined generators.

Not every identifier attribute maps to a (system-generated) surrogate key.Primary keys which are meaningful to the user of the system are callednatural keys.

When the primary key of a table is a natural key, we don’t annotate the identifier attribute@GeneratedValue, and it’s the responsibility of the application code to assign a value to the identifier attribute.

Of particular interest are natural keys which comprise more than one database column, and such natural keys are calledcomposite keys.

If your database uses composite keys, you’ll need more than one identifier attribute.There are two ways to map composite keys in JPA:

• using an@IdClass, or

• using an@EmbeddedId.

Perhaps the most immediately-natural way to represent this in an entity class is with multiple fields annotated@Id, for example:

But this approach comes with a problem: what object can we use to identify aBook and pass to methods likefind() which accept an identifier?

The solution is to write a separate class with fields that match the identifier attributes of the entity.Every such id class must overrideequals() andhashCode().Of course, the easiest way to satisfy these requirements is to declare the id class as arecord.

The@IdClass annotation of theBook entity identifiesBookId as the id class to use for that entity.

This is not our preferred approach.Instead, we recommend that theBookId class be declared as an@Embeddable type:

We’ll learn more aboutEmbeddable objects below.

Now the entity class may reuse this definition using@EmbeddedId, and the@IdClass annotation is no longer required:

This second approach eliminates some duplicated code.

Either way, we may now useBookId to obtain instances ofBook:

An entity may have an attribute which is used by Hibernate foroptimistic lock verification.Aversion attribute is usually of typeInteger,Short,Long,LocalDateTime,OffsetDateTime,ZonedDateTime, orInstant.

A version attribute is automatically assigned by Hibernate when an entity is made persistent, and automatically incremented or updated each time the entity is updated.

If the version attribute is numeric, then an entity is, by default, assigned the version number0 when it’s first made persistent.It’s easy to specify that the initial version should be assigned the number1 instead:

Almost every entity which is frequently updated should have a version attribute.

The@Id and@Version attributes we’ve already seen are just specialized examples ofbasic attributes.

Even when an entity has a surrogate key, it should always be possible to write down a combination of fields which uniquely identifies an instance of the entity, from the point of view of the user of the system.This combination of fields is its natural key.Above, weconsidered the case where the natural key coincides with the primary key.Here, the natural key is a second unique key of the entity, distinct from its surrogate primary key.

Since it’sextremely common to retrieve an entity based on its natural key, Hibernate has a way to mark the attributes of the entity which make up its natural key.Each attribute must be annotated@NaturalId.

Hibernate automatically generates aUNIQUE constraint on the columns mapped by the annotated fields.

The payoff for doing this extra work, as we will seemuch later, is that we can take advantage of optimized natural id lookups that make use of the second-level cache.

Note that even when you’ve identified a natural key, we still recommend the use of a generated surrogate key in foreign keys, since this makes your data modelmuch easier to change.

Abasic attribute of an entity is a field or property which maps to a single column of the associated database table.The JPA specification defines a quite limited set of basic types:

Hibernate slightly extends this list with the following types:

The@Basic annotation explicitly specifies that an attribute is basic, but it’s often not needed, since attributes are assumed basic by default.On the other hand, if a non-primitively-typed attribute cannot be null, use of@Basic(optional=false) is highly recommended.

Note that primitively-typed attributes are inferredNOT NULL by default.

We included Javaenums on the list above.An enumerated type is considered a sort of basic type, but since most databases don’t have a nativeENUM type, JPA provides a special@Enumerated annotation to specify how the enumerated values should be represented in the database:

• by default, an enum is stored as an integer, the value of itsordinal() member, but

• if the attribute is annotated@Enumerated(STRING), it will be stored as a string, the value of itsname() member.

The@EnumeratedValue annotation allows the column value to be customized:

Since Hibernate 6, anenum annotated@Enumerated(STRING) is mapped to:

• aVARCHAR column type with aCHECK constraint on most databases, or

• anENUM column type on MySQL.

Any otherenum is mapped to aTINYINT column with aCHECK constraint.

An interesting special case arises on PostgreSQL and Oracle.

The limited set of pre-defined basic attribute types can be stretched a bit further by supplying aconverter.

A JPAAttributeConverter is responsible for:

• converting a given Java type to one of the types listed above, and/or

• perform any other sort of pre- and post-processing you might need to perform on a basic attribute value before writing and reading it to or from the database.

Converters substantially widen the set of attribute types that can be handled by JPA.

There are two ways to apply a converter:

• the@Convert annotation applies anAttributeConverter to a particular entity attribute, or

• the@Converter annotation (or, alternatively, the@ConverterRegistration annotation) registers anAttributeConverter for automatic application to all attributes of a given type.

For example, the following converter will be automatically applied to any attribute of typeEnumSet<DayOfWeek>, and takes care of persisting theEnumSet<DayOfWeek> to a column of typeINTEGER:

On the other hand, if wedon’t setautoapply=true, then we must explicitly apply the converter using the@Convert annotation:

All this is nice, but it probably won’t surprise you that Hibernate goes beyond what is required by JPA.

Hibernate considers a "basic type" to be formed by the marriage of two objects:

• aJavaType, which models the semantics of a certain Java class, and

• aJdbcType, representing a SQL type which is understood by JDBC.

When mapping a basic attribute, we may explicitly specify aJavaType, aJdbcType, or both.

An instance oforg.hibernate.type.descriptor.java.JavaType represents a particular Java class.It’s able to:

• compare instances of the class to determine if an attribute of that class type is dirty (modified),

• produce a useful hash code for an instance of the class,

• coerce values to other types, and, in particular,

• convert an instance of the class to one of several other equivalent Java representations at the request of its partnerJdbcType.

For example,IntegerJavaType knows how to convert anInteger orint value to the typesLong,BigInteger, andString, among others.

We may explicitly specify a Java type using the@JavaType annotation, but for the built-inJavaTypes this is never necessary.

For a user-writtenJavaType, the annotation is more useful:

Alternatively, the@JavaTypeRegistration annotation may be used to registerBitSetJavaType as the defaultJavaType forBitSet.

Anorg.hibernate.type.descriptor.jdbc.JdbcType is able to read and write a single Java type from and to JDBC.

For example,VarcharJdbcType takes care of:

• writing Java strings to JDBCPreparedStatements by callingsetString(), and

• reading Java strings from JDBCResultSets usinggetString().

By pairingLongJavaType withVarcharJdbcType in holy matrimony, we produce a basic type which mapsLongs and primitivelongss to the SQL typeVARCHAR.

We may explicitly specify a JDBC type using the@JdbcType annotation.

Alternatively, we may specify a JDBC type code:

The@JdbcTypeRegistration annotation may be used to register a user-writtenJdbcType as the default for a given SQL type code.

If a givenJavaType doesn’t know how to convert its instances to the type required by its partnerJdbcType, we must help it out by providing a JPAAttributeConverter to perform the conversion.

For example, to form a basic type usingLongJavaType andTimestampJdbcType, we would provide anAttributeConverter<Long,Timestamp>.

Let’s abandon our analogy right here, before we start calling this basic type a "throuple".

Dates and times should always be represented using the types defined injava.time.

Some of the types injava.time map naturally to an ANSI SQL column type.A source of confusion is that some databases still don’t follow the ANSI standard naming here.Also, as you’re probably aware, theDATE type on Oracle is not an ANSI SQLDATE.In fact, Oracle doesn’t haveDATE orTIME types—​every date or time must be stored as a timestamp.

On the other hand, there are no perfectly natural mappings forInstant andDuration on must databases.By default:

• Duration is mapped to a column of typeNUMERIC(21) holding the length of the duration in nanoseconds, and

• Instant is mapped to a column of typeTIMESTAMP (DATETIME on MySQL).

Fortunately, these mappings can be modified by specifying theJdbcType.

For example, if we wanted to store anInstant usingTIMESTAMP WITH TIME ZONE (TIMESTAMP on MySQL) instead ofTIMESTAMP, then we could annotate the field:

Alternatively, we could set the configuration propertyhibernate.type.preferred_instant_jdbc_type:

We have worked very hard to make sure that Java date and time types work with consistent and correct semantics across all databases supported by Hibernate.In particular, Hibernate is very careful in how it handles time zones.

An embeddable object is a Java class whose state maps to multiple columns of a table, but which doesn’t have its own persistent identity.That is, it’s a class with mapped attributes, but no@Id attribute.

An embeddable object can only be made persistent by assigning it to the attribute of an entity.Since the embeddable object does not have its own persistent identity, its lifecycle with respect to persistence is completely determined by the lifecycle of the entity to which it belongs.

An embeddable class must be annotated@Embeddable instead of@Entity.

An embeddable class must satisfy the same requirements that entity classes satisfy, with the exception that an embeddable class has no@Id attribute.In particular, it must have a constructor with no parameters.

Alternatively, an embeddable type may be defined as a Java record type:

In this case, the requirement for a constructor with no parameters is relaxed.

We may now use ourName class (or record) as the type of an entity attribute:

Embeddable types can be nested.That is, an@Embeddable class may have an attribute whose type is itself a different@Embeddable class.

On the other hand a reference to an embeddable type isnever polymorphic.One@Embeddable classF may inherit a second@Embeddable classE, but an attribute of typeE will always refer to an instance of that concrete classE, never to an instance ofF.

Usually, embeddable types are stored in a "flattened" format.Their attributes map columns of the table of their parent entity.Later, inMapping embeddable types to UDTs or to JSON, we’ll see a couple of different options.

An attribute of embeddable type represents a relationship between a Java object with a persistent identity, and a Java object with no persistent identity.We can think of it as a whole/part relationship.The embeddable object belongs to the entity, and can’t be shared with other entity instances.And it exists for only as long as its parent entity exists.

Next we’ll discuss a different kind of relationship: a relationship between Java objects which each have their own distinct persistent identity and persistence lifecycle.

Anassociation is a relationship between entities.We usually classify associations based on theirmultiplicity.IfE andF are both entity classes, then:

• aone-to-one association relates at most one unique instanceE with at most one unique instance ofF,

• amany-to-one association relates zero or more instances ofE with a unique instance ofF, and

• amany-to-many association relates zero or more instances ofE with zero or more instance ofF.

An association between entity classes may be either:

• unidirectional, navigable fromE toF but not fromF toE, or

• bidirectional, and navigable in either direction.

In this example data model, we can see the sorts of associations which are possible:

There are three annotations for mapping associations:@ManyToOne,@OneToMany, and@ManyToMany.They share some common annotation members:

We’ll explain the effect of these members as we consider the various types of association mapping.

It’s not a requirement to representevery foreign key relationship as an association at the Java level.It’s perfectly acceptable to replace a@ManyToOne mapping with a basic-typed attribute holding an identifier, if it’s inconvenient to think of this relationship as an association at the Java level.That said, it’s possible to take this idea way to far.

Now that we know that associations are actually good and useful, let’s see how to model the various kinds of association we might find need to map to a relational data model.We begin with the most common association multiplicity.

A many-to-one association is the most basic sort of association we can imagine.It maps completely naturally to a foreign key in the database.Almost all the associations in your domain model are going to be of this form.

The@ManyToOne annotation marks the "to one" side of the association, so a unidirectional many-to-one association looks like this:

Here, theBook table has a foreign key column holding the identifier of the associatedPublisher.

Most of the time, we would like to be able to easily navigate our associations in both directions.We do need a way to get thePublisher of a givenBook, but we would also like to be able to obtain all theBooks belonging to a given publisher.

To make this association bidirectional, we need to add a collection-valued attribute to thePublisher class, and annotate it@OneToMany.

To indicate clearly that this is a bidirectional association, and to reuse any mapping information already specified in theBook entity, we must use themappedBy annotation member to refer back toBook.publisher.

ThePublisher.books field is called theunowned side of the association.

Now, we passionatelyhate the stringly-typedmappedBy reference to the owning side of the association.Thankfully, theHibernate Processor gives us a way to make it abit more type safe:

We’re going to use this approach for the rest of the Short Guide.

To modify a bidirectional association, we must change theowning side.

That said, it’snot a hard requirement to update the unowned side, at least if you’re sure you know what you’re doing.

Here we’ve usedSet as the type of the collection, but Hibernate also allows the use ofList orCollection here, with almost no difference in semantics.In particular, theList may not contain duplicate elements, and its order will not be persistent.

We’ll see how to map a collection with a persistent ordermuch later.

The simplest sort of one-to-one association is almost exactly like a@ManyToOne association, except that it maps to a foreign key column with aUNIQUE constraint.

A one-to-one association must be annotated@OneToOne:

Here, theAuthor table has a foreign key column holding the identifier of the associatedPerson.

We can make this association bidirectional by adding a reference back to theAuthor in thePerson entity:

Person.author is the unowned side, because it’s the side markedmappedBy.

This is not the only sort of one-to-one association.

An arguably more elegant way to represent such a relationship is to share a primary key between the two tables.

To use this approach, theAuthor class must be annotated like this:

Notice that, compared with the previous mapping:

• the@Id attribute is no longer a@GeneratedValue and,

• instead, theauthor association is annotated@MapsId.

This lets Hibernate know that the association toPerson is the source of primary key values forAuthor.

Here, there’s no extra foreign key column in theAuthor table, since theid column holds the identifier ofPerson.That is, the primary key of theAuthor table does double duty as the foreign key referring to thePerson table.

ThePerson class doesn’t change.If the association is bidirectional, we annotate the unowned side@OneToOne(mappedBy = Author_.PERSON) just as before.

A unidirectional many-to-many association is represented as a collection-valued attribute.It always maps to a separateassociation table in the database.

It tends to happen that a many-to-many association eventually turns out to be an entity in disguise.

A many-to-many association must be annotated@ManyToMany:

If the association is bidirectional, we add a very similar-looking attribute toBook, but this time we must specifymappedBy to indicate that this is the unowned side of the association:

Remember, if we wish to the modify the collection we mustchange the owning side.

We’ve again usedSets to represent the association.As before, we have the option to useCollection orList.But in this case itdoes make a difference to the semantics of the association.

We’ve now seen the following kinds of entity attribute:

Scanning this taxonomy, you might ask: does Hibernate have multivalued attributes of basic or embeddable type?

Well, actually, we’ve already seen that it does, at least in two special cases.So first, letsrecall that JPA treatsbyte[] andchar[] arrays as basic types.Hibernate persists abyte[] orchar[] array to aVARBINARY orVARCHAR column, respectively.

But in this section we’re really concerned with casesother than these two special cases.So then,apart frombyte[] andchar[], does Hibernate have multivalued attributes of basic or embeddable type?

And the answer again is thatit does. Indeed, there are two different ways to handle such a collection, by mapping it:

• to a column of SQLARRAY type (assuming the database has anARRAY type), or

• to a separate table.

So we may expand our taxonomy with:

There’s actually two new kinds of mapping here:@Array mappings, and@ElementCollection mappings.

We’ll talk about@Array mappings first.

Let’s consider a calendar event which repeats on certain days of the week.We might represent this in ourEvent entity as an attribute of typeDayOfWeek[] orList<DayOfWeek>.Since the number of elements of this array or list is upper bounded by 7, this is a reasonable case for the use of anARRAY-typed column.It’s hard to see much value in storing this collection in a separate table.

Unfortunately, JPA doesn’t define a standard way to map SQL arrays, but here’s how we can do it in Hibernate:

The@Array annotation is optional—​it lets us specify an upper bound on the length of theARRAY column.By writing@Array(length=7) here, we specified that DDL should be generated with the column typeTINYINT ARRAY[7].

Just for fun, we used an enumerated type in the code above, but the array element time may be almost anybasic type.For example, the Java array typesString[],UUID[],double[],BigDecimal[],LocalDate[], andOffsetDateTime[] are all allowed, mapping to the SQL typesVARCHAR(n) ARRAY,UUID ARRAY,FLOAT(53) ARRAY,NUMERIC(p,s) ARRAY,DATE ARRAY, andTIMESTAMP(p) WITH TIME ZONE ARRAY, respectively.

Alternatively, we could store this array or list in a separate table.

JPAdoes define a standard way to map a collection to an auxiliary table: the@ElementCollection annotation.

Actually, we shouldn’t use an array here, since array types can’t beproxied, and so the JPA specification doesn’t even say they’re supported.Instead, we should useSet,List, orMap.

Here, each collection element is stored as a separate row of the auxiliary table.By default, this table has the following definition:

Which is fine, but it’s still a mapping we prefer to avoid.

There’s much more we could say about "element collections", but we won’t say it, because we don’t want to hand you the gun you’ll shoot your foot with.

Let’s pause to remember the annotations we’ve met so far.

Phew!That’s already a lot of annotations, and we have not even started with the annotations for O/R mapping!

Entity classes should overrideequals() andhashCode(), especially when associations arerepresented as sets.

People new to Hibernate or JPA are often confused by exactly which fields should be included in thehashCode().And people with more experience often argue quite religiously that one or another approach is the only right way.The truth is, there’s no unique right way to do it, but there are some constraints.So please keep the following principles in mind:

• You should not include a mutable field in the hashcode, since that would require rehashing every collection containing the entity whenever the field is mutated.

• It’s not completely wrong to include a generated identifier (surrogate key) in the hashcode, but since the identifier is not generated until the entity instance is made persistent, you must take great care to not add it to any hashed collection before the identifier is generated. We therefore advise against including any database-generated field in the hashcode.

It’s OK to include any immutable, non-generated field in the hashcode.

In this example, theequals() andhashCode() methods agree with the@NaturalId annotation:

That said, an implementation ofequals() andhashCode() based on the generated identifier of the entity can workif you’re careful.

InEntity class inheritance we saw that entity classes may exist within an inheritance hierarchy.There’s three basic strategies for mapping an entity hierarchy to relational tables.Let’s put them in a table, so we can more easily compare the points of difference between them.

The three mapping strategies are enumerated byInheritanceType.We specify an inheritance mapping strategy using the@Inheritance annotation.

For mappings with adiscriminator column, we should:

• specify the discriminator column name and type by annotating the root entity@DiscriminatorColumn, and

• specify the values of this discriminator by annotating each entity in the hierarchy@DiscriminatorValue.

For single table inheritance we always need a discriminator:

We don’t need to explicitly specify@Inheritance(strategy=SINGLE_TABLE), since that’s the default.

ForJOINED inheritance we don’t need a discriminator:

Similarly, forTABLE_PER_CLASS inheritance we have:

Notice that in this last case, a polymorphic association like:

is a bad idea, since it’s impossible to create a foreign key constraint that targets both mapped tables.

The following annotations specify exactly how elements of the domain model map to tables of the relational model:

The first two annotations are used to map an entity to itsprimary table and, optionally, one or moresecondary tables.

By default, an entity maps to a single table, which may be specified using@Table:

However, the@SecondaryTable annotation allows us to spread its attributes across multiplesecondary tables.

The@Table annotation can do more than just specify a name:

The@SecondaryTable annotation is even more interesting:

The@JoinTable annotation specifies anassociation table, that is, a table holding foreign keys of both associated entities.This annotation is usually used with@ManyToMany associations:

But it’s even possible to use it to map a@ManyToOne or@OneToOne association to an association table.

Here, there should be aUNIQUE constraint on one of the columns of the association table.

Here, there should be aUNIQUE constraint onboth columns of the association table.

To better understand these annotations, we must first discuss column mappings in general.

These annotations specify how elements of the domain model map to columns of tables in the relational model:

We’ll come back to the last two annotations much later, inOrdered and sorted collections and map keys.

We use the@Column annotation to map basic attributes.

The@Column annotation is not only useful for specifying the column name.