Java Persistence API (JPA)

The student will learn:

At the conclusion of this lecture and related exercises, the student will be able to:

The JPA standard was originally part of Java EE, which is now managed by the Eclipse Foundation within Jakarta. It was released just after Java 5, which was the first version of Java to support annotations. It replaced the older, heavyweight Entity Bean Standard — that was ill-suited for the job of realistic O/R mapping — and progressed on a path in line with Hibernate. There are several persistence providers of the API

JPA transitioned from Oracle/JavaEE to Jakarta in ~2019 and was officially renamed from "Java Persistence API" to "Jakarta Persistence". Official references dropped the "API" portion of the name and used the long name. Unofficial references keep the "API" portion of the name and still reference the product as "JPA". For simplicity — I will take the unofficial reference route and continue to refer to the product as "JPA" for short once we finish this background paragraph.

The last release of the "Java Persistence API" (officially known as "JPA") was 2.2 in ~2017. You will never see a version of the "Java Persistence API" newer than 2.2.x. "Jakarta Persistence" (unofficially known as "JPA") released a clone of the "Java Persistence API" version 2.2.x under the jakarta Maven package naming to help in the transition. "Jakarta Persistence" 3.0 was released in ~2020 with just package renaming from javax.persistence to jakarta.persistence. Enhancements were not added until JPA 3.1 in ~2022. That means the feature set remained idle for close to 5 years during the transition.

Spring Boot 2.7 advanced to jakarta.persistence:jakarta.persistence-api:jar:2.2.3, which kept the javax.persistence Java package naming. Spring Boot 3 advanced to jakarta.persistence:jakarta.persistence-api:jar:3.x.x, which required all Java package references to change from javax.persistence to jakarta.persistence. With a port to Spring Boot 3/Spring 6, we have finally turned the corner on the javax /jakarta naming issues.

Access to JPA requires declaring a dependency on the JPA interface (jakarta.persistence-api) and a provider implementation (e.g., hibernate-core). This is automatically added to the project by declaring a dependency on the spring-boot-starter-data-jpa module.

The following shows a subset of the dependencies brought into the application by declaring a dependency on the JPA starter.

From these dependencies, we can define and inject various JPA beans.

JPA has its own defined bootstrapping constructs that involve settings in persistence.xml and entity mappings in orm.xml configuration files. These files define the overall persistence unit and include information to connect to the database and any custom entity mapping overrides.

Spring Boot JPA automatically configures a default persistence unit and other related beans when the @EnableJpaRepositories annotation is provided. @EntityScan is used to identify packages for @Entities to include in the persistence unit.

By default, this configuration will scan packages below the class annotated with the @EntityScan annotation. We can override that default using the attributes of the @EntityScan annotation.

Spring Boot provides convenient ways to provide property-based configurations through its standard property handing, making the connection areas of persistence.xml unnecessary (but still usable). The following examples show how our definition of the DataSource for the JDBC/SQL example can be used for JPA as well.

JPA provides the capability to automatically generate schema from the Persistence Unit definitions. This can be configured to write to a file to be used to kickstart schema authoring. However, the most convenient use for schema generation is at runtime during development.

Spring Boot will automatically enable runtime schema generation for in-memory database URLs. We can also explicitly enable runtime schema generation using the following Hibernate property.

The JPA provider can be configured to generate schema to a file. This can be used directly by tools like Flyway or simply to kickstart manual schema authoring.

The following configuration snippet instructs the JPA provider to generate a create and drop commands into the same drop_create.sql file based on the metadata discovered within the Persistence Context. Hibernate has the additional features to allow for formatting and line termination specification.

action can have values of none, create, drop-and-create, and drop ^[1]

create/drop-source can have values of metadata, script, metadata-then-script, or script-then-metadata. metadata will come from the class defaults and annotations. script will come from a location referenced by create/drop-script-source

The following snippet shows the output of the Entity Manager when provided with the property activations and configuration. The specific output contains all SQL commands required to drop existing rows/schema (by the same name(s)) and instantiate a new version based upon the @Entity metadata.

It is useful to see database SQL commands coming from the JPA/Hibernate layer during early stages of development or learning. The following properties will print the JPA SQL commands and values mapped to the SQL substitution variables.

The first two property settings both functionally produce logging of SQL statements.

An additional property can be defined to show the mapping of data to/from the database rows. The logging.level.org.hibernate.orm.jdbc.bind property controls whether Hibernate prints the value of binding parameters (e.g., "?") input to or returning from SQL commands. It is quite helpful if you are not getting the field data you expect.

The following snippet shows the result information of the activated debug. We can see the individual SQL commands issued to the database as well as the parameter values used in the call and extracted from the response. The extra logging properties have been redacted from the output.

Spring Boot JPA will automatically scan for @Entity classes. We can provide a specification to external packages to scan using the @EntityScan annotation.

The following shows an example of using a String package specification to a root package to scan for @Entity classes.

The following example, instead uses a Java class to express a package to scan. We are using a specific @Entity class in this case, but some may define an interface simply to help mark the package and use that instead. The advantage of using a Java class/interface is that it will work better when refactoring.

The JPA Persistence Unit represents the overall definition of a group of Entities and how we interact with the database. A defined Persistence Unit can be injected into the application using an EntityManagerFactory. From this injected instance, clients can gain access to metadata and initiate a Persistence Context.

