EclipseLink Solutions Guide for EclipseLink
Release 2.4
  Go To Table Of Contents
 Search
 PDF
Previous Next  

Implementing the Solution

This section contains the following tasks:

Task 1: Prerequisites

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


NoteNote:

When suggested replacements are in oracle.toplink.* packages, you must also change the package names, as described in Task 3: Rename Packages.

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

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.


NoteNote:

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

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)

Miscellaneous API Changes

Other API changes include the following:

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

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

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

Task 3: Rename Packages

EclipseLink 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 EclipseLink 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

Task 4: Convert XML Configuration Files

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

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.

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"

Persistence XML

To use EclipseLink 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.

ORM XML

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

  Previous Next
EclipseLink
Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
  Go To Table Of Contents
 Search
 PDF