The previous lesson ended on an irony: BiblioTech has a @Transactional on lend that does absolutely nothing, because there is no database underneath that could commit or roll back. All the persistence is still what it was in module 7: hand-written CSV files.

This lesson replaces them with a real relational database.

Hibernate is the most widely used ORM in the Java world, and the reference implementation of Jakarta Persistence (formerly JPA). Its job is to translate between two worlds that do not fit together: the world of objects, with inheritance, references and navigation; and the world of tables, with rows, columns and foreign keys. That job is tedious, repetitive and easy to get wrong, and that is why a tool exists to automate it.

But an ORM is not a transparent layer you can use without understanding it. It is probably the piece most people abuse without knowing what is going on: queries that multiply by a hundred, exceptions that appear outside the transaction, entities that save themselves without anybody calling save, and production schemas destroyed by one misplaced property. All of that has an explanation, and this lesson gives it.

The advantage you arrive with is the usual one: Hibernate reads @Entity and @Column by reflection, exactly as your AnnotatedExporter read @CsvField. And Spring Data JPA will give you working repositories without writing the implementation, using the same Proxy.newProxyInstance from 10-03.

By the end you will know what an ORM automates and what it costs; you will map complete entities and relationships; you will understand the persistence context and an entity's states; you will know why the LazyInitializationException appears and what the N+1 problem is, with its solutions; you will write JPQL queries with parameters —and know why concatenating strings is a vulnerability—; you will handle transactions, propagation and optimistic locking; and BiblioTech will store its data in H2 with Material, Employee and Loan as real entities.

1. The object-relational mismatch
2. What you gain and what you lose compared with JDBC
3. JDBC in twenty lines: the baseline
4. JPA versus Hibernate: specification and implementation
5. Getting JPA running with H2 in BiblioTech
6. The first entity: @Entity, @Table, @Id
7. @GeneratedValue and its strategies
8. @Column and type mapping
9. @Enumerated: why STRING and never ORDINAL
10. LocalDate, Instant and your own converters
11. @Embeddable and @Embedded
12. Relationships: the four types
13. The owning side and mappedBy
14. FetchType: lazy versus eager loading
15. The LazyInitializationException
16. The N+1 problem
17. Solving it: JOIN FETCH and @EntityGraph
18. CascadeType and orphanRemoval
19. The persistence context and the EntityManager
20. The four states of an entity
21. Automatic dirty checking
22. flush and the ordering of operations
23. The operations: persist, merge, find, getReference, remove
24. Queries: JPQL
25. Named queries, the Criteria API and native SQL
26. SQL injection: why you never concatenate
27. Transactions: @Transactional with a real database
28. Propagation and isolation
29. Optimistic locking with @Version
30. First- and second-level caches
31. ddl-auto and why never update in production
32. Spring Data JPA
33. BiblioTech: from CSV to H2
34. Common Mistakes and Tips
35. Exercises

The problem has a name of its own: the object-relational impedance mismatch. The object model and the relational model were invented for different things and they do not fit together naturally.

The concrete points of friction:

Look at the inheritance row, because it is the most brutal: the relational model has no inheritance. BiblioTech's sealed Material hierarchy, which in 10-06 allowed exhaustive switch expressions checked by the compiler, simply cannot be expressed in SQL. Somebody has to decide how it is represented, and there are three different strategies, each with its trade-offs.

And the navigation row is the one that causes the most performance problems: in Java, loan.material().publisher() is free; in SQL, every hop can be a query. That is where section 16's N+1 problem comes from.

An ORM (Object-Relational Mapper) is a tool that translates automatically between the two worlds. It does not remove the mismatch: it manages it. And knowing it exists is the difference between using Hibernate well and suffering it.

Honestly, because there are strong opinions in both directions and both are partly right.

The reasonable professional rule:

• ORM for the domain CRUD, which is 80% of the code of a business application: saving a loan, loading an employee, updating a material.
• Direct SQL (JDBC, JdbcTemplate or jOOQ) for reports, complex aggregations and bulk processing.

The two coexist perfectly well in the same project, and that is what BiblioTech does.

To understand what Hibernate automates, you first have to see what had to be written. This is pure JDBC reading loans:

What is in there, and what Hibernate is going to eliminate:

1. Hand-written SQL for every query.
2. Column-by-column mapping, with getLong, getString, getDate.
3. Type conversion: java.sql.Date to LocalDate, null to Optional.empty().
4. Resource management: three nested try-with-resources.
5. Exception translation: SQLException into module 6's hierarchy.
6. Column names as strings: a misspelled "due_date" fails at runtime.

Multiply that by the forty queries of a real application and by six entities, and you get several thousand lines that add no value and have to be maintained every time a column changes.

JDBC is not bad. It is low-level. With Hibernate, that whole query becomes:

And you do not even have to write that line, as you will see in section 32.

Another classic confusion worth clearing up.

