Entity Relationships & Associations

Modeling Relationships

18 min Lesson 1 of 13

Modeling Relationships

Relational databases model the world as tables connected by foreign keys. Object-oriented code models it as objects connected by references. The job of Hibernate — and JPA more broadly — is to map between these two worlds automatically. Before you touch a single annotation, you need to be clear about what kinds of associations exist, how many rows on each side participate, and which direction your Java code needs to navigate. Getting this mental model right saves you from the most common mapping mistakes developers make when they first approach the JPA specification.

The Four Association Multiplicities

JPA defines four annotations that capture how many instances of one entity relate to how many instances of another. Each maps directly to a foreign-key pattern in the database.

@OneToOne — one row in table A corresponds to exactly one row in table B. Example: a User has one UserProfile.
@OneToMany / @ManyToOne — one row in A corresponds to many rows in B. Example: one Customer has many Order rows. This is by far the most common pattern in business applications.
@ManyToMany — many rows in A correspond to many rows in B, requiring a join table. Example: a Student can enrol in many Course objects, and each course has many students.

Choosing the wrong multiplicity is a compile-time-passing, runtime-breaking mistake. Always determine cardinality from the data first, then pick the annotation.

Directionality: Unidirectional vs Bidirectional

Cardinality tells you how many; directionality tells you from which side you can navigate in Java code.

In a unidirectional association only one entity class holds a reference to the other. An Order holds a reference to its Customer, but Customer has no collection of orders. The database still has a foreign key, but Hibernate will not let you write customer.getOrders() because that field does not exist on the Java class.

In a bidirectional association both sides hold references. Order has a Customer field and Customer has a List<Order> field. You can navigate from either side. This is convenient for queries, but it introduces a new responsibility: you must keep both sides in sync in memory, or Hibernate will persist stale data.

Directionality is a Java concept, not a SQL one. The database always stores exactly one foreign-key column regardless of whether you map the association bidirectionally. Adding the inverse side to your Java class costs nothing in the schema — it only adds a navigable reference in the object graph.

A Concrete Domain to Work With

Throughout this tutorial the running example is an e-commerce domain with four entities: Customer, Order, OrderItem, and Product. Here is what the relationships look like before any annotations are applied:

// jakarta.persistence imports are used throughout this tutorial
// (Spring Boot 3 ships with Hibernate 6 which uses jakarta.* not javax.*)

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

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

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

    private String name;
    private String email;

    // bidirectional side — Customer knows about its Orders
    @OneToMany(mappedBy = "customer")
    private List<Order> orders;

    // getters / setters omitted for brevity
}

@Entity
@Table(name = "orders")
public class Order {

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

    // owning side of Customer <-> Order
    @ManyToOne
    @JoinColumn(name = "customer_id")
    private Customer customer;

    // owning side of Order <-> OrderItem
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items;
}

@Entity
@Table(name = "order_items")
public class OrderItem {

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

    @ManyToOne
    @JoinColumn(name = "order_id")
    private Order order;

    @ManyToOne
    @JoinColumn(name = "product_id")
    private Product product;

    private int quantity;
    private java.math.BigDecimal unitPrice;
}

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

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

    private String name;
    private java.math.BigDecimal price;

    // unidirectional — Product does NOT know which OrderItems reference it
    // (no field here pointing back to OrderItem)
}

Notice that Product does not hold a reference back to OrderItem. This is a deliberate unidirectional design choice: the product catalogue has no business reason to iterate over every order line that ever referenced it. Keeping it unidirectional simplifies the class and avoids loading a potentially enormous collection into memory.

The Owning Side and Why It Matters

In a bidirectional association, JPA requires you to designate one side as the owning side. The owning side is the one that Hibernate looks at to decide what to write to the foreign-key column. The other side is called the inverse side and is annotated with mappedBy.

The rule is simple: the side that holds the @JoinColumn is the owning side. In a @ManyToOne / @OneToMany pair, the @ManyToOne end always owns the relationship because that is the table that physically holds the foreign-key column.

If you only update the inverse side, Hibernate will not persist the change. Suppose you add an Order to customer.getOrders() but forget to set order.setCustomer(customer). Hibernate reads the owning side (order.customer), finds null, and writes NULL into the customer_id column — or throws a constraint violation. Always set both sides of a bidirectional relationship.

A Convenience Method for Both Sides

The standard Java idiom is to provide a helper method on one entity that sets both ends at once, eliminating the risk of forgetting the other side:

// Inside the Order class
public void addItem(OrderItem item) {
    items.add(item);      // update the inverse (collection) side
    item.setOrder(this);  // update the owning side
}

public void removeItem(OrderItem item) {
    items.remove(item);
    item.setOrder(null);
}

Callers then simply write order.addItem(item) and both sides stay consistent without the caller having to think about it.

Choosing Directionality in Practice

A useful heuristic: start with the minimum navigation your use cases actually need. Bidirectional associations are powerful but they introduce coupling — changes to one entity's lifecycle can accidentally affect the other. The following guidelines help:

If you only ever load the child starting from the parent (e.g. loading an order's items), a unidirectional @OneToMany from parent to children is enough.
If queries frequently start from the child and need the parent (e.g. loading an order item and needing its order's metadata), make it bidirectional so Hibernate can join efficiently.
For @ManyToMany, always prefer bidirectional so both sides of the join table can be queried without raw SQL.

Map what the domain demands, not what feels symmetric. It is tempting to add an inverse collection to every entity "just in case", but an unnecessary @OneToMany collection is loaded (lazily or eagerly) by Hibernate and adds overhead. Only add the inverse side when your application actually navigates in that direction.

Summary

Relationships in JPA are defined by two independent decisions: cardinality (@OneToOne, @OneToMany, @ManyToOne, @ManyToMany) and directionality (unidirectional or bidirectional). The owning side is the entity that holds the foreign-key column and is the only side Hibernate consults when writing to the database. On bidirectional associations you are responsible for keeping both Java references in sync — convenience helper methods on the entity are the standard way to enforce this. In the next lessons you will implement each association type in detail, starting with @OneToOne.