An Introduction to Hibernate 6

Hibernate was the inspiration behind the Java (now Jakarta) Persistence API, or JPA, and includes a complete implementation of the latest revision of this specification.

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

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:

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 a flaw. 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:

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:

We’re going to come 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 simple gradle build file:

Only the first of these dependencies is absolutely required to run Hibernate.

Next, we’ll add a logging configuration file for log4j:

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

Finally, let’s see code which configures and instantiates Hibernate and asks it to persist and query the entity. Don’t worry if this makes no sense at all right now. It’s the job of this Introduction to make all this crystal clear.

Here we’ve used Hibernate’s native APIs. We could have used JPA-standard APIs to achieve the same thing.

If we limit ourselves to the use of JPA-standard APIs, we need to use XML to configure Hibernate.

Note that our build.gradle and log4j2.properties files are unchanged.

Our entity class is also unchanged from what we had before.

Unfortunately, JPA doesn’t offer an inSession() method, so we’ll have to implement session and transaction management ourselves. We can put that logic in our own inSession() function, so that we don’t have to repeat it for every transaction. Again, you don’t need to understand any of this code right now.

In practice, we never access the database directly from a main() 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 the next chapter, and come back later.

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

Therefore, many developers quickly—even too 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 a bottom-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 also finish 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 the fromTransaction() method, which happens to come built in to Hibernate. But you might prefer to use something else, for example:

The important thing is that calls like createEntityManager() and getTransaction().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 a query 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 it at startup time, that is, when the SessionFactory is created, instead of when the query is first executed. Indeed, since we included the Metamodel Generator in our Gradle build, the query can even be validated at compile time.

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

Notice that our query method doesn’t attempt to hide the EntityManager from its clients. Indeed, the client code is responsible for providing the EntityManager or Session to the query method. This is a quite distinctive feature of our whole approach.

The client code may:

Whatever the case, the code which orchestrates a unit of work usually just calls the Session or EntityManager 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 not very 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.

Fortunately, there’s now a solution to both problems: as an incubating feature of Hibernate 6.3, we now offer the possibility to have the Metamodel Generator fill in the implementation of such query methods for you. This facility is the topic of a whole chapter of this introduction, so for now we’ll just leave you with one simple example.

Suppose we simplify Queries to just the following:

Then the Metamodel Generator automatically produces an implementation of the method annotated @HQL in a class named Queries_. We can call it just like we called 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.

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:

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 least some 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 is extremely 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. We usually do this when we create the Hibernate SessionFactory or JPA EntityManager, and so traditionally we’ve used a configuration property for this.

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

Alternatively, in Hibernate 6, we may use the new SchemaManager API to export the schema, just as we did above.

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:

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

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 file import.sql, and place it in the root classpath, that’s all we need to do.

Otherwise, we need to specify the file in the configuration property jakarta.persistence.sql-load-script-source. If we’re using Configuration to configure Hibernate, we could write:

The SQL script will be executed every time exportMappedObjects() or truncateMappedObjects() 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:

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

Let’s now consider a different approach to code organization, one we treat with suspicion.

Hibernate is an architecture-agnostic library, not a framework, and therefore integrates comfortably with a wide range of Java frameworks and containers. Consistent with our place within the ecosystem, we’ve historically avoided giving out much advice on architecture. This is a practice we’re now perhaps inclined to regret, since the resulting vacuum has come to be filled with advice from people advocating architectures, design patterns, and extra frameworks which we suspect make Hibernate a bit less pleasant to use than it should be.

In particular, frameworks which wrap JPA seem to add bloat while subtracting some of the fine-grained control over data access that Hibernate works so hard to provide. These frameworks don’t expose the full feature set of Hibernate, and so the program is forced to work with a less powerful abstraction.

The stodgy, dogmatic, conventional wisdom, which we hesitate to challenge for simple fear of pricking ourselves on the erect hackles that inevitably accompany such dogma-baiting is:

We lack the courage—perhaps even the conviction—to tell you categorically to not follow this recommendation. But we do ask you to consider the cost in boilerplate of any architectural layer, and whether the benefits this cost buys are really worth it in the context of your system.

To add a little background texture to this discussion, and at the risk of our Introduction degenerating into a rant at such an early stage, we’re going ask you to humor us while talk a little more about ancient history.

Ultimately, we’re not sure you need a separate persistence layer at all. At least consider the possibility that it might be OK to call the EntityManager directly from your business logic.

We can already hear you hissing at our heresy. But before slamming shut the lid of your laptop and heading off to fetch garlic and a pitchfork, take a couple of hours to weigh what we’re proposing.

OK, so, look, if it makes you feel better, one way to view EntityManager is to think of it as a single generic "repository" that works for every entity in your system. From this point of view, JPA is your persistence layer. And there’s few good reasons to wrap this abstraction in a second abstraction that’s less generic.

