3 Migrating to 10g Release 3 (10.1.3)

This chapter describes how to migrate existing Oracle TopLink projects to TopLink 10g Release 3 (10.1.3).

This chapter includes the following sections:

• Upgrading TopLink Workbench Projects

• Package Rename

• Updating Sessions XML Files

• Using Hosted XSD

Refer to the Oracle TopLink Developer's Guide for information on migrating existing OC4J or WebLogic persistence to TopLink.

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

Upgrading TopLink Workbench Projects

Use Table 3-1 to upgrade both your TopLink Workbench project ( .mwp) and, if necessary, your project.xml file from a previous version of TopLink.

Table 3-1 Upgrading TopLink Workbench Projects

To Upgrade From...	Use This Procedure...
Release 2 (9.0.4)	Open the existing project with the 10g Release 3 (10.1.3) TopLink Workbench. Save the new TopLink Workbench project to a new location.
Release 1 (9.0.3)	Open the existing project with the 10g Release 3 (10.1.3) TopLink Workbench. Delete the passwords from all configured logins. Re-enter the passwords as plain (not encrypted) text for all configured logins. Export the project.xml. When you export the project.xml, the TopLink Workbench writes the login passwords using Java Cryptograph Extension (JCE) encryption (when using JDK 1.4 or higher). Use this new project.xml file at runtime. Save the new TopLink Workbench project to a new location.

Package Rename

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

You cannot use the TopLink Workbench's Rename Package function when migrating projects from earlier versions – you must use the Package Rename tool.

Note: If you are upgrading from a version prior to Release 1 (9.0.3), you must convert the package names before you open your TopLink project(s) in 10g Release 3 (10.1.3).

Use the Package Rename tool on your:

• Source code

• Configuration files

• TopLink Workbench project files ( .mwp) that contain references to pre-Release 1 (9.0.3) API packages

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

Running the Package Rename Tool

Use this procedure to upgrade your existing pre-Release 1 (9.0.3) application source code and TopLink Workbench projects to version 10g Release 3 (10.1.3).

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 Release 3 (10.1.3) 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

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

Updating Sessions XML Files

TopLink Workbench 10g Release 3 (10.1.3) can automatically update your sessions.xml file, as needed. Simply open the file in 10g Release 3 (10.1.3), update your data source information (if needed), and save the file.

In 10g Release 3 (10.1.3), the sessions.xml file includes a <login> element that will override any login information included in your project.xml. Use one of the following approaches to correctly configure the session login:

• Use the 10g Release 3 (10.1.3) sessions.xml (XSD) with the <login> element. You should include all login information in the sessions.xml.

• Use the 10g Release 3 (10.1.3) seesions.xml (XSD) without the <login> element. Include all login information in the project.xml (or project class).

• Use the project.xml (or project class) without sessions.xml. Include all login information in the project.xml (or project class).

• Use the 9.0.4 sessions.xml file (DTD). The login information included in the sessions.xml will override any login information in the project.xml (or project class).

See the Oracle TopLink Developer's Guide for complete details.

Using Hosted XSD

For 10g Release 3 (10.1.3), the XSD files for use with Oracle TopLink are included with the standard TopLink installation or available on OTN at:

http://www.oracle.com/technology/oracleas/schema/

Specifically, you can use the following XSD files:

• http://www.oracle.com/technology/oracleas/schema/object-persistence_1_0.xsd

• http://www.oracle.com/technology/oracleas/schema/sessions_10_1_3.xsd

• http://www.oracle.com/technology/oracleas/schema/toplink-object-persistence_10_1_3.xsd

• http://www.oracle.com/technology/oracleas/schema/toplink-was-ejb-jar_10_1_3.xsd