JPA Entity Lifecycle in Spring Boot: States, Callbacks, Cascade

@Service
@RequiredArgsConstructor
public class EntityLifecycleDemo {

    private final EntityManager       em;
    private final ProductRepository   productRepo;

    @Transactional
    public void demonstrateStates() {

        // ── 1. TRANSIENT — not associated with any persistence context ─
        Product product = new Product();
        product.setName("Widget");
        product.setPrice(BigDecimal.valueOf(9.99));
        // No id, no persistence context association, no DB row

        // ── 2. MANAGED — associated with the persistence context ───────
        em.persist(product);
        // product is now managed: id assigned (immediately with IDENTITY,
        // at flush with SEQUENCE), tracked for changes

        product.setPrice(BigDecimal.valueOf(12.99));
        // No explicit save() needed — dirty checking will flush this
        // change at transaction commit automatically

        // ── 3. DETACHED — context closed or explicit detach ────────────
        em.detach(product);
        // product is now detached: changes are NOT tracked automatically.
        // Pending changes that were not flushed yet (such as the price
        // change above) are no longer tracked either.

        product.setName("Super Widget");
        // Not tracked while detached. Without merge() this change would be lost.

        // Re-attach by merging — returns a managed instance
        Product managed = em.merge(product);
        // merge() copies the detached state (name "Super Widget", price 12.99)
        // onto the managed instance. 'managed' is tracked; 'product' (the
        // argument) is still detached. Always continue with the returned object.

        // ── 4. REMOVED — scheduled for deletion ───────────────────────
        em.remove(managed);
        // DELETE executed at flush — row gone at transaction commit
    }

    @Transactional
    public void repositoryStates() {

        // save() on a NEW entity → em.persist() (transient → managed)
        // save() on an entity with an existing id → em.merge() (returns a different instance!)
        Product p = productRepo.save(new Product("Widget", BigDecimal.TEN));

        // findById() returns a managed entity
        Product found = productRepo.findById(p.getId()).orElseThrow();
        found.setName("Updated");
        // No save() needed — dirty checking flushes the UPDATE

        // delete() → removed state
        productRepo.delete(found);
    }
}

@Service
@Slf4j
@RequiredArgsConstructor
public class StateObserver {

    private final EntityManager em;

    @Transactional
    public void observe() {
        Product p = new Product("Widget", BigDecimal.TEN);
        log.info("after new:     managed={}, id={}", em.contains(p), p.getId());
        // managed=false, id=null                       -> TRANSIENT

        em.persist(p);
        log.info("after persist: managed={}, id={}", em.contains(p), p.getId());
        // managed=true,  id=1 (with IDENTITY)          -> MANAGED

        em.flush();
        em.detach(p);
        log.info("after detach:  managed={}", em.contains(p));
        // managed=false                                -> DETACHED

        Product m = em.merge(p);       // SELECT, because the row must be loaded first
        log.info("merge returned a different instance: {}", m != p);
        log.info("p managed={}, m managed={}", em.contains(p), em.contains(m));
        // true
        // p managed=false, m managed=true

        em.remove(m);
        log.info("after remove:  managed={}", em.contains(m));
        // managed=false                                -> REMOVED (DELETE at commit)
    }
}

# application.properties — see the SQL timing:
# logging.level.org.hibernate.SQL=DEBUG

@Service
@RequiredArgsConstructor
public class PersistenceContextDemo {

    private final ProductRepository productRepo;
    private final EntityManager     em;

    // ── First-level cache ──────────────────────────────────────────────
    @Transactional
    public void firstLevelCache(Long id) {
        Product a = productRepo.findById(id).orElseThrow(); // SELECT
        Product b = productRepo.findById(id).orElseThrow(); // no SELECT — cache hit

        System.out.println(a == b);   // true — same Java object
    }

    // ── Dirty checking — automatic UPDATE on commit ────────────────────
    @Transactional
    public void dirtyChecking(Long id) {
        Product product = productRepo.findById(id).orElseThrow();
        product.setPrice(BigDecimal.valueOf(19.99));
        // No save() call — Hibernate detects the change on flush
        // UPDATE products SET price = 19.99 WHERE id = ?
    }

    // ── Explicit flush — send SQL before transaction commits ──────────
    @Transactional
    public void explicitFlush(Long id) {
        Product product = productRepo.findById(id).orElseThrow();
        product.setPrice(BigDecimal.valueOf(24.99));

        em.flush();     // SQL sent to DB now but not yet committed
        // Useful to surface constraint violations early, or to be sure
        // pending changes are visible to your own SQL in this transaction.
        // (With FlushMode AUTO, Hibernate usually flushes before queries anyway.)
        Number count = (Number) em.createNativeQuery(
            "SELECT COUNT(*) FROM products WHERE price > 20")
            .getSingleResult();
        // Cast to Number: depending on the database and Hibernate version the
        // result is Long or BigInteger, so (Long) can throw ClassCastException.
        long expensive = count.longValue();
    }

    // ── Clear — detach all entities, reset first-level cache ─────────
    @Transactional
    public void batchProcess(List<Long> ids) {
        int count = 0;
        for (Long id : ids) {
            Product product = productRepo.findById(id).orElseThrow();
            product.setPrice(product.getPrice()
                .multiply(BigDecimal.valueOf(0.9)));  // 10% discount
            count++;
            if (count % 50 == 0) {
                em.flush();   // flush batch to DB
                em.clear();   // detach all — prevent OutOfMemoryError
            }
        }
    }
    // For real batch performance also set:
    //   spring.jpa.properties.hibernate.jdbc.batch_size=50
    // IDENTITY id generation disables JDBC insert batching; prefer SEQUENCE.

    // ── Merge detached entity ─────────────────────────────────────────
    @Transactional
    public Product reattach(Product detached) {
        // merge() copies detached state onto the managed instance
        // Returns the managed instance — NOT the parameter
        return em.merge(detached);
    }

    // ── Read-only transactions skip dirty checking ────────────────────
    @Transactional(readOnly = true)
    public Product load(Long id) {
        return productRepo.findById(id).orElseThrow();
        // Hibernate does not flush changes in a read-only transaction,
        // which is cheaper for pure reads.
    }
}

@Entity
@Table(name = "orders")
@Getter @Setter @NoArgsConstructor
@Slf4j
public class Order {

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

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private OrderStatus status;

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

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

    @Column(name = "updated_at")
    private LocalDateTime updatedAt;

    @Transient
    private String displayLabel;       // not persisted — set after load

    // ── @PrePersist — runs before INSERT ──────────────────────────────
    @PrePersist
    protected void onPrePersist() {
        LocalDateTime now = LocalDateTime.now(ZoneOffset.UTC);
        this.createdAt = now;
        this.updatedAt = now;
        if (this.status == null) {
            this.status = OrderStatus.PENDING;
        }
        log.debug("About to persist order, status={}", status);
    }

    // ── @PostPersist — runs after the INSERT statement executes (id is set) ─
    @PostPersist
    protected void onPostPersist() {
        log.info("Order {} persisted with status {}", id, status);
    }

    // ── @PreUpdate — runs before UPDATE (only if the entity is dirty) ──
    @PreUpdate
    protected void onPreUpdate() {
        this.updatedAt = LocalDateTime.now(ZoneOffset.UTC);
        log.debug("About to update order {}", id);
    }

    // ── @PostUpdate — runs after the UPDATE statement executes ────────
    @PostUpdate
    protected void onPostUpdate() {
        log.info("Order {} updated, new status={}", id, status);
    }

    // ── @PreRemove — runs before DELETE ──────────────────────────────
    @PreRemove
    protected void onPreRemove() {
        log.warn("About to delete order {}", id);
    }

    // ── @PostRemove — runs after the DELETE statement executes ───────
    @PostRemove
    protected void onPostRemove() {
        log.warn("Order {} deleted", id);
    }

    // ── @PostLoad — runs after SELECT loads the entity ────────────────
    @PostLoad
    protected void onPostLoad() {
        // Compute derived / display fields after loading
        this.displayLabel = "Order #" + id + " ("
            + (status == null ? "unknown" : status.name().toLowerCase()) + ")";
    }
}

