Oracle Fusion Middleware Online Documentation Library

Oracle Fusion Middleware
Developer’s Guide for Oracle TopLink
11g Release 1 (11.1.1)
B32441-03

May 2009

Oracle Fusion Middleware Developer's Guide for Oracle TopLink, 11g Release 1 (11.1.1)
B32441-03
Copyright © 1997, 2009, Oracle and/or its affiliates. All rights reserved.
Primary Author:

Liza Rekadze

Contributing Author:

Rick Sapir

This software and related documentation are provided under a license agreement containing restrictions on
use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your
license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,

transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is
prohibited.
The information contained herein is subject to change without notice and is not warranted to be error-free. If
you find any errors, please report them to us in writing.
If this software or related documentation is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, the following notice is applicable:
U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and
license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of
the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software
License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.
This software is developed for general use in a variety of information management applications. It is not
developed or intended for use in any inherently dangerous applications, including applications which may
create a risk of personal injury. If you use this software in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use
of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of
this software in dangerous applications.

Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks
of their respective owners.
This software and documentation may provide access to or information on content, products, and services
from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and
its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of
third-party content, products, or services.

Contents
Preface ................................................................................................................................................................ lix
Audience...................................................................................................................................................... lix
Documentation Accessibility .................................................................................................................... lix
Related Documentation .............................................................................................................................. lx
Conventions ................................................................................................................................................. lx

Part I

TopLink Application Development Overview

1 Introduction to TopLink

1.1
1.2
1.3
1.4

What Is TopLink?........................................................................................................................
What Is the Object-Persistence Impedance Mismatch...........................................................
TopLink Key Features ................................................................................................................
TopLink Application Architectures .........................................................................................

1-1
1-3
1-4
1-5

2 Introduction to TopLink Application Development
2.1
Introduction to TopLink Application Development .............................................................
2.1.1
Typical Development Stages..............................................................................................

2.1.2
Oracle Development Support ............................................................................................
2.2
Designing Your Application with TopLink ............................................................................
2.2.1
How to Use TopLink in Your Application Design .........................................................
2.2.1.1
Relational Database Usage ..........................................................................................
2.2.1.2
Object-Relational Data Type Database Usage ..........................................................
2.2.1.3
Oracle XML Database (XDB) Usage...........................................................................
2.2.1.4
Enterprise Information System (EIS) Usage .............................................................
2.2.1.5
XML Usage ....................................................................................................................
2.2.2
Target Platforms...................................................................................................................
2.3
Selecting an Architecture with TopLink..................................................................................

2.3.1
Tiers .......................................................................................................................................
2.3.1.1
Three Tier.......................................................................................................................
2.3.1.1.1
Java EE or Non-Java EE ........................................................................................
2.3.1.1.2
Client .......................................................................................................................
2.3.1.2
Two Tier .........................................................................................................................
2.3.2
Service Layer ........................................................................................................................
2.3.2.1
EJB Session Beans .........................................................................................................
2.3.2.1.1
Stateful ....................................................................................................................

2-1
2-2
2-3

2-3
2-4
2-4
2-4
2-4
2-4
2-4
2-5
2-5
2-5
2-6
2-6
2-6
2-6
2-7
2-7
2-7

v

2.3.2.1.2
Stateless................................................................................................................... 2-7
2.3.2.2
EJB Entity Beans............................................................................................................ 2-7
2.3.2.2.1
Container-Managed Persistence (CMP)............................................................. 2-8
2.3.2.2.2
Bean-Managed Persistence (BMP) ...................................................................... 2-8
2.3.2.3
JPA Entities .................................................................................................................... 2-8
2.3.2.4
Plain Old Java Objects (POJO) .................................................................................... 2-8
2.3.3
Data Access ........................................................................................................................... 2-8
2.3.3.1
Data Type....................................................................................................................... 2-9
2.3.3.2
Multiple Data Sources.................................................................................................. 2-9
2.3.3.3
Isolating Data Access ................................................................................................... 2-9

