This chapter describes how to migrate applications using "native" TopLink object-relational mapping (ORM) APIs to the current EclipseLink APIs.
The EclipseLink libraries have been the core libraries in Oracle TopLink staring with TopLink 11g, Release 1 (11.1.1).
This chapter includes the following sections:
A developer wants to upgrade an application that uses the older TopLink native ORM to use a current EclipseLink ORM implementation.
Follow the instructions in this chapter to upgrade the application.
TopLink 12c (12.1.2.0.0) or later.
Note:
TopLink's core functionality is provided by EclipseLink, the open source persistence framework from the Eclipse Foundation. EclipseLink implements Java Persistence API (JPA), Java Architecture for XML Binding (JAXB), and other standards-based persistence technologies, plus extensions to those standards. TopLink includes all of EclipseLink, plus additional functionality from Oracle.
(Optional) EclipseLink Workbench.
"Native" TopLink ORM refers to the API, configuration files, and tools for object-relational mapping that evolved in TopLink before the Java Persistence API (JPA) standardized an object-relational mapping API. Full JPA support was introduced in Oracle TopLink 10g (10.1.3.1.0), via TopLink Essentials. However, native TopLink continued to be supported.
Prior to the TopLink 11g (11.1.1) release, Oracle contributed the TopLink source code--including TopLink JPA and native TopLink--to the Eclipse Foundation, where it was used to form the basis of the open-source EclipseLink persistence services project. Then, in TopLink 11g Release 1 (11.1.1), Oracle started to include EclipseLink in TopLink, providing TopLink's core functionality.
TopLink developers using TopLink versions 11.1.1.0.0 though 11.1.1.6.0 have access to native TopLink ORM in either the proprietary Oracle toplink.jar or in the EclipseLink eclipselink.jar. In toplink.jar, the classes are in packages whose names start with oracle.toplink.*. In eclipselink.jar, those package names begin instead with org.eclipselink.persistence..
Note:
The toplink.jar file was deprecated in TopLink 11g and is no long shipped with TopLink 12c. It is recommended that you migrate off oracle.toplink.* in TopLink 11g.
You can migrate applications that use oracle.toplink.* packages from toplink.jar to use org.eclipselink.persistence. packages from eclipselink.jar. The application functionality remains the same, but migrating to eclipselink.jar provides the most up-to-date code base. After migrating, you will have access to other TopLink features and will be better prepared to convert your application to use JPA or one of the other persistence services included in current versions of TopLink.
This chapter explains how to use the renaming tool that is packaged with stand-alone TopLink to easily change the package names in your application and how to perform other actions necessary to migrate to the current code base.
Note:
Following the instructions in this chapter will update your application to use the current EclipseLink code base. Doing so retains the design and functionality of your application as originally implemented. However, these instructions do not describe how to convert a native TopLink-based application to use JPA or any of the other persistence services in current versions of TopLink. See the other TopLink documentation sources for that information.
This section contains the following tasks:
Section 7.2.2, "Task 2: Replace Deprecated and Removed Native APIs"
Section 7.2.5, "Task 5: Convert Oracle TopLink Workbench Projects (Optional)"
TopLink 12c (12.1.2.0.0) or later.
All TopLink downloads starting with 11g include the renaming tool discussed in this chapter.
Note:
The renaming tool is not included with embedded versions of TopLink, for example in Oracle WebLogic Server or Oracle Glassfish. You must download the standalone TopLink installer.
Download TopLink from http://www.oracle.com/technetwork/middleware/toplink/downloads/index.html. For installation instructions, see Chapter 2, "Installing Oracle TopLink.".
(Optional) EclipseLink Workbench. The EclipseLink Workbench is available in EclipseLink downloads. See the EclipseLink download page at http://www.eclipse.org/eclipselink/downloads/.
APIs that were deprecated in releases before TopLink 11g Release 1 (11.1.1) were removed in EclipseLink and therefore are not included in current versions of TopLink. If your application uses any of those deprecated APIs or any APIs that were already replaced or removed from TopLink, you must update the application to use current APIs.
The following sections lists the replaced and removed APIs, with suggested substitutions:
Note:
When suggested replacements are in oracle.toplink.* packages, you must also change the package names, as described in Section 7.2.3, "Task 3: Rename Packages."
The following tables list the APIs removed as of TopLink 11g Release 1 (11.1.1.1.). Use the replacement API listed in the tables.
Table 7-1 changetracking (oracle.toplink.descriptors.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
|
|
|
|
|
|
Table 7-2 databaseaccess (oracle.toplink.internal*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
|
Table 7-4 mappings (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
Table 7-5 objectrelational (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
|
Table 7-6 oraclespecific (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
.oraclespecific.TopLinkXMLType Foot 2 |
Whole class |
None |
Footnote 1 oracle.toplink.oraclespecific.Oracle9Specific was moved to an internal package and renamed to oracle.toplink.internal.platform.database.oracle.Oracle9Specific. The replacement public API for oracle.toplink.oraclespecific.Oracle9Specific is oracle.toplink.platform.database.oracle.Oracle9Specific.
Footnote 2 oracle.toplink.oraclespecific.TopLinkXMLType was a miscellaneous class, which does not have a replacement API.
Table 7-7 publicinterface (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
|
|
Whole class |
|
Footnote 1 oracle.toplink.publicinterface.DatabaseSession was moved to an internal package and renamed to oracle.toplink.internal.sessions.DatabaseSessionImpl. The replacement public API for oracle.toplink.publicinterface.DatabaseSession is oracle.toplink.sessions.DatabaseSession.
Footnote 2 oracle.toplink.publicinterface.Session was moved to an internal package and renamed to oracle.toplink.internal.sessions.AbstractSessionImpl. The replacement public API for oracle.toplink.publicinterface.Session is oracle.toplink.sessions.Session.
Footnote 3 oracle.toplink.publicinterface.UnitOfWork was moved to an internal package and renamed to oracle.toplink.internal.sessionl.UnitOfWorkImpl. The replacement public API for oracle.toplink.publicinterface.UnitOfWork is oracle.toplink.sessions.UnitOfWork.
Table 7-9 entitymanager (oracle.toplink.sessions.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
All classes |
All methods |
JPA: see Section 7.2.2.4.1, "JPA Persistence Provider Implementation," |
Table 7-10 sessionconfiguration (oracle.toplink.tools.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
All methods |
None |
Table 7-11 xml (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole package |
|
|
|
Whole package |
|
|
|
Whole package |
. |
|
|
Whole package |
|
|
|
Whole package |
|
Table 7-12 XMLCommandConverter (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole class |
None |
|
|
Whole class |
None |
|
|
Whole class |
None |
|
|
"error_loading_resources" |
None |
|
|
"error_parsing_resources" |
None |
|
|
"unexpect_argument" |
None |
Table 7-13 Remote Protocols (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
Whole package |
None |
|
|
Whole package |
None |
|
|
Whole package |
None |
|
|
References for any of |
None |
|
|
References for any of |
None |
|
|
Whole class |
None |
|
|
Whole class |
None |
|
|
Whole class |
None |
|
|
References for any of |
None |
The following tables list the APIs deprecated in the releases prior to TopLink 11g Release 1 (11.1.1) and therefore removed in that release, due to the substitution of EclipseLink libraries. Use the replacement API indicated.
Note:
Because deprecated classes and moved classes have the same name, you may get compile errors if you use import * to import classes from both the old package and the new package. To avoid these errors, use import with a fully qualified package name.
Table 7-15 mappings (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
|
|
Table 7-16 descriptors (oracle.toplink.*)
| Class Name | Method Name | Replacement APIs |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The following classes were removed in the release prior to TopLink 11g Release 1 (11.1.1):
OTSTransactionController
OTSSynchronizationListener
OracleSequenceDefinition (use SequenceObjectDefinition instead)
TimeTenSequenceDefinition (use SequenceObjectDefinition instead)
Other API changes include the following:
Section 7.2.2.4.1, "JPA Persistence Provider Implementation."
Section 7.2.2.4.2, "Session Finalizers Disabled by Default."
Section 7.2.2.4.3, "Vector and Hashtable Return Types Changed to List or Map."
The persistence provider implementation in all TopLink releases since 11g (11.1.1) is packaged in eclipselink.jar. It replaces all previous implementations, for example:
toplink.jar
toplink-essentials.jar
In TopLink 11g (11.1.1) Technology Preview 3, session finalizers were disabled by default to improve performance. To enable session finalizers, use Session method setIsFinalizersEnabled(true).
Any Session or ClassDescriptor method that returns Vector or Hashtable will eventually be changed to return List or Map, respectively. To prepare for this change, cast Vector and Hashtable return types to List or Map, respectively. For example, although the Javadoc for ClassDescriptor method getMappings is java.util.Vector, you should cast the returned value to List:
List mappings = (List) descriptor.getMappings();
Other changes that now return Map include the following:
ClassDescriptor.getQueryKeys()
ClassDescriptor.getProperties()
DescriptorQueryManager.getQueries()
EISInteraction.getProperties()
Session.getProperties()
Session.getQueries()
getAttributesToAlwaysInclude()
getSpecialOperations()
getValuesToExclude()s
Starting with TopLink 11g, Release 1 (11.1.1), all EclipseLink libraries are included in TopLink. EclipseLink provides the core TopLink functionality, which now includes support for JPA 2.x, JAXB, and other standards-based persistence services, as well as extensions to those standards. In addition, TopLink continues to support native TopLink APIs; however, all oracle.toplink.* packages are now renamed to org.eclipse.persistence.*.
To migrate your application to use the new code base, you must rename the packages in your code. To facilitate this, a package renamer tool is included with the TopLink installation. Use this tool on all of the following:
project source code
project.xml file
persistence.xml file
sessions.xml file
The package renamer is located in the toplink_install_directory\toplink\utils\rename directory. Windows and UNIX/LINUX scripts are included.
To run the package renamer using the scripts, do the following:
Find the packageRename.cmd (Windows) and packageRename.sh (UNIX/LINUX) scripts in toplink_install_directory\toplink\utils\rename directory.
Run either packageRename.cmd or packageRename.sh with the following arguments:
sourceLocation - The directory containing the files to rename.
targetLocation - The destination directory for the renamed files. The package renamer removes any existing Java and XML files, so it is advisable 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 target location
The package renamer can rename TopLink XML configuration files, but depending on the type of file, you may need to make additional changes.
You can continue to use sessions.xml files as is. For a more forward-compatible solution, run the renamer on your sessions.xml files.
Deployment XML files from TopLink 10.1.3 and above can be read by TopLink 11.1.1 and later. 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"
To use TopLink as a persistence provider, you must run the renamer on your persistence.xml files. The renamer updates the persistence provider to be EclipseLink and also update any native TopLink specific properties to the EclipseLink equivalent.
In releases prior to TopLink 11g Release 1 (11.1.1), a graphical editing tool called Oracle TopLink Workbench was available for configuring descriptors and mapping your project. That tool is no longer available from Oracle, but a comparable tool, the EclipseLink Workbench is available from the Eclipse Foundation. You can convert old TopLink Workbench projects into EclipseLink Workbench projects and then use the output in current Oracle TopLink applications. You can also import Workbench projects into Oracle JDeveloper.
Note:
EclipseLink Workbench is open-source software and is therefore not supported by Oracle.
To convert Oracle TopLink Workbench (.mwp) project to an EclipseLink Workbench project:
Use the package renamer (as described above) to migrate your Oracle TopLink Workbench project source.
Open the Oracle TopLink Workbench project with EclipseLink Workbench.
EclipseLink Workbench detects the project and displays a message asking if you want to save in the current version of the Workbench.
Click Save Now and select a new directory location in which to save the project.
See the following resources for more information about the technologies and tools used to implement the solutions in this chapter: