JPA — Java Persistence API

What is JPA — and Why Does It Matter?

JPA (Jakarta Persistence API, formerly Java Persistence API) is a specification — a set of interfaces and annotations in jakarta.persistence.* with no working implementation behind them. It standardizes how a Java object graph maps to relational database tables (Object-Relational Mapping) and defines a query language, JPQL, that operates on entities instead of table rows. JPA on its own does not execute a single SQL statement — it needs a provider that implements the spec. Hibernate is the dominant provider; EclipseLink and OpenJPA are the others still in active use.

Before JPA (2006), every ORM vendor had its own proprietary API — Hibernate 2.x had one API, TopLink had another. Switching providers meant rewriting data access code. JPA fixed that by giving providers a common contract to implement, the same way JDBC gave database vendors a common contract for drivers.

// BEFORE JPA — raw JDBC: you manage the connection, the mapping, and cleanup
Connection conn = DriverManager.getConnection(url);
PreparedStatement stmt = conn.prepareStatement(
    "SELECT * FROM customers WHERE id = ?");
stmt.setLong(1, customerId);
ResultSet rs = stmt.executeQuery();
Customer customer = null;
if (rs.next()) {
    customer = new Customer();
    customer.setId(rs.getLong("id"));
    customer.setName(rs.getString("full_name"));
}
rs.close(); stmt.close(); conn.close();

// AFTER JPA — mapping, connection handling, and resource cleanup are gone
Customer customer = em.find(Customer.class, customerId);

The Three Layers: JPA, Hibernate, and Spring Data JPA

This is the single most common source of confusion for developers coming into Spring projects: three names get used almost interchangeably, but they are three distinct layers stacked on top of each other.

Spring Data JPA does not replace Hibernate — it needs a JPA provider underneath it to function, and that provider is Hibernate by default in every Spring Boot starter. When CustomerRepository extends JpaRepository<Customer, Long> generates a working implementation from nothing but a method signature, it is Spring Data JPA parsing that method name, building a JPQL query, and delegating execution to the underlying EntityManager — which is, in turn, backed by Hibernate. Everything covered on this page is the middle and bottom layers: pure JPA and the concepts Hibernate implements underneath it. See Spring Data JPA for the repository abstraction layer on top.

Entities — Mapping Java Objects to Tables

An entity is a plain Java class annotated with @Entity that represents a row in a table. JPA imposes a small set of hard requirements on the class, and violating any of them either fails at startup or fails silently at runtime in ways that are painful to debug.

import jakarta.persistence.*;

@Entity
@Table(name = "customers")
public class Customer {

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

    @Column(name = "full_name", length = 100, nullable = false)
    private String name;

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

    @Column(name = "created_at", updatable = false)
    private Instant createdAt;

    // Required by JPA: a no-arg constructor, package-private or higher.
    // Hibernate uses it (via reflection) to instantiate entities before
    // populating fields — you never call this yourself.
    protected Customer() { }

    public Customer(String name, String email) {
        this.name = name;
        this.email = email;
        this.createdAt = Instant.now();
    }

    public Long getId() { return id; }
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    public String getEmail() { return email; }
}

Primary Key Generation Strategies

EntityManager and the Persistence Context

The EntityManager is the runtime interface to the persistence context — an in-memory first-level cache of managed entities scoped to a transaction. Every entity loaded through it is tracked: modify a field, and the change is written to the database at flush time with no explicit "save" call required.

@Stateless
public class CustomerRepository {

    @PersistenceContext
    private EntityManager em;

    public void createCustomer(Customer customer) {
        em.persist(customer);                       // INSERT — assigns the ID
    }

    public Customer findCustomer(Long id) {
        return em.find(Customer.class, id);   // SELECT, or returns from cache if already managed
    }

    public void renameCustomer(Long id, String newName) {
        Customer customer = em.find(Customer.class, id);
        customer.setName(newName);                  // no em.update() — dirty checking
    }                                                // detects the change and issues UPDATE at flush time

    public void deleteCustomer(Long id) {
        Customer customer = em.find(Customer.class, id);
        if (customer != null) em.remove(customer);  // DELETE at flush time
    }
}