It is rare that you will ever need an EntityManagerFactory and could be a sign that you may not understand yet what it is meant for versus an injected EntityManager. EntityManagerFactory is used to create a custom persistence context and transaction. The caller is responsible for beginning and commiting the transaction — just like with JDBC. This sometimes is useful to create a well-scoped transaction within a transaction. It is a manual process, outside the management of Spring.

Your first choice should be to inject an EntityManager.

A Persistence Context is a usage instance of a Persistence Unit and is represented by an EntityManager. An injected EntityManager provides a first-layer cache of entities for business logic to share and transaction(s) to commit or rollback their state together. An @Entity with the same identity is represented by a single instance within a Persistence Context/EntityManager.

Injected EntityManagers reference the same Persistence Context when called within the same thread. That means that a Song loaded by one client with ID=1 will be available to sibling code when using ID=1.

By convention and supplied annotations, the class as shown above would:

All the convention defaults can be customized by further annotations. We commonly need to:

We create a new object in the database by calling persist() on the EntityManager and passing in an @Entity instance that represents something new. This will:

The following snippet shows a partial DAO implementation using JPA.

A database INSERT SQL command will be queued to the database as a result of a successful call and the @Entity instance will be in a managed state.

In the managed state, any changes to the @Entity will result in either the changes be part of:

Updates are issued during the next JPA session "flush". JPA session flushes can be triggered manually or automatically prior to or no later than the next commit.

JPA supplies a means to get the full @Entity using its primary key.

If the instance is not yet loaded into the Persistence Context, SELECT SQL command(s) will be issued to the database to obtain the persisted state. The following snippet shows the SQL generated by Hibernate to fetch the state from the database to realize the @Entity instance within the JVM.

From that point forward, the state will be returned from the Persistence Context without the need to get the state from the database.

JPA provides many types of queries

The following snippet shows an example of executing a JPQL Query.

The following shows how our JPQL snippet mapped to the raw SQL issued to the database. Notice that our Song @Entity reference was mapped to the REPOSONGS_SONG database table.

Not every change to an @Entity and call to an EntityManager results in an immediate 1:1 call to the database. Some of these calls manipulate an in-memory cache in the JVM and may get issued in a group of other commands at some point in the future. We normally want to allow the EntityManager to cache these calls as much as possible. However, there are times (e.g., before making a raw SQL query) where we want to make sure the database has the current state of the cache.

The following snippet shows an example of flushing the contents of the cache after changing the state of a managed @Entity instance.

Whether it was explicitly issued or triggered internally by the JPA provider, the following snippet shows the resulting UPDATE SQL call to change the state of the database to match the Persistence Context.

JPA provides a means to delete an @Entity from the database. However, we must have the managed @Entity instance loaded in the Persistence Context first to use this capability. The reason for this is that a JPA delete can optionally involve cascading actions to remove other related entities as well.

The following snippet shows how a managed @Entity instance can be used to initiate the removal from the database.

The following snippet shows how the remove command was mapped to a SQL DELETE command.

There are two commands that will remove entities from the Persistence Context. They have their purpose, but know that they are rarely used and can be dangerous to call.

I only bring these up because you may come across class examples where I am calling flush() and clear() in the middle of a demonstration. This is purposely mimicking a fresh Persistence Context within scope of a single transaction.

Calling clear() or detach() will evict all managed entities or targeted managed @Entity from the Persistence Context — loosing any in-progress and future modifications. In the case of returning redacted @Entities — this may be exactly what you want (you don’t want the redactions to remove data from the database).

The injected EntityManager is the target of our application calls, and the transaction gets associated with that object. The following snippet shows the provider throwing a TransactionRequiredException when the calling persist() on the injected EntityManager when no transaction has been activated.

Although you will find transaction methods on the EntityManager, these are only meant for individually managed instances created directly from the EntityManagerFactory. Transactions for injected an EntityManager are managed by the container and triggered by the presence of a @Transactional annotation on a called bean method within the call stack.

This next example annotates the calling @Test method with the @Transactional annotation to cause a transaction to be active for the three (3) contained EntityManager calls.

Nested calls annotated with @Transactional, by default, will continue the current transaction.

Logically speaking, the transaction handling done on behalf of @Transactional is similar to the snippet shown below. However, as complicated as that is — it does not begin to address nested calls. Also note that a thrown RuntimeException triggers a rollback and anything else triggers a commit.

We can alternatively push the demarcation of the transaction boundary down to the @Component methods.

The snippet below shows a DAO @Component that designates each of its methods being @Transactional. This has the benefit of knowing that each of the calls to EntityManager methods will have the required transaction in place. Whether a new one is the right one is a later topic.

The following example shows the calling code invoking methods of the DAO @Component in independent transactions. The code works because there really is no dependency between the INSERT and SELECT to be part of the same transaction, as long as the INSERT commits before the SELECT transaction starts.

The following shows the SQL triggered by the snippet above with the different transactions annotated.

However, we do not always get that lucky — for individual, sequential transactions to play well together. JPA entities follow the notation of managed and unmanaged/detached state.

The following snippet shows an example of where a follow-on method fails because the EntityManager requires that @Entity be currently managed. However, the end of the create() transaction made it detached.

The following text shows the error message thrown by the EntityManager.remove call when a detached entity is passed in to be deleted.

We can get things to work better if we encapsulate methods behind a @Service method defining good transaction boundaries. Lacking a more robust application, the snippet below adds the @Transactional to the @Test method to have it shared by the three (3) DAO @Component calls — making the @Transactional annotations on the DAO meaningless.

There are several attributes that can be set on the @Transactional annotation. A few of the more common properties to set include