Jakarta Persistence (JPA) is a specification: a set of standardised interfaces and annotations, in the jakarta.persistence package. It defines EntityManager, @Entity, @Id, @OneToMany, JPQL... but it contains no working code.

Hibernate is an implementation of that specification. It is what actually generates the SQL, manages the persistence context and talks to the database.

The practical recommendation: program against JPA whenever you can and use Hibernate extensions only when you genuinely need them. It is the same facade principle you will see with SLF4J in 11-07.

Version warning, important. Jakarta EE renamed every javax.* package to jakarta.*. Spring Boot 3 and Hibernate 6 use jakarta.persistence. If you copy an example with import javax.persistence.Entity, it is from Spring Boot 2 or earlier and it will not compile. It is the most frequent copy-and-paste error today.

Two dependencies added to 11-02's pom.xml:

And the configuration in application.yml:

That is all it takes. Run:

And at start-up you will see the conditions from section 19 of 11-02 being met: DataSourceAutoConfiguration detects H2 on the classpath, sees that you have not defined a DataSource, and creates one. HibernateJpaAutoConfiguration detects Hibernate and assembles the EntityManagerFactory and the transaction manager. Zero configuration code.

Two notes about show-sql: it is indispensable while you are learning —you are going to see exactly what SQL Hibernate generates, and that is half the learning— and it must be switched off in production, where proper logging goes through SLF4J (11-07):

We turn BiblioTech's Book into an entity:

The requirements JPA imposes on an entity, worth knowing because the errors are cryptic:

And there you have why a record cannot be a JPA entity: it is final, its fields are final and it has no no-argument constructor. BiblioTech's record types (Card, SessionSummary) will still be perfect as DTOs and as query projections, but entities have to be mutable classes. It is a real ORM trade-off, not a whim.

About @Table: if you leave it out, the table is named after the class. Putting it in explicitly is good practice, because Loan would map to a table LOAN, and words such as ORDER, USER or GROUP are reserved in SQL and give bewildering errors.

Who generates the primary key. It is a decision with a real performance impact.

The recommendation with Hibernate 6 and a database that supports sequences:

The reason allocationSize matters: with IDENTITY, Hibernate cannot batch inserts, because it needs to execute each INSERT so the engine returns the id. With SEQUENCE and allocationSize=50, it can accumulate 50 inserts and send them as one batch. On an import of 10,000 materials, the difference is minutes.

For this lesson's H2 examples we will use IDENTITY for simplicity, but know the reason SEQUENCE is preferred in production.

@Column describes the column. Its useful attributes:

The types JPA maps automatically:

Two concrete warnings about BiblioTech:

One: never double for money. It was said back in 01-04 and here it matters more than ever. Fines are BigDecimal with explicit precision and scale:

Two: Optional is not mapped. Optional<LocalDate> returnDate was an excellent decision in 10-04 for the public API, but JPA cannot persist Optional. The solution is a nullable field and a getter that returns Optional:

That way you keep 10-04's guarantee —callers never receive null— and JPA can persist the field. It is the standard pattern.

BiblioTech has had three enums since module 4: Severity, MaterialType and LoanStatus. Mapping them has a trap with serious consequences.

Why ORDINAL is dangerous. With it, the database stores 0, 1, 2. Now imagine that six months from now somebody adds a status in its logical place:

Every loan stored with 1 (OVERDUE) now reads as RENEWED, and the 2s (RETURNED) as OVERDUE. All the historical data is silently corrupted. No exception, no warning. It is discovered weeks later, when somebody is chased for a fine on a book they returned.

On top of that, ORDINAL makes the database unreadable: SELECT * FROM loans returns numbers that mean nothing.

The rule is absolute: @Enumerated(EnumType.STRING), always. ORDINAL's space saving does not remotely compensate for the risk. And the most dangerous part is that ORDINAL is the default: if you forget the annotation, you get the bad behaviour.

Good news: since JPA 2.2, java.time maps natively. All the work from 10-05 carries straight over:

The distinction from 10-05 is still the right one: LocalDate for business dates (a loan falls due "on the 20th", with no time and no zone) and Instant for audit timestamps (an absolute instant on the timeline).

And java.util.Date and Calendar are never used again. If you see @Temporal(TemporalType.DATE) in an example, it is pre-Java 8 code.

And what if you want to persist a type JPA does not know? That is where AttributeConverter comes in. BiblioTech has a record Isbn as a value object:

The converter:

With autoApply = true, any Isbn field is converted on its own. Without it, you have to mark it:

This lets you have value objects with validation in the domain and simple columns in the database: the best of both worlds. Other common uses: encrypting a sensitive field, storing a short list as a comma-separated string, or mapping a boolean to 'Y'/'N' in a legacy database.

An embeddable is an object that has no identity of its own and whose fields are stored in the same row as the entity containing it. It gives structure to the object model without creating tables.

