Skip Headers
Oracle® Fusion Middleware Solution Guide for Oracle TopLink
11g Release 1 (11.1.1)
E25034-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

10 Migrating From Hibernate to TopLink

This chapter describes how to migrate applications from using Hibernate JPA annotations and its native and proprietary API to using TopLink JPA. The migration involves converting Hibernate annotations to TopLink's native annotations, and converting native Hibernate API to TopLink JPA in the application code. Standard JPA annotations and API are left unchanged.

This chapter contains the following sections:

10.1 Understanding Hibernate

Hibernate is an object-relational mapping tool for Java environments. It provides a framework for mapping Java objects to relational database artifacts, and Java data types to SQL data types. It also provides the ability to query the database and retrieve data.

For more information about Hibernate, see http://www.hibernate.org.

Motivations for Migrating

Reasons why you would want to migrate from Hibernate to TopLink include:

10.2 Main Tasks

Complete these tasks to migrate an application that uses Hibernate as its persistence provider to Oracle TopLink.

10.2.1 Task 1: Convert the Hibernate Entity Annotation

The Hibernate entity annotation, defined by the org.hibernate.annotations.Entity class, adds additional metadata beyond what is defined by the JPA standard @Entity annotation.

Example 10-1 illustrates a sample Hibernate entity annotation. The example uses the selectBeforeUpdate, dynamicInsert, dynamicUpdate, optimisticLock, and polymophism attributes. Note that the Hibernate entity annotation also defines mutable and persister attributes which are not used in this example.

Example 10-1 Sample Hibernate Entity Annotation

@org.hibernate.annotations.Entity(
     selectBeforeUpdate = true,
     dynamicInsert = true, 
     dynamicUpdate = true,
     optimisticLock = OptimisticLockType.ALL,
     polymorphism = PolymorphismType.EXPLICIT)

The following sections describe how TopLink treats selects, dynamic updates and inserts, locks, and polymorphism. For more information, see "EclipseLink/Examples/JPA/Migration/Hibernate/V3Annotations" in the Eclipselink documentation.

http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/Hibernate/V3Annotations

10.2.1.1 Convert the Select Before Update, Dynamic Insert and Update Attributes

In Hibernate, the selectBeforeUpdate attribute specifies that Hibernate should never perform an SQL UPDATE unless it is certain that an object is actually modified. The dynamicInsert attribute specifies that INSERT SQL should be generated at runtime and contain only the columns whose values are not null. The dynamicUpdate attribute specifies that UPDATE SQL should be generated at runtime and can contain only those columns whose values have changed.

By default, TopLink will always insert all mapped columns and will update only the columns that have changed. If alternate operations are required, then the queries used for these operations can be customized by using Java code, SQL, or stored procedures.

10.2.1.2 Convert the Optimistic Lock Attribute

In Hibernate, the optimisticLock attribute determines the optimistic locking strategy.

TopLink's optimistic locking functionality supports all of the Hibernate locking types and more. Table 10-1 translates locking types from Hibernate's @Entity(optimisticLock) attributes into TopLink locking policies. These policies can be configured either with the TopLink @OptimisticLocking annotation or in the TopLink orm.xml file. For more information, see "Using EclipseLink JPA Extensions for Optimistic Locking" in the EclipseLink documentation.

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Extensions_for_Optimistic_Locking

Table 10-1 Transforming Hibernate's OptimisticLock to TopLink's OptimisticLocking

Hibernate's OptimisticLock Type Description EclipseLink OptimisticLocking

NONE

No optimistic locking

EclipseLink defaults to no optimistic locking

VERSION

Use a column version

Use the JPA @Version annotation or EclipseLink annotation:

@OptimisticLocking(type = OptimisticLockingType.VERSION_COLUMN)

DIRTY

Changed columns are compared

Use the JPA @Version annotation or the EclipseLink annotation:

@OptimisticLocking(type = OptimisticLockingType.CHANGED_COLUMNS)

ALL

All columns are compared

Use the EclipseLink annotation:

@OptimisticLocking(type = OptimisticLockingType.ALL_COLUMNS)


Additionally, TopLink allows you to compare a specific set of selected columns using the OptimisticLockingType.SELECTED_COLUMNS annotation. This allows you to select the critical columns that should be compared if the CHANGED or ALL strategies do not meet your needs.

10.2.2 Task 2: Convert the Hibernate Custom Sequence Generator Annotation

In Hibernate, the @GeneratedValue annotation defines the identifier generation strategy. The @GenericGenerator allows you to define a Hibernate-specific ID generator. Example 10-2 illustrates a custom generator for sequence values.

Example 10-2 Custom Generator for Sequence Values

...
@Id
   @GeneratedValue(generator = "system-uuid")
   @GenericGenerator(name = "system-uuid", strategy = "mypackage.UUIDGenerator")
   public String getTransactionGuid()
...
 

In TopLink, a custom sequence generator can be implemented and registered by using the @GeneratedValue annotation. For more information, see: "How to use Custom Sequencing (i.e., UUID)" in the EclipseLink documentation.

