Hbm (jooby-project 1.6.6 API)

java.lang.Object
- org.jooby.hbm.Hbm

All Implemented Interfaces:

Jooby.Module
```
public class Hbm
extends Object
implements Jooby.Module
```
hibernate

Hibernate ORM enables developers to more easily write applications whose data outlives the application process. As an Object/Relational Mapping (ORM) framework, Hibernate is concerned with data persistence as it applies to relational databases.

This module setup and configure Hibernate ORM and JPA Provider.

This module depends on Jdbc module, make sure you read the doc of the Jdbc module.

exports
- SessionFactory / EntityManagerFactory
- Session / EntityManager
- UnitOfWork
usage
```
 {
   use(new Hbm("jdbc:mysql://localhost/mydb")
       .classes(Beer.class)
   );

   get("/api/beer/", req -> {
     return require(UnitOfWork.class).apply(em -> {
       return em.createQuery("from Beer").getResultList();
     });
   });
 }
 
```
unit of work

We provide an UnitOfWork to simplify the amount of code required to interact within the database.

For example the next line:
```
 {
   require(UnitOfWork.class).apply(em -> {
     return em.createQuery("from Beer").getResultList();
   });
 }
 
```
Is the same as:
```
 {
    Session session = require(SessionFactory.class).openSession();
    Transaction trx = session.getTransaction();
    try {
      trx.begin();
      List<Beer> beers = em.createQuery("from Beer").getResultList();
      trx.commit();
    } catch (Exception ex) {
      trx.rollback();
    } finally {
      session.close();
    }
 }
 
```
An UnitOfWork takes care of transactions and session life-cycle. It's worth to mention too that a first requested UnitOfWork bind the Session to the current request. If later in the execution flow an UnitOfWork, Session and/or EntityManager is required then the one that belong to the current request (first requested) will be provided it.

open session in view

We provide an advanced and recommended Open Session in View pattern, which basically keep the Session opened until the view is rendered, but it uses two database transactions:
1. first transaction is committed before rendering the view and then
2. a read only transaction is opened for rendering the view
Here is an example on how to setup the open session in view filter:
```
 {
    use(new Hbm());

    use("*", Hbm.openSessionInView());
 }
 
```
event listeners

JPA event listeners are provided by Guice, which means you can inject dependencies into your event listeners:
```
 &#64;Entity
 &#64;EntityListeners({BeerListener.class})
 public class Beer {

 }

 public class BeerListener {
   &#64;Inject
   public BeerListener(DependencyA depA) {
     this.depA = depA;
   }

   &#64;PostLoad
   public void postLoad(Beer beer) {
     this.depA.complementBeer(beer);
   }
 }

 
```
Hibernate event listeners are supported too via onEvent(EventType, Class):
```
 {
    use(new Hbm()
        .onEvent(EventType.POST_LOAD, MyPostLoadListener.class));
 }
 
```
Again, MyPostLoadListener will be provided by Guice.

persistent classes

Persistent classes must be provided at application startup time via classes(Class...):
```
 {
   use(new Hbm()
       .classes(Entity1.class, Entity2.class, ..., )
   );
 }
 
```
Or via scan():
```
 {
   use(new Hbm()
       .scan()
   );
 }
 
```
Which scan the application package defined by hibernate.packagesToScan, or you can provide where to look:
```
 {
   use(new Hbm()
       .scan("foo.bar", "x.y.z")
   );
 }
 
```
advanced configuration

Advanced configuration is provided via doWithXXX callbacks:
```
 {
   use(new Hbm()
       .doWithBootstrap(bsrb -> {
         // do with bsrb
       })
       .doWithRegistry(ssrb -> {
         // do with ssrb
       })
   );
 }
 
```
Or via hibernate.* properties from your .conf file:
```
   hibernate.hbm2ddl.auto = update
 
```
life-cycle

You are free to inject a SessionFactory or EntityManagerFactory create a new EntityManagerFactory.createEntityManager(), start transactions and do everything you need.

For the time being, this doesn't work for a Session or EntityManager. A Session EntityManager is bound to the current request, which means you can't freely access from every single thread (like manually started thread, started by an executor service, quartz, etc...).

Another restriction, is the access from Singleton services. If you need access from a singleton services, you need to inject a Provider.
```
 @Singleton
 public class MySingleton {

   @Inject
   public MySingleton(Provider<EntityManager> em) {
     this.em = em;
   }
 }
 
```
Still, we strongly recommend to leave your services in the default scope and avoid to use Singleton objects, except of course for really expensive resources. This is also recommend it by Guice.

Services in the default scope won't have this problem and are free to inject the Session or EntityManager directly.
Since:

1.0.0.CR7

Author:

edgar

Constructor Summary