Usage:

The resulting table has columns publisher, year, language, original_publisher, original_year... in the same row of materials. There is no publication_data table and no JOIN.

It is the answer to section 1's granularity problem: you can have small, cohesive objects in Java without fragmenting the schema.

BiblioTech's model:

• A Loan belongs to one Material and one Employee.
• A Material has many Loans.
• An Employee has many Loans and many Reservations.
• A Material has many Category values and a Category has many Materials.

The loans table will have material_id and employee_id columns with foreign keys.

Those convenience methods are not optional in practice: if you add to the list without setting the field on the other side, the relationship is not persisted (section 13) and the in-memory state is left inconsistent too.

A known trap: an optional @OneToOne on the inverse side cannot be lazy with proxies, because Hibernate needs to query in order to know whether there is a row. If performance matters, make it optional = false or use a shared primary key.

A much-repeated piece of professional advice: a pure @ManyToMany falls short almost always. As soon as you need an attribute on the relationship —the date the category was assigned, who assigned it— you have to turn it into an intermediate entity with two @ManyToOnes. Many teams model the intermediate entity from the start.

Summary:

This is a concept that confuses nearly everybody and causes the "I saved it and nothing was saved" bug.

In a relational database, the relationship is a single column: the foreign key. In Java, a bidirectional relationship is two fields. Somebody has to decide which of the two is in charge.

The owning side is the one that holds the foreign key. It is the only one Hibernate looks at in order to persist the relationship. The other side carries mappedBy and is read-only as far as persistence is concerned.

The consequence:

The practical rule: whenever you have a bidirectional relationship, write convenience methods that update both sides. Never manipulate the collections directly from outside.

When you load a Loan, should Hibernate also load its Material and its Employee? That decision is FetchType, and it is the decision with the greatest performance impact in the whole lesson.

JPA's defaults are, unfortunately, inconsistent:

Why @ManyToOne's default EAGER is bad: imagine Loan has eager @ManyToOnes to Material and Employee, and Material has an eager @ManyToOne to Publisher, which has another to Country. Loading one loan drags in five tables. And you pay that cost always, even when all you wanted was the due date.

Professional rule: set fetch = FetchType.LAZY explicitly on ALL associations. And when you need the related data, ask for it explicitly in the query with JOIN FETCH or @EntityGraph.

How a lazy proxy works, and here module 10 returns: when you load a Loan, Hibernate does not put a Material in the field. It puts an object of a generated subclass of Material that has no data, only the id. The first time you call material.getTitle(), that subclass intercepts the call, fires the SELECT and returns the value.

It is your dynamic proxy from 10-03 again, and from it come two consequences you already know:

• An entity cannot be final: the subclass could not be generated.
• While debugging you will see objects called Material$HibernateProxy$xYz123. That is your material, unloaded.

The flip side of lazy loading, and one of the most famous exceptions in the Java world.

What happened, step by step:

1. Inside the transaction, Hibernate loaded the loan and put a proxy in the material field.
2. The transaction ended and the persistence context was closed.
3. On calling getTitle(), the proxy tries to fire the SELECT... and there is no longer a session to do it with.

The solutions, from best to worst:

1. Fetch what you need in the query (the correct one):

2. Return a DTO instead of the entity (the best architecturally):

That LoanCard can perfectly well be a record — where they do fit beautifully.

3. Widen the transaction to cover the usage: sometimes a valid solution, but keeping transactions open longer than necessary has its own cost.

4. spring.jpa.open-in-view=true: discouraged, even though it is Spring Boot's default. It keeps the persistence context open for the whole HTTP request, so the exception never appears... and in exchange it hides the N+1 problem, keeps connections busy for longer and causes queries from the presentation layer. That is why section 5's application.yml explicitly contains:

A tip: keeping it at false makes the LazyInitializationException appear on your machine instead of the performance problem appearing in production.

The number one performance problem of ORMs. And it is so easy to cause that almost everybody has it without knowing.

With 500 loans, the show-sql log shows:

501 queries where there should be one. At 2 ms of latency per query, a whole second lost. And if you add the employee, it is 1001.

The insidious part: in development, with 5 test loans, it is instantaneous. The problem appears in production with real data, and by then the cause is a loop that looks harmless.

An important note: switching to EAGER does not fix it. With EAGER, Hibernate always loads the associations, but it very often does so with one query per entity anyway. All you achieve is having the problem always, even when you were not going to use the materials.

How to detect it:

1. spring.jpa.show-sql=true and count the queries in the log.
2. Hibernate statistics: spring.jpa.properties.hibernate.generate_statistics=true.
3. In production: metrics and distributed tracing (12-07).

Two solutions, both from the specification.

Now a single query is generated:

From 501 queries to 1.