Entity Lifecycle

NEW (Transient)          — created with `new`, not tracked by JPA
    ↓ em.persist()
MANAGED (Persistent)     — tracked; field changes flush to the DB automatically
    ↓ em.detach() / transaction ends / em.close()
DETACHED                 — no longer tracked; changes are silently ignored
    ↓ em.merge()          returns a new MANAGED copy — the original stays detached
MANAGED (again, on the merged copy)
    ↓ em.remove()
REMOVED                  — scheduled for deletion
    ↓ transaction commits
Deleted from the database

Relationships — Modeling Associations Between Entities

@OneToMany / @ManyToOne — bidirectional, with consistency helpers

@Entity
public class Customer {
    @Id @GeneratedValue
    private Long id;

    // mappedBy = the INVERSE side. It does not own the foreign key —
    // it only mirrors what @ManyToOne declares on Order.
    @OneToMany(mappedBy = "customer", cascade = CascadeType.PERSIST, orphanRemoval = true)
    private List<Order> orders = new ArrayList<>();

    // Helper methods keep both sides of the relationship in sync —
    // forgetting this is the #1 bidirectional-relationship bug.
    public void addOrder(Order order) {
        orders.add(order);
        order.setCustomer(this);
    }

    public void removeOrder(Order order) {
        orders.remove(order);
        order.setCustomer(null);
    }
}

@Entity
@Table(name = "orders")
public class Order {
    @Id @GeneratedValue
    private Long id;
    private BigDecimal total;

    // @ManyToOne is the OWNING side — it holds the foreign key column.
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id", nullable = false)
    private Customer customer;

    void setCustomer(Customer customer) { this.customer = customer; }
}

Cascade Types — what actually propagates

@ManyToMany — with an explicit join entity as the modern default

// The classic @ManyToMany + @JoinTable works, but the moment the join
// table needs its own data (e.g. quantity and price at time of sale), you
// need an explicit join entity anyway. Most teams model it explicitly from
// the start: an Order is linked to many Products through OrderItem rows.
@Entity
@Table(name = "order_items")
public class OrderItem {
    @EmbeddedId
    private OrderItemId id;

    @ManyToOne(fetch = FetchType.LAZY) @MapsId("orderId")
    private Order order;

    @ManyToOne(fetch = FetchType.LAZY) @MapsId("productId")
    private Product product;

    private int quantity;              // extra columns plain @ManyToMany can't express
    private BigDecimal unitPrice;   // captured at purchase time, not the live catalog price
}

Fetching Strategies and the N+1 Query Problem

@OneToMany and @ManyToMany default to FetchType.LAZY; @ManyToOne and @OneToOne default to FetchType.EAGER. That EAGER default on @ManyToOne is one of JPA's most-criticized design decisions, and it directly causes the most common performance bug in every JPA codebase: N+1 queries.

// 1 query to fetch all customers, then N additional queries — one per
// customer — the first time .getOrders() is touched inside the loop:
List<Customer> customers = em.createQuery("SELECT c FROM Customer c", Customer.class)
                                  .getResultList();          // query #1

for (Customer c : customers) {
    System.out.println(c.getOrders().size());  // queries #2..N+1
}
// 100 customers → 101 round-trips to the database instead of 1 or 2.

The fix is a fetch join, which retrieves the association in the same query using a single SQL JOIN:

List<Customer> customers = em.createQuery(
    "SELECT DISTINCT c FROM Customer c LEFT JOIN FETCH c.orders",
    Customer.class).getResultList();
// 1 query total. DISTINCT is required — the join multiplies customer rows
// once per order, and Hibernate needs it to de-duplicate the Java result.

Open Session in View (OSIV) — the Setting Everyone Ignores Until It Bites

Spring Boot ships with spring.jpa.open-in-view=true by default, and logs a warning about it on every startup that most developers have learned to ignore. OSIV keeps the persistence context (and its underlying database connection) open for the entire HTTP request, not just for the duration of the @Transactional service method.

