Max Poon's Blog: Community: Java Enterprise Archives

how to configure Java Persistence API (JPA) based application to use Hibernate and Ehcache as the JPA and caching implementation provider respectively.

SimpleJpaHibernateApp is developed based on JSR 220 Java Persistence API with optional Hibernate-specific options, e.g. in persistence.xml or @Cache Annotations for caching applied. Hence, due to the pluggability of the Java Persistence API architecture, JPA-compliant applications such as SimpleJpaHibernateApp can easily be switched to make use of other Java Persistence providers such as Glassfish JPA. This article describes how this can be done.

Glassfish JPA / TopLink Essentials

As mentioned in Oracle's TopLink JPA web page, "TopLink Essentials is the open-source community edition of Oracle's TopLink product. It provides the JPA functionality for the EJB 3.0 Reference Implementation.".

As also mentioned in Glassfish Java Persistence API Implementation web page, TopLink Essentials is "the Java Persistence API implementation at the GlassFish community", and adopted as the JPA Reference Implementation within Glassfish Java EE Reference Implementation.

Configuring SimpleJpaHibernateApp to use Glassfish JPA

The configuration works involve the following suggested steps :

Step 1 - (Optional) Renaming "SimpleJpaHibernateApp" project name and Java package path names to "SimpleJpaToplinkApp"
Step 2 - Changing Java Persistence Provider in Persistence Unit
Step 3 - (Optional) Changing DB Schema Name to "APP_SimpleJpaToplinkApp", and Fixing the Web App Context Path and Referencing URIs
Step 4 - Compiling and Deploying the new "SimpleJpaToplinkApp"

