Jump to: navigation, search


< EclipseLink‎ | Examples‎ | JPA‎ | Migration
Revision as of 15:26, 3 September 2009 by Rick.sapir.oracle.com (Talk | contribs) (xref for 278216)

Migrating from Oracle TopLink to EclipseLink

This article will give an overview of how to migrate an Oracle TopLink project to EclipseLink

Replace Deprecated Oracle TopLink API

API that has been deprecated in Oracle TopLink has been removed from EclipseLink. If your code uses any deprecated TopLink API, you must update the code to the API recommended in the deprecation comment.

Refer to the Oracle TopLink API Modification Guide for a complete list of deprecated API, including recommended replacements.

Rename Packages

The base package in Oracle TopLink has been renamed from oracle.toplink to org.eclipse.persistence. In addition, some lower level packages have also been refactored.

To facilitate moving to these new package names, a package renamer tool is included with the EclipseLink installation. This package renamer will replace the old Oracle TopLink package names with the new EclipseLink names. You should use this tool on your:

  • project source code
  • project.xml file
  • persistence.xml file
  • sessions.xml file

The package renamer is located in the eclipselink\utils\rename directory and includes both a JAR file and some scripts. The utilities.MigrateTopLinkToEclipseLink class contains the main method that runs the package renamer. The project does not have any external dependencies.

Running the Package Renamer

To run the package renamer using the scripts:

  1. Unzip the eclipselink-installer.zip from the base of the SVN structure and find the scripts in the bin directory.
  2. Run either packageRename.cmd or packageRename.sh (both located in the <INSTALL_DIRECTORY>/utils/rename directory) with two arguments:
    • sourceLocation - The directory that contains the files to rename.
    • targetLocation - The destination directory. The package renamer will remove any existing Java and XML files; in most cases you may want to specify an empty directory.

    For example:
    packageRename c:/mySourceLocation c:/myDestinationLocation

The package renamer performs a recursive directory search for Java and XML files to rename. The renamed version of each file is saved in the corresponding directory in the targetLocation.

Dealing with XML Configuration files

The package renamer is capable of renaming our XML configuration files, but depending on the type of file, you may need to make additional changes or have other options.

Sessions XML

Sessions XML files from Oracle TopLink 11 can be read by EclipseLink. You can continue to use those files or for a more forward compatible solution, run the renamer on your sessions xml files.

Deployment XML

Deployment XML files from Oracle TopLink 10.1.3 and above can be read by EclipseLink. You can continue to use those files or for a more forward compatible solution, run the renamer on these files and replace the version string in the XML Header with the following:

"Eclipse Persistence Services"

Persistence XML

In order to use EclipseLink as a persistence provider you will have to run the renamer on your persistence.xml files. The renamer will update the persistence provider to the EclipseLink persistence provider and also update any Oracle TopLink specific properties to the EclipseLink equivalent.

Review the What You May Need to Know About Using EclipseLink JPA Persistence Unit Properties section of the EclipseLink User Guide for additional information when migrating to EclipseLink.


ORM XML is non-TopLink dependant and does not need to be updated.

TopLink Essentials

The above process will also work for TopLink Essentials projects

TopLink Workbench

To convert your TopLink Workbench (.mwp) project to an EclipseLink Workbench project:

  1. Use the package renamer (as detailed above) to migrate your TopLink Workbench project source.
  2. Open the TopLink Workbench project with EclipseLink Workbench.
  3. EclipseLink Workbench detects the project and displays the following message:
    Tlw elb project dialog.png
  4. Click Save Now and select a new directory location in which to save the EclipseLink project.