Hibernate & JPA Internals — Deep Dive

// Accessing native Hibernate API from JPA
Session session = entityManager.unwrap(Session.class);
SessionFactory sf = entityManager.getEntityManagerFactory().unwrap(SessionFactory.class);

// Spring Boot auto-configures everything — you rarely create these manually
@PersistenceContext
private EntityManager em; // Injected, transaction-scoped proxy

Order order1 = em.find(Order.class, 1L); // SQL: SELECT ... WHERE id = 1
Order order2 = em.find(Order.class, 1L); // NO SQL — returns cached instance

assert order1 == order2; // true! Same object reference (not just equals)

// JPQL also respects identity map
Order order3 = em.createQuery("SELECT o FROM Order o WHERE o.id = 1", Order.class)
                 .getSingleResult(); // SQL fires, but result is reconciled with map

assert order1 == order3; // true! Even from a query

// Internal representation (simplified):
// Key: EntityKey(Order.class, id=1)
// Value: Order@7a3b2c1 (the live instance)
// Snapshot: Object[] { "PENDING", BigDecimal(100.00), Timestamp(...) }

// At flush time:
// Current:  Object[] { "SHIPPED", BigDecimal(100.00), Timestamp(...) }
// Snapshot: Object[] { "PENDING", BigDecimal(100.00), Timestamp(...) }
// Diff: index 0 changed → generate UPDATE for status column

// ========== TRANSIENT ==========
Order order = new Order();           // Transient: no ID, no PC
order.setStatus("NEW");

// ========== MANAGED ==========
em.persist(order);                   // Managed: ID assigned (or will be at flush)
                                     // Snapshot taken, INSERT queued

order.setStatus("CONFIRMED");        // Still managed — change auto-detected

// ========== DETACHED ==========
em.detach(order);                    // Detached: has ID, but no longer tracked
// OR: em.clear();                   // Detaches ALL entities
// OR: em.close();                   // Closes session — all entities detached

order.setStatus("SHIPPED");          // This change is INVISIBLE to Hibernate

// ========== RE-ATTACH ==========
Order managed = em.merge(order);     // Returns NEW managed copy
// WARNING: 'order' is still detached! Use 'managed' going forward.

// ========== REMOVED ==========
em.remove(managed);                  // Removed: DELETE queued for flush
// Entity still in memory, but will be deleted from DB on flush

@Entity
public class Order {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // No equals()/hashCode() override
    // Uses Object.equals() — compares memory addresses
}

Set<Order> orders = new HashSet<>();

Order order = new Order();          // id = null (transient)
orders.add(order);                  // hashCode based on identity

em.persist(order);                  // id = 42 assigned by DB
em.flush();

orders.contains(order);            // TRUE — same object reference
// But if you detach + merge:
Order merged = em.merge(order);    // DIFFERENT object reference!
orders.contains(merged);           // FALSE — different hashCode!

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

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Order)) return false;
        return id != null && id.equals(((Order) o).id);
    }

    @Override
    public int hashCode() {
        return Objects.hash(id);  // BROKEN!
    }
}

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

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Order other)) return false;
        // Only use id if both are non-null (both persisted)
        return id != null && id.equals(other.getId());
    }

    @Override
    public int hashCode() {
        // FIXED: return a constant!
        // This degrades HashSet to O(n) but guarantees correctness
        // across persist/detach/merge lifecycle
        return getClass().hashCode();  // same value for all Order instances
    }
}

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

    @NaturalId  // Hibernate-specific — marks immutable business key
    @Column(nullable = false, unique = true, updatable = false)
    private String orderNumber;  // assigned at creation, never changes

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Order other)) return false;
        return orderNumber != null && orderNumber.equals(other.orderNumber);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderNumber);  // stable — never changes
    }
}

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

    @Column(nullable = false, unique = true, updatable = false)
    private UUID uuid = UUID.randomUUID();  // assigned at new Order()

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Order other)) return false;
        return uuid.equals(other.uuid);
    }

    @Override
    public int hashCode() {
        return uuid.hashCode();  // stable from construction through entire lifecycle
    }
}

Order realOrder = em.find(Order.class, 1L);
Order proxyOrder = em.getReference(Order.class, 1L);  // uninitialized proxy

// realOrder.getClass() = Order.class
// proxyOrder.getClass() = Order$HibernateProxy$abc123

// WRONG equals implementation:
if (o == null || getClass() != o.getClass()) return false;
// This FAILS because proxy class != real class!

// CORRECT: use instanceof
if (!(o instanceof Order)) return false;
// Works because proxy IS-A Order (it extends Order)

@Entity
@DynamicUpdate // Only include changed columns in UPDATE
public class Order {
    // If only 'status' changed, generates:
    // UPDATE orders SET status = ? WHERE id = ?
    // Instead of:
    // UPDATE orders SET status = ?, total = ?, created = ?, ... WHERE id = ?
}

// Read-only transaction: skips dirty checking entirely
@Transactional(readOnly = true)
public List<Order> findRecentOrders() {
    return orderRepo.findByCreatedAfter(cutoff);
    // No snapshots taken, no flush, no dirty check
    // Significant memory + CPU savings for read queries
}

// Set flush mode per session
em.unwrap(Session.class).setHibernateFlushMode(FlushMode.MANUAL);

// Batch processing with manual flush
@Transactional
public void importOrders(List<OrderDTO> dtos) {
    Session session = em.unwrap(Session.class);
    session.setHibernateFlushMode(FlushMode.MANUAL);

    for (int i = 0; i < dtos.size(); i++) {
        em.persist(toEntity(dtos.get(i)));
        if (i % 50 == 0) {
            em.flush();  // Execute 50 INSERTs
            em.clear();  // Release memory
        }
    }
    em.flush(); // Final batch
}

// Scenario: Replace an order's items (delete old, insert new)
@Transactional
public void replaceItems(Long orderId, List<ItemDTO> newItems) {
    Order order = orderRepo.findById(orderId).orElseThrow();

    // Developer writes code in this logical order:
    order.getItems().clear();                    // wants DELETE first
    for (ItemDTO dto : newItems) {
        order.getItems().add(new OrderItem(dto)); // then INSERT
    }

    // Hibernate's action queue executes:
    // 1. INSERTs (new OrderItems) — but old items still exist!
    // 2. Collection DELETEs (old items removed from collection)
    // 
    // If there's a UNIQUE constraint on (order_id, sku),
    // the INSERT might violate it because the old item hasn't been deleted yet!
}

@Transactional
public void replaceItems(Long orderId, List<ItemDTO> newItems) {
    Order order = orderRepo.findById(orderId).orElseThrow();

    order.getItems().clear();
    em.flush();  // Force DELETEs to execute NOW

    for (ItemDTO dto : newItems) {
        order.getItems().add(new OrderItem(dto));
    }
    // INSERTs execute at commit — no constraint violation
}

// Scenario: Delete parent, then insert new parent with same natural key
@Transactional
public void replaceCustomer(String email, CustomerDTO newData) {
    Customer old = customerRepo.findByEmail(email);
    em.remove(old);  // DELETE queued (action #6 in queue)

    Customer replacement = new Customer(newData);
    replacement.setEmail(email);  // same unique email
    em.persist(replacement);  // INSERT queued (action #1 in queue)

    // At flush: INSERT fires first, DELETE fires last
    // UNIQUE constraint violation on email!
}

// Fix: flush after remove
@Transactional
public void replaceCustomer(String email, CustomerDTO newData) {
    Customer old = customerRepo.findByEmail(email);
    em.remove(old);
    em.flush();  // DELETE executes NOW

    Customer replacement = new Customer(newData);
    replacement.setEmail(email);
    em.persist(replacement);  // Safe — old row is gone
}

// TERRIBLE: OOM + thousands of individual INSERT statements
@Transactional
public void importOrders(List<OrderDTO> dtos) {
    for (OrderDTO dto : dtos) {
        orderRepo.save(toEntity(dto));
        // Each save: adds to PC, takes snapshot, queues INSERT
        // 100,000 entities = 200,000 Object[] arrays in memory!
    }
    // At commit: 100,000 individual INSERT statements
}

// Without order_inserts:
// INSERT INTO orders ...    (Order #1)
// INSERT INTO order_items ... (Item for Order #1)
// INSERT INTO orders ...    (Order #2)
// INSERT INTO order_items ... (Item for Order #2)
// → JDBC batching BROKEN because statements alternate types

// With order_inserts = true:
// INSERT INTO orders ...    (Order #1)
// INSERT INTO orders ...    (Order #2)
// INSERT INTO order_items ... (Item for Order #1)
// INSERT INTO order_items ... (Item for Order #2)
// → JDBC batching groups them into 2 batch calls

@Service
public class BatchImportService {

    @PersistenceContext
    private EntityManager em;

    private static final int BATCH_SIZE = 50;

    @Transactional
    public void importOrders(List<OrderDTO> dtos) {
        for (int i = 0; i < dtos.size(); i++) {
            em.persist(toEntity(dtos.get(i)));

            if (i > 0 && i % BATCH_SIZE == 0) {
                em.flush();  // Execute batch of 50 INSERTs
                em.clear();  // Release memory (entities + snapshots)
            }
        }
        em.flush();  // Final partial batch
    }
}

@Service
public class StatelessBatchService {

    @Autowired
    private EntityManagerFactory emf;

    public void bulkImport(List<OrderDTO> dtos) {
        SessionFactory sf = emf.unwrap(SessionFactory.class);

        try (StatelessSession session = sf.openStatelessSession()) {
            Transaction tx = session.beginTransaction();

            for (int i = 0; i < dtos.size(); i++) {
                session.insert(toEntity(dtos.get(i)));
                // No persistence context overhead
                // No snapshot taken
                // Direct SQL execution
            }

            tx.commit();
        }
    }
}

@Transactional(readOnly = true)
public void processAllOrders(Consumer<Order> processor) {
    Session session = em.unwrap(Session.class);

    try (ScrollableResults<Order> scroll = session
            .createQuery("FROM Order", Order.class)
            .setFetchSize(100)         // JDBC fetch size (rows per network round-trip)
            .setReadOnly(true)         // No snapshots
            .scroll(ScrollMode.FORWARD_ONLY)) {

        int count = 0;
        while (scroll.next()) {
            Order order = scroll.get();
            processor.accept(order);

            if (++count % 100 == 0) {
                em.clear();  // Prevent memory buildup
            }
        }
    }
}

@Entity
public class Student {
    @ManyToMany
    @JoinTable(name = "student_course")
    private List<Course> courses = new ArrayList<>();  // BAG semantics!
}

@Entity
public class Student {
    @ManyToMany
    @JoinTable(name = "student_course")
    private Set<Course> courses = new HashSet<>();  // SET semantics — individual deletes!
}

@Entity
public class Order {
    // Without @OrderColumn — bag semantics (DELETE ALL + re-INSERT)
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL)
    private List<OrderItem> items = new ArrayList<>();

    // With @OrderColumn — true indexed list (individual operations)
    @OneToMany(cascade = CascadeType.ALL)
    @JoinColumn(name = "order_id")
    @OrderColumn(name = "item_position")  // extra column stores index
    private List<OrderItem> items = new ArrayList<>();
}

@Entity
public class StudentCourse {
    @EmbeddedId
    private StudentCourseId id;

    @ManyToOne @MapsId("studentId")
    private Student student;

    @ManyToOne @MapsId("courseId")
    private Course course;

    private LocalDate enrolledDate;  // extra column
}

// Now use @OneToMany to StudentCourse — no bag semantics issue
@Entity
public class Student {
    @OneToMany(mappedBy = "student", cascade = CascadeType.ALL, orphanRemoval = true)
    private Set<StudentCourse> enrollments = new HashSet<>();
}

@Entity
public class Order {
    @ManyToOne(fetch = FetchType.LAZY)
    private Customer customer; // At load time, this is a PROXY, not a real Customer
}

// When you do:
Order order = em.find(Order.class, 1L);
// order.customer is a ByteBuddy-generated subclass of Customer
// It contains only the ID — no other fields loaded

order.getCustomer().getId();    // Returns ID without hitting DB (already in proxy)
order.getCustomer().getName();  // NOW triggers SQL: SELECT * FROM customers WHERE id = ?

@Service
public class OrderService {
    @Transactional
    public Order getOrder(Long id) {
        return orderRepo.findById(id).orElseThrow();
    } // Transaction ends, Session closed
}

@RestController
public class OrderController {
    public OrderDTO getOrder(Long id) {
        Order order = orderService.getOrder(id);
        // Session is CLOSED here
        order.getCustomer().getName(); // LazyInitializationException!
    }
}

// Solution 1: JOIN FETCH in repository
@Query("SELECT o FROM Order o JOIN FETCH o.customer WHERE o.id = :id")
Optional<Order> findByIdWithCustomer(@Param("id") Long id);

// Solution 2: @EntityGraph
@EntityGraph(attributePaths = {"customer", "items"})
Optional<Order> findById(Long id);

// Solution 3: Hibernate.initialize() within transaction
@Transactional
public Order getOrderWithCustomer(Long id) {
    Order order = orderRepo.findById(id).orElseThrow();
    Hibernate.initialize(order.getCustomer()); // Force load
    return order;
}

// Solution 4: DTO Projection (best performance)
@Query("SELECT new com.app.OrderDTO(o.id, o.status, c.name) " +
       "FROM Order o JOIN o.customer c WHERE o.id = :id")
OrderDTO findOrderDTOById(@Param("id") Long id);

@Entity
@Cache(usage = CacheConcurrencyStrategy.READ_WRITE, region = "orders")
public class Order {
    @Id
    private Long id;

    @Cache(usage = CacheConcurrencyStrategy.READ_ONLY) // Collection cache
    @OneToMany(mappedBy = "order")
    private List<OrderItem> items;
}

// Cache lookup flow:
Order order = em.find(Order.class, 1L);
// 1. Check L1 (Persistence Context) — miss
// 2. Check L2 (Shared Cache) — hit! Returns Object[]{SHIPPED, 150, ...}
// 3. Rehydrate into Order instance
// 4. Place in L1 for remainder of session
// No SQL executed!

// Query cache is INVALIDATED when ANY entity in the target table is modified
@Cacheable // This query is cached
@Query("SELECT o FROM Order o WHERE o.status = 'SHIPPED'")
List<Order> findShippedOrders();

// Now someone inserts a NEW order (status = 'PENDING')
orderRepo.save(new Order("PENDING"));
// The ENTIRE query cache region for "orders" is invalidated!
// Even though the new order wouldn't match the cached query!

@Entity
@SQLDelete(sql = "UPDATE orders SET deleted = true WHERE id = ?")
@Where(clause = "deleted = false")
public class Order {
    @Id @GeneratedValue
    private Long id;

    private String status;

    @Column(nullable = false)
    private boolean deleted = false;
}

// em.remove(order) executes:
// UPDATE orders SET deleted = true WHERE id = 1  (not DELETE!)

// All JPQL queries automatically append WHERE deleted = false:
// SELECT o FROM Order o WHERE o.status = 'PENDING'
// becomes:
// SELECT * FROM orders WHERE status = 'PENDING' AND deleted = false

@Entity
@FilterDef(name = "deletedFilter", 
           parameters = @ParamDef(name = "isDeleted", type = Boolean.class))
@Filter(name = "deletedFilter", condition = "deleted = :isDeleted")
public class Order {
    @Id @GeneratedValue
    private Long id;
    private boolean deleted = false;
}

// Enable filter for the session
Session session = em.unwrap(Session.class);
session.enableFilter("deletedFilter").setParameter("isDeleted", false);

// Now all queries exclude deleted records
List<Order> activeOrders = orderRepo.findAll();  // only non-deleted

// Admin view: see ALL records including deleted
session.disableFilter("deletedFilter");
List<Order> allOrders = orderRepo.findAll();  // includes deleted

// Order #1 is soft-deleted (deleted = true)
// But it's still in the L2 cache from before deletion

Order order = em.find(Order.class, 1L);
// L2 cache hit → returns the entity, @Where NOT applied!
// order.isDeleted() = true — but you have it!

// Fix: evict from L2 cache on soft delete
@Override
@Transactional
public void softDelete(Long id) {
    Order order = orderRepo.findById(id).orElseThrow();
    orderRepo.delete(order);  // triggers @SQLDelete

    // Manually evict from L2 cache
    sessionFactory.getCache().evict(Order.class, id);
}

@Entity
@Immutable  // Hibernate skips dirty checking for this entity entirely
@Cache(usage = CacheConcurrencyStrategy.READ_ONLY)
public class AuditEvent {
    @Id @GeneratedValue
    private Long id;

    @Column(nullable = false, updatable = false)
    private String action;

    @Column(nullable = false, updatable = false)
    private Instant timestamp;

    @Column(nullable = false, updatable = false)
    private String userId;
}

// Modifications are SILENTLY IGNORED:
AuditEvent event = em.find(AuditEvent.class, 1L);
event.setAction("HACKED");  // No effect — no dirty check, no UPDATE
em.flush();                  // Nothing happens

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

    private BigDecimal subtotal;
    private BigDecimal taxRate;

    @Formula("subtotal * (1 + tax_rate)")  // SQL expression, NOT Java
    private BigDecimal total;  // computed on every SELECT, not stored

    @Formula("(SELECT COUNT(*) FROM order_items oi WHERE oi.order_id = id)")
    private int itemCount;  // subquery formula
}

// Hibernate 6+ multi-tenancy with discriminator
@Entity
@TenantId("tenantId")  // Hibernate 6 annotation
public class Order {
    @Id @GeneratedValue
    private Long id;

    @Column(nullable = false)
    private String tenantId;  // automatically filtered

    private String status;
}

// Tenant resolver
@Component
public class TenantIdentifierResolver implements CurrentTenantIdentifierResolver {
    @Override
    public String resolveCurrentTenantIdentifier() {
        return TenantContext.getCurrentTenant();  // from ThreadLocal/SecurityContext
    }

    @Override
    public boolean validateExistingCurrentSessions() {
        return true;
    }
}

@Configuration
public class MultiTenantConfig {

    @Bean
    public MultiTenantConnectionProvider connectionProvider(DataSource dataSource) {
        return new SchemaMultiTenantConnectionProvider(dataSource);
    }
}

public class SchemaMultiTenantConnectionProvider implements MultiTenantConnectionProvider {

    @Override
    public Connection getConnection(String tenantIdentifier) throws SQLException {
        Connection conn = dataSource.getConnection();
        conn.setSchema(tenantIdentifier);  // switch schema
        return conn;
    }
}

// SINGLE_TABLE (default, recommended for most cases)
@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "payment_type")
public abstract class Payment {
    @Id @GeneratedValue
    private Long id;
    private BigDecimal amount;
}

@Entity
@DiscriminatorValue("CARD")
public class CardPayment extends Payment {
    private String cardNumber; // NULL for non-card rows
}

@Entity
@DiscriminatorValue("BANK")
public class BankPayment extends Payment {
    private String accountNumber; // NULL for non-bank rows
}

@Entity
public class Order {

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

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "customer_id")
    private Customer customer;

    public void addItem(OrderItem item) {
        items.add(item);
        item.setOrder(this);
    }

    public void removeItem(OrderItem item) {
        items.remove(item);
        item.setOrder(null); // orphanRemoval will DELETE this from DB
    }
}

@Transactional
public void processOrder(Long orderId) {
    Order order = orderRepo.findById(orderId).orElseThrow();

    order.setStatus("PROCESSING");    // dirty
    order.setStatus("VALIDATED");     // dirty again (same field)
    order.setStatus("CONFIRMED");     // dirty again

    // At flush: ONLY ONE UPDATE with status = 'CONFIRMED'
    // Not three UPDATEs!
}