Even where a distinct persistence layer is appropriate, DAO-style repositories aren’t the unambiguously most-correct way to factorize the equation:

Indeed, repositories, by nature, exhibit very low cohesion. A layer of repository objects might make sense if you have multiple implementations of each repository, but in practice almost nobody ever does. That’s because they’re also extremely highly coupled to their clients, with a very large API surface. And, on the contrary, a layer is only easily replaceable if it has a very narrow API.

Phew, let’s move on.

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

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

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.

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

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

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

You might also add the Hibernate bytecode enhancer to your Gradle build if you want to use field-level lazy fetching.

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

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

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

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

We may obtain an EntityManagerFactory by calling Persistence.createEntityManagerFactory():

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

Alternatively, the venerable class Configuration allows an instance of Hibernate to be configured in Java code.

The Configuration class has survived almost unchanged since the very earliest (pre-1.0) versions of Hibernate, and so it doesn’t look particularly modern. On the other hand, it’s very easy to use, and exposes some options that persistence.xml doesn’t support.

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

The class AvailableSettings 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 by java.sql.DatabaseMetaData.getDatabaseProductName(), for example, PostgreSQL, MySQL H2, Oracle, EnterpriseDB, MariaDB, or Microsoft 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:

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-managed DataSource.

You can have Hibernate infer your database schema from the mapping annotations you’ve specified in your Java code, and export the schema at initialization time by specifying one or more of the following configuration properties:

This feature is extremely useful for testing.

As we mentioned earlier, 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 property hibernate.show_sql to true, and Hibernate will log SQL direct 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 category org.hibernate.SQL using your preferred SLF4J logging implementation.

For example, if you’re using Log4J 2 (as above in Optional dependencies), add these lines to your log4j2.properties file:

But with this approach we miss out on the pretty 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 in Object/relational mapping:

By default, SQL Server’s char and varchar 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 the nchar and nvarchar column types.

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

An entity must:

On the other hand, the entity class may be either concrete or abstract, 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 Introduction, since it’s not our preferred way to do things.

Each entity class has a default access type, either:

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

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

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

An entity class may extend 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:

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 by GenerationType:

For example, this UUID is generated in Java code:

This id maps to a SQL identity, auto_increment, or bigserial column:

The @SequenceGenerator and @TableGenerator annotations allow further control over SEQUENCE and TABLE 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 size allocationSize, 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 named bookSeq:

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

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-defined Generators, which we’ll discuss in User-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 called natural 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 called composite 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:

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 a Book and pass to methods like find() 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 override equals() and hashCode(). Of course, the easiest way to satisfy these requirements is to declare the id class as a record.

The @IdClass annotation of the Book entity identifies BookId as the id class to use for that entity.

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

We’ll learn more about Embeddable 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 use BookId to obtain instances of Book:

An entity may have an attribute which is used by Hibernate for optimistic lock checking. A version attribute is usually of type Integer, Short, Long, LocalDateTime, OffsetDateTime, ZonedDateTime, or Instant.

Version attributes are automatically assigned by Hibernate when an entity is made persistent, and automatically incremented or updated each time the entity is updated.

The @Id and @Version attributes we’ve already seen are just specialized examples of basic 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, we considered 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’s extremely 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 a UNIQUE constraint on the columns mapped by the annotated fields.

The payoff for doing this extra work, as we will see much 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 model much easier to change.

A basic 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 inferred NOT NULL by default.

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

In Hibernate 6, an enum annotated @Enumerated(STRING) is mapped to:

Any other enum is mapped to a TINYINT column with a CHECK constraint.

An interesting special case is PostgreSQL. Postgres supports named ENUM types, which must be declared using a DDL CREATE TYPE statement. Sadly, these ENUM types aren’t well-integrated with the language nor well-supported by the Postgres JDBC driver, so Hibernate doesn’t use them by default. But if you would like to use a named enumerated type on Postgres, just annotate your enum attribute like this:

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

A JPA AttributeConverter is responsible for:

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

There are two ways to apply a converter:

For example, the following converter will be automatically applied to any attribute of type BitSet, and takes care of persisting the BitSet to a column of type varbinary:

On the other hand, if we don’t set autoapply=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:

When mapping a basic attribute, we may explicitly specify a JavaType, a JdbcType, or both.

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

For example, IntegerJavaType knows how to convert an Integer or int value to the types Long, BigInteger, and String, among others.

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

For a user-written JavaType, the annotation is more useful:

Alternatively, the @JavaTypeRegistration annotation may be used to register BitSetJavaType as the default JavaType for BitSet.

A org.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:

By pairing LongJavaType with VarcharJdbcType in holy matrimony, we produce a basic type which maps Longs and primitive longss to the SQL type VARCHAR.

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-written JdbcType as the default for a given SQL type code.

If a given JavaType doesn’t know how to convert its instances to the type required by its partner JdbcType, we must help it out by providing a JPA AttributeConverter to perform the conversion.