Watch out for one detail: a JOIN FETCH over a collection can duplicate rows. If you fetch an employee with their 5 loans, the JOIN returns 5 rows and you could get the employee repeated. It is solved with SELECT DISTINCT or by asking for a Set. And a known limitation: you cannot efficiently paginate a collection JOIN FETCH; Hibernate warns that it is paginating in memory. In that case, the solution is to fetch the paginated ids in one query and the full entities in another.

The advantage: the same method can have several graphs, and there is no JPQL to write.

The DTO projection deserves a separate mention because it is the most efficient solution for reports:

One query, only four columns, no managed entities and no risk of N+1. And LoanCard is a record — which finally finds its place in the persistence layer.

Cascades propagate operations from the parent to the children.

orphanRemoval = true means: if you remove a child from the collection, delete it from the database.

The difference from CascadeType.REMOVE:

A serious warning: CascadeType.ALL on relationships where the child has a life of its own is a source of data loss. If Material had cascade = ALL on its loans, withdrawing a book would delete its entire loan history, with its fines and its audit trail. Use cascades only when the relationship is genuine composition (the child does not exist without the parent).

Here is JPA's conceptual heart, and what separates those who understand Hibernate from those who suffer it.

The EntityManager is the gateway into JPA. And it manages a persistence context: a cache of entities where every entity loaded or saved stays managed for as long as the transaction lasts.

Three properties of the persistence context, all with consequences:

1. It is a first-level cache. If you ask for the same entity twice in the same transaction, the second time generates no query.
2. It guarantees identity. Within a transaction, the same row is always the same Java object: a == b is true. That solves section 1's identity problem.
3. It detects changes automatically. That is section 21, and it is the most surprising part.

In Spring, the EntityManager is injected like this:

That injected EntityManager is not a real instance: it is a proxy that on each call looks up the persistence context bound to the current thread's transaction. Once again, the same mechanism from module 10.

Every entity is in one of four states, and knowing which one is the key to understanding what Hibernate is going to do.

The example that clears everything up:

And the classic error it produces:

For a change to a detached entity to be saved, it has to be re-attached with merge (section 23).

This is the most surprising thing about JPA, and at the same time the most powerful.

How? The mechanism is called dirty checking and it works like this:

1. On loading the entity, Hibernate stores a snapshot of the state of all its fields.
2. On flush (normally on commit), it compares the current state with the snapshot.
3. For every differing field, it generates the corresponding UPDATE.

The practical consequences, all of them important:

One: you do not need to call save on managed entities. A great deal of Spring Data code calls save() unnecessarily. It does no harm, but it is noise.

Two: any accidental modification is persisted. If inside a transaction you touch a field of a managed entity "just to calculate something", that change goes to the database. It is a real source of baffling bugs.

Three: readOnly = true switches it off and saves work.

On queries returning many entities the difference is measurable. It is a good habit to mark readOnly = true on every read-only method.

Four: the cost grows with the number of managed entities. Loading 100,000 entities in one transaction means every flush compares 100,000 snapshots. For bulk processing you have to clear the context periodically with entityManager.clear().

flush is the moment when Hibernate actually writes the pending SQL to the database. It is not the same as commit.

When it happens automatically:

1. On committing the transaction (always).
2. Before running a query that could be affected by the pending changes.
3. When you call entityManager.flush() explicitly.

And here comes a surprising detail: Hibernate does not execute the SQL in the order in which you call the methods. It reorders the operations like this:

1. Entity INSERTs, in persist order
2. UPDATEs
3. Removal of collection elements
4. Insertion of collection elements
5. Entity DELETEs

That is why this code can fail incomprehensibly:

The solution is to force the order:

Understanding that there is "pending SQL" executed later and reordered explains half of Hibernate's odd behaviour.

The rule: always use the object merge returns. Ignoring the return value is an extremely frequent mistake.

All the INSERT needs is the material_id, and getReference has it. You save one SELECT per operation. The flip side: if you access any property of the proxy outside the session, you get a LazyInitializationException, and if the id does not exist, the error arrives late (EntityNotFoundException on access, not on requesting the reference).

JPQL (Jakarta Persistence Query Language) looks like SQL but operates on entities and their Java attributes, not on tables and columns.

Complete examples over BiblioTech:

A warning about that last one: bulk modification queries run directly on the database and do not update entities already loaded in the persistence context, which are left out of sync. After one of those, an em.clear() is advisable.

Key differences from SQL:

They are declared on the entity and validated at start-up, not on execution:

A real advantage: a syntax error in the JPQL stops the application from starting, instead of blowing up the day somebody runs that report.

For queries built dynamically —a search screen with five optional filters— concatenating JPQL by hand is ugly and dangerous. JPA offers a typed API:

It is verbose, and that is why many people prefer Spring Data's Specification or QueryDSL. It is mentioned so you know it exists and what it is for; in practice it is not used much.

When you need an engine-specific function, a heavily optimised query or a complex report:

It is perfectly legitimate. An ORM does not force you to do everything with it, and pretending otherwise leads to convoluted JPQL that nobody understands. The only loss is portability between engines.

This is not a style recommendation. It is a security vulnerability.

If email comes from a form or from an API parameter, an attacker can send:

And the query becomes:

which returns every loan of every employee. With native SQL the consequences are worse: depending on the engine and the permissions, an attacker can end up reading other tables or modifying data.

The solution is always the same, and it is trivial:

With parameters, the value is never interpreted as part of the query: it travels separately and is treated as a literal piece of data, whatever it contains. It is the same reason section 3's JDBC example used a PreparedStatement with ? and setString.

The rule, without exceptions: every value coming from outside goes in as a parameter. Not even "when I know it is a number" — because tomorrow that code gets copied somewhere it is not.

The only things that cannot be parameterised are table and column names and the direction of an ORDER BY. If you need those to be dynamic, validate them against an allow-list of permitted values; never concatenate them as they come.

Application security —input validation, authorisation, secrets management, headers— is covered in 12-07. Here the rule is enough: always parameters.

Now that there is a database, 11-02's @Transactional actually does something.

A transaction satisfies the ACID properties:

BiblioTech's case:

If auditLog.record fails, everything is rolled back: the copy becomes available again and no orphan loan is left behind. Without a transaction, one fewer copy and an unaudited loan would remain, and nobody would know why.

Remember the two rules from 11-02, which still hold here: rollback only on unchecked exceptions by default, and internal calls do not go through the proxy.

The case where REQUIRES_NEW is the right answer:

Careful: REQUIRES_NEW consumes a second connection from the pool while the first is still open. Overusing it exhausts the pool and causes deadlocks. Use it only when independence is a genuine requirement.

The three phenomena, with BiblioTech:

• Dirty read: you read a copy as being on loan and that transaction rolls back. You read something that never existed.
• Non-repeatable read: you read available_copies = 1, somebody else lends it, you read again and there is 0. Two reads, two results.
• Phantom read: you count 3 active loans, somebody inserts one, you repeat the query and there are 4.

In practice, isolation is almost never touched. READ_COMMITTED with optimistic locking (the next section) solves 99% of cases at far less cost than raising the level.

The concrete case, which picks up module 8 directly:

Marta Ruiz and Diego Alonso open the record for "Effective Java" at the same time; it has 1 available copy. Both click "Lend" in the same second.

It is exactly the race condition from 08-04, but distributed: here synchronized is of no use whatsoever, because the two users can be on different instances of the application.

Two strategies:

Optimistic locking is a single annotation:

With that, every UPDATE includes the version that was read in the condition:

If somebody else has already updated, the row has version=6 and the condition matches no row. Hibernate detects it and throws:

Handling it properly:

That Result<T> is the generic type you wrote in 10-01, and it fits perfectly here. And that retry loop is, conceptually, your RetryProxy from 10-03: in a real project you would declare it with Spring Retry's @Retryable.

Pessimistic locking, when the operation is expensive and conflict is likely:

It generates SELECT ... FOR UPDATE: the second waits for the first. Correct, but with a real concurrency cost.

You already know the first-level one: it is section 19's persistence context. It cannot be switched off and it is what guarantees object identity.

The second-level one is optional and shared by every transaction. It needs a provider (Ehcache, Caffeine, Hazelcast):

When to enable it: data that is read a lot and changes little. BiblioTech's material catalogue or its categories are good candidates; the loans are not.

Warnings to bear in mind:

1. Coherence: if another application modifies the database, your cache goes stale and serves old data.
2. In a cluster: with several instances, each one has its own cache. Either you use a distributed cache or you will get inconsistencies.
3. Measure first: enabling the second-level cache "just in case" adds complexity with no demonstrated benefit. It is exactly what 10-07 said: measure before optimising.

Hibernate can generate the schema from your entities. It is convenient and dangerous.

Why update is never used in production, with concrete reasons:

1. It never deletes anything. If you remove a field, the column stays there forever. If you rename title to name, it adds name and leaves title — and it does not copy the data.
2. It versions nothing. There is no record of which changes were applied or when, and no way to undo them.
3. It is unpredictable. The SQL it generates depends on the dialect, the Hibernate version and the current state of the schema.
4. It cannot be reviewed beforehand. Nobody has seen the ALTER TABLE that is about to run against the production database.
5. It cannot do data migrations. Splitting full_name into first_name and surname needs logic no automatic tool can invent.

The correct configuration per environment:

validate is especially valuable: if the real schema does not match the entities, the application does not start, and that is much better than finding out through an error at three in the morning.

In production, the schema is managed with versioned migrations: numbered SQL files applied in order and recorded in a control table.

The advantages: the schema change is in git, it is reviewable, it is reproducible and it can be tested beforehand. It is developed in 12-06, alongside deployment.

The last piece, and the one that removes the most code.

With plain JPA, a repository is about eighty lines. With Spring Data JPA:

