1. Hibernate

Hibernate ORM module.

1.1. Usage

1) Add the dependencies (hikari + hibernate):

Maven
Gradle
<!-- DataSource via HikariCP-->
<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-hikari</artifactId>
  <version>2.0.5</version>
</dependency>

<!-- Hibernate Module-->
<dependency>
  <groupId>io.jooby</groupId>
  <artifactId>jooby-hibernate</artifactId>
  <version>2.0.5</version>
</dependency>

2) Add database driver (mySQL here):

Maven
Gradle
<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.17</version>
</dependency>

3) Set database properties

application.conf
db.url = "jdbc:mysql://localhost/mydb"
db.user = myuser
db.password = mypass

4) Install and use Hibernate

Java
Kotlin
import io.jooby.hikari.HikariModule;
import io.jooby.hibernate.HibernateModule;
{
  install(new HikariModule());                        (1)

  install(new HibernateModule());                     (2)

  get("/", ctx -> {
    EntityManager em = require(EntityManager.class);  (3)
    Transaction trx = em.getTransaction();            (4)
    try {
      trx.begin();                                    (5)

      // work with EntityManager compute a result     (6)

      trx.commit();                                   (7)

      return result;
    } catch(Exception x) {
      trx.rollback();                                 (8)
      throw x;
    } finally {
      em.close();                                     (9)
    }
  });
}
1 Install and creates a DataSource
2 Install and initializes Hibernate. Entities are automatically detected
3 Get a new EntityManager
4 Creates a new transaction
5 Being the transaction
6 Work with EntityManager (read, write to database)
7 Commit the transaction
8 Rollback transaction in case of error
9 Close the EntityManager

1.2. Entity Discovering

By default the HibernateModule module detects all the persistent entities under base/root package. The module provides two options for more explicit control:

  • List persistent classes at creation time:

  install(new HibernateModule(MyEntity1.class, MyEntity2.class));
  • Explicit package scanning

  install(new HibernateModule().scan("mypackage"));

1.3. Transactional Request

The TransactionalRequest decorator takes care of a lifecycle of an EntityManager per HTTP request. The decorator creates, bind, begin/commit/rollback transaction and finally close it, so route handler doesn’t have to deal with that boring lines of code.

TransactionalRequest
Java
Kotlin
import io.jooby.hikari.HikariModule;
import io.jooby.hibernate.HibernateModule;
import io.jooby.hibernate.TransactionalRequest;

{
  install(new HikariModule());

  install(new HibernateModule());

  decorator(new TransactionalRequest());

  post("/create", ctx -> {
    EntityManager em = require(EntityManager.class);

    MyEntity e = ...;

    em.persist(e);

    return e;
  });
}

The EntityManager is tied to the current HTTP request. Multiple require/injection calls produce the same EntityManager. It is a simple way of managed simple read/write operations.

The TransactionalRequest doesn’t extend session to the rendering phase (json, html, etc.). The route handler needs to make sure all the information required by the rendering phase is available. Otherwise, you are going to see LazyInitializationException.

1.4. Schema Creation

Schema creation is controlled by the hibernate.hbm2ddl.auto property. The Hibernate module configure this property using the following rules:

  • When the Flywayby module is present the value of hibernate.hbm2ddl.auto is set to none

  • When running on dev or test mode the value of hibernate.hbm2ddl.auto is set to update

  • Otherwise is set to none

1.5. Advanced Options

Advanced Hibernate configuration is supported from application configuration properties.

application.conf
hibernate.hbm2ddl.auto = create