[Note: Only Step 2 above is the minimally necessary step generally, while Steps 1 & 3 are to fix the NetBeans project and Java package path naming consistencies (applicable to applications like "SimpleJpaHibernateApp" where the NetBeans project name, Java package path names and web app context URI are preferred to be changed as well.]

Step 1 - (Optional) Renaming "SimpleJpaHibernateApp" project name and Java package path names to "SimpleJpaToplinkApp"

To make the NetBeans project and package naming consistent, the "SimpleJpaHibernateApp" project name and Java package path names are first suggested to be changed to, e.g. "SimpleJpaToplinkApp". One way to do this is as follows.

(1A) First, make a complete copy of all the files and sub-directories of the original NetBeans project "SimpleJpaHibernateApp" so that the copy resides under a directory, say "...../SimpleJpaToplinkApp" instead of the original "...../SimpleJpaHibernateApp".

(1B) Open the copy of "SimpleJpaHibernateApp" (now under the directory "...../SimpleJpaToplinkApp"), right-click on NetBeans project "SimpleJpaHibernateApp" and select "Rename" to rename it to "SimpleJpaToplinkApp".

Figure 1B - Renaming "SimpleJpaHibernateApp" to "SimpleJpaToplinkApp" in NetBeans IDE

This changes the NetBeans project name in ...../SimpleJpaToplinkApp/nbproject/project.xml to SimpleJpaToplinkApp as shown below.

Code Listing 1B - New project name in nbproject/project.xml (changes in red)

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://www.netbeans.org/ns/project/1">
<type>org.netbeans.modules.web.project</type>
<configuration>
    <data xmlns="http://www.netbeans.org/ns/web-project/3">
      <name>SimpleJpaToplinkApp</name>
       ....
    </data>
</configuration>
</project>

(1C) Change the Persistence Unit name from "SimpleJpaHibernateAppPU" to "SimpleJpaToplinkAppPU" in persistence.xml

Code Listing 1C - Changing Persistence-Unit name from "SimpleJpaHibernateAppPU" to "SimpleJpaToplinkAppPU" in persistence.xml

[Note: Steps (2A) and (2B) below involve also changes in persistence.xml and hence may be done here as well, but are left to be done later as they are necessary steps to be grouped in Step 2.]

(1D) Re-open the "renamed SimpleJpaToplinkApp" project in NetBeans IDE, then change the Java package path name "SimpleJpaHibernateApp" to "SimpleJpaToplinkApp" by right-clicking on the concerned Source Packages and selecting [Refactor] > [Rename...] to change the package names from :

SimpleJpaHibernateApp.agents to SimpleJpaToplinkApp.agents
SimpleJpaHibernateApp.controller to SimpleJpaToplinkApp.controller
SimpleJpaHibernateApp.entities to SimpleJpaToplinkApp.entities

Figure 1D - Using NetBeans IDE "Refactor" to Rename Java Source Packages path names

Step 2 - Changing Java Persistence Provider in Persistence-Unit

(2A) Double click on [persistence.xml] under [Configuration Files] in [Projects] Window to open up the [Persistence Units] Design Panel, then change the Persistence Provider for SimpleJpaToplinkAppPU from "Hibernate" to "TopLink(default)" as follows.

Figure 2A - Using Netbeans IDE Design Panel for persistence.xml to Change Java Persistence Provider

(2B) Switch from "Design" to "XML" Panel for persistence.xml, observe the change of <provider> element, replace the Hibernate caching properties with TopLink caching, and select [File] > [Save] to save the modified persistence.xml as shown :

Code Listing 2B - Changing <provider> and <properties> for caching in persistence.xml

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
<persistence-unit name="SimpleJpaToplinkAppPU" transaction-type="JTA">
    <provider>oracle.toplink.essentials.ejb.cmp3.EntityManagerFactoryProvider
    </provider>
    <jta-data-source>jdbc/sample</jta-data-source>
    <class>simpleJpaToplinkApp.entities.Manufacturer</class>
    <class>simpleJpaToplinkApp.entities.ProductCode</class>
    <class>simpleJpaToplinkApp.entities.Product</class>
    <properties>
      <property name="toplink.cache.type.Manufacturer" value="HardWeak"/>
      <property name="toplink.cache.type.ProductCode" value="Full"/>
      <property name="toplink.cache.type.Product" value="SoftWeak"/>
    </properties>
</persistence-unit>
</persistence>

While this configuration (similar to corresponding ones for Hibernate) in persistence.xml will enable basic caching for specified JPA entity classes, configuration for Glassfish JPA is a bit simplier (and also more "restrictive") as Glassfish JPA has already included and can only uses its own caching implementation instead of requiring/having the choice to specify/configure for an external caching implementation such as Ehcache.

Any @Cache annotations used in entity class to Hibernate caching should be removed as they are not supported by Glassfish JPA / TopLink Essentials (though TopLink may have its own @Cache annotations). Use <properties> configuration in persistence.xml to enable caching in Glassfish JPA.

Refer to Further Resources for more information on Glassfish JPA / TopLink Essentials caching architecture and options such as "Full", "HardWeak", and "SoftWeak".

(2C) Change SimpleJpaToplinkApp's referencing Library from Hibernate libraries to TopLink Essentials library.

Figure 2C - SimpleJpaToplinkApp changed to use TopLink Essentials library in NetBeans IDE

(2D) Since JMX monitoring is not currently used in SimpleJpaToplinkApp, from all 3 controllers (ManufacturerController, ProductCodeController, ProductController), comment out statements :

import simpleJpaToplinkApp.agents.JmxAgent;
initJMX();
void initJMX() { ... }

and change

@PersistenceUnit(unitName = "SimpleJpaHibernateAppPU")

@PersistenceUnit(unitName = "SimpleJpaToplinkAppPU")

Then, right-click on [simpleJpaToplink.App.JmxAgent] and select [Refactor] > [Safely Delete...] to delete JmxAgent from the NetBeans project.

Step 3 - (Optional) Changing DB Schema Name to APP_SimpleJpaToplinkApp, and Fixing the Web App Context Path and Referencing URIs

(3A) For naming consistency, change the DB schema name to from "APP_SimpleHibernateApp" to "APP_SimpleJpaToplinkApp" using NetBeans IDE "Rename" function.

Figure 3A1 - Using NetBeans IDE "Rename" to Change DB Schema Name

Figure 3A2 - Using NetBeans IDE "Rename" to Change DB Schema Name

(3B) Also, the web application context path can optionally be fixed to "SimpleToplinkApp" (as below), and subsequently all JSF views referencing previous context URI and text labels "SimpleHibernateApp" are required to be changed to "SimpleToplinkApp".

Figure 3B - Changing Context Path

Step 4 - Compiling and Deploying the new "SimpleJpaToplinkApp"

Finally, the "new" SimpleJpaToplinkApp project should look as shown in Figure 3B, and is ready to be compiled and deployed. The service will be available at deployed Glassfish HTTP service port with context URI "/SimpleJpaToplinkApp" as specified above.

Further Resources

Extending the NetBeans Tutorial JSF-JPA-Hibernate Application, Part 3 - Enabling JMX Monitoring on Hibernate v3 and Ehcache 1.3.0 on "SimpleJpaHibernateApp"

Posted by maxpoon on June 27, 2007 at 11:21 AM | Permalink | Comments (0)

Background

This is the continuation from the previous article "Extending the NetBeans Tutorial JSF-JPA-Hibernate Application, Part 2 - Enabling JMX Monitoring on Hibernate v3 and Ehcache 1.3, on HibernateTutorialApp" where we continue with (3) and (4) of the following :

(3) Configuring SimpleJpaHibernateApp to use Ehcache 1.3.0

The configurations for SimpleJpaHibernateApp, created with the NetBeans tutorial "Using Hibernate With the Java Persistence API", to use Ehcache 1.3.0 are similar to those of "Configuring HibernateTutorialApp/HibernateTravelPOJO to use Ehcache 1.3.0" , except :

SimpleJpaHibernateApp is directly configured to use Hibernate (Hibernate-3.2.2, or above, e.g. Hibernate-3.2.4sp1) and Ehcache-1.3.0
persistence.xml and hibernate.cfg.xml (cache related configurations highlighted in bold), and ehcache.cfg.xml as shown :

Code Listing 3.1 - persistence.xml for SimpleJpaHibernateApp

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="1.0" xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
<persistence-unit name="SimpleJpaHibernateAppPU" transaction-type="JTA">
    <provider>org.hibernate.ejb.HibernatePersistence</provider>
    <jta-data-source>jdbc/sample</jta-data-source>
    <class>simpleJpaHibernateApp.entities.ProductCode</class>
    <class>simpleJpaHibernateApp.entities.Product</class>
    <class>simpleJpaHibernateApp.entities.Manufacturer</class>
    <properties>
      <property name=
      "hibernate.ejb.classcache.simpleJpaHibernateApp.entities.ProductCode"
    value="read-write"/>
      <property name=
        "hibernate.ejb.classcache.simpleJpaHibernateApp.entities.Product"
    value="read-write"/>
      <property name=
        "hibernate.ejb.classcache.simpleJpaHibernateApp.entities.Manufacturer"
value="read-write"/>
      <property name="hibernate.ejb.cfgfile" value="/hibernate.cfg.xml"/>
    </properties>
</persistence-unit>
</persistence>

Code Listing 3.2 - hibernate.cfg.xml for SimpleJpaHibernateApp

<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE hibernate-configuration PUBLIC
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">

<hibernate-configuration>

<session-factory>

    
    <property name="hibernate.dialect">
        org.hibernate.dialect.DerbyDialect</property>

    
    <property name="hibernate.show_sql">true</property>

    
    
    <property name="hibernate.cache.provider_class">
        net.sf.ehcache.hibernate.SingletonEhCacheProvider</property>
    <property name="hibernate.cache.provider_configuration">
        /ehcache.cfg.xml</property>
    <property name="hibernate.cache.use_minimal_puts">false</property>
    <property name="hibernate.cache.use_query_cache">true</property>
    <property name="hibernate.cache.use_second_level_cache">true</property>
    <property name="hibernate.cache.use_structured_entries">true</property>

    </session-factory>

</hibernate-configuration>

Coding Listing 3.3 - ehcache.cfg.xml for SimpleJpaHibernateApp

<?xml version="1.0" encoding="UTF-8"?>
<ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="ehcache.xsd">
<diskStore path="java.io.tmpdir"/>
<defaultCache
    maxElementsInMemory="10000"
    eternal="false"
    timeToIdleSeconds="120"
    timeToLiveSeconds="120"
    overflowToDisk="true"
    diskPersistent="true"
    diskExpiryThreadIntervalSeconds="120"
    memoryStoreEvictionPolicy="LRU"
/>
<cache name="simpleJpaHibernateApp.entities.ProductCode"
       maxElementsInMemory="300"
         eternal="true"
         overflowToDisk="false"
/>
<cache name="simpleJpaHibernateApp.entities.Product"
         maxElementsInMemory="300"
         eternal="true"
     overflowToDisk="false"
/>
<cache name="simpleJpaHibernateApp.entities.Manufacturer"
         maxElementsInMemory="300"
         eternal="true"
         overflowToDisk="false"
/>
<cache name="simpleJpaHibernateApp.entities.ProductCode.productCollection"
         maxElementsInMemory="300"
         eternal="true"
         overflowToDisk="false"
/>
<cache name="simpleJpaHibernateApp.entities.Manufacturer.productCollection"
         maxElementsInMemory="300"
         eternal="true"
         overflowToDisk="false"
/>
</ehcache>

(4) Configuring SimpleJpaHibernateApp to enable JMX monitoring on Hibernate and Ehcache

After being configured to use Ehcache 1.3.0 as shown in "Configuring SimpleJpaHibernateApp to use Ehcache 1.3.0" above, the SimpleJpaHibernateApp can also be extended to enable JMX monitoring, e.g. on Hibernate and Ehcache used, similar to "Configuring HibernateTutorialApp/HibernateTravelPOJO to enable JMX monitoring on Hibernate and Ehcache" in previous article.

Step 4.1 - Create JMX Agent with Hibernate and Ehcache MBeans Registration Codes

Similar to Step 2.1 in "Configuring HibernateTutorialApp/HibernateTravelPOJO to enable JMX monitoring on Hibernate and Ehcache", we need to create the JMX Agent which registers the Hibernate and Ehcache MBeans to enable JMX monitoring on them. However, there are a few small but important differences here...

(A) To register Hibernate's MBean, we still need the following codes :

    // Enable Hibernate JMX Statistics
    StatisticsService statsMBean = new StatisticsService();
    statsMBean.setSessionFactory(sessionFactory);
    statsMBean.setStatisticsEnabled(true);
    mbs.registerMBean(statsMBean, on);

i.e. we need to get Hibernate SessionFactory from our JPA execution environment (which uses the implementation-independent JPA PersistentUnit and the associated EntityMangerFactory instead) to enable JMX monitoring on Hibernate, by (also used by the NetBeans Tutorial "NetBeans Wiki - UsingHibernateWithJPA") :

Session session = (Session) em.getDelegate();

And, in our case for SimpleJpaHibernateApp, it is followed by :

SessionFactory sessionFactory = session.getSessionFactory();

to get SessionFactory as in Code Listing 4.1 (additional MBeans registration codes in bold) below.

(B) Also, we would like to modify the init() method to take EntityMangerFactory from the calling context, to get the Hibernate SessionFactory for registering Hibernate statsMBean.

Code Listing 4.1 - SimpleJpaHibernateApp's JmxAgent.java

/*
* JmxAgent.java
*
*/

package simpleJpaHibernateApp.agents;

import java.lang.management.ManagementFactory;
import javax.management.MBeanServer;
import javax.management.ObjectName;
import javax.persistence.EntityManagerFactory;
import javax.persistence.EntityManager;
import net.sf.ehcache.CacheManager;
import net.sf.ehcache.management.ManagementService;
import org.hibernate.Session;
import org.hibernate.SessionFactory;
import org.hibernate.jmx.StatisticsService;

/**
* JMX agent (singleton) for monitoring Hibernate and Ehcache
* in SimpleJpaHibernateApp, which uses:
* <ul>
* <li>JavaServer Faces (JSF) web-tier</li>
* <li>Java Persistence API (JPA) persistence</li>
* <li>Hibernate Core (3.2.4 sp1) and Hibernate EntityManager (3.3.1)</li>
* <li>Ehcache 1.3.0</li>
* </ul>
*
* @author Max Poon (maxpoon@dev.java.net)
*/
public class JmxAgent {

private EntityManager em;
private Session session;
private SessionFactory sf;

/**
   * Instantiate, register MBeans, enable Hibernate & Ehcache JMX Statistics
   * @param emf javax.persistence.EntityManagerFactory to be passed in
   *            from the invoking context (instead of creating it here
   *            which is expensive operation)
   */
public void init(EntityManagerFactory emf) throws Exception {

    try {
      // Create EntityManager from EntityManagerFactory passed in
      // from the invoking context
      em = emf.createEntityManager();

      // Get Hibernate Session and SessionFactory from EntityManager
      // *Important* for registering the Hibernate SessionFactory
      // with org.hibernate.jmx.StatisticsService later on
      // to enable JMX monitoring of Hibernate statistics
      session = (Session) em.getDelegate();
      sf = session.getSessionFactory();
} catch (Exception ex) {
      ex.printStackTrace();
    } finally {
      em.close();
    }

    ObjectName on = new ObjectName
        ("Hibernate:type=statistics,application=SimpleJpaHibernateApp");

    // Enable Hibernate JMX Statistics
    StatisticsService statsMBean = new StatisticsService();
    statsMBean.setSessionFactory(sf);
    statsMBean.setStatisticsEnabled(true);
    mbs.registerMBean(statsMBean, on);
    /*
   * Enable Ehcache JMX Statistics
     * Use CacheManager.getInstance() instead of new CacheManager()
     * as net.sf.ehcache.hibernate.SingletonEhCacheProvider is used
     * to ensure reference to the same CacheManager instance as used
     * by Hibernate
     */
    CacheManager cacheMgr = CacheManager.getInstance();
    ManagementService.registerMBeans
        (cacheMgr, mbs, true, true, true, true);
}

/**
   * Returns an agent singleton.
   */
public synchronized static JmxAgent getDefault(EntityManagerFactory emf)
    throws Exception {
    if(singleton == null) {
      singleton = new JmxAgent();
singleton.init(emf);
    }
    return singleton;
}

public MBeanServer getMBeanServer() {
    return mbs;
}

// Platform MBeanServer used to register your MBeans
private final MBeanServer mbs = ManagementFactory.getPlatformMBeanServer();

// Singleton instance
private static JmxAgent singleton;
}

Step 4.2 Modify JSF Managed Beans to initiate JMX Agent

Unlike the HibernateTravelPOJO application, there is no HibernateUtil.java-like object for getting Hibernate Session in SimpleJpaHibernateApp. One solution is to initiate JmxAgent during the 1st retrieval of EntityManager in following JSF managed beans / controllers :

simpleJpaHibernate.controllers.ProductController
simpleJpaHibernate.controllers.ProductCodeController
simpleJpaHibernate.controllers.ManufacturerController

e.g. as shown in Code Listing 4.2 for simpleJpaHibernate.controllers.ProductController :

Code Listing 4.2 - ProductController.java modified to initiate JmxAgent if needed

/*
* ProductController.java
*
*/

package simpleJpaHibernateApp.controller;

import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import javax.annotation.Resource;
....
import simpleJpaHibernateApp.agents.JmxAgent;
import simpleJpaHibernateApp.entities.Manufacturer;
import simpleJpaHibernateApp.entities.Product;
import simpleJpaHibernateApp.entities.ProductCode;

/**
* This version of ProductController uses JPA query with SQL joint
* to retrieve all Products associated with a given ProductCode
* indicated by its ID 'selectedProdCode'.
* This shows simple code modification to get additional behaviour.
*
* @author Max Poon (maxpoon@dev.java.net)
*/
public class ProductController {

    /** Creates a new instance of ProductController */
    public ProductController() { }

    private Product product;
    private ProductCode selectedProductCode;
    private String selectedProdCode;
    private DataModel model;

    @Resource
    private UserTransaction utx;

    @PersistenceUnit(unitName = "SimpleJpaHibernateAppPU")
    private EntityManagerFactory emf;

    private EntityManager getEntityManager() {
        initJMX();
        return emf.createEntityManager();
    }

    // Initiate JMX if needed
    void initJMX() {
        try {
            JmxAgent.getDefault(emf);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
    ...
    ...

Similar modifications should also be done for :

simpleJpaHibernate.controllers.ProductCodeController
simpleJpaHibernate.controllers.ManufacturerController

Then recompile SimpleJpaHibernateApp with the above configurations and checked that it is working fine getting also the web interface and functionalities as those in "Extending the NetBeans Tutorial JSF-JPA-Hibernate Application, Part 1 - Co-ordinating Query Views Based on Parameter Passing from JSF View to Managed Bean".

Step 4.3 - Use JConsole to Observe JMX Statistics

Similar to Step 2.3 in "Configuring HibernateTutorialApp/HibernateTravelPOJO to enable JMX monitoring on Hibernate and Ehcache", start JConsole and connect to JVM running GlassFish (indicated by "com.sun.enterprise.server.PELaunch" in JConsole) and observe the following real-time JMX information collected.

Starting with the "Listing ProductCodes" page :

Figure 4.3.1 - "Listing ProductCodes" page of SimpleJpaHibernateApp

Figure 4.3.2 - JConsole showing Hibernate Entity Names, Queries, 2nd Level Cache Regions, and related statistics

Figure 4.3.3 - JConsole showing Ehcache Statistics on ProductCode, with 6 cache miss for the 6 ProductCode instances retrieved

Click on "SW" page on "Listing ProductCodes" page to get the following, then click on "List of Product with this Product Code" to get the next screen shown in Figure 4.3.7.

Figure 4.3.4 - "Detail of ProductCode" page of SimpleJpaHibernateApp for ProdCode="SW"

Figure 4.3.5 - JConsole showing Hibernate Statistics being updated as compared to Figure 4.3.2

Figure 4.3.6 - JConsole showing Ehcache Statistics for ProductCode updated (with 2 more cache misses and 7 more cache hits) as compared to Figure 4.3.3

Figure 4.3.7 - "Listing Products" page of SimpleJpaHibernateApp for ProdCode="SW"

Figure 4.3.8 - JConsole showing Hibernate Statistics being updated as compared to Figure 4.3.5

Figure 4.3.9 - JConsole showing Ehcache Statistics for ProductCode updated, with 1 more (ProductCode where ProdCode="SW") cache hit as compared to Figure 4.3.6

Figure 4.3.10 - JConsole showing Ehcache Statistics for Product, with 8 new retrieval, i.e. cache misses, for the 8 Product instances where ProdCode="SW" as shown in Figure 4.3.7

Powered by
Movable Type 3.01D

java.net RSS Feeds