// ── Entity listener with injected Spring bean (Spring Boot 2.1+) ─────
@Component
public class AuditEntityListener {

    private final ApplicationEventPublisher events;

    // Constructor injection works because Spring Boot sets Hibernate's bean container.
    // For repositories/services that depend on the EntityManagerFactory, use @Lazy:
    //   public AuditEntityListener(@Lazy AuditService auditService) { ... }
    public AuditEntityListener(ApplicationEventPublisher events) {
        this.events = events;
    }

    @PostPersist
    public void onPostPersist(Object entity) {
        events.publishEvent(new EntityCreatedEvent(entity));
    }

    @PostUpdate
    public void onPostUpdate(Object entity) {
        events.publishEvent(new EntityUpdatedEvent(entity));
    }

    @PostRemove
    public void onPostRemove(Object entity) {
        events.publishEvent(new EntityDeletedEvent(entity));
    }
}

// ── React only after the transaction really committed ────────────────
@Component
@Slf4j
public class AuditEventHandler {

    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onCreated(EntityCreatedEvent event) {
        log.info("Committed: {}", event.entity());
        // safe to send e-mails, messages, etc.
    }
}

// ── Enable Spring Data auditing ───────────────────────────────────────
@Configuration
@EnableJpaAuditing
public class JpaAuditingConfig { }

// ── Register on a @MappedSuperclass ───────────────────────────────────
@MappedSuperclass
@EntityListeners({
    AuditingEntityListener.class,  // Spring Data auditing
    AuditEntityListener.class      // custom event publisher
})
@Getter
public abstract class AuditableEntity {

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

    @LastModifiedDate
    @Column(name = "updated_at")
    private LocalDateTime updatedAt;
}

// ── Fallback for older setups: static ApplicationContext holder ───────
@Component
public class ApplicationContextHolder
        implements ApplicationContextAware {

    private static ApplicationContext context;

    @Override
    public void setApplicationContext(ApplicationContext ctx) {
        ApplicationContextHolder.context = ctx;
    }

    public static <T> T getBean(Class<T> type) {
        return context.getBean(type);
    }
}

// ── One method can handle several events ──────────────────────────────
public class DomainEventListener {

    @PostPersist
    @PostUpdate
    @PostRemove
    public void onEvent(Object entity) {
        if (entity instanceof DomainEventSource source) {
            ApplicationContextHolder
                .getBean(ApplicationEventPublisher.class)
                .publishEvent(new DomainEntityEvent(source));
        }
    }
}

// Alternative: Spring Data's @DomainEvents with AbstractAggregateRoot
// publishes events when repository.save() is called.

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

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

    // ── CascadeType.ALL — all lifecycle events propagate to items ─────
    // ── orphanRemoval — removing item from collection deletes the row ─
    @OneToMany(
        mappedBy      = "order",
        cascade       = CascadeType.ALL,
        orphanRemoval = true,
        fetch         = FetchType.LAZY
    )
    private List<OrderItem> items = new ArrayList<>();   // no public setter on purpose

    // Helper — keeps both sides in sync
    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }

    public void removeItem(OrderItem item) {
        items.remove(item);
        item.setOrder(null);
        // orphanRemoval = true → DELETE issued for item at flush
    }
}

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

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

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id", nullable = false)
    private Order order;

    @Column(nullable = false)
    private int quantity;

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

// ── Service — cascade in action ────────────────────────────────────────
@Service
@RequiredArgsConstructor
public class OrderService {

    private final OrderRepository orderRepo;

    @Transactional
    public Order create(CreateOrderRequest request) {
        Order order = new Order();
        request.items().forEach(itemReq -> {
            OrderItem item = new OrderItem();
            item.setQuantity(itemReq.quantity());
            item.setUnitPrice(itemReq.unitPrice());
            order.addItem(item);    // CascadeType.PERSIST → items saved too
        });
        return orderRepo.save(order);   // one save — order + all items
    }

