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:
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.
Reasons why you would want to migrate from Hibernate to TopLink include:
Performance and scalability: TopLink's caching architecture allows you to minimize object creation and share instances. TopLink's caching supports single-node and clustered deployments.
Support for leading relation databases: TopLink continues to support all leading relational databases with extensions specific to each. TopLink is also the best ORM solution for the Oracle database.
A comprehensive persistence solution: While TopLink offers industry leading object-relational support, TopLink also uses its core mapping functionality to deliver Object-XML (JAXB), Service Data Object (SDO), and Database Web Services. Depending on your requirements you can use one or more of the persistence services based on the same core persistence engine.
JPA Support: As the JPA 1.0 specification co-leads, Oracle and the TopLink/EclipseLink team have been focused on delivering a JPA-compliant solution with supporting integration with JDeveloper, ADF, Spring, and the Eclipse IDE (Dali project). Oracle has delivered the JPA 1.0 reference implementation and EclipseLink delivers the JPA 2.0 reference implementation. Oracle is focussed on standards-based development, while still offering many advanced capabilities.
Complete these tasks to migrate an application that uses Hibernate as its persistence provider to Oracle TopLink.
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
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.
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.
Table 10-1 Transforming Hibernate's OptimisticLock to TopLink's OptimisticLocking
| Hibernate's OptimisticLock Type | Description | EclipseLink OptimisticLocking |
|---|---|---|
|
|
No optimistic locking |
EclipseLink defaults to no optimistic locking |
|
|
Use a column version |
Use the JPA
|
|
|
Changed columns are compared |
Use the JPA
|
|
|
All columns are compared |
Use the EclipseLink annotation:
|
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.
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
The following sections describe how to convert various Hibernate annotations to TopLink annotations.
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.
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.
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>
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
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"/>
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 Oracle TopLink.
Table 10-2 Hibernate Classes and Equivalent JPA Interfaces
| org.hibernate | javax.persistence | Description |
|---|---|---|
|
|
|
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. |
|
|
|
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. |
|
|
|
Provides APIs to store and load entities to and from the database. It also provides APIs to get a transaction and create a query. |
|
|
|
Provides APIs to manage transactions. |
|
|
|
Provides APIs to execute queries. |
For more information on migrating from Hibernate to EclipseLink, see "EclipseLink/Examples/JPA/Migration/Hibernate":
http://wiki.eclipse.org/EclipseLink/Examples/JPA/Migration/Hibernate