2.3.3.4
Historical Data Access ................................................................................................. 2-9
2.3.4
Caching.................................................................................................................................. 2-9
2.3.4.1
Cache Type ................................................................................................................. 2-10
2.3.4.2
Refreshing ................................................................................................................... 2-10
2.3.4.3
Cache Coordination................................................................................................... 2-10
2.3.4.3.1
Protocol ................................................................................................................ 2-10
2.3.4.3.2
Synchronization.................................................................................................. 2-10
2.3.5
Locking ............................................................................................................................... 2-11
2.3.5.1
Optimistic Locking .................................................................................................... 2-11
2.3.5.2
Pessimistic Locking ................................................................................................... 2-11

2.4
Building and Using the Persistence Layer ........................................................................... 2-11
2.4.1
Implementation Options.................................................................................................. 2-11
2.4.1.1
Using EclipseLink JPA Metatdata, Annotations, and XML ................................ 2-12
2.4.1.2
Using TopLink Metatdata XML .............................................................................. 2-12
2.4.1.3
Using TopLink Metadata Java API ......................................................................... 2-12
2.4.1.4
Using Method and Direct Field Access .................................................................. 2-12
2.4.1.5
Using Weaving........................................................................................................... 2-13
2.4.2
Persistent Class Requirements........................................................................................ 2-13
2.4.3
Persistence Layer Components....................................................................................... 2-14
2.4.3.1
Mapping Metadata .................................................................................................... 2-14

2.4.3.2
Session ......................................................................................................................... 2-14
2.4.3.3
Cache ........................................................................................................................... 2-15
2.4.3.4
Queries and Expressions .......................................................................................... 2-15
2.4.3.5
Transactions................................................................................................................ 2-15
2.4.4
How to Use the Persistence Layer.................................................................................. 2-16
2.5
Deploying the Application ..................................................................................................... 2-16
2.5.1
About Deployments ......................................................................................................... 2-17
2.5.2
How to Use TopLink in a Java EE Application ............................................................ 2-17
2.6
Optimizing and Customizing the Application.................................................................... 2-17
2.7
Troubleshooting the Application........................................................................................... 2-17

2.8
Persisting Objects ..................................................................................................................... 2-18
2.8.1
Application Object Model ............................................................................................... 2-18
2.8.2
Data Storage Schema ........................................................................................................ 2-18
2.8.3
Primary Keys and Object Identity .................................................................................. 2-19
2.8.4
Mappings ........................................................................................................................... 2-19
2.8.5
Foreign Keys and Object Relationships......................................................................... 2-19
2.8.6
Inheritance ......................................................................................................................... 2-19

vi

2.8.7
Concurrency ......................................................................................................................
2.8.8
Caching...............................................................................................................................
2.8.9
Nonintrusive Persistence.................................................................................................
2.8.10
Indirection..........................................................................................................................
2.8.11
Mutability...........................................................................................................................
2.9
Working with TopLink Metadata..........................................................................................
2.9.1
Advantages of the TopLink Metadata Architecture....................................................
2.9.2
Creating Project Metadata ...............................................................................................
2.9.2.1
Descriptors and Mappings .......................................................................................
2.9.2.1.1
Amending Descriptors ......................................................................................
2.9.2.2
Data Source Login Information ...............................................................................
2.9.3
Creating Session Metadata ..............................................................................................
2.9.4
Deploying Metadata.........................................................................................................
2.10
Using Weaving .........................................................................................................................
2.10.1
Configuring Dynamic Weaving Using EclipseLink Agent ........................................
2.10.1.1
To Configure Dynamic Weaving Using EclipseLink Agent ...............................
2.10.2
Configuring Static Weaving ............................................................................................
2.10.3
Disabling Weaving Using TopLink Persistence Unit Properties...............................
2.10.4
Packaging a POJO Application for Weaving................................................................
2.10.4.1
To Package a POJO Application for Weaving.......................................................
2.10.5
What You May Need to Know About Weaving and POJO Classes..........................
2.10.6
What You May Need to Know About Weaving and Java EE Application Servers
2.11
Considering Three-Tier Architecture....................................................................................
2.11.1
Example Implementations...............................................................................................
2.11.2
Advantages and Disadvantages .....................................................................................
2.11.3
Variation Using Remote Sessions...................................................................................
2.11.4
Technical Challenges........................................................................................................
2.12
Considering Two-Tier Architecture .....................................................................................
2.12.1
Example Implementations...............................................................................................
2.12.2
Advantages and Disadvantages .....................................................................................
2.12.3
Technical Challenges........................................................................................................
2.13
Considering EJB Session Bean Facade Architecture ...........................................................
2.13.1
Example Implementation ................................................................................................
2.13.2
Advantages and Disadvantages .....................................................................................
2.13.3
What Are Session Beans...................................................................................................
2.13.4
Technical Challenges........................................................................................................
2.13.5
What Is a Unit of Work Merge........................................................................................
2.14
Considering EJB Entity Beans with CMP Architecture......................................................
2.14.1
Example Implementation ................................................................................................
2.14.2
Advantages and Disadvantages .....................................................................................
2.14.3
Technical Challenges........................................................................................................
2.14.3.1
External JDBC Pools ..................................................................................................
2.14.3.2
JTA/JTS Integration ..................................................................................................
2.14.3.3
Cache Coordination...................................................................................................
2.14.3.4
Maintaining Bidirectional Relationships................................................................
2.14.3.5
Managing Dependent Objects .................................................................................
2.14.3.6
Managing Collections of EJBObject Objects ..........................................................

2-20
2-20
2-20
2-21
2-21
2-22
2-23
2-24
2-24
2-24
2-25
2-25
2-25
2-25
2-26
2-26
2-26
2-26
2-27
2-27
2-27
2-28
2-28
2-29
2-29
2-29
2-29
2-30
2-31
2-31
2-31
2-31
2-32
2-32
2-33
2-33
2-34
2-34
2-35
2-35
2-36
2-36
2-36
2-36
2-36
2-37
2-37

vii

2.15
Considering EJB Entity Beans with BMP Architecture ......................................................
2.15.1
Example Implementations...............................................................................................
2.15.2
Advantages and Disadvantages .....................................................................................
2.15.3
Technical Challenges........................................................................................................
2.15.3.1
External JDBC Pools ..................................................................................................
2.15.3.2
JTA/JTS Integration ..................................................................................................
2.15.3.3
Cache Coordination...................................................................................................
2.16
Considering JPA Entity Architecture....................................................................................
2.16.1
Example Implementations...............................................................................................
2.16.2
Advantages and Disadvantages .....................................................................................
2.17
Considering Web Services Architecture ...............................................................................
2.17.1
Example Implementations...............................................................................................
2.17.2
Advantages and Disadvantages .....................................................................................
2.17.3
Technical Challenges........................................................................................................
2.18
Considering EclipseLink Service Data Objects (SDO) Architecture.................................

Part II
3

TopLink Development Tools Overview

Introduction to TopLink Development Tools
3.1
3.2

4

2-38
2-39
2-39
2-40
2-40
2-40
2-40
2-40
2-42
2-42
2-42
2-43
2-43
2-43
2-43

Development Environment ....................................................................................................... 3-2
TopLink Run-Time Environment ............................................................................................. 3-3

Using Oracle JDeveloper TopLink Editor
4.1
4.2
4.3
4.3.1
4.3.2
4.3.3

Introduction to Oracle JDeveloper TopLink Editor ...............................................................
Configuring the Oracle JDeveloper TopLink Editor .............................................................
Using the Oracle JDeveloper TopLink Editor.........................................................................
TopLink Project Elements in the Application Navigator...............................................
TopLink Editor Tabs in the Editor Window ....................................................................
TopLink Project Elements in the Structure Window......................................................

4-1
4-1
4-1
4-2
4-2
4-3

5 Using TopLink Workbench
5.1
5.2
5.2.1
5.3
5.3.1
5.3.1.1
5.3.1.2
5.3.2
5.3.2.1
5.3.2.2
5.3.3
5.3.4
5.3.5
5.3.6
5.4

viii

Introduction to TopLink Workbench....................................................................................... 5-1
Configuring the TopLink Workbench Environment ............................................................. 5-2
How to Configure the Language Preference ................................................................... 5-3
Using TopLink Workbench ....................................................................................................... 5-3
How to Use Menus .............................................................................................................. 5-5
Using Menu Bar Menus ............................................................................................... 5-5
Using Context Menus .................................................................................................. 5-6
How to Use Toolbars........................................................................................................... 5-6
Using Standard Toolbar............................................................................................... 5-6
Using Context Toolbar................................................................................................. 5-7
How to Use the Navigator.................................................................................................. 5-9
How to Use the Editor...................................................................................................... 5-11
How to Use the Problems Window................................................................................ 5-11
How to Use the Online Help........................................................................................... 5-12
Using TopLink Workbench Preferences............................................................................... 5-12

