Opentaps Hibernate Integration

Beginning with opentaps version 1.4, Hibernate will be available as a persistence tool alongside with the original ofbiz entity engine. Hibernate is a more object oriented persistence framework and better suited for the new Domain Driven Architecture, while the ofbiz entity engine will continue to be supported for legacy features from both ofbiz and opentaps. In this document, we will review how the hibernate integration in opentaps works.

Working with Hibernate in opentaps

Accessing Entities with Hibernate

To use hibernate to access your entities, you will need an org.opentaps.foundation.infrastructure.Session, which is an extension of the org.hibernate.Session class. You can obtain it from the Infrastructure class like this:

       session = infrastructure.getSession();

Then, you can work with it as if it were a Hibernate Session:

       Transaction tx = session.beginTransaction();
       TestEntity newTestEntity = new TestEntity();
       newTestEntity.setTestStringField("testInsertTestEntity string field");
       newTestEntity.setCreatedStamp(UtilDateTime.nowTimestamp());
       session.save(newTestEntity);
       tx.commit();
       session.flush();
       // ...
       TestEntity loadEntity = (TestEntity) session.load(TestEntity.class, newTestEntity.getTestId());
       // ...
       String hql = "from TestEntity eo where eo.testId='" + testEntityId2 + "'";
       Query query = session.createQuery(hql);
       List<TestEntity> list = query.list()

You do not need to close your JDBC connection manually with the opentaps Session, however. When you call

           session.close();

It will do it for you automatically.

Under the Hood: How It Works

Base Class Annotations

In opentaps version 1.4, the entity model XML from the ofbiz entity engine is still used as the base definition for all entities. The opentaps POJO generator is used to create base Java objects automatically from these entity definitions. This POJO generator will also create the annotations which hibernate can then use to map those base objects to the database persistence layer. The definitions of the annotations can be found in BaseEntity.ftl file used by the POJO generator.

Generating Hibernate Configuration Files

The POJO Generator will use hot-deploy/opentaps-common/templates/HibernateCfg.ftl to generate a base hibernate configuration file in hot-deploy/opentaps-common/config/hibernate.cfg.xml When opentaps is started, the following new container in framework/base/config/ofbiz-containers.xml

    <container name="hibernate-container" class="org.opentaps.common.container.HibernateContainer">
        <property name="delegator-name" value="default"/>
    </container>    

will generate all the hibernate configuration XML files in the hot-deploy/opentaps/config/ directory for each data source in your entity engine XML file. For example, it will generate a localmysql.cfg.xml, a localpostgres.cfg.xml

How We Get the Hibernate Session

The opentaps Infrastructure Class maintains a Map of delegatorName and hibernate SessionFactory objects. Each SessionFactory is created for its corresponding delegatorName the first time it is requested from the Infrastructure.getSessionFactory(delegatorName) method. This SessionFactory is created from ofbiz entity engine configurations:

• The HibernateContainer in ofbiz-containers.xml has a property called delegator-name
• From this delegator, we get the data source defined in entityengine.xml for the default group helper name. This is set to org.ofbiz by default in the Infrastructure class and is the group attribute of the entitygroup.xml definitions in ofbiz:

 <entity-group group="org.ofbiz" entity="AcctgTagEnumType"/>

In entityengine.xml, you map a data source to each group:

   <delegator name="default" entity-model-reader="main" entity-group-reader="main" entity-eca-reader="main" distributed-cache-clear-enabled="false">
       <group-map group-name="org.ofbiz" datasource-name="localmysql"/>
   </delegator>

So, we are basically following the entity engine from the delegator to the data source via the group.

• Once we have the data source, we can create the SessionFactory from the hibernate.cfg.xml for that data source. For example, if your data source is "localmysql", we will create the SessionFactory from the localmysql.cfg.xml created by the HibernateContainer

The HibernateContainer, which loads on startup, will cause a SessionFactory to be loaded for the delegator in the delegator-name attribute. Once this SessionFactory is loaded, it will be available for future use. Additional session factories can be obtained later by calling the getSessionFactory directly.

When the Infrastructure.getSession() method is called, it will use the delegator already in the Infrastructure object to open a JDBC connection first, and then use that JDBC connection and the SessionFactory for the delegator to return a Session.

The Infrastructure.getSession() will return an org.opentaps.foundation.infrastructure.Session, which extends the hibernate Session with the following differences:

• when the session is closed, the JDBC connection is also automatically closed
• when a Query is created, this Session will check if the query is on an entity engine view entity and construct the Query from native SQL first

Unit Tests

Unit tests for hibernate are found in org.opentaps.tests.entity.hibernate.HibernateTests in the opentaps-tests component.