That already gives you save, findById, findAll, deleteById, count, existsById, pagination and sorting.

Spring Data analyses the method name and generates the query. The usual keywords:

A practical tip: derived names are fantastic until they stop being so. findByDueDateBeforeAndReturnDateIsNullAndStatusNot is unreadable. When the name goes beyond three conditions, use @Query.

If you do not need the total, Slice<T> avoids the COUNT and is faster.

LoanRepository is an interface with no implementation. Who runs findByStatus?

At start-up, Spring Data:

1. Scans the interfaces that extend Repository.
2. For each one, it creates an implementation on the fly with Proxy.newProxyInstance — the very one from 10-03.
3. The InvocationHandler receives each call, checks whether the method has @Query (and uses that JPQL) or analyses its name (and generates the JPQL), runs it with the EntityManager and adapts the result.

It is literally what you wrote in 10-03: a proxy over an interface that interprets the method's metadata and acts. The difference is the sophistication of the analysis, not the mechanism.

And there is a practical consequence: the repository can be replaced by a mock in tests with no difficulty at all, because it is an interface. That is exactly what 11-06 will do.

The complete result of the migration.

Here one of the ORM's real prices is paid, and it has to be said plainly: the sealed hierarchy from 10-06 disappears. A JPA entity cannot be sealed, a record or final. You lose the exhaustive switch expressions checked by the compiler and have to replace them with polymorphism or with instanceof checks. It is a conscious trade-off: you gain real persistence, queries and integrity; you lose part of the type model's expressiveness. An alternative design —and a frequent one in projects that value the domain highly— keeps the domain pure and uses separate JPA entities with a mapping between the two. That discussion belongs to 12-02.

The three inheritance strategies, so you know what you chose:

The repositories:

Seed data for development, in src/main/resources/data.sql:

Running it:

The before and after:

Mistake: javax.persistence instead of jakarta.persistence. The number one copy-and-paste error today. Spring Boot 3 and Hibernate 6 use jakarta.

Mistake: leaving @Enumerated at its default (ORDINAL). Reordering an enum silently corrupts all the historical data. Always EnumType.STRING.

Mistake: leaving @ManyToOne at EAGER. It is the default and it is bad. Set LAZY explicitly on every association and fetch what you need with JOIN FETCH.

Mistake: the N+1 problem without noticing. A loop over entities accessing a lazy relationship. Switch show-sql on in development and count the queries.

Mistake: spring.jpa.open-in-view=true. It is Spring Boot's default and it hides the N+1 until production. Set it to false.

Mistake: modifying only the inverse side of a relationship. employee.getLoans().add(l) without l.setEmployee(employee) persists nothing. Write convenience methods.

Mistake: ignoring merge's return value. merge(e) returns another instance; the original stays detached and its changes are lost.

Mistake: CascadeType.ALL without thinking. Deleting a material could delete its entire loan history.

Mistake: ddl-auto=update in production. It does not delete, does not version, does not migrate data and nobody reviews the SQL it is about to run. validate plus Flyway.

Mistake: concatenating values into a query. That is SQL injection. Parameters always, no exceptions.

Mistake: final entities, record entities or entities with final methods. Hibernate needs to generate proxy subclasses. Either the model will not compile or lazy loading will fail.

Mistake: equals and hashCode based on the generated id. Before persisting, the id is null; afterwards it changes, and an entity put into a HashSet can no longer be found. Use a business key (the isbn) or Hibernate's recommended pattern.

Tip: switch show-sql on while you are learning. Seeing the generated SQL is half the learning, and it teaches you to spot the N+1 instantly.

Tip: mark readOnly = true on query methods. It switches off dirty checking and saves real work.

Tip: use DTOs (record) for whatever leaves the service. Returning managed entities outside the transaction is the direct cause of the LazyInitializationException, and it also couples your internal API to the schema.

Tip: @Version on every entity modified concurrently. It costs one annotation and prevents lost updates.

Tip: do not do everything with the ORM. For reports and aggregations, native SQL or JdbcTemplate are better tools. It is legitimate and professional.

Tip: getReference when all you need is the reference in order to set an FK. It saves a SELECT per operation.

BiblioTech has reservations: when there are no copies, an employee reserves one and is notified when one is returned. This is module 10's record:

Turn it into a JPA entity that satisfies:

1. A reservations table with an auto-generated primary key.
2. Lazy @ManyToOne relationships to Material and Employee, not strings.
3. The enum stored safely.
4. notifiedAt nullable in the database but exposed as Optional.
5. Optimistic locking.
6. An index over (material_id, status) for the pending-reservations query.
7. A domain method markNotified(Clock clock) that changes the status and records the instant, with validation.
8. The Spring Data repository with: a material's pending reservations ordered by age, reservations expired before a date, and counting an employee's pending ones.

This service works fine with development's 5 loans and takes 9 seconds in production with 800.

