Skip to main content

Extending the NetBeans Tutorial JSF-JPA-Hibernate Application, Part 4 - Switching from Hibernate JPA to TopLink Essentials

Posted by maxpoon on August 11, 2007 at 9:29 AM PDT

Background

It was shown in the previous article

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 :

[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

1_SimpleJpaToplinkApp_renameProj_650.png

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
<?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>org.hibernate.ejb.HibernatePersistence</provider>

    <jta-data-source>jdbc/sample</jta-data-source>

     ....
  </persistence-unit>


</persistence>

[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

1_SimpleJpaToplinkApp_refactorPackageName_650.png

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

2_SimpleJpaToplinkApp_switchTopLink1_650.png

(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

2_SimpleJpaToplinkApp_switchTopLink3a_650.png

(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")

to

  • @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

3_SimpleJpaToplinkApp_changeSchemaName1_650.png

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

2_SimpleJpaToplinkApp_switchTopLink5_650.png

(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

3_SimpleJpaToplinkApp_switchTopLink5_650.png

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

Related Topics >>