5.4.1
How to Use General Preferences....................................................................................
5.4.2
How to Use Help Preferences .........................................................................................
5.4.3
How to Use Mappings Preferences................................................................................
5.4.4
How to Use Class Preferences ........................................................................................
5.4.5
How to Use EJB Preferences............................................................................................
5.4.6
How to Use Database Preferences..................................................................................
5.4.7
How to Use Sessions Configuration Preferences .........................................................
5.4.8
How to Use New Names Preferences............................................................................
5.4.9
How to Use Session Platform Preferences ....................................................................
5.4.10
How to Use Platforms Preferences.................................................................................
5.5
Using Databases ......................................................................................................................
5.5.1
How to Use Database Tables in the Navigator Window ............................................
5.5.1.1
Logging In and Out of a Database ..........................................................................
5.5.1.2
Creating New Tables.................................................................................................
5.5.1.3
Importing Tables from a Database..........................................................................
5.5.1.4
Removing Tables .......................................................................................................
5.5.1.5
Renaming Tables .......................................................................................................
5.5.1.6
Refreshing Tables from the Database .....................................................................
5.5.2
How to Use Database Tables in the Editor Window ...................................................
5.5.2.1
Working with Column Properties...........................................................................
5.5.2.2
Setting a Primary Key for Database Tables ...........................................................
5.5.2.3
Creating Table References ........................................................................................
5.5.2.4
Creating Field Associations .....................................................................................
5.5.3
How to Generate Data from Database Tables ..............................................................
5.5.3.1
Generating SQL Creation Scripts ............................................................................
5.5.3.2
Generating Classes and Descriptors from Database Tables................................
5.5.3.3
Generating EJB Entity Beans and Descriptors from Database Tables ...............
5.5.3.4
Generating Tables on the Database.........................................................................
5.6
Using XML Schemas................................................................................................................
5.6.1
How to Use XML Schemas in the Navigator................................................................
5.6.2
How to Use an XML Schema Structure .........................................................................
5.6.3
How to Import an XML Schema.....................................................................................
5.6.4
How to Configure an XML Schema Reference.............................................................
5.6.4.1
How to Configure an XML Schema Reference Using TopLink Workbench ....
5.6.4.2
How to Configure an XML Schema Reference Using Java .................................
5.6.5
How to Configure XML Schema Namespace...............................................................
5.6.5.1
How to Configure XML Schema Namespace Using TopLink Workbench ......
5.6.5.2
How to Configure XML Schema Namespace Using Java....................................
5.7
Using Classes ............................................................................................................................
5.7.1
How to Create Classes .....................................................................................................
5.7.1.1
How to Create Classes Using TopLink Workbench .............................................
5.7.2
How to Configure Classes ...............................................................................................
5.7.2.1
Configuring Class Information................................................................................
5.7.2.1.1
Using TopLink Workbench...............................................................................
5.7.2.2
Configuring Class Modifiers....................................................................................
5.7.2.2.1
Using TopLink Workbench...............................................................................
5.7.2.3
Configuring Class Interfaces....................................................................................

5-13
5-14
5-15
5-16
5-17
5-18
5-19
5-19
5-20
5-21
5-22
5-23
5-23
5-23
5-24
5-26
5-26
5-26
5-27
5-27
5-28
5-29
5-30
5-31
5-32
5-32
5-34
5-35
5-36
5-36
5-37
5-38
5-40
5-40
5-41
5-42
5-43
5-44
5-44
5-44
5-44
5-45
5-46
5-46
5-46
5-46
5-47

ix