http://wiki.eclipse.org/EclipseLink/Examples/JPA/CustomSequencing

10.2.3 Task 3: Convert Hibernate Mapping Annotations

The following sections describe how to convert various Hibernate annotations to TopLink annotations.

10.2.3.1 Convert the @ForeignKey Annotation

In Hibernate, the @ForeignKey annotation allows you to define the name of the foreign key to be used during schema generation.

TopLink does generate reasonable names, but does not provide an annotation or eclipselink-orm.xml support for specifying the name to use. When migrating, the recommended solution is to have TopLink generate the schema (DDL) commands to a script file instead of directly on the database. The script can then be customized to use different names prior to being executed.


Note:

The foreign key name is not used by TopLink at runtime, but is required if EclipseLink attempts to drop the schema. In this case, the drop script should be generated to a file and customized to match the foreign key names used during creation.

10.2.3.2 Convert the @Cache Annotation

In Hibernate, the @Cache annotation configures the caching of entities and relationships. Because TopLink uses an entity cache instead of a data cache, the relationships are automatically cached. In these cases, the @Cache annotation should simply be removed during migration.When the @Cache annotation is used on an entity, its behavior is similar to TopLink's @Cache annotation. For more information on the @Cache annotation and equivalent eclipselink-orm.xml configuration values, see "Eclipse User Guide on JPA Extensions" in the EclipseLink documentation.

http://wiki.eclipse.org/Using_EclipseLink_JPA_Extensions_%28ELUG%29#Using_EclipseLink_JPA_Extensions_for_Entity_Caching

10.2.4 Task 4: Modify the persistence.xml File

The persistence.xml file is the deployment descriptor file for JPA persistence. It specifies the persistence units, and declares the managed persistence classes, the Object-Relational mapping, and the database connection details. Example 10-3 illustrates a persistence.xml file for an application that uses Hibernate:

Example 10-3 Persistence File for an Application that uses Hibernate

<persistence>
   <persistence-unit name="helloworld">
      <provider>org.hibernate.ejb.HibernatePersistence</provider>
      <jta-data-source>java:/DefaultDS</jta-data-source>
      <properties>
         <property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
         <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
      </properties>
   </persistence-unit>
</persistence>

10.2.4.1 Modified persistence.xml

Example 10-4 illustrates a persistence.xml file modified for an application that uses TopLink. Key differences include the value for the persistence provider. For TopLink, this value is org.eclipse.persistence.jpa.PersistenceProvider. The names of TopLink-specific properties will typically be prefixed by eclipselink, for example, eclipselink.target-database.

Example 10-4 Persistence File Modified for EclipseLink

<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="helloworld">
    <provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
    <jta-data-source>java:/DefaultDS</jta-data-source>
    <!-- Entities must be specified for EclipseLink weaving -->
    <class>Todo</class>
    <properties>
      <property name="eclipselink.ddl-generation" value="drop-and-create-tables"/>
      <property name="eclipselink.ddl-generation.output-mode" value="database"/>
      <property name="eclipselink.weaving" value="false"/>
      <property name="eclipselink.logging.level" value="FINE"/>
    </properties>
  </persistence-unit>
</persistence> 

For more information, see "EclipseLink/Examples/JPA/Migration/JBoss" in the EclipseLink documentation.

http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/JBoss

10.2.4.2 Drop and Create the Database

For production environments, you would normally have the schema setup on the database. The following properties defined in the persistence unit are more suitable for examples and demos. These properties will instruct TopLink to automatically drop and create database tables. Any previously existing tables will be removed.

<property name="eclipselink.ddl-generation" value="drop-and-create-tables"/>
<property name="eclipselink.ddl-generation.output-mode" value="database"/>

10.2.5 Task 5: Convert Hibernate API to EclipseLink API

Table 10-2 describes the Hibernate classes that are commonly used in a JPA project and their equivalent EclipseLink (JPA) interfaces. All of the Hibernate classes are in the org.hibernate package. All of the JPA interfaces (and the Persistence class) are in the javax.persistence package.

For information on the EclipseLink API, see Oracle Fusion Middleware Java API Reference for EclipseLink.

Table 10-2 Hibernate Classes and Equivalent JPA Interfaces

org.hibernate javax.persistence Description

cfg.Configuration

Persistence

A bootstrap class that configures the session factory (in Hibernate) or the entity manager factory (in JPA). It is generally used to create a single session (or entity manager) factory for the JVM.

SessionFactory

EntityManagerFactory

Provides APIs to open Hibernate sessions (or JPA entity managers) to process a user request. Generally, a session (or entity manager) is opened per thread processing client requests.

Session

EntityManager

Provides APIs to store and load entities to and from the database. It also provides APIs to get a transaction and create a query.

Transaction

EntityTransaction

Provides APIs to manage transactions.

Query

Query

Provides APIs to execute queries.


10.3 Additional Resources

For more information on migrating from Hibernate to EclipseLink, see "EclipseLink/Examples/JPA/Migration/Hibernate":

http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/Hibernate