OneToMany

// What mappedBy changes:

// Without mappedBy: Hibernate creates a join table and manages both sides itself.
@OneToMany
private List<OrderItem> items;          // tables: orders, order_items, orders_order_items

// With mappedBy: the foreign key lives on order_items.order_id, owned by OrderItem.order.
@OneToMany(mappedBy = "order")
private List<OrderItem> items;          // tables: orders, order_items (order_id FK)

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

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

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

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List<OrderItem> items = new ArrayList<>();

    protected Order() { }   // required by JPA

    public Order(String reference) {
        this.reference = reference;
    }

    // Keep both sides in step. These are the only way items should change.
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }

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

    public Long getId() { return id; }
    public String getReference() { return reference; }
    public List<OrderItem> getItems() { return Collections.unmodifiableList(items); }
}

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

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

    // Owning side: this is the order_id column. @ManyToOne is EAGER unless told otherwise.
    @ManyToOne(fetch = FetchType.LAZY, optional = false)
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;

    @Column(nullable = false)
    private String productName;

    @Column(nullable = false)
    private int quantity;

    @Column(nullable = false, precision = 10, scale = 2)
    private BigDecimal unitPrice;

    protected OrderItem() { }

    public OrderItem(String productName, int quantity, BigDecimal unitPrice) {
        this.productName = productName;
        this.quantity = quantity;
        this.unitPrice = unitPrice;
    }

    // Identity: equal when both are persisted and share an id; a new item equals only itself.
    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof OrderItem other)) return false;
        return id != null && id.equals(other.getId());   // getId(), so lazy proxies work
    }

    @Override
    public int hashCode() {
        return getClass().hashCode();   // stable before and after the id is assigned
    }

    public Long getId() { return id; }
    public Order getOrder() { return order; }
    void setOrder(Order order) { this.order = order; }   // package-private: Order controls it
    public String getProductName() { return productName; }
    public int getQuantity() { return quantity; }
    public void setQuantity(int quantity) { this.quantity = quantity; }
    public BigDecimal getUnitPrice() { return unitPrice; }
}

@Service
public class OrderService {

    private final OrderRepository orders;

    public OrderService(OrderRepository orders) {
        this.orders = orders;
    }

    @Transactional
    public Long place(String reference, List<NewItem> newItems) {
        Order order = new Order(reference);
        newItems.forEach(i ->
            order.addItem(new OrderItem(i.productName(), i.quantity(), i.unitPrice())));
        return orders.save(order).getId();   // 1 insert for the order, then one per item
    }

    @Transactional
    public void addItem(Long orderId, NewItem item) {
        Order order = orders.findByIdWithItems(orderId).orElseThrow();
        order.addItem(new OrderItem(item.productName(), item.quantity(), item.unitPrice()));
        // No save() call: the order is managed, so the new row is inserted at commit.
    }

    @Transactional
    public void removeItem(Long orderId, Long itemId) {
        Order order = orders.findByIdWithItems(orderId).orElseThrow();
        order.getItems().stream()
            .filter(i -> i.getId().equals(itemId))
            .findFirst()
            .ifPresent(order::removeItem);   // orphanRemoval issues the DELETE at commit
    }

    @Transactional
    public void delete(Long orderId) {
        orders.deleteById(orderId);   // loads the order, deletes each item, then the order
    }
}

// Unidirectional, with a join column: no join table, but needs nullable = false
// to avoid insert-then-update.
@Entity
@Table(name = "users")
public class User {

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

    @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true)
    @JoinColumn(name = "user_id", nullable = false)   // FK lives on the roles table
    private Set<Role> roles = new HashSet<>();
}

// Value collections: no entity, no cascade, rows have no identity.
@Entity
public class Customer {

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

    @ElementCollection
    @CollectionTable(name = "customer_phone_numbers",
                     joinColumns = @JoinColumn(name = "customer_id"))
    @Column(name = "phone_number", nullable = false)
    private Set<String> phoneNumbers = new HashSet<>();

    @ElementCollection
    @CollectionTable(name = "customer_addresses",
                     joinColumns = @JoinColumn(name = "customer_id"))
    private List<Address> addresses = new ArrayList<>();   // Address is @Embeddable
}

public interface OrderRepository extends JpaRepository<Order, Long> {

    // LEFT JOIN so orders with no items are still returned.
    @Query("select o from Order o left join fetch o.items where o.id = :id")
    Optional<Order> findByIdWithItems(@Param("id") Long id);

    // Same idea via an entity graph, handy with derived queries.
    @EntityGraph(attributePaths = "items")
    Optional<Order> findByReference(String reference);

    // Paging safely: step 1, page the ids (a plain, fast query, paginated in SQL).
    @Query("select o.id from Order o")
    Page<Long> findIds(Pageable pageable);

    // Step 2, fetch the items for only those orders.
    @Query("select o from Order o left join fetch o.items where o.id in :ids")
    List<Order> findAllWithItemsByIdIn(@Param("ids") List<Long> ids);
}

// Usage:
//   Page<Long> ids = orderRepository.findIds(PageRequest.of(0, 20, Sort.by("id")));
//   List<Order> orders = orderRepository.findAllWithItemsByIdIn(ids.getContent());
//   // The second query does not preserve page order: sort the result by id before returning it.

// Anti-pattern: this paginates in memory and logs a warning.
// @Query("select o from Order o left join fetch o.items")
// Page<Order> findAllWithItems(Pageable pageable);

spring:
  jpa:
    open-in-view: false          # see the pitfalls section; avoids hidden lazy loading in controllers
    properties:
      hibernate:
        default_batch_fetch_size: 25    # load lazy collections for up to 25 parents per query

logging:
  level:
    org.hibernate.SQL: DEBUG     # count the statements per request to spot N+1 early

# Per-collection alternative, on the field itself:
#   @OneToMany(mappedBy = "order")
#   @BatchSize(size = 25)
#   private List<OrderItem> items = new ArrayList<>();

// Composition: the parent owns the lifecycle.
@OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
private List<OrderItem> items = new ArrayList<>();

// Association between independent entities: no cascade, no orphanRemoval.
@OneToMany(mappedBy = "department")
private List<Employee> employees = new ArrayList<>();

// Unbounded children: skip the collection, query by the child's foreign key instead.
public interface OrderRepository extends JpaRepository<Order, Long> {
    Page<Order> findByCustomerId(Long customerId, Pageable pageable);
}

// A caution: orphanRemoval only works when you modify the existing collection.
// Replacing it breaks the mapping and Hibernate throws an exception:
//   order.setItems(new ArrayList<>(newItems));   // don't
//   order.getItems().clear(); newItems.forEach(order::addItem);   // do (via helpers)

// Return a DTO, not the entity:
public record OrderDto(Long id, String reference, List<ItemDto> items) {

    public static OrderDto from(Order order) {   // call inside @Transactional
        return new OrderDto(
            order.getId(),
            order.getReference(),
            order.getItems().stream().map(ItemDto::from).toList());
    }
}

public record ItemDto(String productName, int quantity, BigDecimal unitPrice) {
    public static ItemDto from(OrderItem i) {
        return new ItemDto(i.getProductName(), i.getQuantity(), i.getUnitPrice());
    }
}

// Lombok on entities: avoid @Data. If you must, keep relationships out of the generated methods.
// @Getter
// @ToString(exclude = "items")
// @EqualsAndHashCode(onlyExplicitlyIncluded = true)