5.7.2.3.1
Using TopLink Workbench...............................................................................
5.7.2.4
Adding Attributes .....................................................................................................
5.7.2.4.1
Using TopLink Workbench...............................................................................
5.7.2.5
Configuring Attribute Modifiers.............................................................................
5.7.2.5.1
Using TopLink Workbench...............................................................................
5.7.2.6
Configuring Attribute Type Declaration ...............................................................
5.7.2.6.1
Using TopLink Workbench...............................................................................
5.7.2.7
Configuring Attribute Accessing Methods............................................................
5.7.2.7.1
Using TopLink Workbench...............................................................................
5.7.2.8
Adding Methods........................................................................................................
5.7.2.8.1
Using TopLink Workbench...............................................................................
5.7.2.9
Configuring Method Modifiers ...............................................................................
5.7.2.9.1
Using TopLink Workbench...............................................................................
5.7.2.10
Configuring Method Return Type ..........................................................................
5.7.2.10.1
Using TopLink Workbench...............................................................................
5.7.2.11
Configuring Method Parameters ............................................................................
5.7.2.11.1
Using TopLink Workbench...............................................................................
5.7.3
How to Import and Update Classes...............................................................................
5.7.3.1
Importing and Updating Classes Using TopLink Workbench ...........................
5.7.4
How to Manage Nondescriptor Classes........................................................................
5.7.5
How to Rename Packages ...............................................................................................
5.7.5.1
Renaming Packages Using TopLink Workbench .................................................
5.8
Integrating TopLink Workbench with Apache Ant............................................................
5.8.1
How to Configure Ant to Use TopLink Workbench Tasks ........................................
5.8.1.1
Creating Library Dependencies...............................................................................
5.8.1.2
Declaring TopLink Workbench Tasks ....................................................................
5.8.2
What You May Need to Know About TopLink Workbench Ant Task API.............
5.8.3
How to Create TopLink Workbench Ant Tasks...........................................................
5.8.4
How to Create the mappings.validate Task .................................................................
5.8.4.1
Using Parameters.......................................................................................................
5.8.4.2
Specifying Parameters Specified as Nested Elements..........................................
5.8.4.3
Examples.....................................................................................................................
5.8.5
How to Create the session.validate Task.......................................................................
5.8.5.1
Using Parameters.......................................................................................................
5.8.5.2
Specifying Parameters Specified as Nested Elements..........................................
5.8.5.3
Examples.....................................................................................................................
5.8.6
How to Create the mappings.export Task ....................................................................
5.8.6.1
Using Parameters.......................................................................................................
5.8.6.2
Specifying Parameters Specified as Nested Elements..........................................
5.8.6.3
Examples.....................................................................................................................
5.8.7
How to Create the classpath Task ..................................................................................
5.8.7.1
Using Parameters.......................................................................................................
5.8.7.2
Specifying Parameters Specified as Nested Elements..........................................
5.8.7.3
Examples.....................................................................................................................
5.8.8
How to Create the ignoreerror Task ..............................................................................
5.8.8.1
Using Parameters.......................................................................................................
5.8.8.2
Specifying Parameters Specified as Nested Elements..........................................

x

5-47
5-48
5-48
5-48
5-48
5-49
5-49
5-51
5-51
5-52
5-52
5-53
5-53
5-54
5-54
5-54
5-54
5-55
5-55
5-57
5-57
5-58
5-58
5-59
5-59
5-59
5-60
5-60
5-62
5-62
5-62
5-62
5-63
5-63
5-63
5-63
5-64
5-64
5-64
5-64
5-65
5-65
5-65
5-65
5-66
5-66
5-66

5.8.8.3
5.8.9
5.8.9.1
5.8.9.2
5.8.9.3
5.8.10
5.8.10.1
5.8.10.2
5.8.10.3

Examples.....................................................................................................................
How to Create the ignoreerrorset Task .........................................................................
Using Parameters.......................................................................................................
Specifying Parameters Specified as Nested Elements..........................................
Examples.....................................................................................................................
How to Create the loginspec Task..................................................................................
Using Parameters.......................................................................................................
Specifying Parameters Specified as Nested Elements..........................................
Examples.....................................................................................................................

5-66
5-66
5-66
5-66
5-67
5-67
5-67
5-68
5-68

6 Using the Schema Manager
6.1
6.1.1
6.1.2
6.2
6.2.1
6.2.2
6.2.3
6.2.3.1
6.2.3.2
6.2.3.3
6.2.3.4
6.3
6.4
6.4.1
6.4.2

7

