Hibernate ORM

ORM, quickly

Hibernate ORM has a huge API surface, but here’s a list of the operations that you’ll need all the time.

Stateful sessions

A Hibernate Session or JPA EntityManager represents a stateful persistence context. That is, it maintains a set of associated entities, automatically detects modifications made to the entities, and propagates such modifications to the database.

#1 find

The find() method fetches the entity with the given primary key from the database.

var book = session.find(Book.class, isbn)

The returned entity is associated with the persistence context, and so any modifications you make its state will be automatically propagated to the database when the session flushes.

Optionally, find() accepts one or more FindOptions, customizing locking, timeout, or interaction with the second-level cache.

var book = session.find(Book.class, isbn, LockModeType.PESSIMISTIC_WRITE, CacheStoreMode.BYPASS)

The find() method even accepts an EntityGraph, allowing you to specify the associations you would like to fetch.

#2 persist

The persist() method add an entity to the persistence context, and schedules it for insertion in the database.

session.persist(book);

The actual insertion doesn’t happen until the session flushes.

#3 refresh

The refresh() method overwrites the state of the given entity with the current persistent state held by the database.

session.refresh(book)

#4 lock

The lock() method may be used to upgrade the current lock mode of an entity.

session.lock(book, LockModeType.PESSIMISTIC_FORCE_INCREMENT)

#5 merge

The merge() method merges the state of an entity which is not associated with the persistence context into the current persistence context.

var managedBook = session.merge(detachedBook);

A call to merge() returns an entity associated with the persistence context, with the same state as the entity passed as an argument to merge().

#6 remove

The remove() method schedules an entity for deletion from the database.

session.remove(book);

The actual deletion doesn’t happen until the session flushes.

#7 selection queries

Selection queries retrieve data from the database.

var books =
        session.createSelectionQuery("where title like :title order by publicationDate", Book.class)
                .setParameter("title", title);
                .setMaxResults(50)
                .getResultList();

The entities returned in the query result set are associated with the persistence context.

#8 mutation queries

Mutation queries update or delete data.

session.createMutationQuery("update Order set status = PROCESSED, processed = local datetime where status = IN_PROCESS")
        .executeUpdate();

#9 criteria queries

A criteria query is a query constructed programmatically.

var query = builder.createQuery(Book.class);
var book = query.from(Book.class);
var where = builder.conjunction();
if (titlePattern != null) {
    where = builder.and(where, builder.like(book.get(Book_.title), titlePattern));
}
if (namePattern != null) {
    var author = book.join(Book_.author);
    where = builder.and(where, builder.like(author.get(Author_.name), namePattern));
}
query.select(book).where(where)
    .orderBy(builder.asc(book.get(Book_.title)));

#10 native queries

Native queries let you write a query in the native SQL dialect of your database, map its result set to Java objects, and execute the SQL via Hibernate. In older versions of Hibernate, native SQL queries were used quite often—​but since Hibernate 6, HQL is so powerful that they’re now rarely needed.

Stateless sessions

The StatelessSession offers a simplified programming model, allowing more direct control over interaction with the database. A stateless session doesn’t have an associated persistence context, and so a change is only made to the database when you explicitly ask for it.

#1 get

The get() method retrieves an entity from the database, but doesn’t associate it with any persistence context.

var book = session.get(Book.class, isbn)

Optionally, you can specify a LockMode, or an EntityGraph.

#2 insert

The insert() method directly inserts an entity in the database.

session.insert(book);

#3 update

The update() operation immediately updates the database.

session.update(book);

For a stateless session, updates to the database never happen automatically.

#4 upsert

The upsert() operation results in execution of a SQL MERGE statement.

session.upsert(book);

#5 delete

The delete() operation immediately deletes the entity from the database.

session.delete(book);

#6 fetch

The fetch() method initializes an unfetched association.

session.fetch(book.getAuthors());

For a stateless session, lazy fetching never happens transparently nor by accident.

#7 refresh

The refresh() method overwrites the state of the given entity with the current persistent state held by the database.

session.refresh(book)

#8 selection, update, criteria, and native queries

Queries work the same with a stateless session as they do in a stateful session, with one clear difference: the entities returned by the query are never associated with any persistence context.

Back to top