Hibernate.

JDBC makes you write the SQL and map results by hand, while Hibernate maps objects to tables and writes the SQL for you. JDBC is Java's low-level API for running SQL. Hibernate is an object-relational mapping (ORM) framework built on top of it.

JDBC gives you full control over each statement and has no mapping overhead, so it suits small tools and hand-tuned queries. Hibernate saves the most work in an application with a large domain model and many related entities.

The core types are Configuration, SessionFactory and Session. Transaction, Query and CriteriaBuilder complete the set.

1. Configuration: a class, not an interface. It reads the settings and creates the SessionFactory.
2. SessionFactory: the factory for Session objects. It is thread-safe and expensive to create.
3. Session: the main interface for persistence operations. It is not thread-safe.
4. Transaction: begins, commits and rolls back a database transaction.
5. Query: runs HQL and native SQL queries.
6. CriteriaBuilder: builds queries in code. It replaced Hibernate's legacy Criteria API, which Hibernate 6.0 removed.

Session extends JPA's EntityManager, so the same object also serves JPA code.

A SessionFactory is the heavyweight, thread-safe factory that an application builds once at startup. A Session is the lightweight object it creates for a single unit of work, opened and closed around each transaction.

The SessionFactory reads the configuration once and is immutable after that. It is expensive to create, so an application typically keeps one. It also holds the second-level cache, which every session it creates shares.

The Session is the interface between your Java code and Hibernate. It is inexpensive to create and is not thread-safe, so each request or thread gets its own and closes it when the work is done.

// SessionFactory - created once
SessionFactory sessionFactory = new Configuration().configure().buildSessionFactory();

// Session - created per transaction
Session session = sessionFactory.openSession();
// ... perform operations
session.close();

An entity starts transient and becomes persistent when a session tracks it. Later it can become detached or removed.

1. Transient. New, unknown to any session, and with no database row.
2. Persistent. Also called managed. The session tracks it and saves its changes to its row.
3. Detached. Its session closed, so changes are no longer tracked.
4. Removed. Marked for deletion. Hibernate deletes the row at the next flush, when pending changes go to the database.

User user = new User(); // Transient state
session.persist(user);  // Persistent state
session.close();        // Detached state
user = newSession.merge(user); // Persistent again
newSession.remove(user);       // Removed state

The last two lines use a new session, because the first one is closed.

save() returns the generated identifier, persist() returns nothing, and saveOrUpdate() either saves a new object or updates an existing one.

• save() saves the entity and returns its identifier. With an identity column, where the database generates the id, it runs the INSERT at once, even outside a transaction.
• persist() is the Java Persistence API (JPA) method. It does not promise to assign the identifier at once, and it never runs the INSERT outside a transaction.
• saveOrUpdate() checks the identifier, then saves a new entity or updates a detached one, an object whose session has closed.

// save() - returns ID
Long id = (Long) session.save(user);

// persist() - no return value
session.persist(user);

// saveOrUpdate() - smart save/update
session.saveOrUpdate(user);

Hibernate 7 removed save() and saveOrUpdate(). Use persist() for a new object and merge() for a detached one.