Introduction to the Schema Manager.......................................................................................
How to Use Schema Manager Java and Database Type Conversion...........................
How to Use Sequencing......................................................................................................
Creating a Table Creator ............................................................................................................
How to Use TopLink Workbench During Development...............................................
How to Use the Default Table Generator at Run Time ..................................................
How to Use Java to Create a Table Creator .....................................................................
Creating a TableCreator Class ....................................................................................
Creating a TableDefinition Class................................................................................
Adding Fields to a TableDefinition............................................................................
Defining Sybase and Microsoft SQL Server Native Sequencing ...........................
Creating Tables with a Table Creator ......................................................................................
Creating Database Tables Automatically ................................................................................
Creating Database Tables Automatically in JPA Projects..............................................
Creating Database Tables Automatically in EJB CMP Projects ....................................

6-1
6-3
6-3
6-4
6-4
6-4
6-5
6-5
6-5
6-5
6-6
6-6
6-6
6-6
6-7

Using an Integrated Development Environment
7.1
Configuring TopLink for Oracle JDeveloper ..........................................................................
7.1.1
How to Use TopLink Mappings ........................................................................................
7.2
Configuring TopLink Workbench with Source Control Management Software ..............
7.2.1
How to Use a Source Control Management System.......................................................
7.2.2
How to Merge Files .............................................................................................................
7.2.2.1
Merging Project Files....................................................................................................
7.2.2.2
Merging Table, Descriptor, and Class Files ..............................................................
7.2.3
How to Share Project Objects .............................................................................................
7.2.4
How to Manage the ejb-jar.xml File ..................................................................................
7.2.5
How to Work with Locked Files........................................................................................

Part III

7-1
7-1
7-3
7-3
7-4
7-4
7-5
7-6
7-6
7-6

TopLink Application Deployment

8 Integrating TopLink with an Application Server
8.1
8.2
8.2.1
8.2.2

Introduction to the Application Server Support ....................................................................
Integrating TopLink with an Application Server...................................................................
What Are the Software Requirements ..............................................................................
How to Configure the XML Parser Platform...................................................................

8-1
8-2
8-2
8-3

xi

8.2.2.1
Configuring XML Parser Platform............................................................................. 8-3
8.2.2.2
Creating an XML Parser Platform.............................................................................. 8-4
8.2.2.3
XML Parser Limitations............................................................................................... 8-4
8.2.3
How to Set Security Permissions....................................................................................... 8-4
8.2.4
How to Migrate the Persistence Manager........................................................................ 8-4
8.2.5
How to Integrate Clustering .............................................................................................. 8-5
8.3
Integrating TopLink with Oracle WebLogic Server............................................................... 8-5
8.3.1
How to Configure Classpath.............................................................................................. 8-5
8.3.2
How to Integrate JTA .......................................................................................................... 8-6
8.3.3
How to Integrate JMX ......................................................................................................... 8-6
8.3.4
How to Integrate the Security Manager ........................................................................... 8-6
8.4
Integrating TopLink with Oracle Containers for Java EE (OC4J) ........................................ 8-7
8.4.1
How to Integrate CMP ........................................................................................................ 8-7
8.4.2
How to Migrate OC4J Orion CMP Persistence to OC4J TopLink Persistence............ 8-7
8.4.2.1
What You May Need to Know About Migrating OC4J Orion Persistence to OC4J
TopLink Persistence 8-8
8.4.2.2
Using the TopLink Migration Tool from TopLink Workbench.......................... 8-11
8.4.2.3
Using the TopLink Migration Tool from the Command Line ............................ 8-12
8.4.2.4
Performing Post-Migration Changes...................................................................... 8-14
8.4.2.4.1
EJB 2.1 Persistence Manager Customization .................................................. 8-15
8.4.2.4.2
Session Event Listener ....................................................................................... 8-15
8.4.2.5
Troubleshooting Your Migration ............................................................................ 8-15
8.4.3
How to Integrate JTA ....................................................................................................... 8-16
8.4.4
How to Integrate with Oracle Application Server Manageability and Diagnosability.....
8-16
8.5
Integrating TopLink with IBM WebSphere Application Server ....................................... 8-16
8.5.1
How to Configure Classpath........................................................................................... 8-17
8.5.1.1
Configuring Classpath for IBM WebSphere Application Server 6.1 and Later 8-17
8.5.2
How to Configure Class Loader Order ......................................................................... 8-17
8.5.3
How to Integrate JTA ....................................................................................................... 8-17
8.5.4
How to Configure Clustering on IBM WebSphere Application Server.................... 8-17
8.6
Integrating TopLink with Sun Application Server ............................................................. 8-17
8.6.1
How to Configure Classpath........................................................................................... 8-18
8.6.2
How to Integrate JTA ....................................................................................................... 8-18
8.7
Integrating TopLink with JBoss Application Server........................................................... 8-18
8.7.1
How to Configure Classpath........................................................................................... 8-18
8.7.2
How to Integrate JTA ....................................................................................................... 8-18
8.7.3
How to Configure JPA Application Deployment to JBoss 4.2 Application Server. 8-18
8.8
Defining Security Permissions ............................................................................................... 8-19
8.8.1
How to Define Permissions Required by TopLink Features...................................... 8-19
8.8.1.1
Defining System Properties...................................................................................... 8-20
8.8.1.2
Loading project.xml or sessions.xml Files ............................................................. 8-20
8.8.1.3
Defining Cache Coordination .................................................................................. 8-20
8.8.1.4
Accessing a Data Source by Port ............................................................................. 8-20
8.8.1.5
Logging with java.util.logging ................................................................................ 8-21
8.8.1.6
Granting Permissions for Java EE Application Deployment .............................. 8-21
8.8.2
How to Define Permissions Required when doPrivileged Is Disabled .................... 8-21
8.8.3
How to Disable doPrivileged Operation....................................................................... 8-21
xii

8.9
8.9.1
8.9.2
8.9.3

Configuring Miscellaneous EJB CMP Options ....................................................................
How to Configure EJB CMP Setter Parameter Type Checking..................................
How to Configure EJB CMP Unknown Primary Key Class Support........................
How to Configure EJB CMP Single-Object Finder Return Type Checking..............

8-21
8-22
8-22
8-22

9 Creating TopLink Files for Deployment
9.1
9.1.1
9.1.1.1
9.1.1.2
9.1.1.3
9.1.1.4
9.1.1.5
9.1.1.6
9.1.1.7
9.1.2
9.1.2.1
9.1.2.2
9.1.2.3
9.1.2.4
9.1.3
9.1.4
9.1.4.1
9.1.4.2
9.1.5
9.1.5.1
9.2
9.3
9.4
9.4.1
9.4.2
9.5
9.6
9.7
9.8
9.8.1
9.9
9.9.1
9.9.1.1
9.9.1.2
9.9.1.3

Introduction to the TopLink Deployment File Creation ....................................................... 9-1
project.xml File ..................................................................................................................... 9-2
XSD File Format ............................................................................................................ 9-2
POJO Applications and Project Metadata................................................................. 9-2
JPA Applications and Project Metadata.................................................................... 9-2
CMP Applications and Project Metadata.................................................................. 9-3
Creating the project.xml File with Oracle JDeveloper ............................................ 9-3
Creating the project.xml File with TopLink Workbench ........................................ 9-3
Creating project.xml Programatically........................................................................ 9-3
sessions.xml File................................................................................................................... 9-4
XSD File Format ............................................................................................................ 9-4
POJO Applications and Session Metadata................................................................ 9-4
JPA Applications and Session Metadata................................................................... 9-4
CMP Applications and Session Metadata................................................................. 9-5
ejb-jar.xml File ...................................................................................................................... 9-5
JAVA-EE-CONTAINER-ejb-jar.xml File ........................................................................... 9-6
Oracle WebLogic Server and the weblogic-ejb-jar.xml File ................................... 9-6
OC4J and the orion-ejb-jar.xml File............................................................................ 9-6
toplink-ejb-jar.xml File ........................................................................................................ 9-7
OC4J and the toplink-ejb-jar.xml File ....................................................................... 9-7
Creating Deployment Files for Java Applications ................................................................. 9-7
Creating Deployment Files for JavaServer Pages and Servlet Applications...................... 9-7
Creating Deployment Files for Session Bean Applications .................................................. 9-7
How to Create Deployment Files for EJB 1.n and 2.n Session Bean Applications ..... 9-8
How to Create Deployment Files for EJB 3.0 Session Bean Applications ................... 9-8
Creating Deployment Files for JPA Applications .................................................................. 9-8
Creating Deployment Files for CMP Applications ................................................................ 9-8
Creating Deployment Files for BMP Applications ................................................................ 9-9
Configuring the weblogic-ejb-jar.xml File for Oracle WebLogic Server............................. 9-9
What You May Need to Know About Unsupported weblogi