You are asked to:

1. Work out how many SQL queries run with 800 loans, broken down.
2. Explain exactly why.
3. Propose three different solutions with their code, saying how many queries each leaves.
4. Say which one you would choose and why.

Marta Ruiz and Diego Alonso try to lend the last copy of "Refactoring" (978-0000000003, 1 copy) at the same time.

You are asked to:

1. Describe the exact sequence of events that produces two loans from a single copy.
2. Explain why synchronized (08-04) does not solve this in a real deployment.
3. Solve it with optimistic locking, including handling the exception with a retry.
4. Solve it with pessimistic locking.
5. Compare the two in a table and recommend one.

Solution 1

The repository (8):

Notable decisions:

• record → class: mandatory, because a record is final and has no empty constructor.
• Relationships instead of strings: Material and Employee instead of isbn and employeeEmail. It gives referential integrity (you cannot reserve a non-existent material) and navigation. The price is having to manage laziness.
• Optional outside, a nullable field inside: 10-04's guarantee is preserved without fighting JPA.
• The behaviour lives in the entity: markNotified, complete and hasExpired validate the transitions. The entity is not a bag of data.
• @EntityGraph on the first query: we know the employee's name is going to be read, so it is fetched in one go.

Solution 2

1. How many queries.

At 3-4 ms of latency per query, between 7 and 10 seconds. That matches the symptom.

2. Why. All three associations are lazy. The initial query fetches only the loans rows, with proxies in material and employee and a lazy collection in categories. Each access inside the map fires its own SELECT. In development, with 5 loans, that is 16 queries and nobody notices.

Solution A — JOIN FETCH (1 query if limited to scalars, 2 with the collection):

DISTINCT is necessary because the JOIN FETCH on the categories collection duplicates loan rows. 1 query. The limitation: you cannot paginate efficiently with a collection JOIN FETCH.

Solution B — @EntityGraph (declarative, same result):

The advantage: the service code is untouched and the same method can carry a different graph in another query. 1-2 queries.

Solution C — DTO projection (the most efficient):

1 query, and only 3 columns instead of all the columns of three tables. No managed entities, no dirty checking, no risk of a later N+1. For the categories you would need an additional query or STRING_AGG in native SQL.

Comparison:

4. Which to choose. For a read-only report, C. Reasons: it fetches only what is needed, there are no managed entities and no dirty checking, and —most importantly— it is structurally impossible for the N+1 to reappear, because there are no proxies that could fire. With A and B, somebody who adds an l.getMaterial().getPublisher().getCountry() to the format tomorrow has the problem back.

If the method had to return entities in order to modify them afterwards, B, because it is declarative and reusable.

Solution 3

1. The sequence.

It is a lost update: Diego's UPDATE was computed from a stale value. With READ_COMMITTED, neither transaction sees anything anomalous.

2. Why synchronized is no use. synchronized synchronises threads within a single JVM. In a real deployment there are several BiblioTech instances behind a load balancer (12-06), and Marta and Diego may be served by different processes, on different machines. A monitor in JVM A locks nothing in JVM B. Besides, even with a single instance, serialising every loan of every material through one lock would be an unnecessary bottleneck. The coordination has to be where the shared data is: in the database.

3. Optimistic locking.

What happens now at t8: Diego's UPDATE carries where id=1 and version=0, but the row already has version=1. It affects 0 rows, Hibernate throws OptimisticLockException and Spring translates it into OptimisticLockingFailureException. The retry reads again, sees available=0 and returns a correct business error.

Result<T> is 10-01's generic type, and the retry loop is your RetryProxy from 10-03 — which in a real project would be @Retryable(retryFor = OptimisticLockingFailureException.class, maxAttempts = 3).

4. Pessimistic locking.

It is worth adding a maximum wait time so as not to block indefinitely:

5. Comparison and recommendation.

Recommendation: optimistic locking. In BiblioTech, the chance of two people lending the same copy in the same second is tiny, and pessimistic locking would make the thousands of operations that never clash pay the cost of serialisation. @Version costs one annotation, does not penalise the normal case and works the same with one instance as with twenty.

Pessimistic locking is reserved for operations where conflict is the norm and the lost work is expensive: for example, a nightly process that recalculates every fine and does not want to retry five thousand times.

BiblioTech's CSVs are gone. There is a real database underneath, and you know exactly what is going on inside it.

You understand the object-relational mismatch an ORM exists to manage: double identity, inheritance that does not exist in SQL, navigation that is free in Java and costs queries in SQL, granularity, collections and types. And you know what you gain and what you lose compared with plain JDBC —which you saw in twenty lines, with its column-by-column mapping, its type conversion and its resource management— with the professional rule that follows: ORM for the domain CRUD, direct SQL for reports and bulk processing, and both coexisting without conflict.

