A plain Hibernate on Z2 sample¶

Note that Hibernate is used in other samples as well, such as Sample-jta-plain, Sample-jta-spring, and others. This sample shows the minimal things to do to use Hibernate as an implementation of the Java Persistence API (JPA).

This sample is stored in the repository z2-samples.hibernate.basic.

Prerequisites¶

You need the z_tx_tests database on a local MySQL database system. Start the MySQL client as the root user and run:

create database z_tx_tests;
grant all on z_tx_tests.* to tx@localhost identified by 'tx';

Run it¶

Like all samples, also this sample can be run as in How to run a sample. If you have the database, the fastest way to verify whether it runs is:

mkdir install
cd install 
git clone -b master http://git.z2-environment.net/z2-base.core
git clone -b master http://git.z2-environment.net/z2-samples.hibernate-basic

# on Linux / Mac OS:
cd z2-base.core/run/bin
./gui.sh

# on Windows:
cd z2-base.core\run\bin
gui.bat

Details¶

A lot of the things happening here relate to what is explained in How to transaction management.

The assumption of this example is that of a re-use domain module com.zfabrik.samples.hibernate-basic.domain that implements a "Thingy Repository" and is used from a web application that is in another module com.zfabrik.samples.hibernate-basic.web. The domain module exposes the Thingy Repository as a Z2 component that is bound by the Web app as an environment (ENC) variable and injected into the controller filter by the Web container.

The domain module makes use of Hibernate's JPA implementation and integrates with the transaction management provided by com.zfabrik.jta.

Now, step-by-step.

The domain module and its persistence context¶

The domain module com.zfabrik.samples.hibernate-basic.domain defines a persistence unit "thingies" in java/src.impl/META-INF/persistence.xml, i.e. in its implementation. That makes sense, as the XML file will be looked up with a class loader and we do not intent to retrieve from another module. Or, put differently, the persistence unit is not part of the module's API.

In order to integrate with the built-in transaction management the persistence.xml declares the JTA data source

<jta-data-source>components:com.zfabrik.samples.hibernate-basic.domain/DB</jta-data-source>

and the Transaction Manager Lookup

<property name="hibernate.transaction.manager_lookup_class" value="com.zfabrik.hibernate.TransactionManagerLookup" />

The former points to the data source component com.zfabrik.samples.hibernate-basic.domain/DB, while the latter makes sure Hibernate can register with the transaction manager implementation.

The persistence unit defines only one entity. The Thingy as in Thingy.java. That is an API-exposed type. We use the simplified pattern of exposing persistent objects in the API rather than using Data Transfer Objects (DTOs).

Also, the domain module exposes the interface of the Thingy Repository. This interface is used by the Web application retrieve, store, and delete thingies.

The implementation of the Thingy Repository, ThingyRepositoryImpl is not a public type. Instead, it is instantiated and held on to via a Z2 component lookup from the Web app on the component com.zfabrik.samples.hibernate-basic.domain/repository.

In ThingyRepositoryImpl, in order to access and re-use the JPA Entity Manager for the persistence unit "thingies" we use EntityManagerUtil from org.hibernate with a Entity Manager Factory that we create upon service instantiation and using the user transaction implementation of com.zfabrik.jta:

public class ThingyRepositoryImpl implements ThingyRepository {
    private EntityManagerFactory emf;

    public ThingyRepositoryImpl() {
        // 
        // initially create the EMF for this domain
        //        
        this.emf = ThreadUtil.cleanContextExecute(
            this.getClass().getClassLoader(), 
            new Callable<EntityManagerFactory>() {
                public EntityManagerFactory call() throws Exception {
                    return Persistence.createEntityManagerFactory("thingies");
                };
            }
        );
    }

    @Override
    public void store(Thingy thingy) {
        this.em().persist(thingy);
    }

    @SuppressWarnings("unchecked")
    @Override
    public Collection<Thingy> findAll() {
        return this.em().createQuery("select t from Thingy t").getResultList();
    }

    @Override
    public void delete(int id) {
        Thingy t = this.em().find(Thingy.class, id);
        if (t != null) {
            this.em().remove(t);
        }
    }

    //
    // Uses the Entity Manager Util that holds on to EMs created from the passed on EMF
    // while the transaction is still open.
    //
    private EntityManager em() {
        return EntityManagerUtil.getEntityManager(
            IComponentsLookup.INSTANCE.lookup(
                "com.zfabrik.jta/userTransaction", 
                TransactionManager.class
            ),
            this.emf
        );
    }
}

Note that when creating the entity manager factory, we have to make sure the right context class loader is set so that the persistence unit definition will be picked up by Hibernate. This is a general pattern when initializing services in a modular application: You need to distinguish when the service's context matters vs. when the caller's context matters.

The web module, transaction boundaries, and service re-use¶

Let's turn to the Web application in com.zfabrik.samples.hibernate-basic.web/web. And let's start with how the Thingy Repository is accessed from the Web app. In this example we do not use Spring or direct lookups, instead we use the Web container provided dependency injection mechanisms. In "WebContent/WEB-INF/jetty-env.xml":redmine.z2-environment.net/projects/z2-samples/repository/z2-samples-hibernate-basic/revisions/master/entry/com.zfabrik.samples.hibernate-basic.web/web/WebContent/WEB-INF/jetty-env.xml we bind the result of a JNDI lookup for the repository implementation component to the Environment Naming Context (ENC) variable "repos/thingies". This is java EE mechanics. It means that from within the Web app, the repository would available under the JNDI name "java:comp/env/repos/thingies":

<Configure class="org.eclipse.jetty.webapp.WebAppContext">
  <New id="thingyRepository" class="org.eclipse.jetty.plus.jndi.Resource">
    <Arg>repos/thingies</Arg>
    <Arg>
      <New class="javax.naming.LinkRef">
        <Arg>components:com.zfabrik.samples.hibernate-basic.domain/repository?type=com.zfabrik.samples.hibernate_basic.thingies.ThingyRepository</Arg>
      </New>
    </Arg>
  </New>
</Configure>

See also Jetty JNDI.

Anyway. Now, in the ControllerFilter we inject the Thingy Repository like this:

public class ControllerFilter implements Filter {

    // inject thingies repository (see WEB-INF/jetty-env.xml)
    @Resource(name="repos/thingies")
    private ThingyRepository thingyRepository;

...
}

Alternatively, if you think this is a little overkill, you might as well use a direct lookup, either with JNDI using the name in the XML or via Z2's component lookup

IComponentsLookup.INSTANCE.lookup("com.zfabrik.samples.hibernate-basic.domain/repository",ThingyRepository.class);

Finally a word on transaction management. Transaction boundaries are controlled by the TransactionFilter contained in the sample. We make use of TransactionUtil from com.zabrik.jta to wrap the actual web app request in a transaction:

@Override
public void doFilter(final ServletRequest sreq, final ServletResponse sres,    final FilterChain chain) throws IOException, ServletException {
  HttpServletRequest req = (HttpServletRequest) sreq;
  if (req.getDispatcherType()==DispatcherType.REQUEST || req.getDispatcherType()==DispatcherType.ASYNC) {
    try {
      TransactionUtil.run(
        (UserTransaction) new InitialContext().lookup("java:comp/UserTransaction"),
        new Callable<Void>() {
          public Void call() throws Exception {
            chain.doFilter(sreq, sres);
            return null;
          }
        }
      );
    } catch (Exception e) {
      throw new ServletException(e);
    }
  } else {
    chain.doFilter(sreq, sres);
  }
}