// Without OSIV, this throws LazyInitializationException:
@GetMapping("/customers/{id}")
public Customer getCustomer(@PathVariable Long id) {
    Customer customer = customerRepository.findById(id).orElseThrow();
    // the @Transactional method that loaded `customer` has already returned,
    // its persistence context is closed, and `orders` was never fetched
    return customer;   // Jackson serialization touches customer.getOrders() here → boom
}

The production-grade fix is spring.jpa.open-in-view=false combined with fetching exactly what each endpoint needs — a fetch join or @EntityGraph in the repository method, or (better for read endpoints) a DTO projection that never touches the entity's lazy associations at all:

// DTO projection: no entity, no lazy loading, no OSIV dependency.
public record CustomerSummary(Long id, String name, long orderCount) {}

@Query("""
    SELECT new com.example.CustomerSummary(c.id, c.name, COUNT(o))
    FROM Customer c LEFT JOIN c.orders o
    GROUP BY c.id, c.name
    """)
List<CustomerSummary> summarize();

JPQL, the Criteria API, and Native SQL

JPQL — operates on entities and their fields, not tables and columns

List<Order> largeOrders = em.createQuery(
    "SELECT o FROM Order o WHERE o.total >= :minTotal ORDER BY o.placedAt", Order.class)
    .setParameter("minTotal", new BigDecimal("100.00"))
    .setFirstResult(0)
    .setMaxResults(20)
    .getResultList();

Long count = em.createQuery("SELECT COUNT(o) FROM Order o", Long.class)
                  .getSingleResult();

The Criteria API — type-safe queries built at compile time

JPQL is a string — typos and field renames only surface at runtime. The Criteria API builds the same query as a type-safe object graph, checked by the compiler, at the cost of considerably more verbose code:

CriteriaBuilder cb = em.getCriteriaBuilder();
CriteriaQuery<Order> query = cb.createQuery(Order.class);
Root<Order> root = query.from(Order.class);

query.select(root)
     .where(cb.greaterThanOrEqualTo(root.get("total"), new BigDecimal("100.00")))
     .orderBy(cb.asc(root.get("placedAt")));

List<Order> largeOrders = em.createQuery(query).getResultList();
// Most teams reserve Criteria for dynamic queries built from optional
// filters (search forms); JPQL for everything with a fixed shape.

Native SQL — the escape hatch, used sparingly

List<Customer> customers = em.createNativeQuery(
    "SELECT * FROM customers WHERE email LIKE ?1", Customer.class)
    .setParameter(1, "%@gmail.com")
    .getResultList();
// Loses database portability and JPQL's compile-time entity awareness —
// reach for it only for vendor-specific features JPQL can't express
// (window functions, full-text search, database-specific hints).

Concurrency: Optimistic and Pessimistic Locking

Optimistic locking — the default and correct choice for most apps

@Entity
public class Product {
    @Id @GeneratedValue
    private Long id;
    private int stockQuantity;

    @Version  // Hibernate adds "WHERE version = ?" to every UPDATE
    private Long version;
}

// If two checkout transactions load the same product row and both try to
// decrement stock, the second commit's WHERE version = ? matches zero rows
// and Hibernate throws OptimisticLockException — no row was silently
// overwritten. The caller decides whether to retry or fail the request.

Pessimistic locking — when lost updates are unacceptable and retries aren't viable

Product product = em.find(Product.class, id, LockModeType.PESSIMISTIC_WRITE);
// Issues SELECT ... FOR UPDATE — the database row-locks until the
// transaction commits. Other transactions requesting the same lock block.
// Trades throughput for a hard guarantee against concurrent writes —
// reach for it in payment capture, seat reservations, and inventory
// decrements where a lost update is not an acceptable outcome.

Entity Lifecycle Callbacks

@Entity
public class Product {
    @Id @GeneratedValue
    private Long id;
    private String name;
    private Instant createdAt;
    private Instant updatedAt;

    @PrePersist
    void onCreate() { createdAt = Instant.now(); }

    @PreUpdate
    void onUpdate() { updatedAt = Instant.now(); }

    @PostLoad
    void afterLoad() { /* e.g. warm a transient computed field */ }
}

Best Practices and Common Pitfalls

Interview Questions