    @Transactional
    public void removeItem(Long orderId, Long itemId) {
        Order order = orderRepo.findById(orderId).orElseThrow();
        order.getItems().removeIf(i -> i.getId().equals(itemId));
        // orphanRemoval=true → DELETE FROM order_items WHERE id = itemId
    }

    @Transactional
    public void deleteOrder(Long orderId) {
        orderRepo.deleteById(orderId);
        // CascadeType.REMOVE → items are loaded and deleted (one DELETE each),
        // then the order is deleted
    }
}

// ── Pitfall 1: LazyInitializationException ────────────────────────────
@Service
public class OrderService {

    @Transactional(readOnly = true)
    public Order findById(Long id) {
        return orderRepo.findById(id).orElseThrow();
    }   // transaction closes here — items collection is still an uninitialized lazy proxy
}

@RestController
public class OrderController {

    @GetMapping("/{id}")
    public OrderResponse findById(@PathVariable Long id) {
        Order order = orderService.findById(id);
        order.getItems().size();   // ← LazyInitializationException (with OSIV off, or outside a web request)
        return OrderResponse.from(order);
    }
}
// FIX 1 — fetch what you need in the query:
@Query("SELECT o FROM Order o LEFT JOIN FETCH o.items WHERE o.id = :id")
Optional<Order> findByIdWithItems(@Param("id") Long id);

// FIX 2 — entity graph:
@EntityGraph(attributePaths = "items")
Optional<Order> findWithItemsById(Long id);

// FIX 3 — return a DTO from the service, built inside the transaction.
// (Avoid JOIN FETCH on collections together with pagination: Hibernate then paginates in memory.)

// ── Pitfall 2: Modifying a detached entity ────────────────────────────
@Transactional(readOnly = true)
public Order loadForDisplay(Long id) {
    return orderRepo.findById(id).orElseThrow();
}   // entity detached here (when the persistence context closes with the transaction)

public void updateDetached(Long id) {
    Order order = loadForDisplay(id);
    order.setStatus(OrderStatus.SHIPPED);  // change is LOST
    // No exception — just silently ignored
}
// FIX — load and modify within the same transaction:
@Transactional
public void updateStatus(Long id, OrderStatus status) {
    Order order = orderRepo.findById(id).orElseThrow();
    order.setStatus(status);
}   // dirty check flushes UPDATE on commit

// ── Pitfall 3: Ignoring the return value of save() / merge() ─────────
@Transactional
public void wrong(Order detached) {
    orderRepo.save(detached);          // returns a NEW managed instance
    detached.setStatus(OrderStatus.CANCELLED);   // changes the detached object — not saved
}
@Transactional
public Order right(Order detached) {
    Order managed = orderRepo.save(detached);
    managed.setStatus(OrderStatus.CANCELLED);    // tracked
    return managed;
}

// ── Pitfall 4: Unintended cascade delete ─────────────────────────────
// CascadeType.ALL (or REMOVE) on a @ManyToMany means deleting ONE product
// also deletes its tags, even though other products still use them
// (a foreign key error, or lost shared data):
@ManyToMany(cascade = CascadeType.ALL)   // WRONG for ManyToMany
private Set<Tag> tags;

// FIX — use only PERSIST and MERGE on @ManyToMany:
@ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
private Set<Tag> tags;

// ── Pitfall 5: equals/hashCode on mutable fields or proxy fields ─────
// WRONG — using a mutable name field:
@Override public boolean equals(Object o) {
    return o instanceof Product p && name.equals(p.name);
}
// FIX — compare the database id, via the getter so Hibernate proxies work
// (reading p.id directly on a lazy proxy returns null):
@Override
public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof Product p)) return false;
    return id != null && id.equals(p.getId());
}
@Override
public int hashCode() {
    return getClass().hashCode();   // stable across transient → managed
}

// ── Pitfall 6: Replacing an orphanRemoval collection ─────────────────
order.setItems(new ArrayList<>());   // HibernateException: A collection with
                                     // cascade="all-delete-orphan" was no longer referenced
order.getItems().clear();            // correct