Fusion Middleware Documentation
Advanced Search


Solutions Guide for Oracle TopLink
Close Window

Table of Contents

Show All | Collapse

7 Migrating from Native TopLink

This chapter tells 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 contains the following sections:

Use Case

A developer wants to upgrade an application that uses the older TopLink native ORM to use a current EclipseLink ORM implementation.

Solution

Follow the instructions in this chapter to upgrade the application.

Components

  • TopLink 12c Release 1 (12.1.2) 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.

7.1 Introduction to the Solution

"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.

7.2 Implementing the Solution

This section contains the following tasks:

7.2.1 Task 1: Prerequisites

7.2.2 Task 2: Replace Deprecated and Removed Native APIs

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."

7.2.2.1 APIs Replaced

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

ChangeTracker

getTopLinkPropertyChangeListener

._persistence_getPropertyChangeListener

ChangeTracker

setTopLinkPropertyChangeListener(PropertyChangeListener)

_persistence_setPropertyChangeListener(PropertyChangeListener)


Table 7-2 databaseaccess (oracle.toplink.internal*)

Class Name Method Name Replacement APIs

.*Platform

Whole class

oracle.toplink.platform.database.*Platform


Table 7-3 jdo (oracle.toplink.*)

Class Name Method Name Replacement APIs

.jdo

Whole package

None


Table 7-4 mappings (oracle.toplink.*)

Class Name Method Name Replacement APIs

TypeConversionMapping

Whole class

.mappings.converters.TypeConversionConverter

ObjectTypeMapping

Whole class

.mappings.converters.ObjectTypeConverter

SerializedObjectMapping

Whole class

.mappings.converters.SerializedObjectConverter


Table 7-5 objectrelational (oracle.toplink.*)

Class Name Method Name Replacement APIs

Oracle8Platform

Whole class

oracle.toplink.platform.database.oracle.Oracle8Platform


Table 7-6 oraclespecific (oracle.toplink.*)

Class Name Method Name Replacement APIs

.oraclespecific.NCharacter

Whole class

.platform.database.oracle.NCharacter

.oraclespecific.NClob

Whole class

.platform.database.oracle.NClob

.oraclespecific.NClob

Whole class

.platform.database.oracle.NClob

.oraclespecific.Oracle8Platform

Whole class

.platform.database.oracle.Oracle8Platform

.oraclespecific.Oracle9Specific Foot 1 

Whole class

.platform.database.oracle.Oracle9Specific

.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

DatabaseRow

Whole class

.sessions.DatabaseRecord

DatabaseSession Foot 1 

Whole class

.sessions.DatabaseSession

Descriptor

Whole class

.descriptors - ClassDescriptor, RelationalDescriptor

DescriptorEvent

Whole class

.descriptors.DescriptorEvent

DescriptorEventListener

Whole class

.descriptors - new interface will not extend old interface

DescriptorEventManager

Whole class

.descriptors

DescriptorQueryManager

Whole class

.descriptors

InheritancePolicy

Whole class

.descriptors

SessionFoot 2 

Whole class

.sessions.Session

UnitOfWorkFoot 3 

Whole class

.sessions.UnitOfWork


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-8 sdk (oracle.toplink.*)

Class Name Method Name Replacement APIs

.sdk

Whole package

.eis


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

WASXMLLoader

All methods

None


Table 7-11 xml (oracle.toplink.*)

Class Name Method Name Replacement APIs

.xml

Whole package

.ox

.xmlstream

Whole package

.ox

.xml.tools

Whole package

.ox

.xml.xerces

Whole package

.ox

.xml.zip

Whole package

.ox


Table 7-12 XMLCommandConverter (oracle.toplink.*)

Class Name Method Name Replacement APIs

.remotecommand.XMLCommandConverter

Whole class

None

.transform.xml.XMLSource

Whole class

None

.transform.xml.XMLResult

Whole class

None

.internal.localization.i18n.ExceptionLocalizationResource

"error_loading_resources"

None

.internal.localization.i18n.ExceptionLocalizationResource

"error_parsing_resources"

None

.internal.localization.i18n.ExceptionLocalizationResource

"unexpect_argument"

None


Table 7-13 Remote Protocols (oracle.toplink.*)

Class Name Method Name Replacement APIs

.remote.corba.orbix

Whole package

None

.remote.corba.visibroker

Whole package

None

.remote.ejb

Whole package

None

.tools.sessionconfiguration.TopLinkSessionsFactory

References for any of JNDIClusteringService in orbix, visibroker and ejb packages.

None

.tools.sessionconfiguration.DTD2SessionConfigLoader

References for any of JNDIClusteringService in orbix, visibroker and ejb packages.

None

.tools.sessionconfiguration.model.clustering.VisibrokerCORBAJNDIClusteringConfig

Whole class

None

.tools.sessionconfiguration.model.clustering.OrbixCORBAJNDIClusteringConfig

Whole class

None

.tools.sessionconfiguration.model.clustering.EJBJNDIClusteringConfig

Whole class

None

.tools.sessionconfiguration.XMLSessionConfigProject

References for any of JNDIClusteringService in orbix, visibroker and ejb packages.

None


Table 7-14 EJB Mapping for BEA WebLogic 6.1

Class Name Method Name Replacement APIs

toplink-cmp-bean_name.xml

None

A warning will be added at the beginning of: internal.ejb.cmp.wls11.CMPDeployer.readTypeSpecificData()


7.2.2.2 Deprecated APIs

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

OneToOneMapping

useJoining

ForeignReferenceMapping.setJoinFetch(int)


Table 7-16 descriptors (oracle.toplink.*)

Class Name Method Name Replacement APIs

ClassDescriptor

addMultipleTableForeignKeyField

addForeignKeyFieldForMultipleTable

ClassDescriptor

addMultipleTablePrimaryKeyField

addForeignKeyFieldForMultipleTable

ClassDescriptor

addMultipleTablePrimaryKeyFieldName

addForeignKeyFieldNameForMultipleTable

ClassDescriptor

addMultipleTableForeignKeyFieldName

addForeignKeyFieldNameForMultipleTable


7.2.2.3 Removed API

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)

7.2.2.4 Miscellaneous API Changes

Other API changes include the following:

7.2.2.4.1 JPA Persistence Provider Implementation

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

7.2.2.4.2 Session Finalizers Disabled by Default

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).

7.2.2.4.3 Vector and Hashtable Return Types Changed to List or Map

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

7.2.3 Task 3: Rename Packages

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:

  1. Find the packageRename.cmd (Windows) and packageRename.sh (UNIX/LINUX) scripts in toplink_install_directory\toplink\utils\rename directory.

  2. 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

7.2.4 Task 4: Convert XML Configuration Files

The package renamer can rename TopLink XML configuration files, but depending on the type of file, you may need to make additional changes.

7.2.4.1 Sessions XML

You can continue to use sessions.xml files as is. For a more forward-compatible solution, run the renamer on your sessions.xml files.

7.2.4.2 Deployment XML

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"

7.2.4.3 Persistence XML

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.

7.2.4.4 ORM XML

The Object-Relational (ORM) XML configuration file (orm.xml) is not TopLink-dependant and does not need to be updated.

7.2.5 Task 5: Convert Oracle TopLink Workbench Projects (Optional)

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:

  1. Use the package renamer (as described above) to migrate your Oracle TopLink Workbench project source.

  2. Open the Oracle TopLink Workbench project with EclipseLink Workbench.

  3. EclipseLink Workbench detects the project and displays a message asking if you want to save in the current version of the Workbench.

  4. Click Save Now and select a new directory location in which to save the project.

7.3 Additional Resources

See the following resources for more information about the technologies and tools used to implement the solutions in this chapter: