Cache-Optimized Catalog Service

Speed up a read-heavy product catalog using the second-level cache.

Second-Level CacheFetch TypesPerformance

Overview

A product catalog is read far more often than it is written — thousands of shoppers browse the same handful of products between any two admin updates — which makes it the textbook case for Hibernate's second-level cache. The first-level cache (the `Session` itself) only lives as long as one session does and is useless across requests; the second-level cache sits at the `SessionFactory` level, shared across every session, and can hand back a `Product` that was loaded five requests ago without touching the database at all.

By the end of this tutorial you will have a `Product` entity marked `@Cacheable` and backed by a JCache/Ehcache second-level cache region, a related `Category` entity mapped with `FetchType.LAZY`, and a hands-on demonstration of the N+1 query problem — fetching ten products the naive way, watching Hibernate issue eleven separate queries, then fixing it with a `JOIN FETCH` HQL query that does the same job in one.

What You'll Build

A `Category` entity and a `Product` entity connected by a `@ManyToOne`/`@OneToMany` pair.
A second-level cache provider (Ehcache via JCache) configured in `hibernate.cfg.xml`.
A `@Cacheable` `Product` entity using `CacheConcurrencyStrategy.READ_WRITE`.
A deliberately naive loop that reproduces the N+1 query problem when reading products and their categories.
A `JOIN FETCH` HQL query that collapses N+1 queries into a single SQL join.
A before/after query-count comparison proving both fixes actually work.

Prerequisites

Everything from the Student-Course Enrollment System and Order Management System projects — `@Entity`, `@ManyToOne`, `@OneToMany`, HQL.
The idea of caching in general — trading a small amount of staleness risk for a large reduction in repeated work.
What FetchType.LAZY vs. FetchType.EAGER means: whether a related entity loads immediately or only when actually accessed.
Basic performance reasoning — why one query touching the database once is cheaper than many queries touching it repeatedly.
A JCache-compatible caching library on the classpath (Ehcache is used in this project) alongside `hibernate-jcache`.

Project Structure

Two entities, one deliberate performance problem, and two independent fixes. `Category` is the "one" side of a one-to-many with `Product`; every product belongs to exactly one category, and a category can have many products. `Product` is where both techniques in this project meet: it is the entity marked cacheable, and it is also the entity whose lazy `category` reference is what triggers the N+1 problem if fetched carelessly.

Entity	Purpose	Key Fields / Mapping
Category	One row per product category	id (PK), name, products (@OneToMany, mappedBy = "category")
Product	One row per product, second-level cached	id (PK), name, price, category (@ManyToOne, FetchType.LAZY), @Cacheable

Step 1: Map the Category and Product Entities

`Product.category` is deliberately `FetchType.LAZY`, which is actually already the JPA default for `@ManyToMany` and `@OneToMany` but NOT for `@ManyToOne` (whose spec default is `EAGER`) — so it has to be set explicitly here to override that default. Loading a `Product` should not force-load its `Category` unless something actually asks for `product.getCategory().getName()`; leaving `@ManyToOne` at its default `EAGER` setting is one of the most common accidental performance mistakes in real Hibernate code, and Step 4 shows exactly what goes wrong even with `LAZY` set correctly.

import jakarta.persistence.*;
import java.util.ArrayList;
import java.util.List;

@Entity
@Table(name = "categories")
public class Category {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String name;

    @OneToMany(mappedBy = "category")
    private List<Product> products = new ArrayList<>();

    public Category() {}
    public Category(String name) { this.name = name; }

    public Long getId() { return id; }
    public String getName() { return name; }
    public List<Product> getProducts() { return products; }
}

import jakarta.persistence.*;
import java.math.BigDecimal;

@Entity
@Table(name = "products")
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private BigDecimal price;

    // EAGER is @ManyToOne's JPA default — LAZY has to be set explicitly here, or
    // every Product load would also force-load its Category whether anything
    // needed it or not. This alone does not fix N+1 (see Step 4); it only makes
    // the extra query happen on demand instead of unconditionally.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id", nullable = false)
    private Category category;

    public Product() {}
    public Product(String name, BigDecimal price, Category category) {
        this.name = name;
        this.price = price;
        this.category = category;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public BigDecimal getPrice() { return price; }
    public Category getCategory() { return category; }
}

Step 2: Enable the Second-Level Cache

The second-level cache is off by default and has to be turned on in configuration before any `@Cacheable` annotation does anything at all. `hibernate.cache.use_second_level_cache` is the master switch, `hibernate.cache.region.factory_class` tells Hibernate which caching library implements the actual storage (Ehcache, via the JCache standard, here), and `hibernate.javax.cache.provider` points at that library's specific `CachingProvider` implementation class.

<!-- Additions to hibernate.cfg.xml from the first project's Step 3 -->
<property name="hibernate.cache.use_second_level_cache">true</property>
<property name="hibernate.cache.region.factory_class">jcache</property>
<property name="hibernate.javax.cache.provider">org.ehcache.jsr107.EhcacheCachingProvider</property>

<!-- Optional but recommended: also cache query results, not just entities by id -->
<property name="hibernate.cache.use_query_cache">true</property>

Second-Level Cache vs. First-Level Cache

The first-level cache (every `Session` has one automatically, no configuration needed) only avoids re-querying the same entity twice within one session. The second-level cache configured here lives at the `SessionFactory` level and is shared across every session in the application, which is what lets it actually save a round trip to the database between two completely unrelated requests.

Step 3: Mark Product as Cacheable

`@Cacheable` opts `Product` into the second-level cache now that Step 2 has turned the feature on globally; without it, `Product` would still be fetched from the database on every `session.get()` call even with caching enabled. `CacheConcurrencyStrategy.READ_WRITE` is chosen deliberately over the faster `READ_ONLY` strategy: a product catalog's prices and names do occasionally change (an admin edits a price), and `READ_WRITE` keeps cached data consistent with those writes at a small locking cost, whereas `READ_ONLY` would require evicting and re-caching an entity by hand after every update.

import jakarta.persistence.*;
import org.hibernate.annotations.Cache;
import org.hibernate.annotations.CacheConcurrencyStrategy;
import java.math.BigDecimal;

@Entity
@Table(name = "products")
@Cacheable                                                      // Opts this entity into the second-level cache enabled in Step 2
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)              // READ_WRITE keeps cached rows consistent after an update, at a small locking cost
public class Product {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private BigDecimal price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id", nullable = false)
    private Category category;

    public Product() {}
    public Product(String name, BigDecimal price, Category category) {
        this.name = name;
        this.price = price;
        this.category = category;
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public BigDecimal getPrice() { return price; }
    public Category getCategory() { return category; }
}

session.get() Behavior After Caching

Click Run to see what this code prints.

Step 4: See the N+1 Problem Firsthand

This loop looks completely reasonable and is exactly how the N+1 problem sneaks into real code: one query loads ten products (`FROM Product`), and then `product.getCategory().getName()` inside the loop triggers one additional lazy-load query per product, because `category` is `FetchType.LAZY` and Hibernate only fetches it the moment it is actually accessed. Ten products means one query to fetch them, plus ten more to resolve each one's category — eleven queries total to display data that could have been fetched in one.

// N+1 problem: 1 query for the products, then 1 more query PER product to
// resolve its lazy-loaded category the moment getCategory().getName() runs.
String hql = "FROM Product";
List<Product> products = session.createQuery(hql, Product.class).getResultList();   // Query #1

for (Product p : products) {
    // Each iteration triggers its own SELECT against categories, because
    // "category" was never loaded up front — this is the "+N" in "N+1".
    System.out.println(p.getName() + " - " + p.getCategory().getName());
}

Generated SQL — 10 Products, 11 Queries Total

Click Run to see what this code prints.

Step 5: Fix It With JOIN FETCH and the Cache

`JOIN FETCH` is HQL's explicit instruction to load an association eagerly for this one query, overriding the entity's normal `FetchType.LAZY` mapping without changing that mapping globally — a query-level override rather than a mapping-level one. Combined with `@Cacheable` from Step 3, the fix is layered: the first request pays for one efficient joined query instead of eleven separate ones, and every subsequent request for the same products can be served from the second-level cache without hitting the database again at all.

// JOIN FETCH: one query, eagerly loading category alongside each product —
// a query-scoped override of Product.category's normal LAZY mapping.
String hql = "SELECT p FROM Product p JOIN FETCH p.category";
List<Product> products = session.createQuery(hql, Product.class).getResultList();   // Just 1 query total

for (Product p : products) {
    System.out.println(p.getName() + " - " + p.getCategory().getName());   // No extra SELECT: category was already loaded
}

Generated SQL — 10 Products, 1 Query Total

Click Run to see what this code prints.

Approach	Queries for 10 Products	Second Read (Cached)
Naive lazy loop (Step 4)	11 (1 + 10)	11 again — no caching involved
JOIN FETCH (Step 5)	1	1 again unless the query cache from Step 2 also applies
JOIN FETCH + @Cacheable	1 (first time only)	0 — served from the second-level cache

Complete Code

The full `Category` and `Product` entities, cache configuration, and both the naive and fixed query methods, assembled from every step above.

@Entity
@Table(name = "categories")
public class Category {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String name;