For example, to form a basic type using LongJavaType and TimestampJdbcType, we would provide an AttributeConverter<Long,Timestamp>.

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

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 our Name 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 is never polymorphic. One @Embeddable class F may inherit a second @Embeddable class E, but an attribute of type E will always refer to an instance of that concrete class E, never to an instance of F.

Usually, embeddable types are stored in a "flattened" format. Their attributes map columns of the table of their parent entity. Later, in Mapping 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.

An association is a relationship between entities. We usually classify associations based on their multiplicity. If E and F are both entity classes, then:

An association between entity classes may be either:

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.

Let’s 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, the Book table has a foreign key column holding the identifier of the associated Publisher.

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 the Publisher of a given Book, but we would also like to be able to obtain all the Books belonging to a given publisher.

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

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

The Publisher.books field is called the unowned side of the association.

Now, we passionately hate the stringly-typed mappedBy reference to the owning side of the association. Thankfully, the Metamodel Generator gives us a way to make it a bit more typesafe:

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

To modify a bidirectional association, we must change the owning side.

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

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

We’ll see how to map a collection with a persistent order much 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 a UNIQUE constraint.

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

Here, the Author table has a foreign key column holding the identifier of the associated Person.

We can make this association bidirectional by adding a reference back to the Author in the Person entity:

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

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, the Author class must be annotated like this:

Notice that, compared with the previous mapping:

This lets Hibernate know that the association to Person is the source of primary key values for Author.

Here, there’s no extra foreign key column in the Author table, since the id column holds the identifier of Person. That is, the primary key of the Author table does double duty as the foreign key referring to the Person table.

The Person 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 separate association 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 to Book, but this time we must specify mappedBy to indicate that this is the unowned side of the association:

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

We’ve again used Sets to represent the association. As before, we have the option to use Collection or List. But in this case it does 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, lets recall that JPA treats byte[] and char[] arrays as basic types. Hibernate persists a byte[] or char[] array to a VARBINARY or VARCHAR column, respectively.

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

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

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 our Event entity as an attribute of type DayOfWeek[] or List<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 an ARRAY-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, but it’s important to limit the amount of storage space the database allocates to the ARRAY column. By writing @Array(length=7) here, we specified that DDL should be generated with the column type TINYINT ARRAY[7].

Just for fun, we used an enumerated type in the code above, but the array element time may be almost any basic type. For example, the Java array types String[], UUID[], double[], BigDecimal[], LocalDate[], and OffsetDateTime[] are all allowed, mapping to the SQL types VARCHAR(n) ARRAY, UUID ARRAY, FLOAT(53) ARRAY, NUMERIC(p,s) ARRAY, DATE ARRAY, and TIMESTAMP(p) WITH TIME ZONE ARRAY, respectively.

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

JPA does 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 be proxied, and so the JPA specification doesn’t even say they’re supported. Instead, we should use Set, List, or Map.

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 override equals() and hashCode(), especially when associations are represented as sets.

People new to Hibernate or JPA are often confused by exactly which fields should be included in the hashCode(). 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:

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

In this example, the equals() and hashCode() methods agree with the @NaturalId annotation:

That said, an implementation of equals() and hashCode() based on the generated identifier of the entity can work if you’re careful.

In Entity 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 by InheritanceType. We specify an inheritance mapping strategy using the @Inheritance annotation.

For mappings with a discriminator column, we should:

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.

For JOINED inheritance we don’t need a discriminator:

Similarly, for TABLE_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 its primary table and, optionally, one or more secondary 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 multiple secondary tables.

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

The @SecondaryTable annotation is even more interesting:

The @JoinTable annotation specifies an association 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 a UNIQUE constraint on one of the columns of the association table.

Here, there should be a UNIQUE constraint on both 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 use the @Column annotation to map basic attributes.

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

Here we see four different ways to use the @Column annotation:

We don’t use @Column to map associations.

The @JoinColumn annotation is used to customize a foreign key column.

A foreign key column doesn’t necessarily have to refer to the primary key of the referenced table. It’s quite acceptable for the foreign key to refer to any other unique key of the referenced entity, even to a unique key of a secondary table.

Here we see how to use @JoinColumn to define a @ManyToOne association mapping a foreign key column which refers to the @NaturalId of Book:

In case this is confusing:

Note that the foreignKey member is completely optional and only affects DDL generation.

For composite foreign keys we might have multiple @JoinColumn annotations:

If we need to specify the @ForeignKey, this starts to get a bit messy:

For associations mapped to a @JoinTable, fetching the association requires two joins, and so we must declare the @JoinColumns inside the @JoinTable annotation:

Again, the foreignKey member is optional.

The @PrimaryKeyJoinColumn is a special-purpose annotation for mapping:

When mapping a subclass table primary key, we place the @PrimaryKeyJoinColumn annotation on the entity class: