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.8.9</version>
</dependency>

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

2) Add database driver (mySQL here):

Maven
Gradle
<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>8.0.20</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.

There is a SessionRequest decorator that works identically but leaves transaction management to you, so no transaction is started/committed or rollback during a HTTP request.

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 FlywayModule module is present, the value of hibernate.hbm2ddl.auto is set to none

  • When application.env property is set to dev or test, 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

Or by providing a custom HibernateConfigurer instance. The HibernateConfigurer let you hook and customize Hibernate bootstrap process:

HibernateConfigurer:
import io.jooby.hibernate.HibernateConfigurer;

public class MyConfigurer extends HibernateConfigurer {
  /**
   * Hook into bootstrap registry and customize it.
   *
   * @param builder Builder.
   * @param config Configuration.
   */
  public void configure(BootstrapServiceRegistryBuilder builder, Config config) {
  }

  /**
   * Hook into service registry and customize it.
   *
   * @param builder Builder.
   * @param config Configuration.
   */
  public void configure(StandardServiceRegistryBuilder builder, Config config) {
  }

  /**
   * Hook into metadata sources and customize it.
   *
   * @param sources Sources.
   * @param config Configuration.
   */
  public void configure(MetadataSources sources, Config config) {
  }

  /**
   * Hook into metadata builder and customize it.
   *
   * @param builder Builder.
   * @param config Configuration.
   */
  public void configure(MetadataBuilder builder, Config config) {
  }

  /**
   * Hook into SessionFactory creation and customize it.
   *
   * @param builder Builder.
   * @param config Configuration.
   */
  public void configure(SessionFactoryBuilder builder, Config config) {
  }
}

{
  install(new HibernateModule().with(new MyConfigurer()));
}

Something similar is possible for custom Session using a SessionProvider:

SessionProvider
{
  install(new HibernateModule().with(builder -> {
    return builder
     .flushMode(AUTO)
     .openSession();
  }));
}