You can tell JPA from Hibernate: specification (jakarta.persistence) versus implementation, with the recommendation to program against the specification and the version warning that today causes more compilation errors than any other — jakarta, never javax.

You know how to map entities: @Entity, @Table, @Id, the @GeneratedValue strategies with the real reason SEQUENCE beats IDENTITY (it allows insert batching), @Column with its attributes, and the requirements JPA imposes —a no-argument constructor, nothing final— that explain why a record cannot be an entity. You know the absolute rule of @Enumerated(EnumType.STRING), because ORDINAL is the default and reordering an enum silently corrupts all the historical data. You map LocalDate and Instant natively with the same distinction from 10-05, you write converters with AttributeConverter for value objects such as Isbn, and you use @Embeddable to have small objects in Java without fragmenting the schema.

You model complete relationships with their four types, you know that the owning side is the one holding the foreign key and that touching only the inverse side persists nothing —hence the convenience methods—, and you have mastered the decision with the greatest performance impact: FetchType. You know the defaults are inconsistent, that @ManyToOne comes as EAGER and that the professional rule is to set LAZY explicitly everywhere and ask for what you need in the query. You know the two consequences: the LazyInitializationException, with its four ranked solutions and the advice to leave open-in-view at false so the problem shows up on your machine and not in production; and the N+1 problem, which turns one query into 501 and is invisible with five test rows, with its solutions —JOIN FETCH, @EntityGraph, @BatchSize and, the most efficient for reports, the DTO projection, where record types finally find their place—. And you know that switching to EAGER fixes nothing: it makes it worse.

You understand the persistence context, which is JPA's conceptual heart: a first-level cache that guarantees the same row is the same object, with an entity's four states and its transitions. And with it, automatic dirty checking, which surprises everybody: you modify a managed entity, you call nothing, and on commit an UPDATE appears. You know how it works (snapshot and comparison), its four consequences —including that an accidental change is persisted— and why readOnly = true switches it off and saves real work. You know flush, which reorders the operations and explains half of Hibernate's odd behaviour, and the difference between persist and merge that causes the "I ignored the return value" bug.

You write queries: JPQL over entities and attributes, named queries validated at start-up, the Criteria API for dynamic cases, native SQL when it is the right call, and projections into record types in a single line. And you have internalised the rule that admits no exceptions: every external value goes in as a parameter, because concatenating is SQL injection —with an allow-list as the only way out when the dynamic part is a column name—.

You handle transactions with a real database: ACID, @Transactional with its two rules inherited from 11-02, readOnly, propagation with the legitimate case for REQUIRES_NEW and its cost in connections, and isolation with the three phenomena explained over BiblioTech and the advice hardly ever to touch it. And you solve the disputed-copy case with optimistic locking using @Version, understanding why module 8's synchronized is no use when there are several instances: the coordination has to be where the shared data is. With a retry over Result<T>, which is your generic from 10-01 and your RetryProxy from 10-03 turned into production code.

You know the first- and second-level caches and when the second is worth it —data read a lot and changed little, measured first—; and you know why ddl-auto=update is never used in production: it does not delete, does not version, does not migrate data and nobody reviews the ALTER TABLE it is about to run. validate plus versioned migrations with Flyway, which arrive in 12-06.

And you have watched Spring Data JPA turn eighty lines of repository into an empty interface, with methods derived from names, @Query for what does not fit in a name, and pagination. With the mechanism laid bare: Proxy.newProxyInstance over an interface, exactly the one from 10-03, analysing the method's metadata and generating the query.

BiblioTech now has real entities, relationships with referential integrity, ACID transactions, optimistic locking and indexed queries over H2. It starts with mvn spring-boot:run and its schema is created on its own.

And it still has not a single automated test.

That is now, by a long way, the most serious debt. You have just carried out an enormous migration: you have changed the domain model, turned record types into classes, replaced the entire persistence layer and introduced optimistic concurrency with retries. How do you know the fine calculation still gives the same result? That the limit of three loans per employee is still respected? That a loan falling due on a Sunday still triggers a notice on the Monday? The only honest answer today is: by starting the application and looking.

And there is something worse. That injectable Clock you introduced in 10-05, which went through Spring in 11-02 as a @Bean and which in this lesson has appeared in every LocalDate.now(clock) and every Instant.now(clock), exists exclusively so the code can be tested without waiting fifteen days. It has spent two modules waiting for somebody to make use of it.

In the next lesson it gets used. You will see what an automated test is and why you are already paying the cost of not having them; you will meet the testing pyramid and the whole of JUnit 5, from @Test and the Arrange-Act-Assert pattern to parameterised tests that verify twelve cases of the fine calculation in six lines; you will compare JUnit's assertions with AssertJ's; and you will discover what makes a design testable — and why everything you have done in the last two modules (constructor injection, interfaces at the boundaries, the injected Clock, the annotation-free domain) was pointing exactly there.

BiblioTech is about to get its first safety net.