| Oracle® TopLink Getting Started Guide 10g (10.1.3.1.0) Part Number B28217-02 |
|
|
View PDF |
| Oracle® TopLink Getting Started Guide 10g (10.1.3.1.0) Part Number B28217-02 |
|
|
View PDF |
This chapter describes how to migrate existing Oracle TopLink projects to TopLink 10g (10.1.3.1.0).
This chapter includes the following sections:
Refer to "Integrating TopLink With an Application Server" in 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, see "Configuring Project Classpath" in the Oracle TopLink Developer's Guide.
Also check your project classes for any references to legacy TopLink classes.
In 10.1.3.0, TopLink provides a JPA preview based on a subset of the functionality specified in the EJB 3.0 public review draft.
In 10.1.3.1, TopLink provides full JPA support (through TopLink Essentials) as per the final EJB 3.0 specification.
See "EJB 3.0 JPA Persistence JAR Files" in the Oracle Containers for J2EE Enterprise JavaBeans Developer's Guide for information on specifying which JPA persistence implementation to use.
You must make code changes to your JPA preview-based application before using it with TopLink 10.1.3.1. This section describes the important differences between the TopLink JPA preview and full TopLink JPA to help you identify where changes must be made, including:
Table 3-1 lists the additions, deletions, and changes made to the javax.persistence package between 10.1.3.0 and 10.1.3.1. If your application uses any of these classes, consult the latest EBJ 3.0 specification and JPA Javadoc for details.
Table 3-1 Changes to javax.persistence
| 10.1.3.0 | 10.1.3.1 | Description |
|---|---|---|
|
|
deleted |
In 10.1.3.1, EJB 3.0 entities do not require local or remote interfaces. Because all entity access is by way of an |
|
|
deleted |
In 10.1.3.1, the EJB 3.0 persistence specification requires the use of a single access type in an entity hierarchy. The placement of the mapping annotations determines the access type in effect. |
|
not applicable |
|
Added in 10.1.3.1 as part of the changes made to annotations for inheritance. For more information, see |
|
not applicable |
|
Added in 10.1.3.1 as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1, attribute For more information, see |
|
not applicable |
|
Added in 10.1.3.1 as part of the changes made to annotations for inheritance. For more information, see |
|
|
deleted |
Added in 10.1.3.1 as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1, attribute |
|
not applicable |
|
Added in 10.1.3.1. |
|
|
deleted |
In 10.1.3.1, use For more information, see |
|
not applicable |
|
Added in 10.1.3.1. For more information, see |
|
|
|
In 10.1.3.1, New methods added in 10.1.3.1 include:
In 10.1.3.1, methods of this class throw additional exceptions such as |
|
|
|
In 10.1.3.1, this exception extends |
|
|
|
New methods added in 10.1.3.1, include:
|
|
|
deleted |
In 10.1.3.1, the EJB 3.0 specification removes the concept of BMP. To develop and deploy a Java EE 5 BMP application, you must use the EJB 2.1 API. |
|
not applicable |
|
Added in 10.1.3.1 to support direct mappings of enumerated types. For more information, see |
|
not applicable |
|
Added in 10.1.3.1 to support direct mappings of enumerated types. For more information, see |
|
not applicable |
|
Added in 10.1.3.1 to support managing lifecycle callback default listeners. For more information, see |
|
not applicable |
|
Added in 10.1.3.1 to support managing lifecycle callback superclass listeners. For more information, see |
|
|
deleted |
In 10.1.3.1, to set the flush mode, use the |
|
not applicable |
|
Added in 10.1.3.1 to support automatic primary key (identity) generation. For more information, see |
|
not applicable |
|
Added in 10.1.3.1 to support automatic primary key (identity) generation. For more information, see |
|
|
deleted |
In 10.1.3.1, use |
|
|
|
In 10.1.3.1, the following attributes are omitted:
For more information, see |
|
|
|
In 10.1.3.1, attribute For more information, see |
|
|
|
In 10.1.3.1, attribute The following attributes are added:
For more information, see |
|
|
deleted |
In 10.1.3.1, use direct mapping annotation Lob to specify a Lob type. A Lob may be either a binary or character type. The persistence provider infers the Lob type from the type of the persistent field or property. For more information, see |
|
not applicable |
|
|
|
not applicable |
|
Added in 10.1.3.1 as part of the changes made to annotations for inheritance. For more information, see |
|
|
|
In 10.1.3.1, attribute For more information, see |
|
|
|
In 10.1.3.1, attribute For more information, see |
|
|
|
In 10.1.3.1, this exception extends |
|
not applicable |
|
|
|
|
|
In 10.1.3.1, attribute For more information, see |
|
not applicable |
|
For more information, see |
|
not applicable |
|
For more information, see |
|
not applicable |
|
|
|
|
|
In 10.1.3.1, attribute For more information, see |
|
|
|
In 10.1.3.1, the default for attribute For more information, see |
|
not applicable |
|
For more information, see |
|
|
|
In 10.1.3.1, attribute For more information, see |
|
|
|
in 10.1.3.1, the following attributes were added:
For more information, see |
|
not applicable |
|
For more information, see |
|
|
|
In 10.1.3.1, enum value For more information, see |
|
|
|
In 10.1.3.1, this exception extends |
In 10.1.3.1, the following new classes were added:
DerbyPlatform
JavaDBPlatform
PostgreSQLPlatform
In 10.1.3.0, you use the java.persistence.setup.config property to identify a class with the list of entities that an entity manager manages.
In 10.1.3.1, this property is obsolete. Instead, you must define managed entity classes in a persistence unit as per the EJB 3.0 specification. For more information, see:
In 10.1.3.0, the persistence-preview.jar provides the TopLink JPA preview implementation.
In 10.1.3.1, the toplink-essentials.jar and toplink-essentials-agent.jar provides the full TopLink JPA implementation.
In your IDE, ensure that any library definitions you may have associated with your projects include only the 10.1.3.1 TopLink JPA libraries and exclude the old 10.1.3.0 libraries.
For more information about TopLink JAR files, see "TopLink JAR Files".
Use Table 3-2 to upgrade both your TopLink Workbench project ( .mwp) and, if necessary, your project.xml file from a previous version of TopLink.
Table 3-2 Upgrading TopLink Workbench Projects
| To Upgrade From... | Use This Procedure... |
|---|---|
|
Release 3 (10.1.3) and Release 2 (10.1.2) |
|
|
Release 2 (9.0.4) |
|
|
Release 1 (9.0.3) |
|
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 (10.1.3.1.0).
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).
Use this procedure to upgrade your existing pre-Release 1 (9.0.3) application source code and TopLink Workbench projects to version 10g (10.1.3.1.0).
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 (10.1.3.1.0) project
the name of a log file. If no file is specified, the logging messages will print to standard output.
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.
Repeat this procedure for your:
Source code
Configuration files
TopLink Workbench project files (*.mwp, *.xml)
TopLink Workbench 10g (10.1.3.1.0) automatically updates your sessions.xml file, as needed. Simply open the file in 10g (10.1.3.1.0), update your data source information (if needed), and save the file.
In 10g (10.1.3.1.0), 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 (10.1.3.1.0) sessions.xml (XSD) with the <login> element. You should include all login information in the sessions.xml.
Use the 10g (10.1.3.1.0) 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 "TopLink Sessions" in the Oracle TopLink Developer's Guide for complete details.
For 10g (10.1.3.1.0), 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
