JPA Cascade Types: ALL, PERSIST, MERGE, REMOVE and orphanRemoval

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

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

    private String reference;

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

    protected PurchaseOrder() { }
    public PurchaseOrder(String reference) { this.reference = reference; }

    // Keep both sides of the association in sync
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }

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

    public List<OrderItem> getItems() { return items; }
}

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

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

    private String name;
    private int quantity;
    private BigDecimal unitPrice;

    @ManyToOne(fetch = FetchType.LAZY)       // no cascade: an item must never delete its order
    @JoinColumn(name = "order_id", nullable = false)
    private PurchaseOrder order;

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

    void setOrder(PurchaseOrder order) { this.order = order; }
}

PurchaseOrder order = new PurchaseOrder("REF-001");
order.addItem(new OrderItem("Widget", 2, new BigDecimal("9.99")));
order.addItem(new OrderItem("Gadget", 1, new BigDecimal("49.99")));

orderRepository.save(order);        // new parent -> em.persist(order) -> persist cascades to both items
// INSERT INTO orders ...
// INSERT INTO order_items ...      (one per item, at flush)

// Problem case: a detached child in a persist cascade
OrderItem detachedItem = itemRepository.findById(5L).orElseThrow();   // detached after its transaction ended
PurchaseOrder another = new PurchaseOrder("REF-002");
another.addItem(detachedItem);
orderRepository.save(another);
// PersistentObjectException: detached entity passed to persist: OrderItem

// Preferred: change managed entities inside a transaction. No merge needed.
@Transactional
public PostResponse updateComment(Long postId, Long commentId, UpdateCommentRequest req) {
    Post post = postRepository.findByIdWithComments(postId).orElseThrow();
    post.getComments().stream()
        .filter(c -> c.getId().equals(commentId))
        .findFirst().orElseThrow()
        .setBody(req.body());
    return PostResponse.from(post);          // dirty checking issues the UPDATE at commit
}

// In the repository
@Query("select p from Post p left join fetch p.comments where p.id = :id")
Optional<Post> findByIdWithComments(@Param("id") Long id);

// Only when you really receive a detached graph (rare)
@OneToMany(mappedBy = "post", cascade = {CascadeType.PERSIST, CascadeType.MERGE})
private List<Comment> comments = new ArrayList<>();

Post managed = postRepository.save(detachedPost);   // merge() -> use the RETURNED instance
// WITH MERGE:    changed comments are merged -> UPDATE comments SET body = ? WHERE id = ?
// WITHOUT MERGE: comment changes are silently ignored

// Owned children: REMOVE cascade is correct
@OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
private List<OrderItem> items = new ArrayList<>();

orderRepository.deleteById(1L);
// SELECT ... FROM orders WHERE id = 1
// SELECT ... FROM order_items WHERE order_id = 1       (collection loaded)
// DELETE FROM order_items WHERE id = ?                  (once per item)
// DELETE FROM orders WHERE id = 1

// Large collections: delete the children in bulk first, then the parent
@Modifying(clearAutomatically = true, flushAutomatically = true)
@Query("DELETE FROM OrderItem i WHERE i.order.id = :orderId")
int deleteByOrderId(@Param("orderId") Long orderId);

@Transactional
public void deleteOrder(Long id) {
    itemRepository.deleteByOrderId(id);
    orderRepository.deleteById(id);
}

// DANGEROUS: cascade REMOVE onto independent entities
@Entity
public class Department {
    @OneToMany(mappedBy = "department", cascade = CascadeType.ALL)   // WRONG: employees are independent
    private List<Employee> employees;
}
// departmentRepository.delete(department) now deletes every employee in it.

// CORRECT: no cascade. Reassign employees before deleting the department.
@OneToMany(mappedBy = "department")
private List<Employee> employees;

@OneToMany(mappedBy = "report", cascade = {CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH})
private List<ReportSection> sections = new ArrayList<>();

@Service
public class ReportService {

    @PersistenceContext
    private EntityManager em;

    @Transactional
    public Report reload(Long id) {
        Report report = em.find(Report.class, id);
        report.getSections().get(0).setTitle("Edited in memory");   // not flushed

        em.refresh(report);
        // WITH REFRESH cascade: report AND sections reloaded, the edit is discarded
        // WITHOUT it: only the report is reloaded; sections keep their dirty state
        return report;
    }
}

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

// Parent removed: REMOVE cascade
orderRepository.deleteById(1L);

// Child unlinked: orphanRemoval, the parent stays
@Transactional
public void removeFirstItem(Long orderId) {
    PurchaseOrder order = orderRepository.findByIdWithItems(orderId).orElseThrow();
    order.removeItem(order.getItems().get(0));
    // no save() needed: dirty checking issues  DELETE FROM order_items WHERE id = ?
}

// WRONG: replaces the managed collection
order.setItems(newItems);

// CORRECT: mutate the existing collection
order.getItems().clear();
order.getItems().addAll(newItems);

-- Flyway migration: the database does the cascading
ALTER TABLE order_items
    ADD CONSTRAINT fk_order_items_order
    FOREIGN KEY (order_id) REFERENCES orders (id) ON DELETE CASCADE;

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

// Independent entity: no cascade
@ManyToOne(fetch = FetchType.LAZY)
@JoinColumn(name = "customer_id")
private Customer customer;

@ManyToMany
@JoinTable(name = "student_tags",
    joinColumns = @JoinColumn(name = "student_id"),
    inverseJoinColumns = @JoinColumn(name = "tag_id"))
private Set<Tag> tags = new HashSet<>();

// Created with the parent, removed separately
@OneToOne(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
@JoinColumn(name = "billing_address_id")
private Address billingAddress;

// Append-only
@OneToMany(mappedBy = "order", cascade = CascadeType.PERSIST)
private List<AuditLog> auditLogs = new ArrayList<>();

@DataJpaTest
class OrderCascadeTest {

    @Autowired private TestEntityManager em;
    @Autowired private OrderRepository orderRepository;
    @Autowired private OrderItemRepository itemRepository;

    @Test
    void persistCascadesToNewItems() {
        PurchaseOrder order = new PurchaseOrder("REF-001");
        order.addItem(new OrderItem("Widget", 2, new BigDecimal("9.99")));

        orderRepository.save(order);
        em.flush();
        em.clear();

        assertThat(itemRepository.count()).isEqualTo(1);
    }

    @Test
    void removingAnItemDeletesItButKeepsTheOrder() {
        PurchaseOrder order = new PurchaseOrder("REF-002");
        order.addItem(new OrderItem("Widget", 2, new BigDecimal("9.99")));
        PurchaseOrder saved = orderRepository.saveAndFlush(order);

        saved.removeItem(saved.getItems().get(0));
        em.flush();
        em.clear();

        assertThat(itemRepository.count()).isZero();
        assertThat(orderRepository.count()).isEqualTo(1);
    }

    @Test
    void deletingTheOrderDeletesItsItems() {
        PurchaseOrder order = new PurchaseOrder("REF-003");
        order.addItem(new OrderItem("Widget", 2, new BigDecimal("9.99")));
        Long id = orderRepository.saveAndFlush(order).getId();
        em.clear();

        orderRepository.deleteById(id);
        em.flush();

        assertThat(itemRepository.count()).isZero();
    }
}