Constructors
Constructor and Description
`Hbm()` Creates a new `Hbm` module.
`Hbm(String db)` Creates a new `Hbm` module.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Hbm`	`classes(Class... classes)` Append persistent classes (classess annotated with Entity).
`com.typesafe.config.Config`	`config()`
`void`	`configure(Env env, com.typesafe.config.Config conf, com.google.inject.Binder binder)` Configure and produces bindings for the underlying application.
`<T> Hbm`	`doWithBootstrap(BiConsumer<org.hibernate.boot.registry.BootstrapServiceRegistryBuilder,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithBootstrap(Consumer<org.hibernate.boot.registry.BootstrapServiceRegistryBuilder> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithRegistry(BiConsumer<org.hibernate.boot.registry.StandardServiceRegistryBuilder,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithRegistry(Consumer<org.hibernate.boot.registry.StandardServiceRegistryBuilder> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionBuilder(BiConsumer<org.hibernate.SessionBuilder,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionBuilder(Consumer<org.hibernate.SessionBuilder> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionFactory(BiConsumer<org.hibernate.SessionFactory,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionFactory(Consumer<org.hibernate.SessionFactory> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionFactoryBuilder(BiConsumer<org.hibernate.boot.SessionFactoryBuilder,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSessionFactoryBuilder(Consumer<org.hibernate.boot.SessionFactoryBuilder> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSources(BiConsumer<org.hibernate.boot.MetadataSources,com.typesafe.config.Config> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`doWithSources(Consumer<org.hibernate.boot.MetadataSources> configurer)` Configurer callback to apply advanced configuration while bootstrapping hibernate:
`<T> Hbm`	`onEvent(org.hibernate.event.spi.EventType<T> type, Class<? extends T> listenerType)` Register an hibernate event listener.
`static Route.Filter`	`openSessionInView()` Creates an open session in view filter as described here.
`Hbm`	`scan()` Scan the packages defined by `hibernate.packagesToScan` property or the application package (that's the package where you application was defined) and discover persistent classes (annotated with Entity).
`Hbm`	`scan(String... packages)` Scan the provided packages and discover persistent classes (annotated with Entity).

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Hbm
```
public Hbm(String db)
```
    Creates a new Hbm module.
    
    Parameters:
    
    db - A jdbc connection string or a property with a jdbc connection string.
  - Hbm
```
public Hbm()
```
    Creates a new Hbm module. A db property must be present in your .conf file.
- Method Detail
  - classes
```
public Hbm classes(Class... classes)
```
    Append persistent classes (classess annotated with Entity).
    
    Parameters:
    
    classes - Persistent classes.
    
    Returns:
    
    This module.
  - scan
```
public Hbm scan(String... packages)
```
    Scan the provided packages and discover persistent classes (annotated with Entity).
    
    Parameters:
    
    packages - Package to scan.
    
    Returns:
    
    This module.
  - scan
```
public Hbm scan()
```
    Scan the packages defined by hibernate.packagesToScan property or the application package (that's the package where you application was defined) and discover persistent classes (annotated with Entity).
    
    Returns:
    
    This module.
  - openSessionInView
```
public static Route.Filter openSessionInView()
```
    Creates an open session in view filter as described here. Please note a call to this method give you only the filter, you must add it to your application like:
```
  {
     use(new Hbm());

     use("*", Hbm.openSessionInView());
  }
 
```
    Returns:
    
    This module.
  - onEvent
```
public <T> Hbm onEvent(org.hibernate.event.spi.EventType<T> type,
                       Class<? extends T> listenerType)
```
    Register an hibernate event listener. Listener will be created and injected by Guice.
    
    Parameters:
    
    type - Event type.
    
    listenerType - Listener type.
    
    Returns:
    
    This module.
  - doWithBootstrap
```
public <T> Hbm doWithBootstrap(BiConsumer<org.hibernate.boot.registry.BootstrapServiceRegistryBuilder,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithBootstrap
```
public <T> Hbm doWithBootstrap(Consumer<org.hibernate.boot.registry.BootstrapServiceRegistryBuilder> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithRegistry
```
public <T> Hbm doWithRegistry(Consumer<org.hibernate.boot.registry.StandardServiceRegistryBuilder> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithRegistry
```
public <T> Hbm doWithRegistry(BiConsumer<org.hibernate.boot.registry.StandardServiceRegistryBuilder,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSources
```
public <T> Hbm doWithSources(Consumer<org.hibernate.boot.MetadataSources> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSources
```
public <T> Hbm doWithSources(BiConsumer<org.hibernate.boot.MetadataSources,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionFactoryBuilder
```
public <T> Hbm doWithSessionFactoryBuilder(Consumer<org.hibernate.boot.SessionFactoryBuilder> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionFactory
```
public <T> Hbm doWithSessionFactory(BiConsumer<org.hibernate.SessionFactory,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionFactory
```
public <T> Hbm doWithSessionFactory(Consumer<org.hibernate.SessionFactory> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionFactoryBuilder
```
public <T> Hbm doWithSessionFactoryBuilder(BiConsumer<org.hibernate.boot.SessionFactoryBuilder,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionBuilder
```
public <T> Hbm doWithSessionBuilder(BiConsumer<org.hibernate.SessionBuilder,com.typesafe.config.Config> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - doWithSessionBuilder
```
public <T> Hbm doWithSessionBuilder(Consumer<org.hibernate.SessionBuilder> configurer)
```
    Configurer callback to apply advanced configuration while bootstrapping hibernate:
    
    Parameters:
    
    configurer - Configurer callback.
    
    Returns:
    
    This module
  - configure
```
public void configure(Env env,
                      com.typesafe.config.Config conf,
                      com.google.inject.Binder binder)
```
    Description copied from interface: Jooby.Module
    
    Configure and produces bindings for the underlying application. A module can optimize or customize a service by checking current the application env and/or the current application properties available from Config.
    
    Specified by:
    
    configure in interface Jooby.Module
    
    Parameters:
    
    env - The current application's env. Not null.
    
    conf - The current config object. Not null.
    
    binder - A guice binder. Not null.
  - config
```
public com.typesafe.config.Config config()
```
    Specified by:
    
    config in interface Jooby.Module
    
    Returns:
    
    Produces a module config object (when need it). By default a module doesn't produce any configuration object.

Class Hbm

hibernate

exports

usage

unit of work

open session in view

event listeners

persistent classes

advanced configuration

life-cycle

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Hbm

Hbm

Method Detail

classes

scan

scan

openSessionInView

onEvent

doWithBootstrap

doWithBootstrap

doWithRegistry

doWithRegistry

doWithSources

doWithSources

doWithSessionFactoryBuilder

doWithSessionFactory

doWithSessionFactory

doWithSessionFactoryBuilder

doWithSessionBuilder

doWithSessionBuilder

configure

config