    @OneToMany(mappedBy = "category")
    private List<Product> products = new ArrayList<>();

    public Category() {}
    public Category(String name) { this.name = name; }
    public Long getId() { return id; }
    public String getName() { return name; }
    public List<Product> getProducts() { return products; }
}

@Entity
@Table(name = "products")
@Cacheable
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)
public class Product {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private BigDecimal price;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id", nullable = false)
    private Category category;

    public Product() {}
    public Product(String name, BigDecimal price, Category category) {
        this.name = name;
        this.price = price;
        this.category = category;
    }
    public Long getId() { return id; }
    public String getName() { return name; }
    public BigDecimal getPrice() { return price; }
    public Category getCategory() { return category; }
}

public class ProductCatalogService {

    // Naive: reproduces the N+1 problem from Step 4. Kept here for comparison only.
    public List<Product> getAllProductsNaive(Session session) {
        return session.createQuery("FROM Product", Product.class).getResultList();
    }

    // Fixed: JOIN FETCH collapses the N+1 queries into one (Step 5).
    public List<Product> getAllProductsFetched(Session session) {
        return session.createQuery(
            "SELECT p FROM Product p JOIN FETCH p.category", Product.class
        ).getResultList();
    }

    // Cached single lookup: served from the second-level cache after the first call (Step 3).
    public Product getProductById(Session session, Long id) {
        return session.get(Product.class, id);
    }
}

Sample Run

Three operations showing the cache and the fetch fix working together against a catalog of ten products across two categories.

// 1. Naive read of all products (Step 4's N+1 problem)
List<Product> naive = catalogService.getAllProductsNaive(session);
naive.forEach(p -> System.out.println(p.getName() + " - " + p.getCategory().getName()));

Result

Click Run to see what this code prints.

// 2. Fixed read using JOIN FETCH (Step 5)
List<Product> fetched = catalogService.getAllProductsFetched(session);
fetched.forEach(p -> System.out.println(p.getName() + " - " + p.getCategory().getName()));

Result

Click Run to see what this code prints.

// 3. Repeated single-product lookup, showing the second-level cache at work
Product first = catalogService.getProductById(session, 5L);   // First call: hits the database
Product again = catalogService.getProductById(session2, 5L);  // Different session, same id

Result

Click Run to see what this code prints.

Extend This Project

Add `@Cache(usage = CacheConcurrencyStrategy.READ_WRITE)` to `Category` as well, and measure whether it reduces queries in the `JOIN FETCH` path further.
Enable `hibernate.generate_statistics` and read `sessionFactory.getStatistics().getSecondLevelCacheHitCount()` to get exact cache hit/miss counts instead of estimating from query logs.
Add a `Set<Product> findByCategory(String categoryName)` method using `JOIN FETCH` and measure its query count against an equivalent naive lazy-loading version.
Switch `Category` from `CacheConcurrencyStrategy.READ_WRITE` to `READ_ONLY` and explain in a comment why that would be unsafe if category names could ever be renamed.
Add pagination (`setFirstResult`/`setMaxResults`) to `getAllProductsFetched()` and confirm the query count stays at 1 regardless of catalog size.

Summary

You built a read-heavy catalog service that fights the two most common Hibernate performance problems from opposite directions: `@Cacheable` with `CacheConcurrencyStrategy.READ_WRITE` avoids re-querying the database for entities that rarely change, while `JOIN FETCH` collapses the classic N+1 query pattern into a single efficient join when a lazy association is genuinely needed on every row. Recognizing when data is read far more than it is written, and profiling actual query counts rather than guessing, is the same instinct that drives performance work in every real Hibernate application beyond this project.

Overview

Prerequisites

Project Structure

Step 1: Map the Category and Product Entities

Step 2: Enable the Second-Level Cache

Step 3: Mark Product as Cacheable

Step 4: See the N+1 Problem Firsthand

Step 5: Fix It With JOIN FETCH and the Cache

Complete Code

Sample Run

Extend This Project

Summary

More Hibernate Practice Builds

Student-Course Enrollment System

Order Management System