3
Migrating to 10g (9.0.4)

For users that have not previously migrated to Release 2 (9.0.3), this chapter describes how to migrate existing 2.x, 3.x and 4.x projects to Oracle Application Server TopLink 10g (9.0.4). This chapter includes the following sections:

• Upgrading OracleAS TopLink Mapping Workbench Projects

• Package Rename

• Name Changes

• Updating Sessions XML Files

Upgrading OracleAS TopLink Mapping Workbench Projects

Use the following procedures to upgrade your project from a previous version of the OracleAS TopLink Mapping Workbench.

From Release 2 (9.0.3)

Open and save the project with 10g (9.0.4).

Note: In 10g (9.0.4), enhancements to the OracleAS TopLink Mapping Workbench include a significant reduction of XML files. If you are using the OracleAS TopLink Mapping Workbench with a source control management (SCM) system in Release 2 (9.0.3) projects, many files in the SCM will no longer be valid in 10g (9.0.4).

From 4.x

Use the "Package Rename" procedures and open the project with 10g (9.0.4).

From 3.6

Use the "Package Rename" procedures and open the project with 10g (9.0.4).

From 2.x, 3.0 or 3.5

If you are migrating an OracleAS TopLink Mapping Workbench project from a version prior to version 3.6, contact Oracle Support Services support for assistance at OracleMetaLink.

http://metalink.oracle.com

Note: The Default Null value for object type mappings was expanded (starting with version 4.6) to differentiate between default and null values. If your 3.6 project contains object type mappings ensure that the default and null values are set properly on the mapping's General tab. For more information, see the Oracle Application Server TopLink Mapping Workbench User's Guide.

Note: If you receive ClassNotFound exceptions after you migrate a project, ensure  JDBC_CLASSPATH variable does not include any Java classes for your persistent business objects. Paths for persistent business objects are set within an OracleAS TopLink Mapping Workbench project. For more information on how to set up a path for a project, see the Oracle Application Server TopLink Mapping Workbench User's Guide. Also check your project classes for any references to legacy OracleAS TopLink classes.

Package Rename

Beginning with Release 2 (9.0.3), the base package for the entire structure became oracle.toplink. To upgrade existing application source code which refers to OracleAS TopLink API packages and existing OracleAS TopLink Mapping Workbench projects previous to Release 2 (9.0.3), you must use the Package Rename tool.

Note: If you are upgrading from a version previous to Release 2 (9.0.3), you must convert the package names before you open your OracleAS TopLink project(s) in 10g (9.0.4).

Use the Package Rename tool on your:

• Source code

• Configuration files

• OracleAS TopLink Mapping Workbench project files that contain references to pre-Release 2 (9.0.3) API packages

The Package Rename tool works on plain text files and should not be used with binary files (such as .jar).

Running the Package Rename Tool

Use this procedure to upgrade your existing pre-Release 2 (9.0.3) application source code and OracleAS TopLink Mapping Workbench projects to version 10g (9.0.4).

1. At the command prompt, execute the packageRename.cmd/sh program located in the <ORACLE_HOME>/toplink/bin directory. You need to specify three parameters on the command line:
   • the complete directory path that contains the Java source code of your existing project

   • the complete directory path that will contain the upgraded 10g (9.0.4) project

   • the name of a log file. If no file is specified, the logging messages will print to standard output.

2. Press Enter and the Package Rename tool will upgrade your project. The Package Rename tool requires approximately 15 minutes for a 1MB file. Larger files may require additional time.

3. Repeat this procedure for your:
   • Source code

   • Configuration files

   • OracleAS TopLink Mapping Workbench project files (*.mwp, *.xml)

Name Changes

Table 3-1, Table 3-2, Table 3-3 and Table 3-4 identify the name changes between version 3.x and 10g (9.0.4).

Table 3-1 New Package Names

Version 3.x	Version 4.x	Release 2 (9.0.3)	10g (9.0.4)
TOPLink.Public TOPLink.Private	com.webgain.integrator	oracle.toplink	oracle.toplink
not applicable	com.webgain.workbench	oracle.toplink. workbench	oracle.toplink. workbench
not applicable	com.webgain.openapi. foundation	oracle.toplink. uitools	oracle.toplink. uitools

Table 3-2 New Class Names

Version 3.x	Version 4.x	Release 2 (9.0.3)	10g (9.0.4)
TOPLinkException. java	WDIException.java	TopLinkException. java	TopLinkException. java

Table 3-3 New JAR/WAR Names

Version 3.x	Version 4.x	Release 2 (9.0.3)	10g (9.0.4)
toplinkall.jar (starting in 3.5)	wdiall.jar	toplink.jar	toplink.jar
toplink.jar	wdi.jar	tl_core.jar	not applicable
toplinksdk.jar	wdisdk.jar	tl_sdk.jar	not applicable
toplinksdkxerces. jar	wdisdkxerces.jar	tl_sdkx.jar	not applicable
tools.jar	wditools.jar	tl_tools.jar	not applicable
toplinkx.jar	wdix.jar	tl_x.jar	not applicable
toplinkwsx.jar	wdiwasx.jar	tl_wasx.jar	not applicable
toplinkwlx.jar	wdiwlsx.jar	tl_wlsx.jar	not applicable
workbench.jar	workbench.jar	workbench.jar	toplinkmw.jar
not applicable	TopLinkWebClient.war	tl_webclient.war	toplinkwc.war
not applicable	wdidemo.jar	tl_demo.jar	not applicable
not applicable	wdidemoui.jar	tl_tour.jar	not applicable

Table 3-4 New XML/DTD Files

Version 3.x	Version 4.x	Release 2 (9.0.3)	10g (9.0.4)
not applicable	wdi-ejb-jar.xml	toplink-ejb-jar. xml	toplink-ejb-jar. xml
not applicable	wdi-was-ejb-jar_45.dtd	toplink-was-ejb- jar_903.dtd	toplink-was-ejb- jar_904.dtd
not applicable	wdi-wls-ejb-jar_40.dtd	toplink-wls-ejb- jar_903.dtd	toplink-wls-ejb- jar_904.dtd

Updating Sessions XML Files

OracleAS TopLink 10g (9.0.4) is backward compatible with previous releases however, you must update the DOCTYPE headers for the Sessions XML files to read as follows:

Table 3-5 Sessions.xml

DocType	DTD Used From the Class Path
"-//Oracle Corp.//DTD TopLink for JAVA 4.0//EN"	sessions_4_0.dtd
"-//Oracle Corp.//DTD TopLink for JAVA 4.5//EN"	sessions_4_5.dtd
"-//Oracle Corp.//DTD TopLink Sessions 9.0.4//EN"	sessions_9_0_4.dtd

Table 3-6 WAS toplink-ejb-jar.xml

DocType	DTD Used From the Class Path
"-//Oracle Corp.//DTD TopLink 4.5 CMP for WebSphere//EN"	toplink-was-ejb-jar_903.dtd
"-//Oracle Corp.//DTD TopLink CMP WebSphere 9.0.4//EN"	toplink-was-ejb-jar_904.dtd

Table 3-7 WLS toplink-ejb-jar.xml

DocType	DTD Used From the Class Path
"-//Oracle Corp.//DTD TopLink 4.0 CMP for WebLogic//EN"	toplink-wls-ejb-jar_903.dtd
"-//Oracle Corp.//DTD TopLink CMP WebLogic 9.0.4//EN"	toplink-wls-ejb-jar_904.dtd