Oracle® TopLinkDeveloper’s Guide, Volume 4

10g (10.1.3.1.0)

B28218-01

September 2006

Understanding Non-Relational Mappings

Oracle TopLink Developer’s Guide, Volume 4, 10g (10.1.3.1.0)

B28218-01

Copyright © 1997, 2006, Oracle. All rights reserved.

Primary Author: Peter Purich, Rick Sapir, Liza Rekadze

The Programs (which include both the software and documentation) contain proprietary information; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly, or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. This document is not warranted to be error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on behalf of the United States 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, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, PeopleSoft, and Siebel are registered trademarks of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites. You bear all risks associated with the use of such content. If you choose to purchase any products or services from a third party, the relationship is directly between you and the third party. Oracle is not responsible for: (a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the third party, including delivery of products or services and warranty obligations related to purchased products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from dealing with any third party.

iii

Contents

Preface .............................................................................................................................................................. xlix

Part I Building a TopLink Application

1 Understanding TopLink

What is TopLink?...................................................................................................................................... 1-1Solving the Object-Persistence Impedance Mismatch ..................................................................... 1-2TopLink Key Features.............................................................................................................................. 1-4TopLink Application Architectures ...................................................................................................... 1-4

2 Understanding TopLink Application Development

Developing Your Application With TopLink ..................................................................................... 2-1Typical Development Stages ............................................................................................................ 2-2Oracle Development Support........................................................................................................... 2-3

Designing Your Application With TopLink ........................................................................................ 2-3Understanding TopLink Usage........................................................................................................ 2-3

Relational Database Usage ........................................................................................................ 2-4Object-Relational Database Usage............................................................................................ 2-4Oracle XML Database (XDB) Usage......................................................................................... 2-4Enterprise Information System (EIS) Usage............................................................................ 2-4XML Usage................................................................................................................................... 2-4

Understanding Target Platforms ..................................................................................................... 2-5Selecting an Architecture With TopLink ............................................................................................. 2-5

Tiers...................................................................................................................................................... 2-5Three Tier ..................................................................................................................................... 2-6Two Tier ....................................................................................................................................... 2-6

Service Layer....................................................................................................................................... 2-7EJB Session Beans........................................................................................................................ 2-7EJB Entity Beans .......................................................................................................................... 2-7EJB 3.0 JPA Entities ..................................................................................................................... 2-8Plain Old Java Objects (POJO) .................................................................................................. 2-8

Data Access ......................................................................................................................................... 2-9Data Type ..................................................................................................................................... 2-9Multiple Data Sources ................................................................................................................ 2-9Isolating Data Access.................................................................................................................. 2-9

iv

Historical Data Access................................................................................................................ 2-9Caching ................................................................................................................................................ 2-9

Cache Type................................................................................................................................ 2-10Refreshing ................................................................................................................................. 2-10Cache Coordination................................................................................................................. 2-10

Locking ............................................................................................................................................. 2-11Optimistic Locking .................................................................................................................. 2-11Pessimistic Locking.................................................................................................................. 2-11

Building and Using the Persistence Layer ....................................................................................... 2-11Implementation Options ................................................................................................................ 2-12Persistent Class Requirements ...................................................................................................... 2-12Persistence Layer Components ..................................................................................................... 2-12

Mapping Metadata .................................................................................................................. 2-13Session Metadata...................................................................................................................... 2-13Cache.......................................................................................................................................... 2-13Queries and Expressions......................................................................................................... 2-13Transactions .............................................................................................................................. 2-14

Using the Persistence Layer........................................................................................................... 2-14Deploying the Application.................................................................................................................. 2-15

Understanding Deployments ........................................................................................................ 2-15TopLink in a J2EE Application...................................................................................................... 2-15

Optimizing and Customizing the Application................................................................................ 2-15Troubleshooting the Application ....................................................................................................... 2-16Understanding Object Persistence..................................................................................................... 2-16

Application Object Model .............................................................................................................. 2-16Data Storage Schema ...................................................................................................................... 2-17Primary Keys and Object Identity ................................................................................................ 2-17Mappings.......................................................................................................................................... 2-17Foreign Keys and Object Relationships ....................................................................................... 2-17Inheritance........................................................................................................................................ 2-18Concurrency..................................................................................................................................... 2-18Caching ............................................................................................................................................. 2-18Nonintrusive Persistence ............................................................................................................... 2-19Indirection ........................................................................................................................................ 2-19

Understanding TopLink Metadata..................................................................................................... 2-19Advantages of the TopLink Metadata Architecture .................................................................. 2-20Creating Project Metadata ............................................................................................................. 2-20

Descriptors and Mappings ..................................................................................................... 2-21Data Source Login Information ............................................................................................. 2-21

Creating Session Metadata ............................................................................................................ 2-21Deploying Metadata ....................................................................................................................... 2-22

Understanding the Three-Tier Architecture..................................................................................... 2-22Example Implementations ............................................................................................................. 2-22Advantages and Disadvantages ................................................................................................... 2-22Variation Using Remote Sessions ................................................................................................. 2-23Technical Challenges ...................................................................................................................... 2-23

Understanding the Two-Tier Architecture ...................................................................................... 2-24

v

Example Implementations ............................................................................................................. 2-24Advantages and Disadvantages ................................................................................................... 2-24Technical Challenges ...................................................................................................................... 2-24

Understanding the EJB Session Bean Facade Architecture........................................................... 2-25Example Implementation............................................................................................................... 2-25Advantages and Disadvantages ................................................................................................... 2-26Understanding Session Beans ....................................................................................................... 2-26Technical Challenges ...................................................................................................................... 2-26Unit of Work Merge........................................................................................................................ 2-27

Understanding the EJB Entity Beans With CMP Architecture ..................................................... 2-27Example Implementation............................................................................................................... 2-28Advantages and Disadvantages ................................................................................................... 2-28Technical Challenges ...................................................................................................................... 2-29

External JDBC Pools ................................................................................................................ 2-29JTA/JTS Integration................................................................................................................. 2-29Cache Coordination................................................................................................................. 2-29Maintaining Bidirectional Relationships .............................................................................. 2-29Managing Dependent Objects................................................................................................ 2-30Managing Collections of EJBObject Objects......................................................................... 2-31

Understanding the EJB Entity Beans With BMP Architecture ..................................................... 2-31Example Implementations ............................................................................................................. 2-32Advantages and Disadvantages ................................................................................................... 2-32Technical Challenges ...................................................................................................................... 2-33

External JDBC Pools ................................................................................................................ 2-33JTA/JTS Integration................................................................................................................. 2-33Cache Coordination................................................................................................................. 2-33

Understanding the EJB 3.0 JPA Entity Architecture ....................................................................... 2-33Example Implementations ............................................................................................................. 2-34Advantages and Disadvantages ................................................................................................... 2-35

Understanding the Web Services Architecture................................................................................ 2-35Example Implementations ............................................................................................................. 2-35Advantages and Disadvantages ................................................................................................... 2-36Technical Challenges ...................................................................................................................... 2-36

Part II Using TopLink Development Tools

3 Understanding TopLink Development Tools

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

4 Using TopLink Workbench

Understanding TopLink Workbench.................................................................................................... 4-1Configuring the TopLink Workbench Environment ......................................................................... 4-2Working With TopLink Workbench ..................................................................................................... 4-3

Using the Menus ................................................................................................................................ 4-5Menu Bar Menus......................................................................................................................... 4-5

vi

Context Menus ............................................................................................................................ 4-5Using the Toolbars ............................................................................................................................. 4-6

Standard Toolbar ........................................................................................................................ 4-6Context Toolbar........................................................................................................................... 4-7

Using the Navigator........................................................................................................................... 4-9Using the Editor .............................................................................................................................. 4-10Using the Problems Window ........................................................................................................ 4-11Using the Online Help.................................................................................................................... 4-12

Working With TopLink Workbench Preferences ............................................................................ 4-12General Preferences ........................................................................................................................ 4-13Help Preferences ............................................................................................................................. 4-14Mappings Preferences .................................................................................................................... 4-15Class Preferences ............................................................................................................................. 4-16EJB Preferences ................................................................................................................................ 4-16Database Preferences ...................................................................................................................... 4-17Sessions Configuration Preferences ............................................................................................. 4-18New Names Preferences ................................................................................................................ 4-19Platform Preferences....................................................................................................................... 4-20

Working With Databases ..................................................................................................................... 4-21Working With Database Tables in the Navigator Window...................................................... 4-21

Logging In and Out of a Database......................................................................................... 4-21Creating New Tables ............................................................................................................... 4-22Importing Tables From a Database ....................................................................................... 4-22Removing Tables...................................................................................................................... 4-24Renaming Tables...................................................................................................................... 4-24Refreshing Tables From the Database................................................................................... 4-24

Working With Database Tables in the Editor Window............................................................. 4-25Working With Column Properties ........................................................................................ 4-25Setting a Primary Key for Database Tables.......................................................................... 4-26Creating Table References ...................................................................................................... 4-26Creating Field Associations.................................................................................................... 4-28

Generating Data From Database Tables ...................................................................................... 4-29Generating SQL Creation Scripts........................................................................................... 4-29Generating Classes and Descriptors From Database Tables ............................................. 4-30Generating EJB Entity Beans and Descriptors From Database Tables ............................. 4-31Generating Tables on the Database ....................................................................................... 4-32

Working With XML Schemas .............................................................................................................. 4-33Working With XML Schemas in the Navigator.......................................................................... 4-33Working With XML Schema Structure ........................................................................................ 4-34Importing an XML Schema............................................................................................................ 4-34Configuring XML Schema Reference ........................................................................................... 4-36

Using TopLink Workbench .................................................................................................... 4-36Using Java ................................................................................................................................. 4-37

Configuring XML Schema Namespace........................................................................................ 4-37Using TopLink Workbench .................................................................................................... 4-38Using Java ................................................................................................................................. 4-39

Working With Classes .......................................................................................................................... 4-40

vii

Creating Classes .............................................................................................................................. 4-40Using TopLink Workbench .................................................................................................... 4-40

Configuring Classes........................................................................................................................ 4-41Configuring Class Information .............................................................................................. 4-41Configuring Class Modifiers .................................................................................................. 4-42Configuring Class Interfaces .................................................................................................. 4-43Adding Attributes.................................................................................................................... 4-44Configuring Attribute Modifiers ........................................................................................... 4-44Configuring Attribute Type Information ............................................................................. 4-45Configuring Attribute Accessing Methods .......................................................................... 4-46Adding Methods ...................................................................................................................... 4-47Configuring Method Modifiers ............................................................................................. 4-48Configuring Method Type Information ............................................................................... 4-48Configuring Method Parameters........................................................................................... 4-49

Importing and Updating Classes.................................................................................................. 4-50Using TopLink Workbench .................................................................................................... 4-50

Managing Nondescriptor Classes................................................................................................. 4-51Renaming Packages ........................................................................................................................ 4-52

Using TopLink Workbench .................................................................................................... 4-52Integrating TopLink Workbench With Apache Ant ....................................................................... 4-53

Configuring Ant to Use TopLink Workbench Tasks ................................................................. 4-53Library Dependencies ............................................................................................................. 4-53Declaring TopLink Workbench Tasks .................................................................................. 4-54

Understanding TopLink Workbench Ant Task API .................................................................. 4-54Creating TopLink Workbench Ant Tasks.................................................................................... 4-55mappings.validate........................................................................................................................... 4-56

Parameters................................................................................................................................. 4-57Parameters Specified as Nested Elements............................................................................ 4-57Examples ................................................................................................................................... 4-57

session.validate................................................................................................................................ 4-57Parameters................................................................................................................................. 4-58Parameters Specified as Nested Elements............................................................................ 4-58Examples ................................................................................................................................... 4-58

mappings.export ............................................................................................................................. 4-58Parameters................................................................................................................................. 4-58Parameters Specified as Nested Elements............................................................................ 4-59Examples ................................................................................................................................... 4-59

classpath ........................................................................................................................................... 4-59Parameters................................................................................................................................. 4-60Parameters Specified as Nested Elements............................................................................ 4-60Examples ................................................................................................................................... 4-60

ignoreerror ....................................................................................................................................... 4-60Parameters................................................................................................................................. 4-60Parameters Specified as Nested Elements............................................................................ 4-60Examples ................................................................................................................................... 4-61

ignoreerrorset................................................................................................................................... 4-61Parameters................................................................................................................................. 4-61

viii

Parameters Specified as Nested Elements............................................................................ 4-61Examples ................................................................................................................................... 4-61

loginspec........................................................................................................................................... 4-62Parameters................................................................................................................................. 4-62Parameters Specified as Nested Elements............................................................................ 4-62Examples ................................................................................................................................... 4-62

5 Using the Schema Manager

Understanding the Schema Manager ................................................................................................... 5-1Schema Manager Java and Database Type Conversion ............................................................... 5-3Sequencing .......................................................................................................................................... 5-3

Creating a Table Creator.......................................................................................................................... 5-4Using TopLink Workbench During Development........................................................................ 5-4Using the Default Table Generator at Run Time ........................................................................... 5-4Using Java............................................................................................................................................ 5-4

Creating a TableCreator Class................................................................................................... 5-5Creating a TableDefinition Class .............................................................................................. 5-5Adding Fields to a TableDefinition.......................................................................................... 5-5Defining Sybase and Microsoft SQL Server Native Sequencing.......................................... 5-6

Creating Tables With a Table Creator ................................................................................................... 5-6Automatic Database Table Creation ..................................................................................................... 5-6

6 Using an Integrated Development Environment

Configuring TopLink for Oracle JDeveloper...................................................................................... 6-1Using TopLink Mappings ................................................................................................................. 6-1Using TopLink Sessions .................................................................................................................... 6-3

Configuring TopLink Workbench With Source Control Management Software........................ 6-3Using a Source Control Management System................................................................................ 6-3Merging Files ...................................................................................................................................... 6-4

Merging Project Files .................................................................................................................. 6-4Merging Table, Descriptor, and Class Files ............................................................................ 6-5

Sharing Project Objects...................................................................................................................... 6-6Managing the ejb-jar.xml File ........................................................................................................... 6-6Working With Locked Files .............................................................................................................. 6-6

Part III Deploying a TopLink Application

7 Integrating TopLink With an Application Server

Application Server Support ................................................................................................................... 7-1Application Server Integration Concepts ............................................................................................ 7-2

Software Requirements ..................................................................................................................... 7-2XML Parser Platform Configuration ............................................................................................... 7-2

Configuring XML Parser Platform ........................................................................................... 7-3Creating an XML Parser Platform ............................................................................................ 7-3XML Parser Limitations ............................................................................................................. 7-3

Security Permissions.......................................................................................................................... 7-4

ix

Persistence Manager Migration ....................................................................................................... 7-4Clustering ............................................................................................................................................ 7-4

Oracle Containers for J2EE (OC4J)........................................................................................................ 7-5CMP Integration ................................................................................................................................. 7-5Migrating OC4J Orion Persistence to OC4J TopLink Persistence............................................... 7-5

Overview...................................................................................................................................... 7-6Using the TopLink Migration Tool From TopLink Workbench .......................................... 7-9Using the TopLink Migration Tool From the Command Line.......................................... 7-10Post-Migration Changes ......................................................................................................... 7-12Troubleshooting Your Migration........................................................................................... 7-13

JTA Integration ................................................................................................................................ 7-14BEA WebLogic Server........................................................................................................................... 7-14

Classpath .......................................................................................................................................... 7-15CMP Integration .............................................................................................................................. 7-15Migrating BEA WebLogic Persistence to OC4J TopLink Persistence...................................... 7-16

Overview................................................................................................................................... 7-16Using the TopLink Migration Tool From TopLink Workbench ....................................... 7-18Using the TopLink Migration Tool From the Command Line.......................................... 7-18

JTA Integration ................................................................................................................................ 7-20Security Manager ............................................................................................................................ 7-20

IBM WebSphere Application Server ................................................................................................. 7-21Classpath .......................................................................................................................................... 7-21

Configuring Classpath for IBM WebSphere Application Server 4.0................................ 7-21Configuring Classpath for IBM WebSphere Application Server 5.0 and Later.............. 7-21

CMP Integration .............................................................................................................................. 7-22JTA Integration ................................................................................................................................ 7-22Clustering on IBM WebSphere Application Server ................................................................... 7-22

Understanding Security Permissions ................................................................................................ 7-22Permissions Required by TopLink Features ............................................................................... 7-23

System Properties..................................................................................................................... 7-23Loading project.xml or sessions.xml Files............................................................................ 7-23Cache Coordination................................................................................................................. 7-23Accessing a Data Source by Port ........................................................................................... 7-24Logging With java.util.logging .............................................................................................. 7-24J2EE Application Deployment ............................................................................................... 7-24

Permissions Required When doPrivileged is Disabled............................................................. 7-24Disabling doPrivileged Operation................................................................................................ 7-25

Configuring Miscellaneous EJB Options ......................................................................................... 7-25Setter Parameter Type Checking................................................................................................... 7-25Unknown Primary Key Class Support......................................................................................... 7-25Single-Object Finder Return Type Checking .............................................................................. 7-26

8 Creating TopLink Files for Deployment

Understanding TopLink Deployment File Creation ......................................................................... 8-1project.xml File ................................................................................................................................... 8-2

XSD File Format .......................................................................................................................... 8-2Non-CMP Applications and Project Metadata ....................................................................... 8-2

x

CMP Applications and Project Metadata ................................................................................ 8-3Creating project.xml With TopLink Workbench.................................................................... 8-3Creating project.xml Programatically ...................................................................................... 8-3

sessions.xml File ................................................................................................................................. 8-4XSD File Format .......................................................................................................................... 8-4Non-CMP Applications and Session Metadata ...................................................................... 8-4CMP Applications and Session Metadata ............................................................................... 8-4

ejb-jar.xml File..................................................................................................................................... 8-5<J2EE-Container>-ejb-jar.xml File..................................................................................................... 8-5

OC4J and the orion-ejb-jar.xml File .......................................................................................... 8-6BEA WebLogic Server and the weblogic-ejb-jar.xml File ..................................................... 8-6

toplink-ejb-jar.xml File ...................................................................................................................... 8-6OC4J and the toplink-ejb-jar.xml File ...................................................................................... 8-7BEA WebLogic Server and the toplink-ejb-jar.xml File......................................................... 8-7IBM WebSphere Application Server and the toplink-ejb-jar.xml File................................. 8-8

Java Applications...................................................................................................................................... 8-8JavaServer Pages and Servlet Applications......................................................................................... 8-8Session Bean Applications ..................................................................................................................... 8-9CMP Applications .................................................................................................................................... 8-9BMP Applications .................................................................................................................................... 8-9Configuring the orion-ejb-jar.xml File for OC4J................................................................................ 8-9

Configuring persistence-manager Entries................................................................................... 8-10Configuring pm-properties .................................................................................................... 8-10Configuring cache-synchronization Properties................................................................... 8-11Configuring default-mapping Properties............................................................................. 8-12

Configuring the weblogic-ejb-jar.xml File for BEA WebLogic Server ....................................... 8-13Configuring persistence-descriptor Entries ................................................................................ 8-14Unsupported weblogic-ejb-jar.xml File Tags .............................................................................. 8-15

9 Packaging a TopLink Application

Java Applications...................................................................................................................................... 9-1JavaServer Pages and Servlet Applications......................................................................................... 9-2

TopLink Domain JAR ........................................................................................................................ 9-2Session Bean Applications ..................................................................................................................... 9-3

TopLink Domain JAR ........................................................................................................................ 9-3EJB JAR ................................................................................................................................................ 9-4

CMP Applications .................................................................................................................................... 9-4EJB JAR ................................................................................................................................................ 9-5

BMP Applications .................................................................................................................................... 9-5TopLink Domain JAR ........................................................................................................................ 9-6EJB JAR ................................................................................................................................................ 9-7

Packaging With TopLink Metadata File Resource Paths .................................................................. 9-7

10 Deploying a TopLink Application

Java Applications................................................................................................................................... 10-1JavaServer Pages and Servlets ............................................................................................................ 10-1Session Bean Applications .................................................................................................................. 10-1

xi

CMP Applications ................................................................................................................................. 10-2Deploying a CMP Application to OC4J ....................................................................................... 10-2Deploying a CMP Application to BEA WebLogic Server ......................................................... 10-2

Troubleshooting ejbc ............................................................................................................... 10-3Deploying a CMP Application to IBM WebSphere Application Server 4.0 .......................... 10-3

Starting the Entity Bean .......................................................................................................... 10-3BMP Applications ................................................................................................................................. 10-4Hot Deployment of EJB........................................................................................................................ 10-4

Hot Deployment in a CMP Application ...................................................................................... 10-4Hot Deployment in a non-CMP Application .............................................................................. 10-4

Using the WebSphere Deploy Tool.................................................................................................... 10-5Using the Deploy Tool on its Own ............................................................................................... 10-5Using the Deploy Tool With WebSphere Studio Application Developer .............................. 10-5

Troubleshooting ....................................................................................................................... 10-6

Part IV Optimizing and Customizing a TopLink Application

11 Optimization

Understanding Optimization.............................................................................................................. 11-1Sources of Application Performance Problems............................................................................... 11-2Measuring TopLink Performance With the TopLink Profiler ...................................................... 11-2

Configuring the TopLink Performance Profiler ......................................................................... 11-3Accessing the TopLink Profiler Results ....................................................................................... 11-3

Measuring TopLink Performance With the Oracle Dynamic Monitoring System (DMS) ..... 11-4Configuring the Oracle DMS Profiler .......................................................................................... 11-6

OC4J Applications ................................................................................................................... 11-7Non-OC4J Applications .......................................................................................................... 11-7

Accessing Oracle DMS Profiler Data Using JMX ....................................................................... 11-7Accessing Oracle DMS Profiler Data Using the DMS Spy Servlet........................................... 11-7

General Performance Optimization .................................................................................................. 11-8Schema Optimization ........................................................................................................................... 11-8

Schema Case 1: Aggregation of Two Tables into One ............................................................... 11-9Schema Case 2: Splitting One Table Into Many.......................................................................... 11-9Schema Case 3: Collapsed Hierarchy......................................................................................... 11-11Schema Case 4: Choosing One out of Many ............................................................................. 11-12

Mapping and Descriptor Optimization .......................................................................................... 11-13Session Optimization ......................................................................................................................... 11-13Cache Optimization ............................................................................................................................ 11-13Data Access Optimization ................................................................................................................. 11-14

JDBC Driver Properties Optimization........................................................................................ 11-14Data Format Optimization........................................................................................................... 11-15Batch Writing ................................................................................................................................. 11-15Parameterized SQL (Binding) and Prepared Statement Caching .......................................... 11-15

Query Optimization............................................................................................................................ 11-17Parameterized SQL and Prepared Statement Caching............................................................ 11-17Named Queries.............................................................................................................................. 11-17

xii

Batch and Join Reading ................................................................................................................ 11-17Partial Object Queries and Fetch Groups .................................................................................. 11-17JDBC Fetch Size ............................................................................................................................. 11-18Cursored Streams and Scrollable Cursors................................................................................. 11-19Read Optimization Examples...................................................................................................... 11-19

Reading Case 1: Displaying Names in a List ..................................................................... 11-20Reading Case 2: Batch Reading Objects.............................................................................. 11-23Reading Case 3: Using Complex Custom SQL Queries ................................................... 11-24Reading Case 4: Using View Objects .................................................................................. 11-25Reading Case 5: Inheritance Views ..................................................................................... 11-26

Write Optimization Examples..................................................................................................... 11-26Writing Case: Batch Writes................................................................................................... 11-27

Unit of Work Optimization ............................................................................................................... 11-30Application Server and Database Optimization ........................................................................... 11-30

12 Customization

Overview ................................................................................................................................................. 12-1Creating Custom Data Types .............................................................................................................. 12-1Using Public Source.............................................................................................................................. 12-2

Part V Troubleshooting a TopLink Application

13 TopLink Exception Reference

Descriptor Exceptions (1 – 201) ........................................................................................................... 13-2Concurrency Exceptions (2001 – 2009) ............................................................................................. 13-25Conversion Exceptions (3001– 3008) ................................................................................................ 13-26Database Exceptions (4002 – 4018).................................................................................................... 13-27Optimistic Lock Exceptions (5001 – 5009) ....................................................................................... 13-29Query Exceptions (6001 – 6129) ......................................................................................................... 13-31Validation Exceptions (7001 – 7200) ................................................................................................. 13-43EJB QL Exceptions (8001 – 8010) ....................................................................................................... 13-63Session Loader Exceptions (9000 - 9010) ......................................................................................... 13-64Communication Exceptions (12000 - 12003).................................................................................... 13-65EIS Exceptions (17007 – 17025), 90000, 91000 .................................................................................. 13-66JMS Processing Exceptions (18001 - 18004)..................................................................................... 13-69Default Mapping Exceptions (20001 - 20008) ................................................................................. 13-69Discovery Exceptions (22001 - 22004)............................................................................................... 13-70Remote Command Manager Exceptions (22101 - 22111) .............................................................. 13-71Transaction Exceptions (23001 - 23015) ............................................................................................ 13-73XML Conversion Exceptions (25501) ............................................................................................... 13-74Migration Utility Exceptions (26001 - 26020).................................................................................. 13-74EJB JAR XML Exceptions (72000 – 72023) ....................................................................................... 13-77Entity Manager Setup Exceptions (28001 – 28007) ........................................................................ 13-80XML Marshal Exceptions (25001 – 25020) ....................................................................................... 13-81XML Platform Exceptions (27001 – 27006, 27101 – 27103, 27201 – 27202) .................................. 13-83

xiii

14 TopLink Workbench Error Reference

Miscellaneous Errors (1 – 89, 106 – 133)............................................................................................. 14-1Project Errors (100 – 102) ...................................................................................................................... 14-3Descriptor Errors (200 – 399)................................................................................................................ 14-3Mapping Errors (400 – 483) ................................................................................................................ 14-13Table Errors (500 – 610) ....................................................................................................................... 14-17XML Schema Errors (700 – 706) ......................................................................................................... 14-23Session Errors (800 – 812) ................................................................................................................... 14-23Common Classpath Problems........................................................................................................... 14-25Data Source Problems ........................................................................................................................ 14-25

Database Connection Problems .................................................................................................. 14-25

15 Troubleshooting Application Deployment

Generating Deployment JAR Files .................................................................................................... 15-1Common J2SE Deployment Exceptions ............................................................................................ 15-1

Classpath Exceptions ...................................................................................................................... 15-2Communication Exceptions........................................................................................................... 15-2Descriptor Validation Exceptions ................................................................................................. 15-2

Common BEA WebLogic Server Deployment Exceptions ............................................................ 15-3Common BEA WebLogic Server 6.1 Exceptions .............................................................................. 15-5

Development Exceptions ............................................................................................................... 15-6Deployment and Run-Time Exceptions....................................................................................... 15-6

Common BEA WebLogic 7.0 Exceptions ........................................................................................... 15-8Development Exceptions ............................................................................................................... 15-8Deployment Exceptions ................................................................................................................. 15-9

Common BEA WebLogic 8.1 Exceptions ......................................................................................... 15-10Development Exceptions ............................................................................................................. 15-10Deployment Exceptions ............................................................................................................... 15-11

Common IBM WebSphere Application Server Exceptions ........................................................ 15-12Problems at Run Time .................................................................................................................. 15-14Common TopLink for IBM WebSphere Deploy Tool Exceptions.......................................... 15-15

Part VI Mapping and Configuration Overview

16 Understanding TopLink Mapping and Configuration Concepts

Mapping and Configuration Concepts ............................................................................................. 16-1Projects.............................................................................................................................................. 16-1Descriptors ....................................................................................................................................... 16-2Mappings.......................................................................................................................................... 16-2

Part VII Projects

17 Understanding Projects

TopLink Project Types .......................................................................................................................... 17-1Project Concepts .................................................................................................................................... 17-2

xiv

Project Architecture ........................................................................................................................ 17-2Relational and Nonrelational Projects.......................................................................................... 17-2Persistent and Nonpersistent Projects.......................................................................................... 17-2Projects and Login........................................................................................................................... 17-3

Non-CMP Session Role: Session Login................................................................................. 17-3CMP Deployment Role: Deployment Login ........................................................................ 17-3Development Role: Development Login .............................................................................. 17-4

Projects and Platforms.................................................................................................................... 17-4Projects and Sequencing................................................................................................................. 17-4

Configuring how to Obtain Sequence Values...................................................................... 17-5Configuring Where to Write Sequence Values.................................................................... 17-5

XML Namespaces............................................................................................................................ 17-5Relational Projects................................................................................................................................. 17-6

Building Relational Projects for a Relational Database ............................................................. 17-6Building Relational Projects for an Object-Relational Database .............................................. 17-6

EIS Projects ............................................................................................................................................. 17-7Building EIS Projects With XML Records.................................................................................... 17-9Building EIS Projects With Indexed or Mapped Records ......................................................... 17-9

XML Projects .......................................................................................................................................... 17-9TopLink Support for Java Architecture for XML Binding (JAXB)......................................... 17-10

Understanding JAXB-Specific Generated Files ................................................................. 17-10Understanding TopLink-Specific Generated Files............................................................ 17-11Using TopLink JAXB Compiler Generated Files at Run Time ........................................ 17-12

JAXB Validation ............................................................................................................................ 17-14Understanding the Project API......................................................................................................... 17-14

Project Inheritance Hierarchy...................................................................................................... 17-14Understanding Sequencing in Relational Projects....................................................................... 17-14

Sequencing Configuration Options ............................................................................................ 17-15Sequencing Types.......................................................................................................................... 17-16

Table Sequencing ................................................................................................................... 17-16Unary Table Sequencing ....................................................................................................... 17-17Query Sequencing.................................................................................................................. 17-18Default Sequencing................................................................................................................ 17-18Native Sequencing With an Oracle Database Platform.................................................... 17-18Native Sequencing With a Non-Oracle Database Platform............................................. 17-19

Sequencing and Preallocation Size ............................................................................................. 17-20Sequencing With Entity Beans WIth Container-Managed Persistence ................................. 17-21

Understanding XML Namespaces.................................................................................................... 17-22TopLink Workbench Namespace Resolution ........................................................................... 17-22Element and Attribute Form Options ........................................................................................ 17-23

Element Form Default Qualified and Attribute Form Default Unqualified ................. 17-23Element and Attribute Form Default Unqualified............................................................ 17-24Element and Attribute Form Default Qualified ................................................................ 17-25

TopLink Runtime Namespace Resolution................................................................................. 17-26

18 Creating a Project

Project Creation Overview .................................................................................................................. 18-1

xv

Using TopLink Workbench ........................................................................................................... 18-2Creating New TopLink Workbench Projects ....................................................................... 18-2

Using Java......................................................................................................................................... 18-3Creating a Project for an Existing Object and Data Model ........................................................... 18-5

Using TopLink Workbench ........................................................................................................... 18-5Creating a Project From an Existing Object Model ........................................................................ 18-5

Using TopLink Workbench ........................................................................................................... 18-5Creating a Project From an Existing Data Model ............................................................................ 18-5

Using TopLink Workbench ........................................................................................................... 18-6Creating an XML Project From an XML Schema............................................................................. 18-6

Using TopLink Workbench ........................................................................................................... 18-6Using the Command Line.............................................................................................................. 18-8

Creating a Project by Migrating an EAR to OC4J ........................................................................... 18-9Creating a Project From an OC4J EJB CMP EAR at Deployment Time.................................... 18-10Working With Projects........................................................................................................................ 18-10

Opening Existing Projects ............................................................................................................ 18-10Saving Projects............................................................................................................................... 18-11

Saving Projects With a New Name or Location ................................................................ 18-12Generating the Project Status Report ......................................................................................... 18-12

Exporting Project Information .......................................................................................................... 18-13Exporting Deployment XML Information................................................................................. 18-14Exporting Model Java Source ...................................................................................................... 18-14Exporting Project Java Source ..................................................................................................... 18-14Exporting Table Creator Files...................................................................................................... 18-15

Working With the ejb-jar.xml File.................................................................................................... 18-15Writing to the ejb-jar.xml File...................................................................................................... 18-16Reading From the ejb-jar.xml File............................................................................................... 18-16

19 Configuring a Project

Configuring Common Project Options............................................................................................. 19-1Configuring Project Save Location .................................................................................................... 19-2

Using TopLink Workbench ........................................................................................................... 19-2Configuring Project Classpath............................................................................................................ 19-3

Using TopLink Workbench ........................................................................................................... 19-3Configuring Mapped Field Access at the Project Level................................................................. 19-4

Using TopLink Workbench ........................................................................................................... 19-4Configuring Persistence Type............................................................................................................. 19-5

Using TopLink Workbench ........................................................................................................... 19-6Configuring Default Descriptor Advanced Properties.................................................................. 19-7

Using TopLink Workbench ........................................................................................................... 19-8Configuring Existence Checking at the Project Level.................................................................... 19-8

Using TopLink Workbench ........................................................................................................... 19-9Configuring Project Deployment XML Options........................................................................... 19-10

Using TopLink Workbench ......................................................................................................... 19-10Configuring Model Java Source Code Options............................................................................. 19-11

Using TopLink Workbench ......................................................................................................... 19-11Configuring Deprecated Direct Mappings .................................................................................... 19-12

xvi

Using TopLink Workbench ......................................................................................................... 19-13Configuring Cache Type and Size at the Project Level................................................................ 19-13

Using TopLink Workbench ......................................................................................................... 19-14Configuring Cache Isolation at the Project Level ......................................................................... 19-16

Using TopLink Workbench ......................................................................................................... 19-16Configuring Cache Coordination Change Propagation at the Project Level........................... 19-17

Using TopLink Workbench ......................................................................................................... 19-18Configuring Cache Expiration at the Project Level ...................................................................... 19-19

Using TopLink Workbench ......................................................................................................... 19-20Configuring Project Comments........................................................................................................ 19-20

Using TopLink Workbench ......................................................................................................... 19-21

20 Configuring a Relational Project

Relational Project Configuration Overview .................................................................................... 20-1Configuring Relational Database Platform at the Project Level.................................................. 20-2

Using TopLink Workbench ........................................................................................................... 20-2Configuring Sequencing at the Project Level .................................................................................. 20-3

Using TopLink Workbench ........................................................................................................... 20-3Using Java......................................................................................................................................... 20-4

Configuring Login Information ......................................................................................................... 20-5Using TopLink Workbench ........................................................................................................... 20-5

Configuring Development and Deployment Logins ..................................................................... 20-6Using TopLink Workbench ........................................................................................................... 20-6

Logging in to the Database ..................................................................................................... 20-7Configuring Named Query Parameterized SQL and Statement Caching at the Project Level......... 20-7

Using TopLink Workbench ........................................................................................................... 20-8Configuring Table Generation Options............................................................................................ 20-9

Using TopLink Workbench ........................................................................................................... 20-9Configuring Table Creator Java Source Options........................................................................... 20-10

Using TopLink Workbench ......................................................................................................... 20-10Configuring Project Java Source Code Options ............................................................................ 20-11

Using TopLink Workbench ......................................................................................................... 20-11

21 Configuring an EIS Project

EIS Project Configuration Overview................................................................................................. 21-1Configuring EIS Data Source Platform at the Project Level ......................................................... 21-2

Using TopLink Workbench ........................................................................................................... 21-2Configuring EIS Connection Specification Options at the Project Level .................................. 21-2

Using TopLink Workbench ........................................................................................................... 21-3

22 Configuring an XML Project

XML Project Configuration Overview .............................................................................................. 22-1

Part VIII Descriptors

xvii

23 Understanding Descriptors

Descriptor Types .................................................................................................................................... 23-1Descriptor Concepts.............................................................................................................................. 23-2

Descriptor Architecture.................................................................................................................. 23-2Descriptors and Inheritance........................................................................................................... 23-3Descriptors and EJB ........................................................................................................................ 23-3

Nondeferred Changes ............................................................................................................. 23-3Creating a New Entity Bean and ejbCreate / ejbPostCreate Methods ............................ 23-4Inheritance ................................................................................................................................ 23-4

Fetch Groups ................................................................................................................................... 23-5Amendment and After-Load Methods ........................................................................................ 23-5Descriptors and Aggregation ........................................................................................................ 23-5

Aggregate and Composite Descriptors in Relational Projects .......................................... 23-5Root and Composite Descriptors in EIS Projects................................................................. 23-8Composite Descriptors in XML Projects............................................................................... 23-8

Descriptor Event Manager............................................................................................................. 23-8Descriptor Query Manager............................................................................................................ 23-8Descriptors and Sequencing .......................................................................................................... 23-9Descriptors and Locking ................................................................................................................ 23-9Default Root Element ..................................................................................................................... 23-9

Relational Descriptors ........................................................................................................................ 23-11Object-Relational Descriptors .......................................................................................................... 23-11EIS Descriptors .................................................................................................................................... 23-12XML Descriptors.................................................................................................................................. 23-12Understanding Descriptors and Inheritance ................................................................................. 23-12

Specifying a Class Indicator......................................................................................................... 23-14Using Class Indicator Fields................................................................................................. 23-14Using Class Extraction Methods.......................................................................................... 23-15

Inheritance and Primary Keys (Relational and EIS Only)....................................................... 23-16Single and Multi-Table Inheritance (Relational Only)............................................................. 23-16

Single Table Inheritance........................................................................................................ 23-16Multitable Inheritance ........................................................................................................... 23-16

Aggregate and Composite Descriptors and Inheritance ......................................................... 23-17Inheritance and EJB....................................................................................................................... 23-17

Understanding Descriptors and Locking ....................................................................................... 23-18Optimistic Version Locking Policies .......................................................................................... 23-18Optimistic Version Locking Policies and Cascading ............................................................... 23-19Optimistic Locking and Rollbacks.............................................................................................. 23-20Optimistic Field Locking Policies ............................................................................................... 23-20Pessimistic Locking Policy........................................................................................................... 23-22Locking in a Three-Tier Application .......................................................................................... 23-22

Optimistic Locking in a Three-Tier Application ............................................................... 23-22Pessimistic Locking in a Three-Tier Application .............................................................. 23-23

Understanding the Descriptor API .................................................................................................. 23-23Descriptor Inheritance Hierarchy ............................................................................................... 23-23

xviii

24 Creating a Descriptor

Descriptor Creation Overview............................................................................................................ 24-1Creating a Relational Descriptor ........................................................................................................ 24-1

Using TopLink Workbench ........................................................................................................... 24-2Relational Class Descriptors................................................................................................... 24-2Relational Aggregate Descriptors.......................................................................................... 24-2Relational Interface Descriptors............................................................................................. 24-2

Using Java......................................................................................................................................... 24-2Creating an Object-Relational Descriptor ........................................................................................ 24-3

Using Java......................................................................................................................................... 24-3Creating an EIS Descriptor .................................................................................................................. 24-4

Using TopLink Workbench ........................................................................................................... 24-4EIS Root Descriptors................................................................................................................ 24-5EIS Composite Descriptors ..................................................................................................... 24-5

Using Java......................................................................................................................................... 24-5Creating an XML Descriptor ............................................................................................................... 24-5

Using TopLink Workbench ........................................................................................................... 24-5Using Java......................................................................................................................................... 24-5

Validating Descriptors.......................................................................................................................... 24-6Generating Java Code for Descriptors .............................................................................................. 24-6

25 Configuring a Descriptor

Configuring Common Descriptor Options ...................................................................................... 25-1Configuring Primary Keys .................................................................................................................. 25-3

Using TopLink Workbench ........................................................................................................... 25-3Using Java......................................................................................................................................... 25-4

Relational Projects.................................................................................................................... 25-4EIS Projects................................................................................................................................ 25-5

Configuring Read-Only Descriptors ................................................................................................. 25-5Using Read-Only Entity Beans...................................................................................................... 25-5Using TopLink Workbench ........................................................................................................... 25-5Using Java......................................................................................................................................... 25-6

Configuring Unit of Work Conforming at the Descriptor Level ................................................. 25-6Using TopLink Workbench ........................................................................................................... 25-7Using Java......................................................................................................................................... 25-7

Configuring Descriptor Alias ............................................................................................................. 25-7Using TopLink Workbench ........................................................................................................... 25-8Using Java......................................................................................................................................... 25-9

Configuring Descriptor Comments ................................................................................................... 25-9Using TopLink Workbench ........................................................................................................... 25-9

Configuring Named Queries at the Descriptor Level .................................................................. 25-10Using TopLink Workbench ......................................................................................................... 25-10

Adding Named Queries........................................................................................................ 25-12Configuring Named Query Type and Parameters ........................................................... 25-13Configuring Named Query Selection Criteria................................................................... 25-14Configuring Read All Query Order .................................................................................... 25-15Configuring Named Query Optimization.......................................................................... 25-16

xix

Configuring Named Query Attributes ............................................................................... 25-17Configuring Named Query Group/Order Options ......................................................... 25-19Creating an EIS Interaction for a Named Query ............................................................... 25-20Configuring Named Query Options ................................................................................... 25-22Configuring Named Query Advanced Options................................................................ 25-24

Using Java....................................................................................................................................... 25-25Configuring Query Timeout at the Descriptor Level ................................................................... 25-26

Using TopLink Workbench ......................................................................................................... 25-26Using Java....................................................................................................................................... 25-27

Configuring Cache Refreshing ......................................................................................................... 25-27Using TopLink Workbench ......................................................................................................... 25-28Using Java....................................................................................................................................... 25-29

Configuring Query Keys.................................................................................................................... 25-30Using TopLink Workbench ......................................................................................................... 25-31Using Java....................................................................................................................................... 25-31

Configuring Interface Query Keys .................................................................................................. 25-33Using TopLink Workbench ......................................................................................................... 25-34Using Java....................................................................................................................................... 25-34

Configuring Cache Type and Size at the Descriptor Level ......................................................... 25-35Using TopLink Workbench ......................................................................................................... 25-36Using Java....................................................................................................................................... 25-37

Configuring Cache Isolation at the Descriptor Level .................................................................. 25-37Using TopLink Workbench ......................................................................................................... 25-38Using Java....................................................................................................................................... 25-38

Configuring Unit of Work Cache Isolation at the Descriptor Level.......................................... 25-38Using Java....................................................................................................................................... 25-39

Configuring Cache Coordination Change Propagation at the Descriptor Level .................... 25-40Using TopLink Workbench ......................................................................................................... 25-40Using Java....................................................................................................................................... 25-41

Configuring Cache Expiration at the Descriptor Level................................................................ 25-42Using TopLink Workbench ......................................................................................................... 25-42Using Java....................................................................................................................................... 25-43

Configuring Cache Existence Checking at the Descriptor Level ............................................... 25-43Using TopLink Workbench ......................................................................................................... 25-44Using Java....................................................................................................................................... 25-45

Configuring a Descriptor With EJB Information .......................................................................... 25-45Using TopLink Workbench ......................................................................................................... 25-46Using Java....................................................................................................................................... 25-48

Configuring CMP Information ............................................................................................ 25-48Configuring BMP Information............................................................................................. 25-49

Configuring Reading Subclasses on Queries ................................................................................ 25-49Using TopLink Workbench ......................................................................................................... 25-49Using Java....................................................................................................................................... 25-50

Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor .................................. 25-51Using TopLink Workbench ......................................................................................................... 25-51Using Java....................................................................................................................................... 25-52

Configuring Inheritance for a Parent (Root) Descriptor.............................................................. 25-52

xx

Using TopLink Workbench ......................................................................................................... 25-53Using Java....................................................................................................................................... 25-54

Configuring Inheritance Expressions for a Parent (Root) Class Descriptor ............................ 25-55Using Java....................................................................................................................................... 25-57

Configuring Inherited Attribute Mapping in a Subclass............................................................ 25-58Using TopLink Workbench ......................................................................................................... 25-58Using Java....................................................................................................................................... 25-59

Configuring a Domain Object Method as an Event Handler ..................................................... 25-59Using TopLink Workbench ......................................................................................................... 25-60Using Java....................................................................................................................................... 25-62

Configuring a Descriptor Event Listener as an Event Handler.................................................. 25-62Using Java....................................................................................................................................... 25-64

Configuring Locking Policy .............................................................................................................. 25-64Using TopLink Workbench ......................................................................................................... 25-65Using Java....................................................................................................................................... 25-67

Configuring an Optimistic Locking Policy ........................................................................ 25-67Configuring Optimistic Locking Policy Cascading .......................................................... 25-67Configuring a Pessimistic Locking Policy.......................................................................... 25-67

Configuring Returning Policy .......................................................................................................... 25-67Using TopLink Workbench ......................................................................................................... 25-68Using Java....................................................................................................................................... 25-69

Configuring Instantiation Policy ..................................................................................................... 25-70Using TopLink Workbench ......................................................................................................... 25-70Using Java....................................................................................................................................... 25-71

Configuring Copy Policy ................................................................................................................... 25-71Using TopLink Workbench ......................................................................................................... 25-72Using Java....................................................................................................................................... 25-72

Configuring Change Policy ............................................................................................................... 25-73Using Java....................................................................................................................................... 25-73

Configuring Deferred Change Detection Policy ............................................................... 25-73Configuring Object Change Tracking Policy ..................................................................... 25-73Configuring Attribute Change Tracking Policy ................................................................ 25-75

Configuring a History Policy ............................................................................................................ 25-76Using Java....................................................................................................................................... 25-77

Configuring Write Responsibility ....................................................................................... 25-77Configuring Wrapper Policy ............................................................................................................. 25-78

Using Java....................................................................................................................................... 25-79Configuring Fetch Groups................................................................................................................. 25-79

Using Java....................................................................................................................................... 25-80Configuring Amendment Methods ................................................................................................. 25-81

Using TopLink Workbench ......................................................................................................... 25-81

26 Configuring a Relational Descriptor

Relational Descriptor Configuration Overview.............................................................................. 26-1Configuring Associated Tables........................................................................................................... 26-2

Using TopLink Workbench ........................................................................................................... 26-2Using Java......................................................................................................................................... 26-3

xxi

Configuring Sequencing at the Descriptor Level ........................................................................... 26-3Using TopLink Workbench ........................................................................................................... 26-4Using Java......................................................................................................................................... 26-5

Configuring a Sequence by Name......................................................................................... 26-5Configuring the Same Sequence for Multiple Descriptors ................................................ 26-5Configuring the Platform Default Sequence........................................................................ 26-6

Configuring Custom SQL Queries for Basic Persistence Operations......................................... 26-6Using TopLink Workbench ........................................................................................................... 26-7Using Java......................................................................................................................................... 26-8

Configuring Interface Alias .............................................................................................................. 26-10Using TopLink Workbench ......................................................................................................... 26-11Using Java....................................................................................................................................... 26-11

Configuring a Relational Descriptor as a Class or Aggregate Type .......................................... 26-11Using TopLink Workbench ......................................................................................................... 26-12Using Java....................................................................................................................................... 26-12

Configuring Multitable Information .............................................................................................. 26-13Using TopLink Workbench ......................................................................................................... 26-13Using Java....................................................................................................................................... 26-14

27 Configuring an Object-Relational Descriptor

Object-Relational Descriptor Configuration Overview ................................................................ 27-1Configuring Field Ordering ................................................................................................................ 27-2

Using Java......................................................................................................................................... 27-2

28 Configuring an EIS Descriptor

EIS Descriptor Configuration Overview .......................................................................................... 28-1Configuring Schema Context for an EIS Descriptor ...................................................................... 28-2

Using TopLink Workbench ........................................................................................................... 28-2Choosing a Schema Context ................................................................................................... 28-3

Using Java......................................................................................................................................... 28-3Configuring Default Root Element ................................................................................................... 28-3

Using TopLink Workbench ........................................................................................................... 28-4Choosing a Root Element........................................................................................................ 28-4

Using Java......................................................................................................................................... 28-5Configuring Record Format ................................................................................................................ 28-5

Using Java......................................................................................................................................... 28-6Configuring Custom EIS Interactions for Basic Persistence Operations ................................... 28-6

Using TopLink Workbench ........................................................................................................... 28-6Using Java......................................................................................................................................... 28-8

Configuring an EIS Descriptor as a Root or Composite Type ...................................................... 28-8Using TopLink Workbench ........................................................................................................... 28-9Using Java......................................................................................................................................... 28-9

29 Configuring an XML Descriptor

XML Descriptor Configuration Overview ....................................................................................... 29-1Configuring Schema Context for an XML Descriptor.................................................................... 29-1

xxii

Using TopLink Workbench ........................................................................................................... 29-2Choosing a Schema Context ................................................................................................... 29-2

Using Java......................................................................................................................................... 29-3Configuring for Complex Type of anyType ..................................................................................... 29-3

Using TopLink Workbench ........................................................................................................... 29-4Configuring Default Root Element ................................................................................................... 29-5

Using TopLink Workbench ........................................................................................................... 29-5Choosing a Root Element........................................................................................................ 29-5

Configuring Document Preservation ................................................................................................ 29-6Using TopLink Workbench ........................................................................................................... 29-6Using Java......................................................................................................................................... 29-6

Part IX Mappings

30 Understanding Mappings

Mapping Types ...................................................................................................................................... 30-1Mapping Concepts ................................................................................................................................ 30-2

Mapping Architecture .................................................................................................................... 30-2Example Mapping........................................................................................................................... 30-3Automatic Mappings...................................................................................................................... 30-4

Automapping With TopLink Workbench at Development Time .................................... 30-4Default Mapping in CMP Projects Using OC4J at Run Time ............................................ 30-4JAXB Project Generation at Development Time.................................................................. 30-5

Indirection ........................................................................................................................................ 30-5Value Holder Indirection ........................................................................................................ 30-7Transparent Indirect Container Indirection......................................................................... 30-8Proxy Indirection ..................................................................................................................... 30-8Indirection and EJB.................................................................................................................. 30-9Indirection, Serialization, and Detachment.......................................................................... 30-9

Method Accessors and Attribute Accessors.............................................................................. 30-10Mapping Converters and Transformers .................................................................................... 30-10

Serialized Object Converter.................................................................................................. 30-10Type Conversion Converter ................................................................................................. 30-11Object Type Converter .......................................................................................................... 30-12Simple Type Translator ......................................................................................................... 30-12Transformation Mappings.................................................................................................... 30-14

Mappings and XPath .................................................................................................................... 30-15XPath by Position................................................................................................................... 30-15XPath by Path and Name...................................................................................................... 30-15XPath by Name....................................................................................................................... 30-16Self XPath ................................................................................................................................ 30-16

Mappings and xsd:list and xsd:union Types ............................................................................ 30-17Mapping an xsd:union Type ................................................................................................ 30-17Mapping an xsd:list Type ..................................................................................................... 30-18Mapping a List of Unions ..................................................................................................... 30-18Mapping a Union of Lists ..................................................................................................... 30-19Mapping a Union of Unions................................................................................................. 30-19

xxiii

Mappings and the jaxb:class Customization............................................................................. 30-20all, choice, or sequence Structure......................................................................................... 30-20group Structure ...................................................................................................................... 30-21sequence or choice Structure Containing a group ............................................................ 30-21group Structure Containing a sequence or choice ............................................................ 30-22group Structure Containing a group................................................................................... 30-23Limitations of jaxb:class Customization Support.............................................................. 30-23

Mappings and JAXB Typesafe Enumerations........................................................................... 30-24Understanding the Mapping API..................................................................................................... 30-25Relational Mappings .......................................................................................................................... 30-25Object-Relational Mappings............................................................................................................. 30-26XML Mappings .................................................................................................................................... 30-27EIS Mappings....................................................................................................................................... 30-27

31 Creating a Mapping

Mapping Creation Overview .............................................................................................................. 31-1Creating Mappings Manually During Development .................................................................... 31-1

Using TopLink Workbench ........................................................................................................... 31-1Creating Mappings Automatically During Development ............................................................ 31-2

Using TopLink Workbench ........................................................................................................... 31-2Creating Mappings Automatically During Deployment .............................................................. 31-2Creating Mappings to Oracle LOB Database Objects.................................................................... 31-2

Using the Oracle JDBC OCI Driver or Server Driver................................................................. 31-3Using the Oracle JDBC Thin Driver ............................................................................................. 31-5

Removing Mappings ............................................................................................................................ 31-6Using TopLink Workbench ........................................................................................................... 31-6

32 Configuring a Mapping

Configuring Common Mapping Options......................................................................................... 32-1Configuring Read-Only Mappings.................................................................................................... 32-2

Using TopLink Workbench ........................................................................................................... 32-3Using Java......................................................................................................................................... 32-3

Configuring Indirection....................................................................................................................... 32-3Using TopLink Workbench ........................................................................................................... 32-4Using Java......................................................................................................................................... 32-5

Configuring ValueHolder Indirection ................................................................................. 32-6Configuring ValueHolder Indirection With Method Accessing....................................... 32-7Configuring ValueHolder Indirection With EJB 3.0 on OC4J ........................................... 32-8Configuring IndirectContainer Indirection ......................................................................... 32-8Configuring Proxy Indirection............................................................................................... 32-9

Configuring XPath .............................................................................................................................. 32-10Using TopLink Workbench ......................................................................................................... 32-11

Choosing the XPath ............................................................................................................... 32-12Configuring a Default Null Value at the Mapping Level ........................................................... 32-12

Using TopLink Workbench ......................................................................................................... 32-13Using Java....................................................................................................................................... 32-13

xxiv

Configuring Method Accessing........................................................................................................ 32-14Using TopLink Workbench ......................................................................................................... 32-14Using Java....................................................................................................................................... 32-15

Configuring Private or Independent Relationships..................................................................... 32-16Using TopLink Workbench ......................................................................................................... 32-17Using Java....................................................................................................................................... 32-17

Configuring Mapping Comments.................................................................................................... 32-18Using TopLink Workbench ......................................................................................................... 32-18

Configuring a Serialized Object Converter ................................................................................... 32-18Using TopLink Workbench ......................................................................................................... 32-19Using Java....................................................................................................................................... 32-19

Configuring a Type Conversion Converter .................................................................................... 32-20Using TopLink Workbench ......................................................................................................... 32-20Using Java....................................................................................................................................... 32-21

Configuring an Object Type Converter .......................................................................................... 32-22Using TopLink Workbench ......................................................................................................... 32-22Using Java....................................................................................................................................... 32-23

Configuring a Simple Type Translator............................................................................................ 32-23Using TopLink Workbench ......................................................................................................... 32-24Using Java....................................................................................................................................... 32-24

Configuring a JAXB Typesafe Enumeration Converter ............................................................... 32-25Using Java....................................................................................................................................... 32-26

Configuring Container Policy........................................................................................................... 32-26Using TopLink Workbench ......................................................................................................... 32-27Using Java....................................................................................................................................... 32-28

Configuring Attribute Transformer ................................................................................................. 32-29Using TopLink Workbench ......................................................................................................... 32-30Using Java....................................................................................................................................... 32-31

Configuring Field Transformer Associations ................................................................................ 32-31Using TopLink Workbench ......................................................................................................... 32-32

Specifying Field-to-Transformer Associations .................................................................. 32-32Using Java....................................................................................................................................... 32-33

Configuring Mutable Mappings ...................................................................................................... 32-33Using TopLink Workbench ......................................................................................................... 32-34Using Java....................................................................................................................................... 32-34

Configuring Bidirectional Relationship ......................................................................................... 32-34Using TopLink Workbench ......................................................................................................... 32-35

Configuring the Use of a Single Node ............................................................................................ 32-36Using TopLink Workbench ......................................................................................................... 32-36Using Java....................................................................................................................................... 32-37

Part X Relational Mappings

33 Understanding Relational Mappings

Relational Mapping Types .................................................................................................................. 33-1Relational Mapping Concepts ............................................................................................................ 33-2

Directionality ................................................................................................................................... 33-2

xxv

Converters and Transformers ....................................................................................................... 33-3Using a Direct Mapping.......................................................................................................... 33-3Using a Converter Mapping................................................................................................... 33-3Using a Transformation Mapping ......................................................................................... 33-3

Relational Mappings and EJB........................................................................................................ 33-3Direct-to-Field Mapping ...................................................................................................................... 33-4Direct-to-XMLType Mapping.............................................................................................................. 33-4One-to-One Mapping ........................................................................................................................... 33-5

One-to-One Mappings and EJB..................................................................................................... 33-6Variable One-to-One Mapping ........................................................................................................... 33-6One-to-Many Mapping ........................................................................................................................ 33-7

One-to-Many Mappings and EJB.................................................................................................. 33-8Many-to-Many Mapping ..................................................................................................................... 33-8

Many-to-Many Mappings and EJB............................................................................................... 33-9Aggregate Collection Mapping ........................................................................................................ 33-10

Aggregate Collection Mappings and Inheritance .................................................................... 33-10Aggregate Collection Mappings and EJB .................................................................................. 33-11Implementing Aggregate Collection Mappings ....................................................................... 33-11

Direct Collection Mapping................................................................................................................ 33-11Direct Map Mapping .......................................................................................................................... 33-12Aggregate Object Mapping ............................................................................................................... 33-12

Aggregate Object Mappings with a Single Source Object....................................................... 33-13Aggregate Object Mappings With Multiple Source Objects................................................... 33-14Implementing an Aggregate Object Relationship Mapping................................................... 33-14

Transformation Mapping................................................................................................................... 33-15

34 Configuring a Relational Mapping

Configuring Common Relational Mapping Options..................................................................... 34-1Configuring a Database Field ............................................................................................................. 34-2

Using TopLink Workbench ........................................................................................................... 34-4Configuring Reference Descriptor..................................................................................................... 34-5

Using TopLink Workbench ........................................................................................................... 34-5Configuring Batch Reading................................................................................................................. 34-6

Using TopLink Workbench ........................................................................................................... 34-7Using Java......................................................................................................................................... 34-7

Configuring Query Key Order ........................................................................................................... 34-8Using TopLink Workbench ........................................................................................................... 34-8

Configuring Table and Field References (Foreign and Target Foreign Keys) ........................... 34-8Using TopLink Workbench ........................................................................................................... 34-9

35 Configuring a Relational Direct-to-Field Mapping

Relational Direct-to-Field Mapping Configuration Overview .................................................... 35-1

36 Configuring a Relational Direct-to-XMLType Mapping

Relational Direct-to-XMLType Mapping Overview....................................................................... 36-1Configuring Read Whole Document................................................................................................. 36-1

xxvi

Using TopLink Workbench ........................................................................................................... 36-1

37 Configuring a Relational One-to-One Mapping

Relational One-to-One Mapping Configuration Overview ......................................................... 37-1Configuring Joining at the Mapping Level...................................................................................... 37-1

Using TopLink Workbench ........................................................................................................... 37-2

38 Configuring a Relational Variable One-to-One Mapping

Relational Variable One-to-One Mapping Configuration Overview ......................................... 38-1Configuring Class Indicator ................................................................................................................ 38-1

Using TopLink Workbench ........................................................................................................... 38-2Configuring Unique Primary Key ..................................................................................................... 38-3

Understanding Unique Primary Key ........................................................................................... 38-3Using TopLink Workbench ........................................................................................................... 38-3Using Java......................................................................................................................................... 38-4

Configuring Query Key Association ................................................................................................. 38-4Using TopLink Workbench ........................................................................................................... 38-4

39 Configuring a Relational One-to-Many Mapping

Relational One-to-Many Mapping Configuration Overview ...................................................... 39-1

40 Configuring a Relational Many-to-Many Mapping

Relational Many-to-Many Mapping Configuration Overview.................................................... 40-1Configuring a Relation Table.............................................................................................................. 40-1

Using TopLink Workbench ........................................................................................................... 40-2

41 Configuring a Relational Aggregate Collection Mapping

Relational Aggregate Collection Mapping Configuration Overview......................................... 41-1

42 Configuring a Relational Direct Collection Mapping

Relational Direct Collection Mapping Configuration Overview ................................................ 42-1Configuring Target Table ..................................................................................................................... 42-1

Using TopLink Workbench ........................................................................................................... 42-2Configuring Direct Value Field .......................................................................................................... 42-2

Using TopLink Workbench ........................................................................................................... 42-2

43 Configuring a Relational Aggregate Object Mapping

Relational Aggregate Object Mapping Configuration Overview ............................................... 43-1Configuring Aggregate Fields ............................................................................................................ 43-1

Using TopLink Workbench ........................................................................................................... 43-2Configuring Allowing Null Values ................................................................................................... 43-2

Using TopLink Workbench ........................................................................................................... 43-2

xxvii

44 Configuring a Relational Direct Map Mapping

Relational Direct Map Mapping Configuration Overview .......................................................... 44-1Configuring Direct Value Field .......................................................................................................... 44-1

Using TopLink Workbench ........................................................................................................... 44-1Configuring Direct Key Field ............................................................................................................. 44-2

Using TopLink Workbench ........................................................................................................... 44-2Configuring Key Converters ............................................................................................................... 44-3

Using TopLink Workbench ........................................................................................................... 44-3Configuring Value Converters............................................................................................................ 44-4

Using TopLink Workbench ........................................................................................................... 44-4

45 Configuring a Relational Transformation Mapping

Relational Transformation Mapping Configuration Overview ................................................... 45-1

Part XI Object-Relational Mappings

46 Understanding Object-Relational Mappings

Object-Relational Mapping Types ..................................................................................................... 46-1Object-Relational Structure Mapping............................................................................................... 46-2Object-Relational Reference Mapping ............................................................................................. 46-2Object-Relational Array Mapping ..................................................................................................... 46-2Object-Relational Object Array Mapping ........................................................................................ 46-2Object-Relational Nested Table Mapping........................................................................................ 46-3

47 Configuring an Object-Relational Mapping

Configuring Common Object-Relational Mapping Options ....................................................... 47-1Configuring Reference Class .............................................................................................................. 47-2

Using Java......................................................................................................................................... 47-2Configuring Attribute Name .............................................................................................................. 47-2

Using Java......................................................................................................................................... 47-3Configuring Field Name ...................................................................................................................... 47-3

Using Java......................................................................................................................................... 47-3Configuring Structure Name .............................................................................................................. 47-4

Using Java......................................................................................................................................... 47-4

48 Configuring an Object-Relational Structure Mapping

Object-Relational Structure Mapping Configuration Overview................................................. 48-1

49 Configuring an Object-Relational Reference Mapping

Object-Relational Reference Mapping Configuration Overview ............................................... 49-1

50 Configuring an Object-Relational Array Mapping

Object-Relational Array Mapping Configuration Overview ....................................................... 50-1

xxviii

51 Configuring an Object-Relational Object Array Mapping

Object-Relational Object Array Mapping Configuration Overview .......................................... 51-1

52 Configuring an Object-Relational Nested Table Mapping

Object-Relational Nested Table Mapping Configuration Overview.......................................... 52-1

Part XII EIS Mappings

53 Understanding EIS Mappings

EIS Mapping Types............................................................................................................................... 53-1EIS Mapping Concepts......................................................................................................................... 53-2

EIS Record Type .............................................................................................................................. 53-2Indexed Records....................................................................................................................... 53-2Mapped Records ...................................................................................................................... 53-3XML Records ............................................................................................................................ 53-3

XPath Support.................................................................................................................................. 53-3xsd:list and xsd:union Support ..................................................................................................... 53-3jaxb:class Support............................................................................................................................ 53-3Typesafe Enumeration Support .................................................................................................... 53-3Composite and Reference EIS Mappings .................................................................................... 53-4

Composite EIS Mappings ....................................................................................................... 53-4Reference EIS Mappings ......................................................................................................... 53-4

EIS Mapping Architecture ............................................................................................................. 53-5EIS Direct Mapping .............................................................................................................................. 53-5EIS Composite Direct Collection Mapping...................................................................................... 53-6EIS Composite Object Mapping......................................................................................................... 53-7EIS Composite Collection Mapping .................................................................................................. 53-7EIS One-to-One Mapping.................................................................................................................... 53-8

EIS One-to-One Mappings With Key on Source......................................................................... 53-9EIS One-to-One Mappings With Key on Target ....................................................................... 53-10

EIS One-to-Many Mapping ............................................................................................................... 53-12EIS One-to-Many Mappings With Key on Source.................................................................... 53-13EIS One-to-Many Mappings With Key on Target .................................................................... 53-15

EIS Transformation Mapping ........................................................................................................... 53-17

54 Configuring an EIS Mapping

Configuring Common EIS Mapping Options ................................................................................. 54-1Configuring Reference Descriptors ................................................................................................... 54-2

Using TopLink Workbench ........................................................................................................... 54-2Configuring Selection Interaction ..................................................................................................... 54-3

Using TopLink Workbench ........................................................................................................... 54-4

55 Configuring an EIS Direct Mapping

EIS Direct Mapping Configuration Overview ................................................................................ 55-1

xxix

56 Configuring an EIS Composite Direct Collection Mapping

EIS Composite Direct Collection Mapping Configuration Overview........................................ 56-1

57 Configuring an EIS Composite Object Mapping

EIS Composite Object Mapping Configuration Overview........................................................... 57-1

58 Configuring an EIS Composite Collection Mapping

EIS Composite Collection Mapping Configuration Overview .................................................... 58-1

59 Configuring an EIS One-to-One Mapping

EIS One-to-One Mapping Configuration Overview...................................................................... 59-1Configuring Foreign Key Pairs........................................................................................................... 59-1

Using TopLink Workbench ........................................................................................................... 59-2

60 Configuring an EIS One-to-Many Mapping

EIS One-to-Many Mapping Configuration Overview ................................................................... 60-1Configuring Foreign Key Pairs........................................................................................................... 60-1

Using TopLink Workbench ........................................................................................................... 60-2Configuring Delete All Interactions.................................................................................................. 60-3

Using TopLink Workbench ........................................................................................................... 60-4

61 Configuring an EIS Transformation Mapping

EIS Transformation Mapping Configuration Overview ............................................................... 61-1

Part XIII XML Mappings

62 Understanding XML Mappings

XML Mapping Types ............................................................................................................................ 62-1XML Mapping Concepts ...................................................................................................................... 62-2

Mapping to Simple and Complex Types ..................................................................................... 62-2Mapping Order................................................................................................................................ 62-3XPath Support.................................................................................................................................. 62-3xsd:list and xsd:union Support ..................................................................................................... 62-3xs:any and xs:anyType Support.................................................................................................... 62-4jaxb:class Support............................................................................................................................ 62-4Typesafe Enumeration Support .................................................................................................... 62-4Mapping Extensions ....................................................................................................................... 62-4

XML Direct Mapping............................................................................................................................ 62-5Mapping to a Text Node ................................................................................................................ 62-5

Mapping to a Simple Text Node............................................................................................ 62-5Mapping to a Text Node in a Simple Sequence................................................................... 62-6Mapping to a Text Node in a Subelement............................................................................ 62-6Mapping to a Text Node by Position .................................................................................... 62-7

Mapping to an Attribute ................................................................................................................ 62-8

xxx

Mapping to a Specified Schema Type .......................................................................................... 62-9Mapping to a List Field With an XML Direct Mapping .......................................................... 62-10Mapping to a Union Field With an XML Direct Mapping...................................................... 62-10Mapping to a Union of Lists With an XML Direct Mapping.................................................. 62-12Mapping to a Union of Unions With an XML Direct Mapping ............................................. 62-12Mapping With a Simple Type Translator .................................................................................. 62-13

XML Composite Direct Collection Mapping ................................................................................. 62-14Mapping to Multiple Text Nodes ............................................................................................... 62-15

Mapping to a Simple Sequence............................................................................................ 62-15Mapping to a Sequence in a Subelement............................................................................ 62-15

Mapping to Multiple Attributes.................................................................................................. 62-16Mapping to a Single Text Node With an XML Composite Direct Collection Mapping ..... 62-17Mapping to a Single Attribute With an XML Composite Direct Collection Mapping ....... 62-18Mapping to a List of Unions With an XML Composite Direct Collection Mapping........... 62-18Mapping to a Union of Lists With an XML Composite Direct Collection Mapping........... 62-19Specifying the Content Type of a Collection With an XML Composite Direct Collection Mapping 62-20

XML Composite Object Mapping .................................................................................................... 62-21Mapping Into the Parent Record................................................................................................. 62-21Mapping to an Element ................................................................................................................ 62-22Mapping to Different Elements by Element Name.................................................................. 62-23Mapping to Different Elements by Element Position .............................................................. 62-24

XML Composite Collection Mapping ............................................................................................. 62-25XML Any Object Mapping ................................................................................................................ 62-27XML Any Collection Mapping ......................................................................................................... 62-29XML Transformation Mapping......................................................................................................... 62-31

63 Configuring an XML Mapping

Configuring Common XML Mapping Options .............................................................................. 63-1Configuring Reference Descriptor..................................................................................................... 63-2

Using TopLink Workbench ........................................................................................................... 63-2Configuring Maps to Wildcard........................................................................................................... 63-3

Using TopLink Workbench ........................................................................................................... 63-3

64 Configuring an XML Direct Mapping

XML Direct Mapping Configuration Overview.............................................................................. 64-1

65 Configuring an XML Composite Direct Collection Mapping

XML Composite Direct Collection Mapping Configuration Overview ..................................... 65-1

66 Configuring an XML Composite Object Mapping

XML Composite Object Mapping Configuration Overview ........................................................ 66-1

67 Configuring an XML Composite Collection Mapping

XML Composite Collection Mapping Configuration Overview ................................................. 67-1

xxxi

68 Configuring an XML Any Object Mapping

XML Any Object Mapping Configuration Overview .................................................................... 68-1

69 Configuring an XML Any Collection Mapping

XML Any Collection Mapping Configuration Overview ............................................................. 69-1

70 Configuring an XML Transformation Mapping

XML Transformation Mapping Configuration Overview............................................................. 70-1

Part XIV Using TopLink Overview

71 Understanding the Persistence Layer

Overview of the Persistence Layer..................................................................................................... 71-1Sessions ................................................................................................................................................... 71-1Data Access ............................................................................................................................................. 71-1Cache........................................................................................................................................................ 71-2Queries and Expressions...................................................................................................................... 71-2Transactions ............................................................................................................................................ 71-3

Part XV TopLink Sessions

72 Understanding TopLink Sessions

Session Types ......................................................................................................................................... 72-1Session Concepts ................................................................................................................................... 72-2

Session Architecture ....................................................................................................................... 72-2Object Cache ............................................................................................................................. 72-3Connection Pools ..................................................................................................................... 72-3Query Mechanism.................................................................................................................... 72-4Java Object Builder .................................................................................................................. 72-4

Session Configuration and the sessions.xml File........................................................................ 72-4Session Customization ................................................................................................................... 72-4Acquiring a Session at Run Time With the Session Manager................................................... 72-5Managing Session Events With the Session Event Manager .................................................... 72-5

Session Event Manager Events .............................................................................................. 72-6Session Event Listeners ........................................................................................................... 72-7

Logging............................................................................................................................................. 72-7Log Types .................................................................................................................................. 72-8Log Output.............................................................................................................................. 72-10Log Level ................................................................................................................................. 72-10Logging SQL........................................................................................................................... 72-10Logging Chained Exceptions ............................................................................................... 72-11Viewing TopLink Log Messages From the Application Server Control Console ........ 72-11

Profiler ............................................................................................................................................ 72-11TopLink Profiler ..................................................................................................................... 72-12Oracle Dynamic Monitoring System (DMS) ...................................................................... 72-12

xxxii

Integrity Checker........................................................................................................................... 72-12Exception Handlers....................................................................................................................... 72-12Registering Descriptors ................................................................................................................ 72-13Sessions and CMP ......................................................................................................................... 72-13Sessions and Sequencing.............................................................................................................. 72-13

Server and Client Sessions ................................................................................................................ 72-14Three-Tier Architecture Overview ............................................................................................. 72-14Advantages of the TopLink Three-Tier Architecture .............................................................. 72-15

Shared Resources ................................................................................................................... 72-15Providing Read Access.......................................................................................................... 72-16Providing Write Access......................................................................................................... 72-17Security and User Privileges ................................................................................................ 72-18Concurrency............................................................................................................................ 72-18Connection Allocation........................................................................................................... 72-18

Unit of Work Sessions ........................................................................................................................ 72-19Isolated Client Sessions ..................................................................................................................... 72-19

Isolated Client Sessions and Oracle Virtual Private Database (VPD) ................................... 72-21VPD With Oracle Database Proxy Authentication ........................................................... 72-22VPD Without Oracle Database Proxy Authentication ..................................................... 72-22Isolated Client Session Life Cycle........................................................................................ 72-22

Isolated Client Session Limitations............................................................................................. 72-24Historical Sessions .............................................................................................................................. 72-25

Historical Session Limitations ..................................................................................................... 72-25Session Broker and Client Sessions ................................................................................................ 72-26

Session Broker Architecture ........................................................................................................ 72-26Committing a Transaction with a Session Broker .................................................................... 72-27

Committing a Session with a JTA Driver: Two-Phase Commits .................................... 72-27Committing a Session Without a JTA Driver: Two-Stage Commits............................... 72-27

Session Broker Session Limitations ............................................................................................ 72-28Many-to-Many Join Tables and Direct Collection Tables ................................................ 72-28

Session Broker Alternatives ......................................................................................................... 72-28Database Linking ................................................................................................................... 72-28Multiple Sessions .................................................................................................................. 72-28

Database Sessions ............................................................................................................................... 72-29Remote Sessions .................................................................................................................................. 72-30

Architectural Overview................................................................................................................ 72-30Application Layer .................................................................................................................. 72-31Transport Layer...................................................................................................................... 72-31Server Layer ............................................................................................................................ 72-31

Remote Session Concepts............................................................................................................. 72-31Securing Remote Session Access ......................................................................................... 72-32Queries..................................................................................................................................... 72-32Refreshing ............................................................................................................................... 72-32Indirection ............................................................................................................................... 72-32Cursored Streams................................................................................................................... 72-32Unit of Work ........................................................................................................................... 72-32

Sessions and the Cache ...................................................................................................................... 72-33

xxxiii

Server and Database Session Cache ........................................................................................... 72-33Isolated Session Cache.................................................................................................................. 72-33Historical Session Cache .............................................................................................................. 72-33

Understanding the Session API ....................................................................................................... 72-33

73 Creating Sessions

Session Creation Overview ................................................................................................................. 73-1Creating a Sessions Configuration .................................................................................................... 73-1

Using TopLink Workbench ........................................................................................................... 73-2Configuring a Sessions Configuration ............................................................................................. 73-2

Using TopLink Workbench ........................................................................................................... 73-2Creating a Server Session .................................................................................................................... 73-4

Using TopLink Workbench ........................................................................................................... 73-4Using Java......................................................................................................................................... 73-5

Creating Session Broker and Client Sessions.................................................................................. 73-6Using TopLink Workbench ........................................................................................................... 73-6Using Java......................................................................................................................................... 73-8

Creating Database Sessions ................................................................................................................ 73-8Using TopLink Workbench ........................................................................................................... 73-8Using Java....................................................................................................................................... 73-10

Creating Remote Sessions ................................................................................................................. 73-10Using Java....................................................................................................................................... 73-10

Server ....................................................................................................................................... 73-11Client........................................................................................................................................ 73-11

74 Configuring a Session

Configuring Common Session Options ........................................................................................... 74-1Configuring a Primary Mapping Project .......................................................................................... 74-2

Using TopLink Workbench ........................................................................................................... 74-3Using Java......................................................................................................................................... 74-3

Configuring a Session Login............................................................................................................... 74-4Configuring Logging ............................................................................................................................ 74-4

Using TopLink Workbench ........................................................................................................... 74-5Using Java......................................................................................................................................... 74-7

Using Session Logging API .................................................................................................... 74-7Configuring a Session to use java.util.logging Package..................................................... 74-8Configuring Logging in a CMP Application ....................................................................... 74-9

Configuring Multiple Mapping Projects.......................................................................................... 74-9Using TopLink Workbench ........................................................................................................... 74-9Using Java....................................................................................................................................... 74-10

Configuring a Performance Profiler ................................................................................................ 74-10Using TopLink Workbench ......................................................................................................... 74-11Using Java....................................................................................................................................... 74-12

Configuring an Exception Handler.................................................................................................. 74-12Using TopLink Workbench ......................................................................................................... 74-12Using Java....................................................................................................................................... 74-12

xxxiv

Configuring Customizer Class ......................................................................................................... 74-13Using TopLink Workbench ......................................................................................................... 74-14

Configuring the Server Platform...................................................................................................... 74-14Using TopLink Workbench ......................................................................................................... 74-15Using Java....................................................................................................................................... 74-17

Configuring Session Event Listeners .............................................................................................. 74-17Using TopLink Workbench ......................................................................................................... 74-17Using Java....................................................................................................................................... 74-18

Configuring the Integrity Checker .................................................................................................. 74-18Using Java....................................................................................................................................... 74-19

Configuring Connection Policy........................................................................................................ 74-19Using TopLink Workbench ......................................................................................................... 74-20Using Java....................................................................................................................................... 74-21

Configuring Named Queries at the Session Level ....................................................................... 74-21Using Java....................................................................................................................................... 74-22

75 Acquiring and Using Sessions at Run Time

Session Acquisition Overview ........................................................................................................... 75-1Understanding the Session Manager ........................................................................................... 75-2Multiple Sessions............................................................................................................................. 75-2

Acquiring the Session Manager ......................................................................................................... 75-2Acquiring a Session From the Session Manager............................................................................. 75-3

Loading a Session From sessions.xml Using Defaults............................................................... 75-3Loading a Session From sessions.xml With an Alternative Class Loader .............................. 75-4Loading a Session From an Alternative Session Configuration File ....................................... 75-4Loading a Session Without Logging In........................................................................................ 75-5Reloading and Refreshing Session Configuration...................................................................... 75-5Refreshing a Session When the Class Loader Changes ............................................................. 75-6

Acquiring a Client Session .................................................................................................................. 75-6Acquiring an Isolated Client Session ........................................................................................... 75-7Acquiring a Client Session That Uses Exclusive Connections ................................................. 75-7Acquiring a Client Session That Uses Connection Properties.................................................. 75-8Acquiring a Client Session That Uses a Named Connection Pool........................................... 75-8Acquiring a Client Session That Does Not Use Lazy Connection Allocation ........................ 75-9

Acquiring a Historical Session ........................................................................................................... 75-9Logging In to a Session ...................................................................................................................... 75-10Using Session API ............................................................................................................................... 75-10Logging Out of a Session ................................................................................................................... 75-10Storing Sessions in the Session Manager Instance ...................................................................... 75-10Destroying Sessions in the Session Manager Instance................................................................ 75-11

76 Configuring Server Sessions

Server Session Configuration Overview .......................................................................................... 76-1Configuring Internal Connection Pools ........................................................................................... 76-1Configuring External Connection Pools ........................................................................................... 76-2

xxxv

77 Configuring Exclusive Isolated Client Sessions for Virtual Private Database

Exclusive Isolated Client Session Configuration Overview......................................................... 77-1PostAcquireExclusiveConnection Event Handler .......................................................................... 77-1

Using Java......................................................................................................................................... 77-2PreReleaseExclusiveConnection Event Handler ............................................................................. 77-2

Using Java......................................................................................................................................... 77-2NoRowsModifiedSessionEvent Event Handler.............................................................................. 77-3

Using Java......................................................................................................................................... 77-3ValidationException Handler.............................................................................................................. 77-3

78 Configuring Historical Sessions

Historical Session Configuration Overview .................................................................................... 78-1Configuring Historical Sessions Using an Oracle Platform...................................................... 78-1Configuring Historical Sessions Using a TopLink HistoryPolicy............................................ 78-1

79 Configuring Session Broker and Client Sessions

Session Broker and Client Session Configuration Overview ...................................................... 79-1Removing, Renaming, or Adding Sessions ..................................................................................... 79-1

Using TopLink Workbench ........................................................................................................... 79-2

80 Configuring Database Sessions

Database Session Configuration Overview ..................................................................................... 80-1Configuring External Connection Pools ........................................................................................... 80-1

Part XVI Data Access

81 Understanding Data Access

Data Access Concepts ........................................................................................................................... 81-1Externally Managed Transactional Data Sources....................................................................... 81-1Data Source Login Types ............................................................................................................... 81-2

DatabaseLogin.......................................................................................................................... 81-2EISLogin .................................................................................................................................... 81-3

Data Source Platform Types .......................................................................................................... 81-3Database Platforms .................................................................................................................. 81-3EIS Platforms ............................................................................................................................ 81-4

Authentication ................................................................................................................................. 81-5Simple JDBC Authentication.................................................................................................. 81-5Oracle Database Proxy Authentication................................................................................. 81-5Auditing .................................................................................................................................... 81-6

Connections...................................................................................................................................... 81-6Connection Pools............................................................................................................................. 81-7

Internal Connection Pools....................................................................................................... 81-7External Connection Pools...................................................................................................... 81-8Default (Write) and Read Connection Pools........................................................................ 81-8Sequence Connection Pools.................................................................................................... 81-8

xxxvi

Application-Specific Connection Pools................................................................................. 81-9Understanding Data Access API ........................................................................................................ 81-9

Login Inheritance Hierarchy ....................................................................................................... 81-10Platform Inheritance Hierarchy .................................................................................................. 81-10

82 Configuring a Data Source Login

Configuring Common Data Source Login Options........................................................................ 82-1Configuring User Name and Password ............................................................................................ 82-1

Using TopLink Workbench ........................................................................................................... 82-2Configuring Password Encryption .................................................................................................... 82-2

Using Java......................................................................................................................................... 82-2Configuring External Connection Pooling....................................................................................... 82-2

Using TopLink Workbench ........................................................................................................... 82-3Configuring Properties......................................................................................................................... 82-4

Using TopLink Workbench ........................................................................................................... 82-4Using Java......................................................................................................................................... 82-5

Configuring a Default Null Value at the Login Level.................................................................... 82-5Using Java......................................................................................................................................... 82-6

83 Configuring a Database Login

Database Login Configuration Overview ........................................................................................ 83-1Configuring a Relational Database Platform at the Session Level ............................................. 83-1

Using TopLink Workbench ........................................................................................................... 83-1Configuring Database Login Connection Options......................................................................... 83-2

Using TopLink Workbench ........................................................................................................... 83-2Configuring Sequencing at the Session Level................................................................................. 83-4

Using TopLink Workbench ........................................................................................................... 83-5Using Java......................................................................................................................................... 83-5

Using the Platform Default Sequence ................................................................................... 83-6Configuring Multiple Sequences ........................................................................................... 83-6Configuring Query Sequencing ............................................................................................. 83-7

Configuring a Table Qualifier ............................................................................................................ 83-8Using TopLink Workbench ........................................................................................................... 83-8

Configuring JDBC Options ................................................................................................................. 83-9Using TopLink Workbench ........................................................................................................... 83-9Using Java....................................................................................................................................... 83-11

Configuring Advanced Options ....................................................................................................... 83-11Using TopLink Workbench ......................................................................................................... 83-11

Configuring Oracle Database Proxy Authentication ................................................................... 83-12Using Java....................................................................................................................................... 83-13

84 Configuring an EIS Login

EIS Login Configuration Overview................................................................................................... 84-1Configuring an EIS Data Source Platform at the Session Level .................................................. 84-1

Using TopLink Workbench ........................................................................................................... 84-1Configuring EIS Connection Specification Options at the Session Level................................. 84-2

xxxvii

Using TopLink Workbench ........................................................................................................... 84-2

85 Creating an Internal Connection Pool

Internal Connection Pool Creation Overview ................................................................................. 85-1Using TopLink Workbench ........................................................................................................... 85-1

86 Configuring an Internal Connection Pool

Internal Connection Pool Configuration Overview ....................................................................... 86-1Configuring Connection Pool Sizes .................................................................................................. 86-1

Using TopLink Workbench ........................................................................................................... 86-2Configuring Properties......................................................................................................................... 86-2

Using TopLink Workbench ........................................................................................................... 86-2Using Java......................................................................................................................................... 86-3

Configuring a Nontransactional Read Login................................................................................... 86-3Using TopLink Workbench ........................................................................................................... 86-3

Configuring Connection Pool Connection Options ....................................................................... 86-4Using TopLink Workbench ........................................................................................................... 86-4

Configuring Exclusive Read Connections........................................................................................ 86-6Using TopLink Workbench ........................................................................................................... 86-6

Part XVII Cache

87 Understanding the Cache

Cache Architecture ................................................................................................................................ 87-1Session Cache................................................................................................................................... 87-2Unit of Work Cache ........................................................................................................................ 87-2

Cache Concepts ...................................................................................................................................... 87-2Cache Type and Object Identity.................................................................................................... 87-3

Full Identity Map ..................................................................................................................... 87-3Weak Identity Map .................................................................................................................. 87-3Soft and Hard Cache Weak Identity Maps........................................................................... 87-4No Identity Map....................................................................................................................... 87-4Guidelines for Configuring the Cache and Identity Maps ................................................ 87-4Understanding the Internals of Soft and Hard Cache Weak Identity Map .................... 87-5

Querying and the Cache................................................................................................................. 87-6Handling Stale Data........................................................................................................................ 87-6

Configure a Locking Policy .................................................................................................... 87-6Configure the Cache on a Per-Class Basis ............................................................................ 87-7Force a Cache Refresh When Required on a Per-Query Basis........................................... 87-7Configure Cache Invalidation ................................................................................................ 87-7Configure Cache Coordination.............................................................................................. 87-7

Explicit Query Refreshes................................................................................................................ 87-7Refresh Policy ........................................................................................................................... 87-8EJB Finders and Refresh Policy.............................................................................................. 87-8

Cache Invalidation .......................................................................................................................... 87-8Cache Coordination ........................................................................................................................ 87-9

xxxviii

Cache Isolation ................................................................................................................................ 87-9Cache Locking and Transaction Isolation.................................................................................... 87-9Cache Optimization ...................................................................................................................... 87-10

Understanding Cache Coordination ................................................................................................ 87-10When to use Cache Coordination ............................................................................................... 87-11Coordinated Cache Architecture ................................................................................................ 87-11

Session ..................................................................................................................................... 87-11Descriptor................................................................................................................................ 87-12Unit of Work ........................................................................................................................... 87-12

Coordinated Cache Types............................................................................................................ 87-12JMS Coordinated Cache ........................................................................................................ 87-12RMI Coordinated Cache ....................................................................................................... 87-12CORBA Coordinated Cache ................................................................................................. 87-13

Custom Coordinated Cache ........................................................................................................ 87-13Understanding the Cache API .......................................................................................................... 87-13

Object Identity API ....................................................................................................................... 87-14Cache Refresh API......................................................................................................................... 87-14Cache Invalidation API ................................................................................................................ 87-14Cache Coordination API .............................................................................................................. 87-15

88 Configuring a Coordinated Cache

Configuring Common Coordinated Cache Options ...................................................................... 88-1Configuring the Synchronous Change Propagation Mode........................................................... 88-2

Using TopLink Workbench ........................................................................................................... 88-2Configuring a Service Channel .......................................................................................................... 88-3

Using TopLink Workbench ........................................................................................................... 88-3Configuring a Multicast Group Address .......................................................................................... 88-4

Using TopLink Workbench ........................................................................................................... 88-5Configuring a Multicast Port .............................................................................................................. 88-5

Using TopLink Workbench ........................................................................................................... 88-6Configuring a Naming Service Type ................................................................................................. 88-7Configuring JNDI Naming Service Information ............................................................................ 88-7

Using TopLink Workbench ........................................................................................................... 88-8Configuring RMI Registry Naming Service Information ............................................................. 88-9

Using TopLink Workbench ......................................................................................................... 88-10Configuring an Announcement Delay............................................................................................ 88-11

Using TopLink Workbench ......................................................................................................... 88-12Configuring Connection Handling.................................................................................................. 88-13

Using TopLink Workbench ......................................................................................................... 88-13Configuring Context Properties ....................................................................................................... 88-14

Using TopLink Workbench ......................................................................................................... 88-14Configuring a Packet Time-to-Live.................................................................................................. 88-15

Using TopLink Workbench ......................................................................................................... 88-16

89 Configuring a JMS Coordinated Cache

JMS Coordinated Cache Configuration Overview ......................................................................... 89-1Configuring a Topic Name .................................................................................................................. 89-1

xxxix

Using TopLink Workbench ........................................................................................................... 89-1Configuring a Topic Connection Factory Name .............................................................................. 89-2

Using TopLink Workbench ........................................................................................................... 89-2Configuring a Topic Host URL ........................................................................................................... 89-3

Using TopLink Workbench ........................................................................................................... 89-3

90 Configuring an RMI Coordinated Cache

RMI Coordinated Cache Configuration Overview ........................................................................ 90-1

91 Configuring a CORBA Coordinated Cache

CORBA Coordinated Cache Configuration Overview .................................................................. 91-1

92 Configuring a Custom Coordinated Cache

Custom Coordinated Cache Configuration Overview................................................................... 92-1Configuring Transport Class ............................................................................................................... 92-1

Using TopLink Workbench ........................................................................................................... 92-1

Part XVIII Queries

93 Understanding TopLink Queries

Query Types............................................................................................................................................ 93-1Query Concepts ..................................................................................................................................... 93-2

Call..................................................................................................................................................... 93-3DatabaseQuery ................................................................................................................................ 93-3Data-Level and Object-Level Queries .......................................................................................... 93-3Summary Queries ........................................................................................................................... 93-3Descriptor Query Manager............................................................................................................ 93-3TopLink Expressions ...................................................................................................................... 93-3Query Keys....................................................................................................................................... 93-4Query Languages ............................................................................................................................ 93-4

SQL Queries .............................................................................................................................. 93-4EJB QL Queries......................................................................................................................... 93-5XML Queries............................................................................................................................. 93-5EIS Interactions......................................................................................................................... 93-5Query-by-Example................................................................................................................... 93-6

Building Queries ................................................................................................................................... 93-6Executing Queries ................................................................................................................................. 93-6Handling Query Results ...................................................................................................................... 93-8

Collection Query Results................................................................................................................ 93-8Report Query Results ..................................................................................................................... 93-8Stream and Cursor Query Results ................................................................................................ 93-8

Session Queries ..................................................................................................................................... 93-9Read-Object Session Queries ......................................................................................................... 93-9Create, Update, and Delete Object Session Queries................................................................. 93-10

Database Queries................................................................................................................................. 93-10

xl

Object-Level Read Query ............................................................................................................. 93-11ReadObjectQuery................................................................................................................... 93-11ReadAllQuery......................................................................................................................... 93-11Partial Object Queries............................................................................................................ 93-11Join Reading and Object-Level Read Queries.................................................................... 93-12Fetch Groups and Object-Level Read Queries................................................................... 93-13

Data-Level Read Query................................................................................................................ 93-13DataReadQuery...................................................................................................................... 93-13DirectReadQuery ................................................................................................................... 93-13ValueReadQuery.................................................................................................................... 93-14

Object-Level Modify Query......................................................................................................... 93-14WriteObjectQuery.................................................................................................................. 93-14UpdateObjectQuery............................................................................................................... 93-14InsertObjectQuery.................................................................................................................. 93-14DeleteObjectQuery................................................................................................................. 93-14UpdateAllQuery..................................................................................................................... 93-14Object-Level Modify Queries and Privately Owned Parts .............................................. 93-15

Data-Level Modify Query............................................................................................................ 93-15Report Query ................................................................................................................................. 93-15

Named Queries .................................................................................................................................... 93-16Call Queries .......................................................................................................................................... 93-17

SQL Calls ........................................................................................................................................ 93-17SQLCall.................................................................................................................................... 93-17StoredProcedureCall.............................................................................................................. 93-17StoredFunctionCall ................................................................................................................ 93-18Oracle Extensions................................................................................................................... 93-18

EJB QL Calls ................................................................................................................................... 93-19Enterprise Information System (EIS) Interactions.................................................................... 93-19

IndexedInteraction................................................................................................................. 93-19MappedInteraction ................................................................................................................ 93-19XMLInteraction ...................................................................................................................... 93-20XQueryInteraction ................................................................................................................. 93-20QueryStringInteraction ......................................................................................................... 93-20

Redirect Queries .................................................................................................................................. 93-20Historical Queries ............................................................................................................................... 93-21

Using an ObjectLevelReadQuery With an AsOfClause .......................................................... 93-21Using an ObjectLevelReadQuery With Expression Operator asOf ....................................... 93-22Using an ObjectLevelReadQuery in a Historical Session........................................................ 93-22

Interface and Inheritance Queries ................................................................................................... 93-22Descriptor Query Manager Queries ................................................................................................ 93-23

Configuring Named Queries....................................................................................................... 93-23Configuring Default Query Implementations .......................................................................... 93-23Configuring Additional Join Expressions ................................................................................. 93-24

EJB Finders ........................................................................................................................................... 93-24Predefined Finders........................................................................................................................ 93-24

Predefined CMP Finders....................................................................................................... 93-25Predefined BMP Finders ....................................................................................................... 93-25

xli

Default Finders .............................................................................................................................. 93-26Call Finders .................................................................................................................................... 93-26DatabaseQuery Finders................................................................................................................ 93-26Named Query Finders.................................................................................................................. 93-27Primary Key Finders..................................................................................................................... 93-27Expression Finders........................................................................................................................ 93-27EJB QL Finders............................................................................................................................... 93-27SQL Finders.................................................................................................................................... 93-28Redirect Finders............................................................................................................................. 93-28The ejbSelect Method.................................................................................................................... 93-28

Queries and the Cache........................................................................................................................ 93-29Configuring the Cache ................................................................................................................. 93-29Using In-Memory Queries ........................................................................................................... 93-30

Configuring Cache Usage for In-Memory Queries........................................................... 93-30Expression Options for In-Memory Queries...................................................................... 93-31Handling Exceptions Resulting From In-Memory Queries............................................. 93-33

Primary Key Queries and the Cache .......................................................................................... 93-34Disabling the Identity Map Cache Update During a Read Query......................................... 93-34Refreshing the Cache .................................................................................................................... 93-35

Object Refresh......................................................................................................................... 93-35Cascading Object Refresh ..................................................................................................... 93-35Refreshing the Identity Map Cache During a Read Query.............................................. 93-35

Caching Query Results in the Session Cache............................................................................ 93-36Caching Query Results in the Query Cache.............................................................................. 93-36

Internal Query Cache Restrictions....................................................................................... 93-37Caching and EJB Finders.............................................................................................................. 93-37

Caching Options..................................................................................................................... 93-37Disabling Cache for Returned Finder Results ................................................................... 93-38Refreshing Finder Results..................................................................................................... 93-38

Understanding the Query API .......................................................................................................... 93-38

94 Using Basic Query API

Using Session Queries.......................................................................................................................... 94-1Reading Objects With a Session Query........................................................................................ 94-1

Reading an Object With a Session Query............................................................................. 94-2Reading All Objects With a Session Query ......................................................................... 94-2Refreshing an Object With a Session Query......................................................................... 94-2

Creating, Updating, and Deleting Objects With a Session Query ........................................... 94-3Writing a Single Object to the Database With a Session Query ........................................ 94-3Writing All Objects to the Database With a Session Query............................................... 94-3Adding New Objects to the Database With a Session Query............................................ 94-4Modifying Existing Objects in the Database With a Session Query................................. 94-4Deleting Objects in the Database With a Session Query.................................................... 94-4

Using DatabaseQuery Queries ........................................................................................................... 94-4Reading Objects Using a DatabaseQuery.................................................................................... 94-4

Basic DatabaseQuery Read Operations ................................................................................ 94-5Reading Objects Using Partial Object Queries .................................................................... 94-6

xlii

Reading Objects Using Report Queries ................................................................................ 94-6Reading Objects Using Query-By-Example ......................................................................... 94-6Specifying Read Ordering ...................................................................................................... 94-9Specifying a Collection Class ................................................................................................. 94-9Specifying the Maximum Rows Returned ......................................................................... 94-10Configuring Query Timeout at the Query Level............................................................... 94-10Using Batch Reading ............................................................................................................. 94-10Using Join Reading ................................................................................................................ 94-11

Creating, Updating, and Deleting Objects With a DatabaseQuery ....................................... 94-13Write Query Overview.......................................................................................................... 94-13UpdateAll Queries ................................................................................................................. 94-13Noncascading Write Queries ............................................................................................... 94-14Disabling the Identity Map Cache During a Write Query............................................... 94-15

Reading Data With a DatabaseQuery ........................................................................................ 94-15Using a DataReadQuery ....................................................................................................... 94-15Using a DirectReadQuery..................................................................................................... 94-16Using a ValueReadQuery ..................................................................................................... 94-16

Updating Data With a DatabaseQuery ...................................................................................... 94-16Specifying a Custom SQL String in a DatabaseQuery............................................................. 94-16Specifying a Custom EJB QL String in a DatabaseQuery........................................................ 94-17Using Parameterized SQL and Statement Caching in a DatabaseQuery.............................. 94-17

Using Named Queries ........................................................................................................................ 94-18Using SQL Calls .................................................................................................................................. 94-19

Using an SQLCall .......................................................................................................................... 94-19Specifying a SQLCall Input Parameter ............................................................................... 94-20Specifying a SQLCall Output Parameter............................................................................ 94-20Specifying a SQLCall Input / Output Parameter.............................................................. 94-21

Using a StoredProcedureCall ...................................................................................................... 94-21Specifying an Input Parameter ............................................................................................ 94-22Specifying an Output Parameter ......................................................................................... 94-22Specifying an Input / Output Parameter ........................................................................... 94-22Using an Output Parameter Event ...................................................................................... 94-23

Using a StoredFunctionCall......................................................................................................... 94-23Using EJB QL Calls ............................................................................................................................. 94-24Using EIS Interactions........................................................................................................................ 94-24Handling Exceptions........................................................................................................................... 94-25Handling Collection Query Results ................................................................................................ 94-26Handling Report Query Results....................................................................................................... 94-26

95 Understanding TopLink Expressions

Understanding the Expression Framework...................................................................................... 95-1Expressions Compared to SQL ..................................................................................................... 95-1

Expression Components....................................................................................................................... 95-2Boolean Logic................................................................................................................................... 95-3Database Functions and Operators .............................................................................................. 95-3Mathematical Functions ................................................................................................................. 95-4XMLType Functions ....................................................................................................................... 95-5

xliii

Platform and User-Defined Functions ......................................................................................... 95-5Expressions for One-to-One and Aggregate Object Relationships.......................................... 95-5Expressions for Joining and Complex Relationships ................................................................ 95-6

Understanding Joins................................................................................................................ 95-6Using TopLink Expression API For Joins............................................................................. 95-7

Parameterized Expressions .................................................................................................................. 95-8Expression Method getParameter................................................................................................. 95-8Expression Method getField.......................................................................................................... 95-9

Query Keys and Expressions............................................................................................................. 95-10Using Multiple Expressions .............................................................................................................. 95-10

Subselects and Subqueries ........................................................................................................... 95-10Parallel Expressions ...................................................................................................................... 95-11

Data Queries and Expressions .......................................................................................................... 95-12getField ........................................................................................................................................... 95-12getTable .......................................................................................................................................... 95-12

Creating an Expression....................................................................................................................... 95-13Using TopLink Workbench ......................................................................................................... 95-13

Adding Arguments................................................................................................................ 95-14Using Java....................................................................................................................................... 95-15

Creating and Using a User-Defined Function ............................................................................... 95-16Making a User-Defined Function Available to a Specific Platform....................................... 95-17Making a User-Defined Function Available to All Platforms ................................................ 95-17

Using a User-Defined Function ........................................................................................... 95-17

96 Using Advanced Query API

Using Redirect Queries ........................................................................................................................ 96-1Creating a Redirect Query ............................................................................................................. 96-1

Using Historical Queries...................................................................................................................... 96-2Using Queries With Fetch Groups ..................................................................................................... 96-2

Configuring Default Fetch Group Behavior................................................................................ 96-3Querying With a Static Fetch Group ............................................................................................ 96-3Querying With a Dynamic Fetch Group...................................................................................... 96-4

Querying on Interfaces......................................................................................................................... 96-4Querying on an Inheritance Hierarchy ............................................................................................. 96-4Appending Additional Join Expressions.......................................................................................... 96-4

Using Java......................................................................................................................................... 96-5Using Queries on Variable One-to-One Mappings ........................................................................ 96-5Using Oracle Database Features......................................................................................................... 96-5

Oracle Hints ..................................................................................................................................... 96-6Hierarchical Queries ....................................................................................................................... 96-6

startWith Parameter ................................................................................................................ 96-7connectBy Parameter ............................................................................................................... 96-7orderSibling Parameter ........................................................................................................... 96-7

Using EJB Finders.................................................................................................................................. 96-7Creating a Finder............................................................................................................................. 96-8

ejb-jar.xml Finder Options...................................................................................................... 96-9Using DatabaseQuery Finders .................................................................................................... 96-10

xliv

Using Named Query Finders ...................................................................................................... 96-10Using Primary Key Finders ......................................................................................................... 96-11Using EJB QL Finders ................................................................................................................... 96-11Using SQL Finders ........................................................................................................................ 96-12Using Redirect Finders ................................................................................................................. 96-12Using the ejbSelect Method ......................................................................................................... 96-15

Handling Cursor and Stream Query Results ................................................................................. 96-15Cursors and Java Iterators ........................................................................................................... 96-16

Traversing Data With Scrollable Cursors........................................................................... 96-16Java Streams................................................................................................................................... 96-17

Cursored Stream Support ..................................................................................................... 96-17Optimizing Streams ...................................................................................................................... 96-18Using Cursors and Streams With EJB Finders .......................................................................... 96-18

Building the Query ................................................................................................................ 96-19Executing the Finder From the Client................................................................................. 96-19

Using Queries and the Cache............................................................................................................ 96-20Caching Results in a ReadQuery ................................................................................................ 96-20Configuring Cache Expiration at the Query Level................................................................... 96-21

Part XIX Transactions

97 Understanding TopLink Transactions

Unit of Work Architecture ................................................................................................................... 97-1Unit of Work Transaction Context................................................................................................ 97-2Unit of Work Transaction Demarcation....................................................................................... 97-2

JTA Controlled Transactions .................................................................................................. 97-3OTS Controlled Transactions ................................................................................................. 97-3CMP Controlled Transactions................................................................................................ 97-3

Unit of Work Transaction Isolation .............................................................................................. 97-4Unit of Work Concepts ......................................................................................................................... 97-4

Unit of Work Benefits ..................................................................................................................... 97-4Unit of Work Life Cycle ................................................................................................................. 97-5Unit of Work and Change Policy .................................................................................................. 97-6

Deferred Change Detection Policy ........................................................................................ 97-7Object-Level Change Tracking Policy................................................................................... 97-7Attribute Change Tracking Policy......................................................................................... 97-8Change Policy Mapping Support .......................................................................................... 97-9

Clones and the Unit of Work......................................................................................................... 97-9Nested and Parallel Units of Work............................................................................................... 97-9

Nested Unit of Work ............................................................................................................. 97-10Parallel Unit of Work............................................................................................................. 97-10

Commit and Rollback Transactions ........................................................................................... 97-10Commit Transactions ............................................................................................................ 97-10Rollback Transactions............................................................................................................ 97-11

Primary Keys ................................................................................................................................. 97-11Unit of Work Optimization.......................................................................................................... 97-11

Understanding the Unit of Work API.............................................................................................. 97-11

xlv

Unit of Work as Session ............................................................................................................... 97-12Reading and Querying Objects with the Unit of Work.................................................... 97-12Locking and the Unit of Work ............................................................................................. 97-12

Example Model Object and Schema................................................................................................ 97-12

98 Using Basic Unit of Work API

Acquiring a Unit of Work .................................................................................................................... 98-1Creating an Object ................................................................................................................................ 98-2Modifying an Object ............................................................................................................................ 98-2Associating a New Target to an Existing Source Object ................................................................ 98-3

Associating Without Reference to the Cache Object.................................................................. 98-3Associating With Reference to the Cache Object........................................................................ 98-4

Associating a New Source to an Existing Target Object ................................................................ 98-6Associating an Existing Source to an Existing Target Object ....................................................... 98-7Deleting Objects .................................................................................................................................... 98-7

Using privateOwnedRelationship ................................................................................................ 98-8Explicitly Deleting From the Database ........................................................................................ 98-9Understanding the Order in Which Objects Are Deleted ......................................................... 98-9

99 Using Advanced Unit of Work API

Registering and Unregistering Objects............................................................................................. 99-1Creating and Registering an Object in One Step ........................................................................ 99-2Using registerNewObject ............................................................................................................... 99-2

Registering a New Object With registerNewObject ........................................................... 99-2Associating New Objects With One Another ...................................................................... 99-3

Using registerAllObjects ................................................................................................................ 99-4Using Registration and Existence Checking ............................................................................... 99-5

Check Database ........................................................................................................................ 99-5Assume Existence .................................................................................................................... 99-5Assume Nonexistence ............................................................................................................. 99-5

Working With Aggregates ............................................................................................................. 99-6Unregistering Working Clones ..................................................................................................... 99-6

Declaring Read-Only Classes ............................................................................................................. 99-6Configuring Read-Only Classes for a Single Unit of Work ...................................................... 99-6Configuring Default Read-Only Classes ..................................................................................... 99-7Read-Only Descriptors ................................................................................................................... 99-7

Writing Changes Before Commit Time ............................................................................................. 99-7Using Conforming Queries and Descriptors ................................................................................... 99-8

Guidelines for Using Conforming ................................................................................................ 99-8Ensure That the Query Supports Conforming .................................................................... 99-8Consider how Conforming Affects Database Results ........................................................ 99-9Register New Objects and Instantiate Relationships ........................................................ 99-10

Using Conforming Queries.......................................................................................................... 99-11Using Conforming Descriptors ................................................................................................... 99-12Conforming Query Alternatives ................................................................................................. 99-12

Using Unit of Work Method writeChanges Instead of Conforming.............................. 99-12

xlvi

Using Unit of Work Properties Instead of Conforming ................................................... 99-13Merging Changes in Working Copy Clones .................................................................................. 99-13Resuming a Unit of Work After Commit ........................................................................................ 99-14Reverting a Unit of Work ................................................................................................................... 99-15Using a Nested or Parallel Unit of Work ........................................................................................ 99-15

Parallel Unit of Work.................................................................................................................... 99-15Nested Unit of Work..................................................................................................................... 99-15

Using a Unit of Work With Custom SQL........................................................................................ 99-16Controlling the Order of Delete Operations.................................................................................. 99-16

Using the Unit of Work setShouldPerformDeletesFirst Method ........................................... 99-17Using the Descriptor addConstraintDependencies Method .................................................. 99-17Using deleteAllObjects Without addConstraintDependencies.............................................. 99-17Using deleteAllObjects With addConstraintDependencies.................................................... 99-17

Using Optimistic Read Locking With forceUpdateToVersionField .......................................... 99-18Forcing a Check of the Optimistic Read Lock........................................................................... 99-18Forcing a Version Field Update .................................................................................................. 99-19Disabling forceUpdateToVersionField ...................................................................................... 99-20

Implementing User and Date Auditing With the Unit of Work ................................................ 99-21Integrating the Unit of Work With an External Transaction Service......................................... 99-21

Acquiring a Unit of Work With an External Transaction Service.......................................... 99-21Using a Unit of Work When an External Transaction Exists.................................................. 99-22Using a Unit of Work When No External Transaction Exists................................................. 99-23Using the Unit of Work to Handle External Transaction Timeouts and Exceptions .......... 99-23

External Transaction Commit Timeouts............................................................................. 99-24External Transaction Commit Exceptions .......................................................................... 99-24

Integrating the Unit of Work With CMP ........................................................................................ 99-24CMP Transaction Attribute.......................................................................................................... 99-25Local Transactions......................................................................................................................... 99-25Nondeferred Changes .................................................................................................................. 99-26

Database Transaction Isolation Levels ............................................................................................ 99-26General Factors Affecting Transaction Isolation Level............................................................ 99-26

External Applications ............................................................................................................ 99-27TopLink Coordinated Cache ................................................................................................ 99-27DatabaseLogin Method setTransactionIsolation............................................................... 99-27Reading Through the Write Connection ............................................................................ 99-28Managing Cache Access........................................................................................................ 99-29CMP and External Transactions .......................................................................................... 99-30

Read Uncommitted Level ............................................................................................................ 99-30Read Committed Level................................................................................................................. 99-30Repeatable Read Levels................................................................................................................ 99-30Serializable Read Levels............................................................................................................... 99-30

Troubleshooting a Unit of Work....................................................................................................... 99-31Avoiding the Use of Post-Commit Clones ................................................................................ 99-31Determining Whether or Not an Object Is the Cache Object.................................................. 99-32Dumping the Contents of a Unit of Work ................................................................................. 99-32Handling Exceptions .................................................................................................................... 99-33

Exceptions at Commit Time ................................................................................................. 99-33

xlvii

Exceptions During Conforming........................................................................................... 99-34Validating a Unit of Work............................................................................................................ 99-34

Validating the Unit of Work Before Commit Time........................................................... 99-35

Index

xlviii

xlix

Preface

Oracle TopLink Developer’s Guide explains how to use Oracle TopLink to design, implement, deploy, and optimize an advanced persistence or object-to-XML transformation layer for a wide range of Java 2 Enterprise Edition (J2EE) and Java applications. It describes TopLink mapping metadata, sessions, data access, queries, transactions (both with and without an external transaction controller), and cache.

It describes how to use TopLink application development tools and how to integrate TopLink with a variety of J2EE containers. It also introduces the concepts with which you should be familiar to get the most out of TopLink.

AudienceOracle TopLink Developer’s Guide is intended for application developers creating applications that use TopLink to manage persistence.

This document assumes that you are familiar with the concepts of object-oriented programming, the Enterprise JavaBeans (EJB) specification, and your own particular Java development environment.

The document also assumes that you are familiar with your particular operating system (such as Windows, UNIX, or other). The general operation of any operating system is described in the user documentation for that system, and is not repeated in this manual.

Documentation AccessibilityOur goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Accessibility standards will continue to evolve over time, and Oracle is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For more information, visit the Oracle Accessibility Program Web site at

http://www.oracle.com/accessibility/

Accessibility of Code Examples in DocumentationScreen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an

l

otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in DocumentationThis documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.

TTY Access to Oracle Support ServicesOracle provides dedicated Text Telephone (TTY) access to Oracle Support Services within the United States of America 24 hours a day, seven days a week. For TTY support, call 800.446.2398.

Related DocumentationFor more information, see the following documents:

■ Oracle TopLink Release Notes

■ Oracle Application Server Release Notes

■ Oracle TopLink Getting Started Guide

■ Oracle TopLink API Reference

ConventionsThe following text conventions are used in this document:

Convention Meaning

boldface Boldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.

italic Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

monospace Monospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Part XII EIS Mappings

TopLink enterprise information system (EIS) mappings provide support for accessing legacy data sources and enterprise applications through J2EE Connector architecture (J2C) adapter. TopLink EIS mappings use the J2C Common Client Interface (CCI) to access the EIS through its resource adapter. This provides the ability to directly map from an existing Java object model to any transactional data source, such as mainframes with flat file/hierarchical data. An EIS mapping transforms object data members to the EIS record format defined by the object’s descriptor.

This part contains the following chapters:

■ Chapter 53, "Understanding EIS Mappings"

This chapter describes each of the different TopLink EIS mapping types and important EIS mapping concepts.

■ Chapter 54, "Configuring an EIS Mapping"

This chapter explains how to configure TopLink EIS mapping options common to two or more EIS mapping types.

■ Chapter 55, "Configuring an EIS Direct Mapping"

This chapter explains how to configure a direct EIS mapping.

■ Chapter 56, "Configuring an EIS Composite Direct Collection Mapping"

This chapter explains how to configure a direct collection EIS mapping.

■ Chapter 57, "Configuring an EIS Composite Object Mapping"

This chapter explains how to configure a composite object EIS mapping.

■ Chapter 58, "Configuring an EIS Composite Collection Mapping"

This chapter explains how to configure a composite collection EIS mapping.

■ Chapter 61, "Configuring an EIS Transformation Mapping"

This chapter explains how to configure a transformation EIS mapping.

■ Chapter 59, "Configuring an EIS One-to-One Mapping"

This chapter explains how to configure a one-to-one EIS mapping.

■ Chapter 60, "Configuring an EIS One-to-Many Mapping"

This chapter explains how to configure a one-to-many EIS mapping.

Understanding EIS Mappings 53-1

53Understanding EIS Mappings

TopLink enterprise information system (EIS) mappings provide support for accessing legacy data sources and enterprise applications through J2EE Connector architecture (J2C) adapter. TopLink EIS mappings use the J2C Common Client Interface (CCI) to access the EIS through its resource adapter. This provides the ability to directly map from an existing Java object model to any transactional data source, such as mainframes with flat file/hierarchical data.

An EIS mapping transforms object data members to the EIS record format defined by the object’s descriptor.

This chapter describes the following:

■ EIS Mapping Types

■ EIS Mapping Concepts

EIS Mapping TypesTopLink supports the EIS mappings listed in Table 53–1.

Table 53–1 TopLink Object EIS Mapping Types

Mapping Type Description TypeTopLink Workbench Java

"EIS Direct Mapping" on page 53-5 Map a simple object attribute directly to an EIS record.

Basic

"EIS Composite Direct Collection Mapping" on page 53-6

Map a collection of Java attributes directly to an EIS record.

Basic

"EIS Composite Object Mapping" on page 53-7

Map a Java object to an EIS record in a privately owned one-to-one relationship. Composite object mappings represent a relationship between two classes.

Advanced

"EIS Composite Collection Mapping" on page 53-7

Map a Map or Collection of Java objects to an EIS record in a privately owned one-to-many relationship.

Advanced

EIS Mapping Concepts

53-2 Oracle TopLink Developer’s Guide

EIS Mapping ConceptsThis section describes concepts unique to TopLink EIS mappings, including the following:

■ EIS Record Type

■ XPath Support

■ xsd:list and xsd:union Support

■ jaxb:class Support

■ Typesafe Enumeration Support

■ Composite and Reference EIS Mappings

■ EIS Mapping Architecture

EIS Record TypeTopLink supports the following J2C EIS record types:

■ Indexed Records

■ Mapped Records

■ XML Records

You configure the record type at the EIS descriptor level (see "Configuring Record Format" on page 28-5). EIS mappings use the record type of their EIS descriptor to determine how to map Java attributes. That is, you use the same EIS mapping regardless of the record type, with which you configure an EIS descriptor.

Indexed RecordsThe javax.resource.cci.IndexedRecord represents an ordered collection of record elements based on the java.util.List interface.

The TopLink runtime maps Java objects to indexed record elements or subrecords of an indexed record depending on the type of EIS mapping you use (see "Composite and Reference EIS Mappings" on page 53-4).

"EIS One-to-One Mapping" on page 53-8 Define a reference mapping that represents the relationship between a single source object and a single mapped persistent Java object.

Basic

"EIS One-to-Many Mapping" on page 53-12 Define a reference mapping that represents the relationship between a single source object and a collection of mapped persistent Java objects.

Basic

"EIS Transformation Mapping" on page 53-17

Create custom mappings where one or more EIS record fields can be used to create the object to be stored in a Java class’s attribute.

Advanced

Note: Not all J2C adapters support all record types. Consult your J2C adapter documentation for details.

Table 53–1 (Cont.) TopLink Object EIS Mapping Types

Mapping Type Description TypeTopLink Workbench Java

EIS Mapping Concepts

Understanding EIS Mappings 53-3

Mapped RecordsThe javax.resource.cci.MappedRecord represents a key-value map-based collection of record elements based on the java.util.Map interface.

The TopLink runtime maps Java objects to mapped record elements or subrecords of a mapped record depending on the type of EIS mapping you use (see "Composite and Reference EIS Mappings" on page 53-4).

XML RecordsAn XML record represents a javax.resource.cci.Record as an XML schema (XSD)-based XML document. Not all J2C adapters support XML records.

The TopLink runtime maps Java objects to XML documents according to your XSD and the behavior defined for XML mappings.

For more information, see "Understanding XML Mappings" on page 62-1.

XPath SupportWhen using XML records, TopLink EIS mappings use XPath statements to efficiently map the attributes of a Java object to locations in an XML record. For more information about using XPath with XML mappings, see "Mappings and XPath" on page 30-15.

xsd:list and xsd:union SupportWhen using XML records, you can use EIS direct (see "EIS Direct Mapping") and composite direct collection (see "EIS Composite Direct Collection Mapping") mappings to map to xsd:list and xsd:union types in an XML record.

For more information, see "Mappings and xsd:list and xsd:union Types" on page 30-17.

jaxb:class SupportWhen using XML records, you can configure an EIS composite object mapping (see "EIS Composite Object Mapping" on page 53-7) to accommodate jaxb:class customizations with the following XSD structures:

■ all

■ sequence

■ choice

■ group

For more information, see "Mappings and the jaxb:class Customization" on page 30-20.

Typesafe Enumeration SupportYou can map a Java attribute to a typesafe enumeration using the JAXBTypesafeEnumConverter with an EISDirectMapping or EISCompositeDirectCollectionMapping with XML records.

For more information, see "Mappings and JAXB Typesafe Enumerations" on page 30-24.

EIS Mapping Concepts

53-4 Oracle TopLink Developer’s Guide

Composite and Reference EIS MappingsTopLink supports composite and reference EIS mappings. Although there is a source and target object in both mapping types, the TopLink runtime handles interactions with each differently. This section explains how.

Composite EIS MappingsIn a composite EIS mapping ("EIS Composite Direct Collection Mapping", "EIS Composite Object Mapping", and "EIS Composite Collection Mapping"), the source object contains (owns) the target object.

TopLink puts the attributes of the target (owned) object (or the owned collection of objects) into the source (owning) object’s record as a subrecord. The target object needs not be a root object type (see "Configuring an EIS Descriptor as a Root or Composite Type" on page 28-8): it needs not have interactions defined for it.

Figure 53–1 illustrates a read interaction on an instance of the Customer class using indexed records. For the composite object EIS mapping defined for the address attribute, TopLink creates an Address subrecord in the Customer record.

Figure 53–1 EIS Composite Mappings

Reference EIS MappingsIn a reference EIS mapping ("EIS One-to-One Mapping" and "EIS One-to-Many Mapping"), the source object contains only a foreign key (pointer) to the target object or, alternatively, the target object contains a foreign key to the source object (key on target).

TopLink puts the foreign key of the target object into the source object’s record as a simple value. When an interaction is executed on the source object, TopLink uses the selection interaction that you define on its descriptor to retrieve the appropriate target object instance and creates a record for it in the source object’s transaction. By default, the selection interaction is the target object’s read interaction. If the read interaction is not sufficient, you can define a separate selection interaction (see "Configuring Selection Interaction" on page 54-3). Because both the source and target object use interactions, they must both be of a root object type (see "Configuring an EIS Descriptor as a Root or Composite Type" on page 28-8).

Figure 53–2 illustrates a read interaction on an instance of the Order class using indexed records. For the one-to-one EIS mapping defined for the customer attribute, TopLink puts the target Customer object’s foreign key into the Order record as a simple value. TopLink then uses the selection interaction you configure on the Order descriptor to retrieve the appropriate instance of Customer and creates a record for it in the Order object’s transaction.

EIS Direct Mapping

Understanding EIS Mappings 53-5

Figure 53–2 EIS Reference Mappings

EIS Mapping ArchitectureFigure 53–3 illustrates the following possible TopLink EIS mapping architectures:

■ JDBC database gateway (such as Oracle Database 10g)

■ JDBC adapter

■ Proprietary adapter (such as Oracle Interconnect)

■ J2C

Figure 53–3 Possible EIS Mapping Architectures

The best solution may vary, depending on your specific EIS and infrastructure.

EIS Direct MappingAn EIS direct mapping maps a simple object attribute directly to an EIS record according to its descriptor’s record type as shown in Table 53–2.

EIS Composite Direct Collection Mapping

53-6 Oracle TopLink Developer’s Guide

Figure 53–4 illustrates a direct EIS mapping between Order class attribute orderedBy and XML record attribute ordered_by within the order element.

Figure 53–4 EIS Direct Mappings

See Chapter 55, "Configuring an EIS Direct Mapping" for more information.

EIS Composite Direct Collection MappingAn EIS composite direct collection mapping maps a collection of Java attributes directly to an EIS record according to its descriptor’s record type, as shown in Table 53–3.

Figure 53–5 illustrates a composite direct collection mapping between Order class attribute items and an XML record. The Order attribute items is a collection type (such as Vector). It is mapped to an XML record composed of an order element that contains a sequence of item elements.

Figure 53–5 EIS Composite Direct Collection Mapping

Table 53–2 EIS Direct Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed Maps directly to a field in the indexed record.

Mapped Maps directly to a field in the mapped record.

XML Maps directly to an attribute or text node in the XML record1.1 See also "XML Direct Mapping" on page 62-5.

Table 53–3 EIS Composite Direct Collection Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed Maps directly to a subrecord in the indexed record1.

1 See also "Composite EIS Mappings" on page 53-4.

Mapped Maps directly to a subrecord in the mapped record1.

XML Maps directly to an attribute or text node in the XML record2.

2 See also "XML Composite Direct Collection Mapping" on page 62-14.

EIS Composite Collection Mapping

Understanding EIS Mappings 53-7

See Chapter 56, "Configuring an EIS Composite Direct Collection Mapping" for more information.

EIS Composite Object MappingAn EIS composite object mapping maps a Java object to a privately owned one-to-one relationship in an EIS record according to its descriptor’s record type, as shown in Table 53–4.

Figure 53–6 illustrates a composite object EIS mapping between Order class attribute address and an XML record. Order attribute address is mapped to an XML record composed of an order element that contains an address element.

Figure 53–6 EIS Composite Object Mappings

You can use an EIS composite object mapping with a change policy (see "Configuring Change Policy" on page 25-73.

See Chapter 57, "Configuring an EIS Composite Object Mapping" for more information.

EIS Composite Collection MappingAn EIS composite collection mapping maps a collection of Java objects to a privately owned one-to-many relationship in an EIS record according to its descriptor’s record type as shown in Table 53–5. Composite collection mappings can reference any class that has a TopLink descriptor.

Table 53–4 EIS Composite Object Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed Maps directly to a subrecord in the indexed record1.

1 See also "Composite EIS Mappings" on page 53-4.

Mapped Maps directly to a subrecord in the mapped record1.

XML Maps directly to an attribute or text node in the XML record2.

2 See also "XML Composite Object Mapping" on page 62-21.

Table 53–5 EIS Composite Collection Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed Maps directly to a subrecord in the indexed record1.

Mapped Maps directly to a subrecord in the mapped record1.

XML Maps directly to an attribute or text node in the XML record2.

EIS One-to-One Mapping

53-8 Oracle TopLink Developer’s Guide

Figure 53–7 illustrates a composite collection EIS mapping between Phone class attribute phoneNumbers and an XML record. Employee attribute phoneNumbers is mapped to an XML record composed of an EMPLOYEE element that contains a sequence of PHONE_NUMBER elements.

Figure 53–7 EIS Composite Collection Mappings

See Chapter 58, "Configuring an EIS Composite Collection Mapping" for more information.

EIS One-to-One MappingAn EIS one-to-one mapping is a reference mapping that represents the relationship between a single source and target object. The source object usually contains a foreign key (pointer) to the target object (key on source). Alternatively, the target object may contain a foreign key to the source object (key on target). Because both the source and target object use interactions, they must both be of a root object type (see "Configuring an EIS Descriptor as a Root or Composite Type" on page 28-8)

Table 53–6 summarizes the behavior of this mapping depending on the EIS record type you are using.

1 See also "Composite EIS Mappings" on page 53-4.2 See also "XML Composite Collection Mapping" on page 62-25.

Table 53–6 EIS One-to-One Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed A new indexed record is created for the target object1:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

Mapped A new mapped record is created for the target object1:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

EIS One-to-One Mapping

Understanding EIS Mappings 53-9

This section describes the following:

■ EIS One-to-One Mappings With Key on Source

■ EIS One-to-One Mappings With Key on Target

See Chapter 59, "Configuring an EIS One-to-One Mapping" for more information.

EIS One-to-One Mappings With Key on SourceFigure 53–8 illustrates a EIS one-to-one mapping between the Employee class attribute project and the Project class using XML records in a key on source design.

Figure 53–8 EIS One-to-One Mapping with Key on Source

When a read interaction is executed on the Employee object, TopLink puts the target Project object’s primary key into the Employee record as a simple value. TopLink then uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instance of Project and creates a record for it in the Employee object’s transaction. In this example, you can designate the Project class’s read interaction as the selection interaction.

The general procedure for creating and configuring this mapping is as follows:

1. Create a one-to-one EIS mapping on Employee attribute project.

2. Configure the reference descriptor as Project (see "Configuring Reference Descriptors" on page 54-2).

3. Configure the source and target foreign keys (see "Configuring Foreign Key Pairs" on page 59-1).

In this example:

XML .A new XML record is created for the target object:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

1 See also "Reference EIS Mappings" on page 53-4.

Table 53–6 (Cont.) EIS One-to-One Mapping by EIS Record Type

EIS Record Type Mapping Behavior

EIS One-to-One Mapping

53-10 Oracle TopLink Developer’s Guide

■ Source XML Field: @project-id

■ Target XML Field: @id

4. Configure the selection interaction (see "Configuring Selection Interaction" on page 54-3).

In this example, you can designate the Project class’s read interaction as the selection interaction.

Given the XSD shown in Example 53–1, you can configure an EIS one-to-one mapping with key on source, as Example 53–2 shows. In this case, the source object contains a foreign key reference to the target object. In the following example, the source object is Employee and the target object is Project. Here, the Employee object has a Project that is referenced using the project's id.

Example 53–1 XML Schema for EIS One-to-One Mapping with Key on Source

<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"attributeFormDefault="unqualified"><xsd:element name="employee" type="employee-type"/><xsd:element name="project" type="project-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="name" type="xsd:string"/><xsd:element name="project">

<xsd:complexType><xsd:sequence>

<xsd:element name="project-id" type="xsd:integer"/></xsd:sequence>

</xsd:complexType></xsd:element>

</xsd:sequence></xsd:complexType><xsd:complexType name="project-type">

<xsd:sequence><xsd:element name="id" type="xsd:integer"/><xsd:element name="leader" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Example 53–2 EIS One-to-One Mapping with Key On Source

// Employee descriptorEISDescriptor descriptor = new EISDescriptor();descriptor.setJavaClass(Employee.class);descriptor.setDataTypeName("employee");descriptor.setPrimaryKeyFieldName("name/text()");

EISOneToOneMapping projectMapping = new EISOneToOneMapping();projectMapping.setReferenceClass(Project.class);projectMapping.setAttributeName("project");projectMapping.dontUseIndirection();projectMapping.addForeignKeyFieldName("project/project-id/text()", "id/text()");

EIS One-to-One Mappings With Key on TargetFigure 53–9 illustrates EIS one-to-one mapping between the Employee class attribute project and the Project class using XML records in a key on target design. You still configure a one-to-one EIS mapping between Employee and Project, but in this

EIS One-to-One Mapping

Understanding EIS Mappings 53-11

design, the Project attribute leader contains the foreign key of the Employee object.

Figure 53–9 EIS One-to-One Mapping with Key on Target

When a read interaction is executed on the Employee object, TopLink uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instance of Project and creates a record for it in the Employee object’s transaction. In this example, the Project class’s read interaction is unlikely to be sufficient: it is likely implemented to read based on Project attribute Id, not on leader. If this is the case, you must define a separate selection interaction on the Employee descriptor that does the following: finds the Project, whose leader equals X, where X is the value of Employee attribute firstName.

Note that in this configuration, Project attribute leader is not persisted. If you want this attribute persisted, you must configure a one-to-one EIS mapping from it to Employee attribute firstName.

The general procedure for creating and configuring this mapping is as follows:

1. Create a one-to-one EIS mapping on Employee attribute project.

2. Configure the reference descriptor as Project (see "Configuring Reference Descriptors" on page 54-2).

3. Configure the source and target foreign keys (see "Configuring Foreign Key Pairs" on page 59-1).

In this example:

■ Source XML Field: firstName/text()

■ Target XML Field: leader/text()

4. Configure the selection interaction (see "Configuring Selection Interaction" on page 54-3).

In this example, you must define a separate selection interaction on the Employee descriptor.

Given the XSD shown in Example 53–3, you can configure an EIS one-to-one mapping with key on target, as Example 53–4 shows. In this case, the target object contains a foreign key reference to the source object. In the following example, the source object is Employee, and the target object is Project. Here, a Project references its leader using the employee's name.

EIS One-to-Many Mapping

53-12 Oracle TopLink Developer’s Guide

Example 53–3 XML Schema for EIS One-to-One Mapping with Key on Target

<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"attributeFormDefault="unqualified"><xsd:element name="employee" type="employee-type"/><xsd:element name="project" type="project-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="name" type="xsd:string"/><xsd:element name="project">

<xsd:complexType><xsd:sequence>

<xsd:element name="project-id" type="xsd:integer"/></xsd:sequence>

</xsd:complexType></xsd:element>

</xsd:sequence></xsd:complexType><xsd:complexType name="project-type">

<xsd:sequence><xsd:element name="id" type="xsd:integer"/><xsd:element name="leader" type="xsd:string"/>

</xsd:sequence></xsd:complexType></xsd:schema>

Example 53–4 EIS One-to-One Mapping with Key on Target

// Project descriptorEISDescriptor descriptor = new EISDescriptor();descriptor.setJavaClass(Project.class);descriptor.setDataTypeName("project");descriptor.setPrimaryKeyFieldName("id/text()");

EISOneToOneMapping leaderMapping = new EISOneToOneMapping();leaderMapping.setReferenceClass(Employee.class);leaderMapping.setAttributeName("leader");leaderMapping.dontUseIndirection();leaderMapping.addForeignKeyFieldName("leader/text()", "name/text()");

EIS One-to-Many MappingAn EIS one-to-many mapping is a reference mapping that represents the relationship between a single source object and a collection of target objects. The source object usually contains a foreign key (pointer) to the target objects (key on source); alternatively, the target objects may contain a foreign key to the source object (key on target). Because both the source and target objects use interactions, they must all be of a root object type (see "Configuring an EIS Descriptor as a Root or Composite Type" on page 28-8).

Table 53–7 summarizes the behavior of this mapping depending on the EIS record type you are using.

EIS One-to-Many Mapping

Understanding EIS Mappings 53-13

This section describes the following:

■ EIS One-to-Many Mappings With Key on Source

■ EIS One-to-Many Mappings With Key on Target

See Chapter 60, "Configuring an EIS One-to-Many Mapping" for more information.

EIS One-to-Many Mappings With Key on SourceFigure 53–10 illustrates an EIS one-to-many mapping between the Employee class attribute projects and multiple Project class instances using XML records in a key on source design.

Table 53–7 EIS One-to-Many Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed A new indexed record is created for each target object1:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

1 See also "Reference EIS Mappings" on page 53-4.

Mapped A new mapped record is created for each target object1:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

XML .A new XML record is created for each target object:

■ With the Key on Source use case, the foreign key(s) is added to the record for the source object for each target object.

■ With the Key on Target use case, the foreign key(s) is added to the record for the target object

EIS One-to-Many Mapping

53-14 Oracle TopLink Developer’s Guide

Figure 53–10 EIS One-to-Many Mapping with Key on Source

When a read interaction is executed on the Employee object, TopLink puts each target Project object’s foreign key into the Employee record as a subelement. If you specify only one pair of source and target XML fields, by default, the foreign keys are not grouped in the Employee record. If you specify more than one pair of source and target XML fields, you must choose a grouping element (see "Configuring Reference Descriptors" on page 54-2). Figure 53–10 shows an Employee record with grouping element Project. TopLink then uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instances of Project and creates a record for each in the Employee object’s transaction. In this example, you can designate the Project class’s read interaction as the selection interaction.

The general procedure for creating and configuring this mapping is as follows:

1. Create a one-to-many EIS mapping on Employee attribute project.

2. Configure the reference descriptor as Project (see "Configuring Reference Descriptors" on page 54-2).

3. Configure the source and target foreign keys (see "Configuring Foreign Key Pairs" on page 60-1).

In this example:

■ Source XML Field: PROJECT

■ Target XML Field: @ID

4. Configure the selection interaction (see "Configuring Selection Interaction" on page 54-3).

In this example, you can designate the Project class’s read interaction as the selection interaction.

Given the XSD shown in Example 53–3, you can configure an EIS one-to-many mapping with key on source, as Example 53–4 shows. In this case, the source object contains a foreign key reference to the target object. In the following example, the

EIS One-to-Many Mapping

Understanding EIS Mappings 53-15

source object is Employee, and the target object is Project. Here, the Employee object has one or more Project instances that are referenced by Project id.

Example 53–5 XML Schema for EIS One-to-Many Mapping with Key on Source

<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"attributeFormDefault="unqualified"><xsd:element name="employee" type="employee-type"/><xsd:element name="project" type="project-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="name" type="xsd:string"/><xsd:element name="projects">

<xsd:complexType><xsd:sequence>

<xsd:element name="project-id"type="xsd:integer" maxOccurs="unbounded"/>

</xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType><xsd:complexType name="project-type">

<xsd:sequence><xsd:element name="id" type="xsd:integer"/><xsd:element name="leader" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Example 53–6 EIS One-to-Many Mapping with Key on Source

// Employee descriptorEISDescriptor descriptor = new EISDescriptor();descriptor.setJavaClass(Employee.class);descriptor.setDataTypeName("employee");descriptor.setPrimaryKeyFieldName("name/text()");

EISOneToManyMapping projectMapping = new EISOneToManyMapping();projectMapping.setReferenceClass(Project.class);projectMapping.setAttributeName("projects");projectMapping.setForeignKeyGroupingElement("projects"); projectMapping.setIsForeignKeyRelationship(true); projectMapping.dontUseIndirection();projectMapping.addForeignKeyFieldName("project-id/text()", "id/text()");

EIS One-to-Many Mappings With Key on TargetFigure 53–9 illustrates an EIS one-to-many mapping between the Employee class attribute projects and multiple Project class instances using XML records in a key on target design. You still configure a one-to-one EIS mapping between Employee and Project but in this design, the Project attribute leader contains the foreign key of the Employee object.

EIS One-to-Many Mapping

53-16 Oracle TopLink Developer’s Guide

Figure 53–11 EIS One-to-Many Mapping with Key on Target

When a read interaction is executed on the Employee object, TopLink uses the selection interaction you configure on the Employee descriptor to retrieve the appropriate instances of Project and creates a record for each in the Employee object’s transaction. In this example, the Project class’s read interaction is unlikely to be sufficient: it is likely implemented to read based on Project attribute Id, not on leader. If this is the case, you must define a separate selection interaction on the Employee descriptor that does the following: finds the Project, whose leader equals X, where X is "Jane".

Note that in this configuration, Project attribute leader is not persisted. If you want this attribute persisted, you must configure a one-to-one EIS mapping from it to Employee attribute firstName.

The general procedure for creating and configuring this mapping is as follows:

1. Create a one-to-one EIS mapping on Employee attribute project.

2. Configure the reference descriptor as Project (see "Configuring Reference Descriptors" on page 54-2).

3. Configure the source and target foreign keys (see "Configuring Foreign Key Pairs" on page 59-1).

In this example, you select Foreign Keys Located On Source and specify one pair of source and target XML fields:

■ Source XML Field:

■ Target XML Field:

4. Configure the selection interaction (see "Configuring Selection Interaction" on page 54-3).

In this example, you must define a separate selection interaction on the Employee descriptor.

Given the XSD shown in Example 53–3, you can configure an EIS one-to-many mapping with key on target as Example 53–4 shows. In this case, the target object contains a foreign key reference to the source object. In the following example, the

EIS Transformation Mapping

Understanding EIS Mappings 53-17

source object is Employee, and the target object is Project. Here, each Project references its leader using the employee's name.

Example 53–7 XML Schema for EIS One-to-Many Mapping with Key on Target

<?xml version="1.0"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"attributeFormDefault="unqualified"><xsd:element name="employee" type="employee-type"/><xsd:element name="project" type="project-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="name" type="xsd:string"/><xsd:element name="projects">

<xsd:complexType><xsd:sequence>

<xsd:element name="project-id"type="xsd:integer" maxOccurs="unbounded"/>

</xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType><xsd:complexType name="project-type">

<xsd:sequence><xsd:element name="id" type="xsd:integer"/><xsd:element name="leader" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Example 53–8 EIS One-to-Many Mapping with Key on Target

// Project descriptorEISDescriptor descriptor = new EISDescriptor();descriptor.setJavaClass(Project.class);descriptor.setDataTypeName("project");descriptor.setPrimaryKeyFieldName("id/text()");

EISOneToManyMapping leaderMapping = new EISOneToOneMapping();leaderMapping.setReferenceClass(Employee.class);leaderMapping.setAttributeName("leader");leaderMapping.dontUseIndirection();leaderMapping.addForeignKeyFieldName("leader/text()", "name/text()");

EIS Transformation MappingA transformation EIS mapping lets you create a custom mapping, where one or more fields in an EIS record can be used to create the object to be stored in a Java class’s attribute.

Table 53–8 summarizes the behavior of this mapping depending on the EIS record type you are using.

Table 53–8 EIS Transformation Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Indexed .The field transformer adds data to the indexed record (you have access to the indexed record in the attribute transformer).

Mapped .The field transformer adds data to the mapped record (you have access to the mapped record in the attribute transformer).

EIS Transformation Mapping

53-18 Oracle TopLink Developer’s Guide

As Figure 53–12 illustrates, you configure the transformation mapping with an oracle.toplink.mappings.transformers.AttributeTransformer instance to perform the XML instance-to-Java attribute transformation at unmarshall time. In this example, the AttributeTransformer combines two XML text nodes into a single Java object.

Figure 53–12 EIS Transformation Mappings

See Chapter 61, "Configuring an EIS Transformation Mapping" for more information.

XML .The field transformer adds data to the XML record (you have access to the XML record in the attribute transformer).

Table 53–8 (Cont.) EIS Transformation Mapping by EIS Record Type

EIS Record Type Mapping Behavior

Configuring an EIS Mapping 54-1

54Configuring an EIS Mapping

This chapter describes how to configure an enterprise information service (EIS) mapping.

Table 54–2 lists the types of EIS mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

Table 54–2 lists the configurable options shared by two or more EIS mapping types.

Fore more information, see:

■ "Mapping Creation Overview" on page 31-1

■ "Understanding EIS Mappings" on page 53-1

Configuring Common EIS Mapping OptionsTable 54–2 lists the configurable options shared by two or more EIS mapping types. In addition to the configurable options described here, you must also configure the options described for the specific EIS Mapping Types, as shown in Table 54–1.

Table 54–1 Configuring EIS Mappings

If you are creating... See Also...

EIS Direct Mapping Chapter 55, "Configuring an EIS Direct Mapping"

EIS Composite Direct Collection Mapping Chapter 56, "Configuring an EIS Composite Direct Collection Mapping"

EIS Composite Object Mapping Chapter 57, "Configuring an EIS Composite Object Mapping"

EIS Composite Collection Mapping Chapter 58, "Configuring an EIS Composite Collection Mapping"

EIS One-to-One Mapping Chapter 59, "Configuring an EIS One-to-One Mapping"

EIS One-to-Many Mapping Chapter 60, "Configuring an EIS One-to-Many Mapping"

EIS Transformation Mapping Chapter 61, "Configuring an EIS Transformation Mapping"

Table 54–2 Common Options for EIS Mapping

Option TypeTopLink Workbench Java

"Configuring Read-Only Mappings" on page 32-2 Basic

"Configuring Indirection" on page 32-3 Basic

"Configuring XPath" on page 32-10 Basic

Configuring Reference Descriptors

54-2 Oracle TopLink Developer’s Guide

Configuring Reference DescriptorsIn EIS mappings that extend oracle.toplink.mappings.ForeignReferenceMapping or oracle.toplink.mappings.AggregateMapping class, attributes reference other TopLink descriptors–not the data source. You can select a descriptor in the current project, or a descriptor from some other project.

Table 54–3 summarizes which EIS mappings support this option.

Using TopLink WorkbenchTo specify a reference descriptor for an EIS mapping, use this procedure.

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

"Configuring a Default Null Value at the Mapping Level" on page 32-12

Basic

"Configuring Reference Descriptors" on page 54-2 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Private or Independent Relationships" on page 32-16

Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Selection Interaction" on page 54-3 Advanced

"Configuring the Use of a Single Node" on page 32-36 Advanced

"Configuring a JAXB Typesafe Enumeration Converter" on page 32-25

Advanced

Table 54–3 Mapping Support for Reference Descriptor

Mapping Using TopLink Workbench Using Java

EIS Direct Mapping

EIS Composite Direct Collection Mapping

EIS One-to-One Mapping

EIS One-to-Many Mapping

EIS Composite Object Mapping

EIS Composite Collection Mapping

EIS Transformation Mapping

Table 54–2 (Cont.) Common Options for EIS Mapping

Option TypeTopLink Workbench Java

Configuring Selection Interaction

Configuring an EIS Mapping 54-3

Figure 54–1 General Tab, Reference Descriptor Field

Use the Reference Descriptor field to select the descriptor referenced by this relationship mapping.

You can specify a reference descriptor that is not in the current TopLink Workbench project. For example, to create a mapping to an Employee class that does not exist in the current project, do the following:

1. Add the Employee class to your current project. See "Working With Projects" on page 18-10.

2. Create the relationship mapping to the Employee descriptor.

3. Deactivate the Employee descriptor. See "Active and Inactive Descriptors" on page 4-10.

When you generate the deployment XML for your project, the mapping to the Employee class will be included, but not the Employee class itself.

Configuring Selection InteractionIn EIS mappings that extend oracle.toplink.mappings.ForeignReferenceMapping class, TopLink uses a selection interaction to acquire the instance of the target object to which the mapping refers.

By default, TopLink uses the read interaction you define for the mapping’s reference descriptor (see "Configuring Reference Descriptors" on page 54-2). In most cases, this interaction is sufficient. If the reference descriptor’s read interaction is not sufficient, you can define a separate interaction.

Table 54–4 summarizes which EIS mappings support this option.

Note: For one-to-one and one-to-many EIS mappings, the reference descriptor must be a root descriptor. See "Configuring an EIS Descriptor as a Root or Composite Type" on page 28-8.

Configuring Selection Interaction

54-4 Oracle TopLink Developer’s Guide

For more information about how TopLink uses the selection criteria, see "Reference EIS Mappings" on page 53-4.

Using TopLink WorkbenchTo specify the selection interaction (such as Read Object) for the EIS mapping, use this procedure:

1. Select the one-to-many EIS mapping in the Navigator. Its properties appear in the Editor.

2. Click the Selection Interaction tab. The Selection Interaction tab appears.

Figure 54–2 Selection Interaction Tab

Use the following information to enter data in each field on the tab:

Table 54–4 Mapping Support for Selection Interaction

Mapping Using TopLink Workbench Using Java

EIS Direct Mapping

EIS Composite Direct Collection Mapping

EIS One-to-One Mapping

EIS One-to-Many Mapping

EIS Composite Object Mapping

EIS Composite Collection Mapping

EIS Transformation Mapping

Configuring Selection Interaction

Configuring an EIS Mapping 54-5

Field Description

Function Name The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.

Input Record Name The name passed to the J2C adapter when creating the input record.

Input Root Element Name The root element name to use for the input DOM.

Input Arguments The query argument name to map to the interaction field or XPath nodes in the argument record.

For example, if you are using XML records, use this option to map input argument name to the XPath name/first-name.

Output Arguments The result record field or XPath nodes to map to the correct nodes in the record used by the descriptor's mappings.

For example, if you are using XML records, use this option to map the output fname to name/first-name.

Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.

Input Result Path Use this option if the EIS interaction expects the interaction arguments to be nested in the XML record.

For example, specify arguments, if the arguments were to be nested under the root element exec-find-order, then under an arguments element.

Output Result Path The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.

Properties Any properties required by your EIS platform. For example, property name operation (from AQPlatform.QUEUE_OPERATION) and property value enqueue (from AQPlatform.ENQUEUE).

Configuring Selection Interaction

54-6 Oracle TopLink Developer’s Guide

Configuring an EIS Direct Mapping 55-1

55Configuring an EIS Direct Mapping

This chapter describes the various components that you must configure in order to use an EIS direct mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS Direct Mapping" on page 53-5

EIS Direct Mapping Configuration OverviewTable 55–1 lists the configurable options for an EIS direct mapping.

Table 55–1 Configurable Options for EIS Direct Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring the Use of a Single Node" on page 32-36 Advanced

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring a Default Null Value at the Mapping Level" on page 32-12

Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a JAXB Typesafe Enumeration Converter" on page 32-25

Advanced

EIS Direct Mapping Configuration Overview

55-2 Oracle TopLink Developer’s Guide

Configuring an EIS Composite Direct Collection Mapping 56-1

56Configuring an EIS Composite Direct

Collection Mapping

This chapter describes the various components that you must configure in order to use an EIS composite direct collection mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS Composite Direct Collection Mapping" on page 53-6

EIS Composite Direct Collection Mapping Configuration OverviewTable 56–1 lists the configurable options for an EIS composite direct collection mapping.

Table 56–1 Configurable Options for EIS Composite Direct Collection Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring the Use of a Single Node" on page 32-36 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a JAXB Typesafe Enumeration Converter" on page 32-25

Advanced

EIS Composite Direct Collection Mapping Configuration Overview

56-2 Oracle TopLink Developer’s Guide

Configuring an EIS Composite Object Mapping 57-1

57Configuring an EIS Composite

Object Mapping

This chapter describes the various components that you must configure in order to use an EIS composite object mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS Composite Object Mapping" on page 53-7

EIS Composite Object Mapping Configuration OverviewTable 57–1 lists the configurable options for an EIS composite object mapping.

Table 57–1 Configurable Options for EIS Composite Object Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Reference Descriptors" on page 54-2 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

EIS Composite Object Mapping Configuration Overview

57-2 Oracle TopLink Developer’s Guide

Configuring an EIS Composite Collection Mapping 58-1

58Configuring an EIS Composite Collection

Mapping

This chapter describes the various components that you must configure in order to use an EIS composite collection mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS Composite Collection Mapping" on page 53-7

EIS Composite Collection Mapping Configuration OverviewTable 58–1 lists the configurable options for an EIS composite collection mapping.

Table 58–1 Configurable Options for EIS Composite Collection Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Reference Descriptors" on page 54-2 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

EIS Composite Collection Mapping Configuration Overview

58-2 Oracle TopLink Developer’s Guide

Configuring an EIS One-to-One Mapping 59-1

59Configuring an EIS One-to-One Mapping

This chapter describes the various components that you must configure in order to use an EIS one-to-one mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS One-to-One Mapping" on page 53-5

EIS One-to-One Mapping Configuration OverviewTable 59–1 lists the configurable options for an EIS one-to-one mapping.

Configuring Foreign Key PairsIn a one-to-one EIS mapping, you relate a source object attribute to a target object attribute by specifying one or more pairs of source and target object fields.

In a one-to-one EIS mapping with key on source (see "EIS One-to-One Mappings With Key on Source" on page 53-9) using XML records, TopLink puts the target XML field value into the source object’s record as a simple value.

In a one-to-one EIS mapping with key on target (see "EIS One-to-One Mappings With Key on Target" on page 53-10) using XML records, TopLink uses the source XML field value in the selection interaction to acquire the appropriate instance of target object.

Table 59–1 Configurable Options for EIS One-to-One Mappings

Option TypeTopLink Workbench Java

"Configuring Reference Descriptors" on page 54-2 Basic

"Configuring Foreign Key Pairs" on page 59-1 Basic

"Configuring Bidirectional Relationship" on page 32-34 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Private or Independent Relationships" on page 32-16

Advanced

"Configuring Indirection" on page 32-3 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring Selection Interaction" on page 54-3 Basic

Configuring Foreign Key Pairs

59-2 Oracle TopLink Developer’s Guide

Using TopLink WorkbenchTo specify the source and target XML field pairs for a one-to-one EIS mapping, use this procedure:

1. Select the one-to-one EIS mapping in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab opens.

Figure 59–1 General Tab, Foreign Keys Field

3. Click Add in the Foreign Keys area to add a key pair. The Specify Field Pair dialog box appears.

Figure 59–2 Specify Field Pair Dialog Box

Click Browse to add a foreign key for the Source XPath and Target XPath fields.

Configuring an EIS One-to-Many Mapping 60-1

60Configuring an EIS One-to-Many Mapping

This chapter describes the various components that you must configure in order to use an EIS one-to-many mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS One-to-Many Mapping" on page 53-12

EIS One-to-Many Mapping Configuration OverviewTable 60–1 lists the configurable options for an EIS one-to-many mapping.

Configuring Foreign Key PairsIn a one-to-many EIS mapping, you relate a source object attribute to a target object attribute by specifying one or more pairs of source and target object fields.

In a one-to-many EIS mapping with key on source (see "EIS One-to-Many Mappings With Key on Source" on page 53-13) using XML records, TopLink puts the target XML field value into the source object’s record as a simple value. By default, these values are not grouped, as Example 60–1 shows.

Table 60–1 Configurable Options for EIS One-to-Many Mappings

Option TypeTopLink Workbench Java

"Configuring Reference Descriptors" on page 54-2 Basic

"Configuring Foreign Key Pairs" on page 60-1 Advanced

"Configuring Bidirectional Relationship" on page 32-34 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Private or Independent Relationships" on page 32-16

Advanced

"Configuring Indirection" on page 32-3 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring Selection Interaction" on page 54-3 Advanced

"Configuring Delete All Interactions" on page 60-3 Advanced

Configuring Foreign Key Pairs

60-2 Oracle TopLink Developer’s Guide

Example 60–1 Source Object XML Record without Grouping

<employee><name>Jane</name><project-id>3</project-id><project-id>4</project-id>

</employee>

If you specify more than one source and target XML field pair, you must specify a grouping element, as Example 60–2 shows.

Example 60–2 Source Object XML Record with Grouping

<employee><name>Jane</name><project>

<project-id>3</project-id><project-name>Project 3</project-name>

</project><project>

<project-id>4</project-id><project-name>Project 4</project-name>

</project></employee>

In a one-to-one EIS mapping with key on target (see "EIS One-to-Many Mappings With Key on Target" on page 53-15) using XML records, TopLink uses the source XML field value in the selection interaction to acquire the appropriate instances of target object.

Using TopLink WorkbenchTo specify the source and target XML field pairs for a one-to-many EIS mapping, use this procedure:

1. Select the one-to-one EIS mapping in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

Configuring Delete All Interactions

Configuring an EIS One-to-Many Mapping 60-3

Figure 60–1 Foreign Keys Field on General Tab

Use the following information to complete the Foreign Keys fields on the General tab:

Configuring Delete All InteractionsThe TopLink query and expression framework supports delete all queries. If your J2C adapter provides access to an EIS Delete All function, you can configure a delete all interaction to support TopLink delete all queries.

Field Description

Foreign Keys Located On Target Select if you are creating a one-to-many EIS mapping with key on target (see "EIS One-to-Many Mappings With Key on Target" on page 53-15).

Foreign Keys Located On Source Select if you are creating a one-to-many EIS mapping with key on source (see "EIS One-to-Many Mappings With Key on Source" on page 53-13).

Grouping Element Specify the element in which foreign key pairs are grouped in the source object’s EIS record.

If you specify only one pair of source and target XML fields, this is optional.

If you specify more than one pair of source and target XML fields, this is required.

Field Pairs Click Add to add a pair of source and target XML fields.

Specify Field Pair dialog box opens. Click Browse to add a foreign key for the Source XPath and Target XPath fields.

Configuring Delete All Interactions

60-4 Oracle TopLink Developer’s Guide

Using TopLink WorkbenchTo specify the DeleteAll interaction for an EIS one-to-many mapping, use this procedure:

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the Delete All Interaction tab. The Delete All Interaction tab appears.

Figure 60–2 Delete All Interaction Tab

Use the following information to enter data in each field on the Delete All Interaction tab:

Field Description

Function Name The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.

Input Record Name The name passed to the J2C adapter when creating the input record.

Input Root Element Name The root element name to use for the input DOM.

Input Arguments The query argument name to map to the interaction field or XPath nodes in the argument record.

For example, if you are using XML records, use this option to map input argument name to the XPath name/first-name.

Output Arguments The result record field or XPath nodes to map to the correct nodes in the record used by the descriptor's mappings.

For example, if you are using XML records, use this option to map the output fname to name/first-name.

Output arguments are not required if the interaction returns an XML result that matches the descriptor's mappings.

Configuring Delete All Interactions

Configuring an EIS One-to-Many Mapping 60-5

Input Result Path Use this option if the EIS interaction expects the interaction arguments to be nested in the XML record.

For example, specify arguments, if the arguments were to be nested under the root element exec-find-order, then under an arguments element.

Output Result Path The name of the EIS function that this call type (Read Object or Read All) invokes on the EIS.

Properties Any properties required by your EIS platform. For example, property name operation (from AQPlatform.QUEUE_OPERATION) and property value enqueue (from AQPlatform.ENQUEUE).

Field Description

Configuring Delete All Interactions

60-6 Oracle TopLink Developer’s Guide

Configuring an EIS Transformation Mapping 61-1

61Configuring an EIS Transformation Mapping

This chapter describes the various components that you must configure in order to use an EIS transformation mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "EIS Transformation Mapping" on page 53-17

EIS Transformation Mapping Configuration OverviewTable 61–1 lists the configurable options for an EIS transformation mapping.

Table 61–1 Configurable Options for EIS Transformation Mapping

Option TypeTopLink Workbench Java

"Configuring Attribute Transformer" on page 32-29 Basic

"Configuring Field Transformer Associations" on page 32-31 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mutable Mappings" on page 32-33 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

EIS Transformation Mapping Configuration Overview

61-2 Oracle TopLink Developer’s Guide

Part XIII XML Mappings

An XML mapping transforms object data members to the XML nodes of an XML document, whose structure is defined by an XML schema document (XSD).

This part contains the following chapters:

■ Chapter 62, "Understanding XML Mappings"

This chapter describes each of the different TopLink XML mapping types and important XML mapping concepts.

■ Chapter 63, "Configuring an XML Mapping"

This chapter explains how to configure TopLink XML mapping options common to two or more XML mapping types.

■ Chapter 64, "Configuring an XML Direct Mapping"

This chapter explains how to configure a direct XML mapping.

■ Chapter 65, "Configuring an XML Composite Direct Collection Mapping"

This chapter explains how to configure a composite direct collection XML mapping.

■ Chapter 66, "Configuring an XML Composite Object Mapping"

This chapter explains how to configure a composite object XML mapping including an XML mapping to a single named complex type of type xs:anyType.

■ Chapter 67, "Configuring an XML Composite Collection Mapping"

This chapter explains how to configure a composite collection XML mapping.

■ Chapter 68, "Configuring an XML Any Object Mapping"

This chapter explains how to configure an XML mapping to a single unnamed complex type specified as xs:any.

■ Chapter 69, "Configuring an XML Any Collection Mapping"

This chapter explains how to configure an XML mapping to an unnamed sequence of complex types specified as xs:any, an unnamed sequence of complex types of type xs:anyType, or a root element of type xs:anyType.

■ Chapter 70, "Configuring an XML Transformation Mapping"

This chapter explains how to configure a transformation XML mapping.

Understanding XML Mappings 62-1

62Understanding XML Mappings

An XML mapping transforms object data members to the XML nodes of an XML document whose structure is defined by an XML schema document (XSD).

This chapter describes the following:

■ XML Mapping Types

■ XML Mapping Concepts

XML Mapping TypesTopLink supports the XML mappings listed in Table 62–1.

Table 62–1 TopLink XML Mapping Types

Mapping Type Description TypeTopLink Workbench Java

"XML Direct Mapping" on page 62-5 Map a simple object attribute to an XML attribute or text node.

Basic

"XML Composite Direct Collection Mapping" on page 62-14

Map a collection of simple object attributes to XML attributes or text nodes.

Basic

"XML Composite Object Mapping" on page 62-21

Map any attribute that contains a single object to an XML element. The TopLink runtime uses the descriptor for the referenced object to populate the contents of that element.

Basic

"XML Composite Collection Mapping" on page 62-25

Map an attribute that contains a homogenous collection of objects to multiple XML elements. The TopLink runtime uses the descriptor for the referenced object to populate the contents of those elements.

Basic

XML Mapping Concepts

62-2 Oracle TopLink Developer’s Guide

XML Mapping ConceptsYou can map the attributes of a Java object to a combination of XML simple and complex types using a wide variety of XML mapping types.

TopLink stores XML mappings for each class in the class descriptor. TopLink uses the descriptor to instantiate objects mapped from an XML document and to store new or modified objects as an XML document.

To configure XML mappings, Oracle recommends that you use TopLink Workbench and its rich graphical user interface (GUI) environment to set the descriptor properties and configure the mappings.

This section describes concepts unique to TopLink XML mappings, including the following:

■ Mapping to Simple and Complex Types

■ Mapping Order

■ XPath Support

■ xsd:list and xsd:union Support

■ xs:any and xs:anyType Support

■ jaxb:class Support

■ Typesafe Enumeration Support

■ Mapping Extensions

Mapping to Simple and Complex TypesConsider the XML document shown in Example 62–1.

Example 62–1 XML Document

<EMPLOYEE ID="123"><NAME>Jane Doe</NAME>

"XML Any Object Mapping" on page 62-27

The any object XML mapping is similar to the composite object XML mapping (see "XML Composite Object Mapping" on page 62-21), except that the reference object may be of different types (including String), not necessarily related to each other through inheritance or a common interface.

Advanced

"XML Any Collection Mapping" on page 62-29

The any collection XML mapping is similar to the composite collection XML mapping (see "XML Composite Collection Mapping" on page 62-25) except that the referenced objects may be of different types (including String), not necessarily related to each other through inheritance or a common interface.

Advanced

"XML Transformation Mapping" on page 62-31

Create custom mappings where one or more XML nodes can be used to create the object to be stored in a Java class’s attribute.

Advanced

Table 62–1 (Cont.) TopLink XML Mapping Types

Mapping Type Description TypeTopLink Workbench Java

XML Mapping Concepts

Understanding XML Mappings 62-3

<ADDRESS><STREET>123 Any St.</STREET><CITY>MyCity</CITY>

</ADDRESS></EMPLOYEE>

In general, using TopLink XML mappings, you can map a Java class to a simple type (such as NAME) or to a complex type (such as ADDRESS).

Specifically, you can map a Java object’s simple attributes to XML attributes (such as ID) and text nodes (such as NAME). You can also map a Java object’s relationships to XML elements (such as ADDRESS).

Table 62–2 summarizes the XML simple and complex types supported by each TopLink XML mapping.

Mapping OrderUnlike relational database mappings, the order in which mappings are persisted in XML is significant.

The order in which you define XML mappings in TopLink (whether in TopLink Workbench or in Java code) including the order in which you define mapping components such as Transformers (see "XML Transformation Mapping" on page 62-31) is reflected in the order, in which TopLink persists data in an XML document.

XPath SupportTopLink uses XPath statements to efficiently map the attributes of a Java object to locations in an XML document. For more information about using XPath with XML mappings, see "Mappings and XPath" on page 30-15.

xsd:list and xsd:union SupportYou can use XML direct (see "XML Direct Mapping" on page 62-5) and composite direct collection (see "XML Composite Direct Collection Mapping" on page 62-14) mappings to map to xsd:list and xsd:union types in an XML document.

For more information, see "Mappings and xsd:list and xsd:union Types" on page 30-17.

Table 62–2 XML Mapping Support for XML Simple and Complex Types

MappingXML Attribute

XML Text Node

XML Element

XML Direct Mapping

XML Composite Direct Collection Mapping

XML Composite Object Mapping

XML Composite Collection Mapping

XML Any Object Mapping

XML Any Collection Mapping

XML Transformation Mapping

XML Mapping Concepts

62-4 Oracle TopLink Developer’s Guide

xs:any and xs:anyType SupportIn an XML schema, you can define elements and complex types that correspond to any data type using xs:any and xs:anyType. You can map objects to such elements and complex types using XML mappings XMLAnyObjectMapping and XMLAnyCollectionMapping.

Table 62–3 lists the XML mappings to use with common applications of xs:any and xs:anyType. For more details, see the specified XML mapping type.

jaxb:class SupportYou can configure an XML composite object mapping (see "XML Composite Object Mapping" on page 62-21) to accommodate jaxb:class customizations with the following XSD structures:

■ all

■ sequence

■ choice

■ group

For more information, see "Mappings and the jaxb:class Customization" on page 30-20.

Typesafe Enumeration SupportYou can map a Java attribute to such a typesafe enumeration using the JAXBTypesafeEnumConverter with an XMLDirectMapping or XMLCompositeDirectCollectionMapping with XML documents.

For more information, see "Mappings and JAXB Typesafe Enumerations" on page 30-24

Mapping ExtensionsIf existing TopLink XML mappings do not meet your needs, you can create custom XML mappings using XML mapping extensions, including object type, serialized object, type conversion converters, and a simple type translator. For more information, see "Mapping Converters and Transformers" on page 30-10.

Table 62–3 XML Mappings and XML Schema xs:any and xs:anyType

Use XML Mapping ... To Map XML Schema Definition ...

See "XML Any Object Mapping" on page 62-27

Element with a single1 unnamed complex type specified as xs:any.

1 minOccurs and maxOccurs are both equal to 1.

See "XML Any Collection Mapping" on page 62-29

Element with an unnamed sequence2 of complex types specified as xs:any.

Element with a named sequence2 of complex types of type xs:anyType.

Root element of type xs:anyType.

2 maxOccurs is greater than 1.

XML Direct Mapping

Understanding XML Mappings 62-5

XML Direct MappingXML direct mappings map a Java attribute directly to XML text nodes. You can use an XML direct mapping in the following scenarios:

■ Mapping to a Text Node

■ Mapping to an Attribute

■ Mapping to a Specified Schema Type

■ Mapping to a List Field With an XML Direct Mapping

■ Mapping to a Union Field With an XML Direct Mapping

■ Mapping to a Union of Lists With an XML Direct Mapping

■ Mapping to a Union of Unions With an XML Direct Mapping

■ Mapping With a Simple Type Translator

See Chapter 64, "Configuring an XML Direct Mapping" for more information.

Mapping to a Text NodeThis section describes using an XML direct mapping when:

■ Mapping to a Simple Text Node

■ Mapping to a Text Node in a Simple Sequence

■ Mapping to a Text Node in a Subelement

■ Mapping to a Text Node by Position

Mapping to a Simple Text NodeGiven the XML schema in Example 62–2, Figure 62–1 illustrates an XML direct mapping to a simple text node in a corresponding XML document. Example 62–3 shows how to configure this mapping in Java.

Example 62–2 Schema for XML Direct Mapping to Simple Text Node

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="phone-number" type="xsd:string"/></xsd:schema>

Figure 62–1 XML Direct Mapping to Simple Text Node

Note: Do not confuse an XML direct mapping with a relational direct-to-XMLType mapping (see "Direct-to-XMLType Mapping" on page 33-4).

XML Direct Mapping

62-6 Oracle TopLink Developer’s Guide

Example 62–3 Java for XML Direct Mapping to Simple Text Node

XMLDirectMapping numberMapping = new XMLDirectMapping();numberMapping.setAttributeName("number");numberMapping.setXPath("text()");

Mapping to a Text Node in a Simple SequenceGiven the XML schema in Example 62–4, Figure 62–2 illustrates an XML direct mapping to individual text nodes in a sequence in a corresponding XML document. Example 62–5 shows how to configure this mapping in Java.

Example 62–4 Schema for XML Direct Mapping to a Text Node in a Simple Sequence

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Figure 62–2 XML Direct Mapping to a Text Node in a Simple Sequence

Example 62–5 Java for XML Direct Mapping to a Text Node in a Simple Sequence

XMLDirectMapping firstNameMapping = new XMLDirectMapping();firstNameMapping.setAttributeName("firstName");firstNameMapping.setXPath("first-name/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();lastNameMapping.setAttributeName("lastName");lastNameMapping.setXPath("last-name/text()");

Mapping to a Text Node in a SubelementGiven the XML schema in Example 62–6, Figure 62–3 illustrates an XML direct mapping to a text node in a subelement in a corresponding XML document. Example 62–7 shows how to configure this mapping in Java.

XML Direct Mapping

Understanding XML Mappings 62-7

Example 62–6 Schema for XML Direct Mapping to a Text Node in a Subelement

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="personal-info">

<xsd:complexType><xsd:sequence>

<xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/>

<xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType></xsd:schema>

Figure 62–3 XML Direct Mapping to a Text Node in a Subelement

Example 62–7 Java for XML Direct Mapping to a Text Node in a Subelement

XMLDirectMapping firstNameMapping = new XMLDirectMapping();firstNameMapping.setAttributeName("firstName");firstNameMapping.setXPath("personal-info/first-name/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();lastNameMapping.setAttributeName("lastName");lastNameMapping.setXPath("personal-info/last-name/text()");

Mapping to a Text Node by PositionGiven the XML schema in Example 62–8, Figure 62–4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62–9 shows how to configure this mapping in Java.

Example 62–8 Schema for XML Direct Mapping to Text Node by Position

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="name" type="xsd:string" maxOccurs="2"/>

</xsd:sequence></xsd:complexType>

XML Direct Mapping

62-8 Oracle TopLink Developer’s Guide

</xsd:schema>

Figure 62–4 XML Direct Mapping to Text Node by Position

Example 62–9 Java for XML Direct Mapping to Text Node by Position

XMLDirectMapping firstNameMapping = new XMLDirectMapping();firstNameMapping.setAttributeName("firstName");firstNameMapping.setXPath("name[1]/text()");

XMLDirectMapping lastNameMapping = new XMLDirectMapping();lastNameMapping.setAttributeName("lastName");lastNameMapping.setXPath("name[2]/text()");

Mapping to an AttributeGiven the XML schema in Example 62–8, Figure 62–4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62–9 shows how to configure this mapping in Java.

Example 62–10 Schema for XML Direct Mapping to an Attribute

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"><xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:attribute name="id" type="xsd:integer"/></xsd:complexType>

</xsd:schema>

Figure 62–5 XML Direct Mapping to an Attribute

Example 62–11 Java for XML Direct Mapping to an Attribute

XMLDirectMapping idMapping = new XMLDirectMapping();

XML Direct Mapping

Understanding XML Mappings 62-9

idMapping.setAttributeName("id");idMapping.setXPath("@id");

Mapping to a Specified Schema TypeIn most cases, TopLink can determine the target format in the XML document. However, there are cases where you must specify which one of a number of possible targets TopLink should use. For example, a java.util.Calendar could be marshalled to a schema date, time, or dateTime node, or a byte[] could be marshalled to a schema hexBinary or base64Binary node.

Given the XML schema in Example 62–8, Figure 62–4 illustrates an XML direct mapping to a text node by position in a corresponding XML document. Example 62–9 shows how to configure this mapping in Java.

Example 62–12 Schema for XML Direct Mapping to a Specified Schema Type

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="picture" type="xsd:hexBinary"/><xsd:element name="resume" type="xsd:base64Binary"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Figure 62–6 XML Direct Mapping to a Specified Schema Type

Example 62–13 Java for XML Direct Mapping to a Specified Schema Type

XMLDirectMapping pictureMapping = new XMLDirectMapping();pictureMapping.setAttributeName("picture");pictureMapping.setXPath("picture/text()");XMLField pictureField = (XMLField) pictureMapping.getField();pictureField.setSchemaType(XMLConstants.HEX_BINARY_QNAME);

XMLDirectMapping resumeMapping = new XMLDirectMapping();resumeMapping.setAttributeName("resume");resumeMapping.setXPath("resume/text()");XMLField resumeField = (XMLField) resumeMapping.getField();resumeField.setSchemaType(XMLConstants.BASE_64_BINARY_QNAME);

XML Direct Mapping

62-10 Oracle TopLink Developer’s Guide

Mapping to a List Field With an XML Direct MappingGiven the XML schema in Example 62–14, Figure 62–7 illustrates an XML direct mapping to an xsd:list type in a corresponding XML document when you represent the list in your object model as a String of white space delimited tokens. Example 62–15 shows how to configure this mapping in Java.

Example 62–14 Schema for XML Direct Mapping to a List Field

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="tasks" type="tasks-type"/>

</xsd:sequence></xsd:complexType><xsd:simpleType name="tasks-type">

<xsd:list itemType="xsd:string"/></xsd:simpleType>

</xsd:schema>

Figure 62–7 XMLDirect Mapping to a List Field

Example 62–15 Java for XML Direct Mapping to a List Field Node

XMLDirectMapping tasksMapping = new XMLDirectMapping();tasksMapping.setAttributeName("tasks");XMLField myField = new XMLField("tasks/text()"); // pass in the XPathmyField.setUsesSingleNode(true);tasksMapping.setField(myField);

Mapping to a Union Field With an XML Direct MappingGiven the XML schema in Example 62–16, Figure 62–8 illustrates a Java class that can be mapped to a corresponding XML document. Note the shoeSize attribute in this class: when using a union field, the corresponding attribute must be able to store all possible values.

Example 62–16 Schema for XML Direct Mapping to a Union Field

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="shoe-size" type="size-type"/>

</xsd:sequence></xsd:complexType><xsd:simpleType name="size-type">

<xsd:union memberTypes="xsd:decimal xsd:string"/>

XML Direct Mapping

Understanding XML Mappings 62-11

</xsd:simpleType></xsd:schema>

Figure 62–8 Java Class for XML Direct Mapping to a Union Field

Figure 62–9 illustrates an XML direct mapping to a union field in an XML document that conforms to the schema in Example 62–16. When TopLink unmarshalls the XML document, it tries each of the union types until it can make a successful conversion. The first schema type in the union is xsd:decimal. Because "10.5" is a valid decimal, TopLink converts the value to the appropriate type. If the Object attribute is specific enough to trigger an appropriate value, TopLink will use that type instead. Otherwise, TopLink uses a default (in this case BigDecimal). You can override this behavior in Java code.

Figure 62–9 XML Direct Mapping to the First Valid Union Type

Figure 62–10 illustrates an XML direct mapping to union field in another XML document that conforms to the schema in Example 62–16. In this document, the value "M" is not a valid xsd:decimal type so the next union type is tried. The next union type is xsd:string and a conversion can be done.

Figure 62–10 XML Direct Mapping to Another Valid Union Type

Example 62–17 shows how to configure this mapping in Java.

Example 62–17 Java for XML Direct Mapping to a Union Type

XMLDirectMapping shoeSizeMapping = new XMLDirectMapping();shoeSizeMapping.setAttributeName("shoeSize");XMLUnionField shoeSizeField = new XMLUnionField();shoeSizeField.setXPath("shoe-size/text()");shoeSizeField.addSchemaType(XMLConstants.DECIMAL_QNAME);shoeSizeField.addSchemaType(XMLConstants.STRING_QNAME);shoeSizeMapping.setField(shoeSizeField);

To override the default conversion, use the XMLUnionField method addConversion:

XML Direct Mapping

62-12 Oracle TopLink Developer’s Guide

shoeSizeField.addConversion(XMLConstants.DECIMAL_QNAME, Float.class);

Mapping to a Union of Lists With an XML Direct MappingGiven the XML schema in Example 62–18, Figure 62–11 illustrates an XML direct mapping to a union of lists in a corresponding XML document. Example 62–19 shows how to configure this mapping in Java.

Example 62–18 Schema for XML Direct Mapping to Union of Lists

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="vacation" type="unionOfLists"/><xsd:simpleType name="unionOfLists">

<xsd:union memberTypes="xsd:double"><xsd:simpleType>

<xsd:list itemType="xsd:date"/></xsd:simpleType><xsd:simpleType>

<xsd:list itemType="xsd:integer"/></xsd:simpleType>

</xsd:union></xsd:simpleType>

</xsd:schema>

Figure 62–11 XML Direct Mapping to Union of Lists

Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.

Example 62–19 Java for XML Direct Mapping to Union of Lists

XMLDirectMapping mapping = new XMLDirectMapping();mapping.setAttributeName("vacation");mapping.setXPath("UnionOfLists/text()");

Mapping to a Union of Unions With an XML Direct MappingGiven the XML schema in Example 62–20, Figure 62–12 illustrates a Java class that can be mapped to a corresponding XML document. Example 62–27 shows how to configure this mapping in Java.

Example 62–20 Schema for XML Direct Mapping to a Union of Unions

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="vacation" type="unionOfUnions"/><xsd:simpleType name="unionOfUnions">

<xsd:union><xsd:simpleType>

<xsd:union><xsd:simpleType>

XML Direct Mapping

Understanding XML Mappings 62-13

<xsd:list itemType="xsd:date"/></xsd:simpleType><xsd:simpleType>

<xsd:list itemType="xsd:integer"/></xsd:simpleType>

</xsd:union></xsd:simpleType><xsd:simpleType>

<xsd:union><xsd:simpleType>

<xsd:list itemType="xsd:string"/></xsd:simpleType><xsd:simpleType>

<xsd:list itemType="xsd:float"/></xsd:simpleType>

</xsd:union></xsd:simpleType>

</xsd:union></xsd:simpleType>

</xsd:schema>

Figure 62–12 Java Class for XML Direct Mapping to a Union of Unions

Example 62–21 Java for XML Direct Mapping to a Union of Unions

XMLDirectMapping vacationMapping = new XMLDirectMapping();vacationMapping.setAttributeName("vacation");XMLUnionField vacationField = new XMLUnionField();vacationField.setXPath("vacation/text()");vacationField.addSchemaType(XMLConstants.DATE_QNAME);vacationField.addSchemaType(XMLConstants.INTEGER_QNAME);vacationField.addSchemaType(XMLConstants.STRING_QNAME);vacationField.addSchemaType(XMLConstants.FLOAT_QNAME);vacationMapping.setField(vacationField);

Mapping With a Simple Type TranslatorIf the type of a node is not defined in your XML schema, you can configure an XML direct mapping to use the xsi:type attribute to provide type information.

Given the XML schema fragment in Example 62–22, Figure 62–13 illustrates a Java class that can be mapped to a corresponding XML document.

Example 62–22 Schema for XML Direct Mapping with Simple Type Translator

...<xs:element name="area-code" type="anySimpleType"/><xs:element name="number" type="anySimpleType"/>

...

XML Composite Direct Collection Mapping

62-14 Oracle TopLink Developer’s Guide

Figure 62–13 Java Class for XML Direct Mapping with Simple Type Translator

Figure 62–14 illustrates an XML direct mapping with a simple type translator in an XML document that conforms to the schema in Example 62–22.

Figure 62–14 XML Direct Mapping with a Simple Type Translator

Example 62–23 shows how to configure this mapping in Java.

Example 62–23 Java for XML Direct Mapping with Simple Type Translator

XMLDirectMapping numberMapping = new XMLDirectMapping();numberMapping.setAttributeName("number");numberMapping.setXPath("number/text()");XMLField numberField = (XMLField) numberMapping.getField();numberField.setIsTypedTextField(true);

For more information, see "Simple Type Translator" on page 30-12.

XML Composite Direct Collection MappingXML composite direct collection mappings map a Java collection of simple object attributes to XML attributes and text nodes. Use multiplicity settings to specify an element as a collection. The XML schema allows you to define minimum and maximum occurrences. You can use a composite direct collection XML mapping in the following scenarios:

■ Mapping to Multiple Text Nodes

■ Mapping to Multiple Attributes

■ Mapping to a Single Text Node With an XML Composite Direct Collection Mapping

■ Mapping to a Single Attribute With an XML Composite Direct Collection Mapping

■ Mapping to a List of Unions With an XML Composite Direct Collection Mapping

■ Mapping to a Union of Lists With an XML Composite Direct Collection Mapping

■ Specifying the Content Type of a Collection With an XML Composite Direct Collection Mapping

See Chapter 65, "Configuring an XML Composite Direct Collection Mapping" for more information.

XML Composite Direct Collection Mapping

Understanding XML Mappings 62-15

Mapping to Multiple Text NodesThis section describes using a composite direct collection XML mapping when:

■ Mapping to a Simple Sequence

■ Mapping to a Sequence in a Subelement

Mapping to a Simple SequenceGiven the XML schema in Example 62–24, Figure 62–15 illustrates a composite direct collection XML mapping to a simple sequence of text nodes in a corresponding XML document. Example 62–25 shows how to configure this mapping in Java.

Example 62–24 Schema for Composite Direct Collection XML Mapping to a Simple Sequence

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="task" type="xsd:string" maxOccurs="unbounded"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Figure 62–15 Composite Direct Collection XML Mapping to a Simple Sequence

Example 62–25 Java for Composite Direct Collection XML Mapping to a Simple Sequence

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("tasks");tasksMapping.setXPath("task/text()");

Mapping to a Sequence in a SubelementGiven the XML schema in Example 62–26, Figure 62–16 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 62–27 shows how to configure this mapping in Java.

Example 62–26 Schema for Composite Direct Collection XML Mapping to a Subelement Sequence

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence>

XML Composite Direct Collection Mapping

62-16 Oracle TopLink Developer’s Guide

<xsd:element name="tasks"><xsd:complexType>

<xsd:sequence><xsd:element name="task" type="xsd:string" maxOccurs="unbounded"/>

</xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType></xsd:schema>

Figure 62–16 Composite Direct Collection XML Mapping to a Subelement Sequence

Example 62–27 Java for Composite Direct Collection XML Mapping to a Subelement Sequence

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("tasks");tasksMapping.setXPath("tasks/task/text()");

Mapping to Multiple AttributesGiven the XML schema in Example 62–28, Figure 62–17 illustrates a composite direct collection XML mapping to a sequence of text nodes in a subelement in a corresponding XML document. Example 62–29 shows how to configure this mapping in Java.

Example 62–28 Schema for Composite Direct Collection XML Mapping to Multiple Attributes

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="tasks" maxOccurs="unbounded">

<xsd:complexType><xsd:attribute name="task" type="xsd:string"/>

</xsd:complexType></xsd:element>

</xsd:sequence></xsd:complexType>

</xsd:schema>

XML Composite Direct Collection Mapping

Understanding XML Mappings 62-17

Figure 62–17 Composite Direct Collection XML Mapping to Multiple Attributes

Example 62–29 Java for Composite Direct Collection XML Mapping to Multiple Attributes

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("tasks/@task");tasksMapping.setXPath("task/text()");

Mapping to a Single Text Node With an XML Composite Direct Collection MappingWhen you map a collection to a single node, the contents of the node is treated as a space-separated list.

Given the XML schema in Example 62–30, Figure 62–18 illustrates a composite direct collection XML mapping to a single text node in a corresponding XML document. Example 62–31 shows how to configure this mapping in Java.

Example 62–30 Schema for XML Composite Direct Collection Mapping to a Single Text Node

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="tasks" type="tasks-type"/>

</xsd:sequence></xsd:complexType><xsd:simpleType name="tasks-type">

<xsd:list itemType="xsd:string"/></xsd:simpleType>

</xsd:schema>

Figure 62–18 XML Composite Direct Collection Mapping to a Single Text Node

Example 62–31 Java for XML Composite Direct Collection Mapping to a Single Text Node

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("tasks");

XML Composite Direct Collection Mapping

62-18 Oracle TopLink Developer’s Guide

tasksMapping.setXPath("tasks/text()");tasksMapping.setUsesSingleNode(true);

Mapping to a Single Attribute With an XML Composite Direct Collection MappingGiven the XML schema in Example 62–32, Figure 62–19 illustrates a composite direct collection XML mapping to a single attribute in a corresponding XML document. Example 62–33 shows how to configure this mapping in Java.

Example 62–32 Schema for XML Composite Direct Collection Mapping to a Single Attribute

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:attribute name="tasks" type="tasks-type"/></xsd:complexType><xsd:simpleType name="tasks-type">

<xsd:list itemType="xsd:string"/></xsd:simpleType>

</xsd:schema>

Figure 62–19 XML Composite Direct Collection Mapping to a Single Attribute

Example 62–33 Java for XML Composite Direct Collection Mapping to a Single Attribute

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("tasks");tasksMapping.setXPath("@tasks");tasksMapping.setUsesSingleNode(true);

Mapping to a List of Unions With an XML Composite Direct Collection MappingGiven the XML schema in Example 62–34, Figure 62–20 illustrates a composite direct collection XML mapping to a list of unions in a corresponding XML document. Example 62–35 shows how to configure this mapping in Java.

Example 62–34 Schema for XML Composite Direct Collection Mapping to List of Unions

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="vacation" type="listOfUnions"/><xsd:simpleType name="listOfUnions">

<xsd:list><xsd:simpleType>

<xsd:union memberTypes="xsd:date xsd:integer"/></xsd:simpleType>

</xsd:list>

XML Composite Direct Collection Mapping

Understanding XML Mappings 62-19

</xsd:simpleType></xsd:schema>

Figure 62–20 Composite XML Direct Collection Mapping to List of Unions

Example 62–35 Java for XML Composite Direct Collection Mapping to List of Unions

XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();mapping.setAttributeName("myattribute");XMLUnionField field = new XMLUnionField("listOfUnions/text()");mapping.addSchemaType(new Qname(url,"int"));mapping.addSchemaType(new Qname(url,"date"));mapping.setField(field);mapping.useSingleElement(false);

Mapping to a Union of Lists With an XML Composite Direct Collection MappingGiven the XML schema in Example 62–34, Figure 62–20 illustrates an XML composite direct collection mapping to a list of unions in a corresponding XML document. Example 62–35 shows how to configure this mapping in Java.

Example 62–36 Schema for XML Composite Direct Collection Mapping to a Union of Lists

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="vacation" type="unionOfLists"/><xsd:simpleType name="unionOfLists">

<xsd:union memberTypes="xsd:double"><xsd:simpleType>

<xsd:list itemType="xsd:date"/></xsd:simpleType><xsd:simpleType>

<xsd:list itemType="xsd:integer"/></xsd:simpleType>

</xsd:union></xsd:simpleType>

</xsd:schema>

Figure 62–21 XML Composite Direct Collection Mapping to a Union of Lists

Note that in this example, valid XML documents contain either all xsd:double, all xsd:date, or all xsd:integer values.

XML Composite Direct Collection Mapping

62-20 Oracle TopLink Developer’s Guide

Example 62–37 Java for XML Composite Direct Collection Mapping to a Union of Lists

XMLCompositeDirectCollectionMapping mapping = new XMLCompositeDirectCollectionMapping();mapping.setAttributeName("myattribute");mapping.useSingleElement(false);XMLUnionField unionField = new XMLUnionField("UnionOfLists/text()");field.addSchemaType(new Qname(url," integer"))field.addSchemaType (new Qname(url," date"))field.addSchemaType (new Qname(url," double"))field.setUsesSingleNode(false);

Specifying the Content Type of a Collection With an XML Composite Direct Collection Mapping

By default, TopLink will treat the node values read by a composite direct collection XML mapping as objects of type String. You can override this behavior by specifying the type of the collection’s contents.

Given the XML schema in Example 62–38, Figure 62–22 illustrates an XML composite direct collection mapping to a simple sequence in a corresponding XML document. The mapping is configured to specify the content type of the collection as Calendar. Example 62–39 shows how to configure this mapping in Java.

Example 62–38 Schema for XML Composite Direct Collection Mapping with Specified Content Type

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="employee" type="employee-type"/><xsd:complexType name="employee-type">

<xsd:sequence><xsd:element name="vacation" type="xsd:string" maxOccurs="unbounded"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Figure 62–22 XML Composite Direct Collection Mapping with Specified Content Type

Example 62–39 Java for XML Composite Direct Collection Mapping with Specified Content Type

XMLCompositeDirectCollectionMapping tasksMapping = new XMLCompositeDirectCollectionMapping();tasksMapping.setAttributeName("vacationDays");tasksMapping.setXPath("vacation/text()");tasksMapping.setAttributeElementClass(Calendar.class);

XML Composite Object Mapping

Understanding XML Mappings 62-21

XML Composite Object MappingXML composite object mappings represent a relationship between two classes. In XML, the "owned" class may be nested with the element tag representing the "owning" class. You can use a composite object XML mapping in the following scenarios:

■ Mapping Into the Parent Record

■ Mapping to an Element

■ Mapping to Different Elements by Element Name

■ Mapping to Different Elements by Element Position

See Chapter 66, "Configuring an XML Composite Object Mapping" for more information.

Mapping Into the Parent RecordThe composite object may be mapped to the same record as the parent.

Given the XML schema in Example 62–40, Figure 62–23 illustrates an XML composite object mapping into the parent record in a corresponding XML document. Example 62–41 shows how to configure this mapping in Java.

Example 62–40 Schema for XML Composite Object Mapping into the Parent Record

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/><xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Note: The nodes mapped to by the composite object must be sequential.

XML Composite Object Mapping

62-22 Oracle TopLink Developer’s Guide

Figure 62–23 XML Composite Object Mapping into the Parent Record

Example 62–41 Java for XML Composite Object Mapping into the Parent Record

XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();addressMapping.setAttributeName("address");addressMapping.setXPath(".");addressMapping.setReferenceClass(Address.class);

Mapping to an ElementGiven the XML schema in Example 62–42, Figure 62–24 illustrates an XML composite object mapping to an element in a corresponding XML document. Example 62–43 shows how to configure this mapping in Java.

Example 62–42 Schema for XML Composite Object Mapping to an Element

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/><xsd:element name="address">

<xsd:complexType><xsd:sequence>

<xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType></xsd:schema>

XML Composite Object Mapping

Understanding XML Mappings 62-23

Figure 62–24 XML Composite Object Mapping to an Element

Example 62–43 Java for XML Composite Object Mapping to an Element

XMLCompositeObjectMapping addressMapping = new XMLCompositeObjectMapping();addressMapping.setAttributeName("address");addressMapping.setXPath("address");addressMapping.setReferenceClass(Address.class);

Mapping to Different Elements by Element NameAn object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by name .

Given the XML schema in Example 62–44, Figure 62–25 illustrates an XML composite object mapping to different elements by name in a corresponding XML document. Example 62–45 shows how to configure this mapping in Java.

Example 62–44 Schema for XML Composite Object Mapping to Elements by Name

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/><xsd:element name="billing-address" type="address-type"/><xsd:element name="shipping-address" type="address-type"/>

</xsd:sequence></xsd:complexType><xsd:complexType name="address-type">

<xsd:sequence><xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:schema>

XML Composite Object Mapping

62-24 Oracle TopLink Developer’s Guide

Figure 62–25 XML Composite Object Mapping to Elements by Name

Example 62–45 Java for XML Composite Object Mapping to Elements by Name

XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();billingAddressMapping.setAttributeName("billingAddress");billingAddressMapping.setXPath("billing-address");billingAddressMapping.setReferenceClass(Address.class);

XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();shippingAddressMapping.setAttributeName("shippingAddress");shippingAddressMapping.setXPath("shipping-address");shippingAddressMapping.setReferenceClass(Address.class);

Mapping to Different Elements by Element PositionAn object may have multiple composite object mappings to the same reference class. Each composite object mapping must have a unique XPath. This example uses unique XPaths by position.

Given the XML schema in Example 62–44, Figure 62–25 illustrates an XML composite object mapping to different elements by position in a corresponding XML document. Example 62–45 shows how to configure this mapping in Java.

Example 62–46 Schema for XML Composite Object Mapping to Elements by Position

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/><xsd:element name="address" maxOccurs="2">

<xsd:complexType><xsd:sequence>

XML Composite Collection Mapping

Understanding XML Mappings 62-25

<xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:element></xsd:sequence>

</xsd:complexType></xsd:schema>

Figure 62–26 XML Composite Object Mapping to Elements by Position

Example 62–47 Java for XML Composite Object Mapping to Elements by Position

XMLCompositeObjectMapping billingAddressMapping = new XMLCompositeObjectMapping();billinAddressMapping.setAttributeName("billingAddress");billinAddressMapping.setXPath("address[1]");billinAddressMapping.setReferenceClass(Address.class);

XMLCompositeObjectMapping shippingAddressMapping = new XMLCompositeObjectMapping();shippingAddressMapping.setAttributeName("shippingAddress");shippingAddressMapping.setXPath("address[2]");shippingAddressMapping.setReferenceClass(Address.class);

XML Composite Collection MappingUse XML composite collection mappings to represent one-to-many relationships. Composite collection XML mappings can reference any class that has a TopLink descriptor. The attribute in the object mapped must implement either the Java Collection interface (for example, Vector or HashSet) or Map interface (for example, Hashtable or TreeMap). The CompositeCollectionMapping class allows a reference to the mapped class and the indexing type for that class.

Given the XML schema in Example 62–48, Figure 62–27 illustrates an XML composite collection mapping to different elements by position in a corresponding XML

XML Composite Collection Mapping

62-26 Oracle TopLink Developer’s Guide

document. Example 62–49 shows how to configure this mapping in Java for a Collection attribute and Example 62–50 shows how to configure this mapping in Java for a Map attribute.

Example 62–48 Schema for XML Composite Collection Mapping

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="first-name" type="xsd:string"/><xsd:element name="last-name" type="xsd:string"/><xsd:element name="phone-number">

<xsd:complexType><xsd:sequence>

<xsd:element name="number" type="xsd:string"/></xsd:sequence><xsd:attribute name="type" type="xsd:string"/>

</xsd:complexType></xsd:element>

</xsd:sequence></xsd:complexType>

</xsd:schema>

Figure 62–27 XML Composite Collection Mapping

Example 62–49 Java for XML Composite Collection Mapping for a Collection Attribute

XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();phoneNumbersMapping.setAttributeName("phoneNumbers");phoneNumbersMapping.setXPath("phone-number");phoneNumbersMapping.setReferenceClass(PhoneNumber.class);

XML Any Object Mapping

Understanding XML Mappings 62-27

Example 62–50 Java for XML Composite Collection Mapping for a Map Attribute

XMLCompositeCollectionMapping phoneNumbersMapping = new XMLCompositeCollectionMapping();phoneNumbersMapping.setAttributeName("phoneNumbers");phoneNumbersMapping.setXPath("phone-number");phoneNumbersMapping.setReferenceClass(PhoneNumber.class);phoneNumbersMapping.useMapClass(HashMap.class, "getType");

See Chapter 67, "Configuring an XML Composite Collection Mapping" for more information.

XML Any Object MappingThe XML any object mapping is similar to the composite object XML mapping (see "XML Composite Object Mapping" on page 62-21) except that the reference object may be of any type (including String). This type does not need to be related to any other particular type through inheritance or a common interface.

The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.

This mapping is useful with the following XML schema constructs:

■ any

■ choice

■ substitution groups

Referenced objects can specify a default root element on their descriptor (see "Default Root Element" on page 23-9).

Given the XML schema in Example 62–51, Figure 62–28 illustrates the Java classes used in this example. A single XML any object mapping is used to map Customer attribute contactMethod. This attribute must be generic enough to reference all possible values: in this example, instances of Address, PhoneNumber, and String.

Example 62–51 Schema for XML Any Object Mapping

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="contact-method" type="xsd:anyType"/>

</xsd:sequence></xsd:complexType><xsd:element name="address">

<xsd:complexType><xsd:sequence>

<xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:element><xsd:element name="phone-number" type="xsd:string"/>

Note: The undefined document root element of a referenced object is ignored during marshalling with an any collection mapping and object mapping.

XML Any Object Mapping

62-28 Oracle TopLink Developer’s Guide

</xsd:schema>

Figure 62–28 Java Classes for XML Any Object Mapping

Figure 62–29, Figure 62–30, and Figure 62–31 illustrate how the XML any object mapping maps to an Address, PhoneNumber, and String (respectively) in XML documents that conform to the schema in Example 62–51.

Figure 62–29 XML Any Object Mapping to Address Type

Figure 62–30 XML Any Object Mapping to PhoneNumber Type

XML Any Collection Mapping

Understanding XML Mappings 62-29

Figure 62–31 XML Any Object Mapping to String Type

Example 62–49 shows how to configure this mapping in Java.

Example 62–52 Java for XML Any Object Mapping

XMLAnyObjectMapping contactMethodMapping = new XMLAnyObjectMapping();contactMethodMapping.setAttributeName("contactMethod");contactMethodMapping.setXPath("contact-method");

For more information about TopLink XML mapping support for xs:any and xs:anyType, see "xs:any and xs:anyType Support" on page 62-4.

See Chapter 68, "Configuring an XML Any Object Mapping" for more information.

XML Any Collection MappingThe XML any collection mapping is similar to the composite collection XML mapping (see "XML Composite Collection Mapping" on page 62-25), except that the referenced objects may be of different types (including String). These types need not be related to each other through inheritance or a common interface.

The corresponding object attribute value can be an instance of any object with a Descriptor, a java.lang.Object, a java.lang.String, a primitive object (such as java.lang.Integer), or a user defined type generic enough for all possible application values.

This mapping is useful with the following XML schema constructs:

■ any

■ choice

■ substitution groups

Each of the referenced objects (except String) must specify a default root element on their descriptor (see "Default Root Element" on page 23-9).

Given the XML schema in Example 62–53, Figure 62–32 illustrates the Java classes used in this example. A single XML any collection mapping is used to map Customer attribute contactMethods. This attribute must be generic enough to reference all possible values: in this example, instances of Address, PhoneNumber, and String.

Example 62–53 Schema for XML Any Collection Mapping

<?xml version="1.0" encoding="UTF-8"?><xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">

<xsd:element name="customer" type="customer-type"/><xsd:complexType name="customer-type">

<xsd:sequence><xsd:element name="contact-methods" type="xsd:anyType"/>

</xsd:sequence></xsd:complexType><xsd:element name="address">

XML Any Collection Mapping

62-30 Oracle TopLink Developer’s Guide

<xsd:complexType><xsd:sequence>

<xsd:element name="street" type="xsd:string"/><xsd:element name="city" type="xsd:string"/>

</xsd:sequence></xsd:complexType>

</xsd:element><xsd:element name="phone-number" type="xsd:string"/>

</xsd:schema>

Figure 62–32 Java Classes for XML Any Collection Mapping

Figure 62–33 illustrate how the XML any collection mapping maps to a collection of Address, PhoneNumber, and String objects in an XML document that conforms to the schema in Example 62–53.

Figure 62–33 XML Any Collection Mapping

Example 62–54 shows how to configure this mapping in Java.

XML Transformation Mapping

Understanding XML Mappings 62-31

Example 62–54 Java for XML Any Collection Mapping

XMLAnyCollectionMapping contactMethodsMapping = new XMLAnyCollectionMapping();contactMethodsMapping.setAttributeName("contactMethods");contactMethodsMapping.setXPath("contact-methods");

For more information about TopLink XML mapping support for xs:any and xs:anyType, see "xs:any and xs:anyType Support" on page 62-4.

See Chapter 69, "Configuring an XML Any Collection Mapping" for more information.

XML Transformation MappingYou can use an XML transformation mapping to create a custom mapping where one or more XML nodes can be used to create the object to be stored in a Java class’s attribute. To handle the custom requirements at marshall (write) and unmarshall (read) time, a transformation mapping takes instances of oracle.toplink.mappings.transformers (such as AttributeTransformer and FieldTransformer) that you provide. This provides a nonintrusive solution that avoids the need for your domain objects to implement special interfaces for this purpose.

As Figure 62–34 illustrates, you configure the transformation mapping with an oracle.toplink.mappings.transformers.AttributeTransformer instance to perform the XML instance-to-Java attribute transformation at unmarshall time. In this example, the AttributeTransformer combines two XML text nodes into a single Java object.

Similarly, you also configure the transformation mapping with one or more oracle.toplink.mappings.transformers.FieldTransformer instances to perform the Java attribute-to-XML instance transformation at marshall time. In this example, each FieldTransformer is responsible for mapping one of the Java object values to an XML text node.

Figure 62–34 XML Transformation Mappings

See Chapter 70, "Configuring an XML Transformation Mapping" for more information.

XML Transformation Mapping

62-32 Oracle TopLink Developer’s Guide

Configuring an XML Mapping 63-1

63Configuring an XML Mapping

This chapter describes how to configure an XML mapping.

Table 63–1 lists the types of XML mappings that you can configure and provides a cross-reference to the type-specific chapter that lists the configurable options supported by that type.

Table 63–2 lists the configurable options shared by two or more XML mapping types.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "Understanding XML Mappings" on page 62-1

■ "Understanding Descriptors" on page 23-1

■ "Configuring an XML Descriptor" on page 29-1

Configuring Common XML Mapping OptionsTable 63–2 lists the configurable options shared by two or more XML mapping types. In addition to the configurable options described here, you must also configure the options described for the specific XML Mapping Types, as shown in Table 63–1.

Table 63–1 Configuring XML Mappings

If you are creating... See Also...

XML Direct Mapping Chapter 64, "Configuring an XML Direct Mapping"

XML Composite Direct Collection Mapping

Chapter 65, "Configuring an XML Composite Direct Collection Mapping"

XML Composite Object Mapping Chapter 66, "Configuring an XML Composite Object Mapping"

XML Composite Collection Mapping Chapter 67, "Configuring an XML Composite Collection Mapping"

XML Any Object Mapping Chapter 68, "Configuring an XML Any Object Mapping"

XML Any Collection Mapping Chapter 69, "Configuring an XML Any Collection Mapping"

XML Transformation Mapping Chapter 70, "Configuring an XML Transformation Mapping"

Table 63–2 Common Options for XML Mappings

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Reference Descriptor" on page 63-2 Basic

Configuring Reference Descriptor

63-2 Oracle TopLink Developer’s Guide

Configuring Reference DescriptorFor XML attributes that reference other descriptors (instead of a schema element), you must select a specific reference descriptor.

Table 63–3 summarizes which XML mappings support reference descriptor configuration.

Using TopLink WorkbenchTo specify a reference descriptor for an XML mapping that references another descriptor (instead of a schema element), use this procedure.

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

2. Click the General tab. The General tab appears.

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Maps to Wildcard" on page 63-3 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring the Use of a Single Node" on page 32-36 Advanced

Table 63–3 XML Mapping Support for Reference Descriptor Configuration

XML MappingUsing TopLink Workbench Using Java

XML Direct Mapping

XML Composite Direct Collection Mapping

XML Composite Object Mapping

XML Composite Collection Mapping

XML Any Object Mapping

XML Any Collection Mapping

XML Transformation Mapping

Table 63–2 (Cont.) Common Options for XML Mappings

Option TypeTopLink Workbench Java

Configuring Maps to Wildcard

Configuring an XML Mapping 63-3

Figure 63–1 General Tab, Reference Descriptor Field

If this XML attribute refers to another descriptor (instead of a schema element), use the Reference Descriptor field to select a descriptor in the project.

Configuring Maps to WildcardThis attribute applies only to TopLink Workbench. Use this option to solve "No XPath specified" problems (see "Using the Problems Window" on page 4-11) for an XML mapping that does not need an XPath (see "Configuring XPath" on page 32-10) for it maps to a wildcard.

If the XML mapping is owned by an anyType descriptor (see "Configuring for Complex Type of anyType" on page 29-3), it cannot map to a wildcard, and you must specify an XPath.

Table 63–4 summarizes which XML mappings support maps to wildcard configuration.

Using TopLink WorkbenchTo specify a map a schema element using the xs:any declaration, use this procedure.

1. Select the mapped attribute in the Navigator. Its properties appear in the Editor.

Table 63–4 XML Mapping Support for Maps to Wildcard Configuration

XML MappingUsing TopLink Workbench Using Java

XML Direct Mapping

XML Composite Direct Collection Mapping

XML Composite Object Mapping

XML Composite Collection Mapping

XML Any Object Mapping

XML Any Collection Mapping

XML Transformation Mapping

Configuring Maps to Wildcard

63-4 Oracle TopLink Developer’s Guide

Figure 63–2 Mapping Tab, Maps to Wildcard Option

If the XML mapping is not owned by an anyType descriptor (see "Configuring for Complex Type of anyType" on page 29-3) and maps to a wildcard, then you do not need to specify an XPath (see "Configuring XPath" on page 32-10). Select the Maps to Wildcard (uses "any" tag) option to clear the missing XPath neediness message.

If the XML mapping is owned by an anyType descriptor, it cannot map to a wildcard and you must specify an XPath. Deselect the Maps to Wildcard (Uses "any" tag) option and ensure that you specify an XPath.

Configuring an XML Direct Mapping 64-1

64Configuring an XML Direct Mapping

This chapter describes the various components that you must configure in order to use an XML direct mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Direct Mapping" on page 62-5

XML Direct Mapping Configuration OverviewTable 64–1 lists the configurable options for an XML direct mapping.

Table 64–1 Configurable Options for XML Direct Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring the Use of a Single Node" on page 32-36 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring a Default Null Value at the Mapping Level" on page 32-12

Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a JAXB Typesafe Enumeration Converter" on page 32-25

Advanced

XML Direct Mapping Configuration Overview

64-2 Oracle TopLink Developer’s Guide

Configuring an XML Composite Direct Collection Mapping 65-1

65Configuring an XML Composite Direct

Collection Mapping

This chapter describes the various components that you must configure in order to use an XML composite direct collection mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Composite Direct Collection Mapping" on page 62-14

XML Composite Direct Collection Mapping Configuration OverviewTable 65–1 lists the configurable options for an XML direct collection mapping.

Table 65–1 Configurable Options for XML Direct Collection Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring a Simple Type Translator" on page 32-23 Advanced

"Configuring the Use of a Single Node" on page 32-36 Advanced

"Configuring Method Accessing" on page 32-14 Basic

"Configuring Read-Only Mappings" on page 32-2 Basic

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring a Serialized Object Converter" on page 32-18 Advanced

"Configuring a Type Conversion Converter" on page 32-20 Advanced

"Configuring an Object Type Converter" on page 32-22 Advanced

"Configuring a JAXB Typesafe Enumeration Converter" on page 32-25

Advanced

XML Composite Direct Collection Mapping Configuration Overview

65-2 Oracle TopLink Developer’s Guide

Configuring an XML Composite Object Mapping 66-1

66Configuring an XML Composite Object

Mapping

This chapter describes the various components that you must configure in order to use an XML composite object mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Composite Object Mapping" on page 62-21

XML Composite Object Mapping Configuration OverviewTable 66–1 lists the configurable options for an XML composite object mapping.

Table 66–1 Configurable Options for XML Composite Object Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Reference Descriptor" on page 63-2 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

XML Composite Object Mapping Configuration Overview

66-2 Oracle TopLink Developer’s Guide

Configuring an XML Composite Collection Mapping 67-1

67Configuring an XML Composite Collection

Mapping

This chapter describes the various components that you must configure in order to use an XML composite collection mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Composite Collection Mapping" on page 62-21

XML Composite Collection Mapping Configuration OverviewTable 67–1 lists the configurable options for an XML composite collection mapping.

Table 67–1 Configurable Options for XML Composite Collection Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Reference Descriptor" on page 63-2 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

XML Composite Collection Mapping Configuration Overview

67-2 Oracle TopLink Developer’s Guide

Configuring an XML Any Object Mapping 68-1

68Configuring an XML Any Object Mapping

This chapter describes the various components that you must configure in order to use an XML any object mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Any Object Mapping" on page 62-27

XML Any Object Mapping Configuration OverviewTable 68–1 lists the configurable options for an XML any object mapping.

Table 68–1 Configurable Options for XML Any Object Mapping

Option TypeTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Maps to Wildcard" on page 63-3 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

XML Any Object Mapping Configuration Overview

68-2 Oracle TopLink Developer’s Guide

Configuring an XML Any Collection Mapping 69-1

69Configuring an XML Any Collection Mapping

This chapter describes the various components that you must configure in order to use an XML any collection mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Any Collection Mapping" on page 62-29

XML Any Collection Mapping Configuration OverviewTable 69–1 lists the configurable options for an XML any collection mapping.

Table 69–1 Configurable Options for XML Any Collection Mapping

Option AdvancedTopLink Workbench Java

"Configuring XPath" on page 32-10 Basic

"Configuring Maps to Wildcard" on page 63-3 Advanced

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Container Policy" on page 32-26 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

XML Any Collection Mapping Configuration Overview

69-2 Oracle TopLink Developer’s Guide

Configuring an XML Transformation Mapping 70-1

70Configuring an XML Transformation Mapping

This chapter describes the various components that you must configure in order to use an XML transformation mapping.

For more information, see the following:

■ "Mapping Creation Overview" on page 31-1

■ "XML Transformation Mapping" on page 62-31

XML Transformation Mapping Configuration OverviewTable 70–1 lists the configurable options for a XML transformation mapping.

Table 70–1 Configurable Options for XML Transformation Mapping

Option TypeTopLink Workbench Java

"Configuring Attribute Transformer" on page 32-29 Basic

"Configuring Field Transformer Associations" on page 32-31 Basic

"Configuring Method Accessing" on page 32-14 Advanced

"Configuring Read-Only Mappings" on page 32-2 Advanced

"Configuring Mutable Mappings" on page 32-33 Advanced

"Configuring Mapping Comments" on page 32-18 Advanced

"Configuring Indirection" on page 32-3 Advanced

XML Transformation Mapping Configuration Overview

70-2 Oracle TopLink Developer’s Guide

Glossary-1

Glossary

This glossary contains terms and abbreviations that you should be familiar with when using Oracle TopLink.

attribute

A variable of a class or object. In TopLink, an attribute describes all instance variables of a class. Every attribute contains a single mapping. Attributes store primitive data such as integers, and simple Java types such as String or Date.

authentication

The means by which a data source validates a user’s identity and determines whether or not the user has sufficient privileges to perform a given action.

bean class

The implementation of the bean. The bean is accessed from the client using the home and remote interfaces.

bean-managed persistence (BMP)

A scheme for persisting entity beans that requires the developer to manually code the methods that perform the persistence.

Compare to container-managed persistence (CMP).

branch class

Has a persistent superclass and also has subclasses. By default, queries performed on the branch class return instances of the branch class and any of its subclasses. However, the branch class can be configured so that queries on it return only instances of itself without instances of its subclasses.

Compare to leaf class.

class

A category of objects. Classes allow data and method to be grouped together.

class indicator field

A field in the table of the root class that indicates which subclass should be instantiated

client session broker

A collection of client sessions, one from each server session associated with the session broker.

Glossary-2

connection pool

A collection of reusable connections to a single data source.

container-managed persistence (CMP)

A scheme for persisting entity beans that uses information supplied by the developer or deployer to perform the persistence

Compare to bean-managed persistence (BMP).

custom SQL

Refers to any non-TopLink-generated SQL used through TopLink. This includes hard-coded SQL and stored procedure calls.

data definition language (DDL)

The data definition part of the structured query language (SQL). TopLink Workbench can generate DDL creation scripts that can be used to create tables on the desired database.

database session

A database session provides a client application with a single data store connection, for simple, standalone applications in which a single connection services all data store requests for one user.

default mapping

A relational persistence framework term that refers to making the framework automatically generate the object descriptor metadata (including such things as mappings, login data, database platform, locking, and foreign keys). Default mapping is available for TopLink projects using EJB 2.0 CMP applications with OC4J.

dependent class path (IBM WebSphere)

Location where nonbean classes are specified. TopLink requires that the bean classes be included here since they are referenced by the project.

deployment descriptor

A set of XML files that provide the additional required information to install an EJB within its server. Typically, this incudes security, transaction, relationship, and persistence information.

Compare with TopLink descriptors.

descriptors

An TopLink object that describes how an object’s attributes and relationships are to be represented in relational database table(s). An "TopLink descriptor" is not the same as a deployment descriptor, although it plays a similar role.

direct access

By default, TopLink accesses public attributes directly when writing the attributes of the object to the database or reading the attributes of the object from the database.

Compare to method access.

direct mapping

There are two basic ways of storing object attributes directly in a table:

Glossary-3

■ The information can be stored directly if the attribute type is comparable to a database type.

■ If there is no database primitive type that is logically comparable to the attribute’s type, it must be transformed on its way to and from the database

TopLink provides five classes of direct mappings.

Compare to relationship mapping.

Enterprise Java Beans (EJB)

EJB are server-side domain objects that fit into a standard component-based architecture for building enterprise applications with Java. They are objects that become distributed, transactional, and secure components. TopLink Workbench uses three types of EJB: session beans, entity beans, and message-driven beans.

expressions

The TopLink equivalent of an SQL conditional clause. TopLink expressions are specified using the Expression and ExpressionBuilder classes.

entity beans

EJB that represent a persistent data object. TopLink uses two schemes for persisting entity beans: bean-managed persistence (BMP) and container-managed persistence (CMP).

fetch group

A performance enhancement that defines a subset of object attributes to be loaded initially and ensures that all other attributes are loaded on demand.

hub

A common connection point for devices in a network.

identity map

Used to cache objects for performance and to maintain object identity.

See also object identity.

independent relationship

A relationship in which the source and target are public objects that exist independently; the destruction of one object does not necessarily imply the destruction of the other.

Compare to private relationship.

indirection

An indirection object is one that acts as a stand-in for another object. In TopLink, indirection is implemented through value holders, which delay database access through acting as substitute for any object relationships.

inheritance

Describes how a child class inherits the characteristics of its parent class. TopLink supports multiple approaches to database implementations that preserve the inheritance relationship.

in-memory query

A query that is run against the shared session cache.

Glossary-4

instantiate

Create an instance of a Java class.

J2C

The J2EE Connector architecture (J2C) adapter is a way to persist Java objects to a nonrelational data source, such as XML.

J2SE

The Java 2 Platform, Standard Edition (J2SE) is the core Java technology platform. It provides software compilers, tools, runtimes, and APIs for writing, deploying, and running applets and applications in Java.

J2EE

The Java 2 Platform, Enterprise Edition (J2EE) is an environment for developing and deploying enterprise applications. J2EE includes a set of services, APIs, and protocols for developing multitiered web-based applications.

J2EE Containers

A J2EE container is a run-time environment for Enterprise Java Beans (EJB) that includes such basic functions as security, life cycle management, transaction management, and deployment services. J2EE containers are usually provided by a J2EE server, such as Oracle Containers for J2EE.

Java Messaging Service (JMS)

The JMS API is a protocol for communication that provides asynchronous communication between components in a distributed computing environment.

Java Naming and Directory Interface (JNDI)

The JDBC specification recommends using a JNDI naming service to acquire a connection to a database. TopLink supports acquiring a database connection in this fashion. To take advantage of this feature, construct and configure an instance of oracle.toplink.jndi.JNDIConnector and pass it to the project login object using the setConnector method.

Java Transaction API (JTA)

The Java Transaction API (JTA) specifies the interfaces between a transaction manager, a resource manager, an application server, and transactional applications involved in a distributed transaction system.

leaf class

Has a persistent superclass in the hierarchy but does not have subclasses; queries performed on the leaf class can return only instances of the leaf class.

Compare to branch class.

locking policy

A mechanism that ensures one user does not overwrite another users’s work. TopLink descriptors support optimistic and pessimistic locking policies.

mappings

Describe how individual Java objects and attributes relate to a data source.

Glossary-5

message-driven beans

An EJB that processes asynchronous Java Messaging Service (JMS) messages. For TopLink clients, a message-driven bean is simply a JMS consumer with no conversational state and no home or remote interfaces.

method access

The application registers accessor methods for the attribute.

Compare to direct access.

named query

A TopLink query that is created and stored, by name, in a session for later retrieval and execution

object identity

Ensures that each object is represented by one and only one instance in the application; that is, multiple retrievals of the same object return references to the same object instance, not multiple copies of the same object. Violating object identity can corrupt the object model.

See also identity map.

optimistic locking

Also known as write locking; allows unlimited read access to objects. A client can write an object to the database only if the object has not changed since it was last read.

Compare to pessimistic locking.

packet

A piece of a message transmitted over a packet-switching network. One of the key features of a packet is that it contains the destination address in addition to the data.

packet time-to-live

A number of hops that session data packets can take before expiring. The default is 2.

See also packet.

persist

In object technology, the storage of an Java object by a data source.

pessimistic locking

Objects are locked before they are edited, which ensures that only one client is editing the object at any given time.

Compare to optimistic locking.

primary key

A field (or combination of fields) that uniquely identifies a record in the data source.

private relationship

A relationship in which the target object is considered to be a private component of the source object; the target object cannot exist without the source and is accessible only through the source object; furthermore, if the source object is destroyed, the target object is destroyed as well.

Compare to independent relationship.

Glossary-6

query manager

An object, owned by a descriptor, that controls the way the descriptor accesses the database. The query manager generates its own default SQL to access the database in a transparent manner.

query optimization

TopLink supports two forms of query optimization: joining and batch reading. Their purpose is to optimize database access through reducing the number of database calls required to read a group of objects.

relationship

In TopLink, a reference between two TopLink-enabled objects.

relationship mapping

Persistent objects use relationship mappings to store references to instances of other persistent classes. The appropriate mapping class is chosen primarily by the cardinality of the relationship. TopLink provides five classes of relationship mappings.

Compare to direct mapping.

Remote Method Invocation (RMI)

A set of protocols that enable Java objects to communicate remotely with other Java objects.

remote session

A remote session is a client-side session that communicates over RMI with a corresponding client session and server session on the server side. Remote sessions handle object identity and marshalling and unmarshalling between client side and server side.

service channel

A name of the TopLink coordinated cache channel to which sessions subscribe in order to participate in the same coordinated cache.

session beans

EJB that represent a business operation, task, or process. TopLink can use session beans to make the regular Java objects they access persistent, or to wrap other legacy applications.

stale data

An artifact of caching, in which an object in the cache is not the most recent version committed to the data source.

TopLink session broker

A mechanism that enables client applications to transparently access multiple databases through a single TopLink session.

unit of work

A transactional TopLink session that allows for a transaction to occur at the object level not only the database level. Changes to objects are not visible globally until the unit of work is committed.

value holder

A wrapping object used by TopLink to delay database access.

Index-1

Index

Aaccess

data access, 81-1direct, 32-32modifiers, 4-42optimizing data access, 11-14remote sessions, 72-32

access methoddirect, 32-14generating, 4-30mappings, 32-15method, 32-14specifying, 32-32

access modifiers, classes, 4-42acquiring

client sessions, 75-6sessions, at runtime, 72-5unit of work, 98-1

activating descriptors, 4-10Add Named Query dialog, 25-12, 25-18, 25-20Add New Class dialog, 4-40, 4-53Add New Table button, 4-22Add or Refresh Class button, 4-50addConstraingDependencies(), 99-17address

multicast group, 88-4multicast port, 88-5

Add/Update Existing Tables from Database button, 4-23

advanced properties for descriptors, 19-7After Load tab, 25-81aggregate collection relational mappings

and EJB, 33-11configuring, 41-1understanding, 33-10

aggregate descriptorsabout, 23-5aggregate object mapping, 23-5EIS projects, 23-8EJB 3.0, 23-6inheritance, 23-17relational projects, 23-5XML projects, 23-8

aggregate object relational mappingsaggregate descriptors, and, 23-5

configuring, 43-1understanding, 33-12

aggregation, isolated client sessions, 72-24AllFieldsLockingPolicy, 23-20allows none, 25-18, 95-15allows null, 25-18, 95-15amending descriptors, 2-21, 23-5, 25-81

see also after loadannouncement delay, 88-11Ant, integrating with Oracle TopLink

Workbench, 4-53any collection XML mappings

configuring, 69-1understanding, 62-29

any object XML mappingsconfiguring, 68-1understanding, 62-27

application developmentdeploying, 10-1mapping, 2-21querying, 2-13, 71-2troubleshooting, 15-1

application layer, remote sessions, 72-31application servers

EJB support, customizing, 7-25integrating with Oracle TopLink, 7-1logging, 72-9optimization, 11-30setter parameter type checking, 7-25single-object finder return type checking, 7-25,

7-26software requirements, 7-2target platforms, 2-5unknown primary key class support, 7-25

architecturesapplication, 1-4BMP, 1-6, 2-31cache, 87-1choosing, 2-3CMP, 1-5, 2-27EIS, 2-4, 53-5EJB entity beans, 1-5, 1-6, 2-27, 2-31EJB session bean facade, 1-5, 2-25locking, 2-11optimistic locking, 2-11Oracle TopLink, 1-1

Index-2

pessimistic locking, 2-11selecting, 2-5session brokers, 72-26sessions, 72-2three-tier, 1-4, 2-22two-tier, 1-6, 2-24unit of work, 97-1web services, 1-6, 2-35

arguments, binding in query, 26-6array

dimensionality, 4-45, 4-49object-relational mappings, 46-2

AsOfClause, 96-2asynchronous change propagation, 88-2AttributeChangeTrackingPolicy

about, 97-8OC4J CMP integration, 97-8OC4J EJB 3.0 CMP integration, 97-8other application servers, 97-8

attributesadding to descriptors, 4-44array dimensionality, 4-45, 4-49changes, tracking, 25-75final, 4-45, 4-48in TopLink Workbench, Navigator window, 4-9lazy loading. see fetch groupsstatic, 4-45, 4-48transforming, 32-29, 32-31, 33-15transient, 4-45, 4-48unmapping, 31-6volatile, 4-45, 4-48

Attributes tab, 4-44, 4-48Attunity Connect platform, 81-3auditing

authentication, 81-6unit of work, 99-21

authenticationabout, 81-5auditing, 81-6proxy authentication, 81-5simple JDBC authentication, 81-5three-tier architecture, 81-5two-tier architecture, 81-5

Automap, 31-2automapping descriptors

about, 31-2see also mappings

automatic table generationabout, 30-4configuring, 8-12

BBase64 encoded strings, 32-25batch options

mappings, 34-7writing, 11-15

batch readingin query objects, 94-10read optimization, and, 11-20

batch writingabout, 11-15, 11-26, 83-11dynamic, 11-15dynamic, setMaxBatchWritingSize(), 11-15MySQL4 platform, 83-9non-parameterized, 11-15parameterized, 11-15setMaxBatchWritingSize(), 11-15

BEA WebLogicdeploying to, 10-2deployment exceptions, 15-3modifying persistence descriptor, 8-14setting classpath, 7-15setting shared library, 7-15transport layer, 72-31using a security manager, 7-20

@Bean fetch=lazy, 30-9beans

session beans, 2-26stateful beans, 2-26stateless beans, 2-26

bidirectional relationshipsabout, 33-2generating, 4-31in one-to-one mappings, 32-34target keys, 33-5with indirection, 32-35

bindAllParameters() method, 20-7bindings

arguments, 26-6input paramters, 94-20JAXB, 17-10LOB mappings, 31-3see parameter binding

BLOBmapping to, 31-2

BMPand EJB 1.1, 2-32and EJB 2.0, 2-32and TopLink, 2-31deployment files, 8-9descriptors, 23-3, 25-46packaging for deployment, 9-5

boolean logic in expressions, 95-3branch classes, 23-13buttons. see toolbarsbye array binding, LOB mappings, 31-3Byte array Base64, 32-25

Ccache

about, 2-13, 2-18, 87-1architecture, 87-1configuring, 87-6, 96-20coordination, 87-9, 88-1, 89-1, 90-1descriptor level, 25-35disabling during read query, 93-34distributed, 87-9expiration, 19-19, 25-42, 96-21

Index-3

expression limitations, 93-31identity maps, using, 72-29in-memory queries, 93-30, 93-31internal query object cache, 93-36, 93-37, 96-20,

96-21invalidation, 19-19, 25-42, 87-7, 87-8isolated client sessions, 72-24isolation, 87-6, 87-9object cache, 93-36object cascading refresh, 93-35object refresh, 93-35optimizing, 11-13project level, 19-13queries, 87-6, 93-29query cache, 93-36readObject method, and, 94-2refreshing, 25-27, 87-8, 93-35restrictions, 93-37service channel, 88-3sessions, 72-3, 72-33, 87-2stale data, 87-6storing query results, 93-36, 96-20type and size, 19-13, 25-35unit of work cache, 87-2

cache coordinationabout, 87-9application server clustering, and, 7-4avoiding stale data, 87-7CMP projects, 8-11EJB Entity Beans with BMP architecture,

and, 2-33explicit query refreshes, 87-7JMS, 89-1orion-ejb-jar.xml, 8-11packet time-to-live, 88-15permissions, 7-23RMI, 90-1

cache invalidation, avoiding stale data, 87-7cache synchronization. see cache coordinationcacheAllStatements(), 20-7cacheQueryResults(), 25-25cache-synchronization property, 8-11Caching tab, 25-36, 25-38, 25-40, 25-44calendar, 34-3call

call queries, 93-17EIS, 94-24EJBQLCall, 94-24SQLCall, 94-19StoredFunctionCall, 94-23StoredProcedureCall, 94-21

Call object, queries, 93-3cascading

object refresh, 93-35optimistic version locking, 23-19write queries, compared to non-cascading, 93-15,

94-14catalog, database, 4-22catchExcpetions(), 74-19change policy

about, 25-73attribute change tracking, configuring, 25-75deferred change detection, configuring, 25-73empty transaction, 97-6object change tracking, configuring, 25-73unit of work, 97-6

change trackingattribute, configuring, 25-75deferred, configuring, 25-73object, configuring, 25-73

changed items, displaying in TopLink Workbench Navigator window, 4-9

ChangedFieldsLockingPolicy, 23-21changing package names, 4-52checkDatabase(), 74-18checking in/out projects, 6-3checkInstantiationPolicy(), 74-19Choose a Schema Context dialog box, 28-3, 29-2Choose Query Key dialog box, 95-14Choose Relationships to Generate dialog box, 4-30Choose Root Element dialog box, 28-4, 29-5class extraction method

about, 23-15inheritance, 23-15

class indicatorabout, 23-14class extraction method, 23-15class indicator field, 23-14, 38-1

class loaderhost application, 2-5loading session, 75-4

class modifiers, 4-42Class tab, 4-41, 4-42, 4-43classes

access modifiers, 4-42adding and refreshing, 4-50branch, 23-13creating, 4-40, 4-52CursoredStream, optimizing, 96-18Database Exception, 94-25DatabaseMapping, 30-25default null values, 32-36DeleteObjectQuery, 94-13ExpressionBuilder, 95-16generating from database, 4-30InsertObjectQuery, 94-13InsertObjectQuery, 97-12interfaces, 4-43leaf, 23-13merging files, 6-5methods, adding, 4-47naming, 4-41non-descriptor classes, 4-51object model, 2-16Performance Profiler, 11-3persistent requirements, 2-12preferences, 4-16refreshing, 4-50removing, 4-51root, 23-13

Index-4

troubleshooting, 14-25unit of work, 97-12UpdateObjectQuery, 94-13, 94-14ValueHolderInterface, 2-12, 30-7, 33-9VariableOneToOneMapping, 33-6see also specific class name

classpathadding, 19-3BEA WebLogic, 7-15configuring, 4-2, 7-15, 7-21connector.jar, 4-2custom Collection class, 4-3DRIVER_CLASSPATH, Oracle TopLink

Workbench, 4-2IBM WebSphere, 7-21J2C adapter, 4-2JDBC driver, 4-2, 4-23JDBC_CLASSPATH, 4-2Oracle TopLink Workbench DRIVER_

CLASSPATH, 4-2relative, 19-3setting for BEA WebLogic, 7-15troubleshooting, 14-25xdb.jar file, 4-3

client sessionsabout, 72-1, 72-14, 72-26acquiring, 75-6configuration, 79-1example, 72-16shared resources, 72-15

client-controlled transactions, 99-25client-server architecture. See two-tierCLOB

mapping to, 31-2clones

copying methods, 25-72merging changes, 99-13post-commit, avoiding, 99-31unit of work, 97-2, 97-9

Cloudscape platform, 81-3clustering, integrating TopLink with, 7-4CMP

and EJB 1.1, 2-27and EJB 2.x, 2-27and EJB 3.0, 2-27and TopLink, 2-27CMPPolicy, 23-3, 25-46deploying, 8-9, 10-2descriptors, inheritance, 23-4external transactions, 97-3isolated client sessions, 72-25local transaction, 99-25non-deferred write, 99-26OC4J persistence, 7-5packaging for deployment, 9-4setter parameter type checking, 7-25single-object finder return type checking, 7-26transaction attribute, 99-25unit of work, 97-3, 99-24unknown primary key class support, 7-25

code generation, optimizing, 11-8collapsing items in Navigator window, 4-9collection class

specifying, 94-9specifying in query objects, 94-9

collectionspersistent requirements for mappings, 2-12query results, 93-8

commentsdescriptors, 25-8, 25-9mappings, 32-18projects, 19-20

commitand Java Transaction API, 97-10failure, resuming after, 99-14resuming unit of work after, 99-14

Communication Exceptions, 13-65composite collection EIS mappings

configuring, 58-1example, 53-8understanding, 53-7

composite collection XML mappingsconfiguration, 67-1configuring, 67-1understanding, 62-25

composite descriptorsabout, 23-5composite object mapping, 23-8EIS projects, 23-8XML projects, 23-8

composite direct collection EIS mappingsconfiguring, 56-1understanding, 53-6

composite direct collection XML mappingsconfiguring, 65-1understanding, 62-14

composite EIS descriptors, 24-5composite object EIS mappings

composite descriptors, and, 23-8configuring, 57-1understanding, 53-7

composite object mappingscomposite descriptors, and, 23-8

composite object XML mappingsconfiguration, 66-1configuring, 66-1understanding, 62-21

composite primary key, 33-9concrete class. see container policyconcurrency

about, 2-18exceptions, 13-25server session, 72-18

Concurrency Exceptions, 13-25configurations

about, 73-2creating, 73-2development environment, 6-1new, 73-2Oracle JDeveloper, 6-1

Index-5

session, 73-2, 73-4, 73-6, 73-9conforming

about, 99-8alternatives, UnitOfWork method

writeChanges, 99-12alternatives, UnitOfWork properties, 99-13descriptors, and, 99-12queries, alternatives to, 99-12

ConnectBy, 96-7connection policy

configuring, 74-19exclusive connections, 74-19lazy connection acquisition, 74-20

connection poolabout, 81-7connection count, 86-1ConnectionPolicy, 72-20external, 81-8internal, 81-7, 81-8, 81-9lazy connection allocation, 72-19, 75-9named, 81-9parameter binding, 11-16prepared statement caching, 11-16read, 81-8sequence, 17-5, 81-8server session, 72-18sessions, and, 72-3size, 86-1write, 81-8

Connection Specifications tab, 21-3Connection tab, 21-3connections

about, 81-6connection pool, 81-7exclusive write connection, 74-19lazy acquisition, 74-20reading through the write connection, 99-28

connector.jar, 4-2, 17-7container configuration file, 8-5container policy

about, 32-26custom Collection class, 4-3sorting, in memory, 32-26

container-controlled transactions, 99-25context

JAXB path, 17-13menus, 4-5schema, 28-2, 29-2

Context.SECURITY_CREDENTIALS, 88-9Context.SECURITY_PRINCIPAL, 88-9Conversion Exception, 13-26Converter tab

object type mappings, 32-22converters

custom, 33-3object type, 32-22

coordinated announcement delay, 88-11coordinated cache, 8-11

configuring, 88-1naming service, 88-7

service channel, 88-3copy policy

about, 25-71method, 25-72setting, 25-72

copying project objects, 6-6Copying tab, 25-72CORBA

Oracle TopLink transport layer support, 72-31Transaction Service see OTS

Create New Project button, 18-2Create New Project dialog box, 18-2Create New Session dialog, 73-4, 73-6, 73-8Create Project from JAXB dialog, 18-6Create Project from OC4J dialog, 7-9creating

configurations, 73-2expressions, 95-13sessions, 73-4, 73-6, 73-8, 85-1

Crimson XML parser, 7-3cursored streams

example, 96-18optimizing, 96-18remote sessions, 72-32usage example, 72-32

cursorsas query results, 93-8traversing scrollable, 96-16

Custom Calls tab, 28-6custom SQL

Custom SQL tab, 26-7unit of work, 99-16

customizationabout, 12-1data types, 12-1EIS, 12-1mapping extensions, 12-1overview, 2-15XML, 12-1

Ddata access

about, 81-1authentication, 81-5connection pool, 81-7connections, 81-6optimizing, 11-14, 11-15platforms, 81-3

data level queriesexample, 95-13in expressions, 95-12

data source platformabout, 81-3Attunity Connect database, 81-3Cloudscape database, 81-3databases, 81-3DB2 database, 81-3EIS, 81-4HSQL database, 81-3

Index-6

Informix database, 81-3J2C adapter, 81-4JDBC drivers, 81-3Microsoft Access database, 81-3MySQL4 database, 81-3Oracle database, 81-3Oracle8 database, 81-3Oracle9 database, 81-3PointBase database, 81-3SQLAnyWhere database, 81-3SQLServer database, 81-3SybasePlatform database, 81-3

data sourcesconfiguring, 82-1nontransactional, 81-1transactional, 81-1troubleshooting, 14-25

Database Exceptions, 13-27, 94-25database fields, configuring, 34-2database functions, in expressions, 95-3database login

parameter binding, 83-9prepared statement caching, 83-9

Database Preferences, 4-17database queries

about, 93-10, 94-4fetch groups, 93-13join reading, 93-12object level modify query, 93-14, 93-15object level read query, 93-11, 93-13partial object query, 93-11read all query, 93-11read object query, 93-11report query, 93-15

database schematables, 4-22

database sessionsabout, 72-2, 72-29cache, 72-33configuration, 80-1creating, 73-8

database tablesabout, 4-21adding to database, 4-22creating, 4-22descriptors and classes, generating, 4-30EJB entity generation, 4-31fields, 4-25generating, 4-29, 4-30, 4-32importing, 4-22Java source generation, 18-15JDBC driver classpath, 4-23properties, 4-25references, 4-26, 4-28removing, 4-24renaming, 4-24schema, 4-22SQL generation, 4-29TopLink Workbench, Navigator window, 4-9

DatabaseException class, 94-25

DatabaseLogin, 81-2DatabaseMapping class, 30-25DatabaseQuery, 93-3DatabaseRow, 33-15databases

catalog, 4-22common problems, 14-25connect to, 4-21creating reference tables on, 4-27custom drivers, 4-18disconnect from, 4-21drivers, 4-18exceptions, 94-25fields, configuring, 34-2for project, 18-3Java type conversion, 5-3linking, 72-28log out of, 4-22logging into, 4-22, 20-7logins, 83-1mapping. See mappingsplatform, 18-3, 20-2, 21-2, 83-1, 84-1preferences, 4-17schema, 4-22schema manager, 5-1tables, 4-21TopLink Workbench, Navigator window, 4-9troubleshooting, 14-25type conversion, schema manager, 5-3using with Oracle TopLink Workbench, 4-21

DatabaseSession classlogging SQL and messages, 72-10

DB2platform, 81-3schema manager type conversion, 5-3

DBase platform, 81-3default mapping

about, 30-4automatic table generation, and, 30-4configuring, 8-12default table generator, 5-6

Default Mapping Exception, 13-69default table generator

default mapping, 5-6table creator, creating, 5-4

defaultslogin level null values, 82-5mapping level null values, 32-12null values, 32-12, 32-36, 82-5optimization, 11-8root, 29-5see also preferences

DefaultSequence, 83-6deferred change detection

configuring, 25-73DeferredChangeDetectionPolicy, 97-7Delete All Interaction tab, 60-3deleteObject(), 26-8DeleteObjectQuery, 94-13deletes

Index-7

controlling order, 99-16delete operation, 94-4queries, EIS mappings, 60-3

demarcation of unit of work transactions, 97-2dependent objects

non-deferred write, 23-4deploy tool

about, 10-5troubleshooting, 10-6using with WebSphere Studio Application

Developer, 10-5deploying

about, 2-15, 10-1application server requirements, 7-1BEA WebLogic, 10-2CMP applications, 10-2, 10-4database login, 20-7entity beans overview, 2-15generating XML for, 8-3hot deployment, 10-4IBM WebSphere, 10-3Java applications, 10-1JSP and Servlet applications, 10-1modifying BEA WebLogic persistence

descriptor, 8-14non-CMP applications, 10-4packaging, 9-1Session Bean applications, 10-1troubleshooting, 15-1

deployment descriptors, 23-3deployment exceptions

BEA WebLogic deployment, 15-3IBM WebSphere deployment, 15-12

deployment filesBMP applications, 8-9CMP applications, 8-9creating, 8-1descriptors, 23-3EJB 3.0, 8-2, 9-1JARs, troubleshooting, 15-1Java applications, 8-8JSP and Servlet applications, 8-8Session Bean applications, 8-9XML, generating, 8-3

deployment XML, exporting, 18-14DeploymentXMLGenerator, 8-3Descriptor Event Listener, 25-62Descriptor Event Manager

about, 23-8Descriptor Event Listener, 25-62domain object methods, 25-59event types, 25-59handlers, 23-8, 25-59, 25-62handlers, Descriptor Event Listener, 25-62understanding, 23-8

descriptor eventsabout, 23-8Descriptor Event Listener, 25-62domain object methods, 25-59handlers, 23-8, 25-59, 25-62

types of, 25-59understanding, 23-8

Descriptor Exceptions, 13-2, 13-29Descriptor Info tab, 25-3, 25-6, 25-7, 26-2, 26-4, 28-2,

28-4, 29-2, 29-4, 29-5, 29-6DescriptorEventListener, 25-62descriptors

about, 16-2, 23-1advanced properties, default, 19-7aggregate, 23-5, 24-2aggregate, EJB 3.0 and, 23-6aggregate, relational projects and, 23-5amending, 2-21, 23-5, 25-81API, 23-23architecture, 23-2attributes, adding, 4-44automapping, 31-2automatically mapping, 31-2BMP, 23-3, 25-46cache refreshing, 25-27change policy, 25-73child inheritance, 25-51class, 24-2CMP, 23-3, 25-46CMPPolicy, 23-3, 25-46comments, 25-8, 25-9composite, 23-5, 23-8, 24-5composite EIS, 24-5configuring, 25-1conforming, 99-8creating, 24-1, 24-2, 24-5custom EIS interactions for basic persistence, 28-6custom SQL queries for basic persistence, 26-6deactivating, 4-10default mappings, 30-4default root, 28-4deployment information, 23-3Descriptor Event Listener, 25-62domain object methods, 25-59EIS, 23-12, 24-5, 28-1EIS projects, 23-8EJB, 23-3, 25-46EJB information, 23-3, 25-46errors, 4-10, 4-11, 14-3event handlers, 23-8, 25-59, 25-62events, 23-8, 25-59existence checking, 11-13, 25-43fetch groups, 25-79files, merging, 6-5generating from database, 4-30hierarchy, inheritance, 23-23history policy, 25-76identity maps, 19-14, 25-35, 25-38, 25-40in Java, 23-23inactive, 4-10inheritance, 23-3, 23-12, 25-51, 25-52instantiation, 11-13interface, 24-2, 25-31, 25-33mapping, 25-3, 26-2, 30-4, 31-1, 31-2merging, 6-5

Index-8

named queries, 25-10nondescriptor classes, 4-51object-relational, 23-11, 27-1optimizing, 11-13parent inheritance, 25-52projects, 16-2, 23-1query key interfaces, 25-31query timeout, 25-24, 25-26read only, 25-5registering with sessions, 72-13, 74-2, 74-3, 74-10relational, 23-11, 24-2, 26-1removing, 4-51returning policy, 25-67root EIS, 24-5root element, 29-5schema context, 28-2, 29-2, 29-3sequencing, 23-9, 26-3TopLink Workbench, Navigator window, 4-9types of, 23-1validating, 24-6XML, 23-12, 29-1XML projects, 23-8

detachment indirection, 30-10developing applications with Oracle TopLink, 2-1development environments

about, 3-2configuring, 6-1database logins, 20-7

development processabout, 2-1additional support, 2-3stages of, 2-2with Oracle TopLink, 2-1

development toolsabout, 3-1profiler, 11-2schema manager, 5-1

dimensionality, array, 4-45, 4-49direct access

about, 19-4, 32-14specifying, 32-32

direct collection relational mappingsconfiguring, 42-1example, 33-11understanding, 33-11

direct collectionssession broker limitations, 72-28

direct EIS mappingsconfiguring, 55-1understanding, 53-5

direct fieldin direct collection mappings, 42-2

direct key fields, 44-2direct map relational mappings

configuring, 44-1direct keys, 44-2direct value, 44-1understanding, 33-12

direct mappingsgenerating deprecated, 19-12

with EJB, 33-4direct value fields, 44-1direct XML mappings

configuring, 64-1understanding, 62-5

directionality in mappings, 33-2direct-to-field mappings

ObjectTypeMapping deprecated, 33-3SerializedObjectMapping deprecated, 33-3type conversions, 34-3TypeConversionMapping deprecated, 33-3

direct-to-field relational mappingsconfiguring, 35-1options, 35-1timestamp support, 34-3understanding, 33-4

direct-to-XMLType relational mappingsconfiguring, 36-1understanding, 33-4

Discovery Exception, 13-70DMS profiler

about, 11-4, 72-12accessing with JMX, 11-7and JMXnouns, 11-4, 72-12selecting, 74-11, 74-14, 74-17, 74-20sensors, 11-4, 72-12

document information in XML schemas, 4-34, 4-36, 4-38

documentationhosted, 4-14See also Help

does exist write object, 11-27dontOptimizeDataConversion(), 11-15doPrivileged(), 7-4DRIVER_CLASSPATH

Oracle TopLink Workbench environment, 4-2drivers, custom database, 4-18dynamic batch writing

about, 11-15setMaxBatchWritingSize(), 11-15

dynamic fetch groups, querying with, 96-4

EEditor window, about, 4-4, 4-10EIS

about, 17-8architecture, 2-4call, 94-24custom interactions for basic persistence, per

descriptor, 28-6indexed records, configuring, 28-5interactions, 28-6, 93-5, 94-24mapped records, configuring, 28-5mappings, 17-8, 53-2projects, 18-3queries, 93-5record format, configuring, 28-5XML records, configuring, 28-5

Index-9

EIS descriptorscomposite, 24-5configuring, 28-1default root, 28-4locking policy, 25-64root descriptor, 24-5schema context, 28-2setDataTypeName, 28-5understanding, 23-12

EIS mappingsabout, 53-1, 53-2architecture, 53-5composite collection, 53-7, 58-1composite direct collection, 53-6, 56-1composite object, 53-7, 57-1configuring, 54-1direct, 53-5, 55-1jaxb:class support, 53-3list support, 53-3one-to-many, 53-12, 60-1one-to-many, key on source, 53-13one-to-many, key on target, 53-15one-to-one, 53-8, 59-1one-to-one, key on source, 53-9one-to-one, key on target, 53-10transformation, 53-17, 61-1types of, 53-1union support, 53-3xsd:list, 53-3xsd:union, 53-3

EIS projectsconfiguring, 21-1connector.jar, 17-7indexed records, 17-9mapped records, 17-9sequencing, 17-5understanding, 17-7XML records, 17-9

EIS queries, 93-5EIS record types, supported, 53-2EISLogin, 81-2EJB

descriptors, 18-10isolated client sessions, 72-25setter parameter type checking, 7-25single-object finder return type checking, 7-25unknown primary key class support, 7-25

EJB 1.1and BMP, 2-32and CMP, 2-27

EJB 1.xindirection, 30-9serialization, 30-9

EJB 2.xand BMP, 2-32and CMP, 2-27default mapping, 30-4indirection, 30-9serialization, 30-9

EJB 3.0

<J2EE-Container>-jar.xml file, 8-6and CMP, 2-27attribute change tracking policy, OC4J CMP

integration, 7-5, 97-8Bean annotation, fetch=lazy, 30-9default mapping, 30-4deployment files, 8-2, 9-1deployment files, OC4J CMP integration, 7-5detachment, 30-10Embedded annotation, 23-6packaging for deployment, 9-1packaging, OC4J CMP integration, 7-5projects.xml file, 8-3, 8-5serialization, 30-10sessions.xml file, 8-5toplink-ejb.xml file, 8-7value holder indirection, 30-9

EJB descriptors, opening projects with, 18-10EJB entities

CMP hot deployment, 10-4deployment overview, 2-15EJB 2.x indirection, 30-9EJB 3.0 indirection, 30-9generating, 4-31hot deployment, 10-4inheritance, 23-4, 23-17inserting after ejbCreate, 23-4inserting after ejbPostCreate, 23-4mapping, 19-6non-CMP hot deployment, 10-4non-deferred write, understanding, 23-3, 99-26sequencing, 17-21

EJB entity beansand EJB 1.1, 2-27, 2-32and EJB 2.x, 2-27, 2-32and EJB 3.0, 2-27with BMP architecture, 1-6, 2-31with CMP architecture, 1-5, 2-27

EJB findersabout, 93-24Call finders, 93-26creating, 96-8DatabaseQuery finders, about, 93-26default finders, about, 93-26default finders, creating, 96-8EJB QL finders, about, 93-27ejb-jar.xml options, 96-9ejbSelect method, 93-28ejbSelect, creating, 96-15ejbSelect, using, 96-15expression finders, about, 93-27named query finders, about, 93-27predefined, about, 93-24primary key finders, about, 93-27redirect finders, about, 93-28redirect finders, using, 96-12single-object finder return type checking, 7-25SQL finders, about, 93-28

EJB Info tab, 25-46EJB JAR XML Exception, 13-77

Index-10

EJB Preferences, 4-16EJB QL

exceptions, 13-63queries, 26-6, 93-5query language, 93-5

EJB session bean facade architectureabout, 1-5, 2-25understanding, 2-25

EJB Session Beans, 72-31ejbc

about, 10-2troubleshooting, 10-3

ejbCreate, 23-4ejb-jar.xml file

about, 8-5, 18-15configuring, 8-5corresponding to Oracle TopLink Workbench

functions, 18-15EJB finder options, 96-9location, 19-7managing, 6-6preferences, 4-16synchronization under EJB 2.0, 8-5updating from, 18-16writing, 18-16

ejbPostCreate, 23-4@Embeddable, 23-6@Embedded, 23-6empty unit of work transactions, 97-6encrypting login passwords, 18-13enhanced validation exceptions, 8-4Enterprise Information Systems. see EISentity beans

deployment, 2-15descriptor information, 23-3direct mappings, 33-4indirection, EJB 2.x, 30-9indirection, EJB 3.0, 30-9sequencing with, 17-21

Entity Manager Setup Exception, 13-80, 13-81EntityManagerSetupException, 13-80, 13-81, 13-83environment

configuring, 4-2JAVA_HOME, 4-2JDBC_CLASSPATH, 4-2proxy, 4-13, 4-14, 18-16

error codes1-176, 13-21-99, 14-1100-199, 14-3200-399, 14-3400-599, 14-13500-699, 14-17700-799, 14-23800-899, 14-2312000-12004, 13-6518001-18002, 13-6922001-22004, 13-7022101-22105, 13-713001-3007, 13-26

4002-4018, 13-275001-5008, 13-296001-6098, 13-317001-7104, 13-4372000-72023, 13-77, 13-80, 13-81, 13-838001-8010, 13-639000-9009, 13-64

errorsabout, 13-1codes and descriptions, 13-1, 14-1descriptors, 4-10, 4-11migration, 7-13Oracle TopLink Workbench, 14-1

Event Manager, 72-5events

about, 23-8client session, 72-6database access, 72-6Descriptor Event Listener, 25-62domain object methods, 25-59handlers, 23-8, 25-59, 25-62listeners, sessions, 72-7session, 72-5session manager, 72-6sever session, 72-6types of, 25-59unit of work, 72-6

examplescomposite collection EIS mapping, 53-8context menu, 4-5cursored streams, 96-17direct collection mappings, 33-11direct-to-field mappings, 33-4exception handler, 74-13indirection, 30-6inheritance, 23-12Oracle TopLink Workbench, 4-3performance optimization, 11-23, 11-25proxy indirection in code, 32-9READALL finders, 96-10report query, 94-6scrollable cursors, 96-17serialized mapping, 30-10stored procedure call, 94-22, 94-23transformation mapping, 33-15transformation XML mapping, 53-18, 62-31Unit of Work, 97-6, 98-7write, write all, 94-3

exception handlerabout, 72-12example, 74-13selecting, 74-12

exceptionschained, 72-11communication exceptions, 13-65conversion exceptions, 13-26database exceptions, 13-27, 94-25Default mapping exception, 13-69descriptor exceptions, 13-2discovery exceptions, 13-70

Index-11

EJB JAR XML exceptions, 13-77, 13-80, 13-81, 13-83

EJB QL exceptions, 13-63enhanced validation, 8-4java.security.AccessControlException,

15-12, 15-13JMS processing exceptions, 13-69Migration utility exception, 13-74optimistic locking, 13-29query exceptions, 13-31remote command manager exceptions, 13-71selecting exception handler, 74-12session loader exceptions, 13-64Transaction exception, 13-73validation exceptions, 13-43XML conversion exception, 13-74

exclusive connectionsabout, 99-29internal read connection pool, 86-6isolated sessions, 72-20, 74-19named queries, 25-24

existence checking, 99-5descriptors, 25-43projects, 19-8

expanding items in Navigator window, 4-9expiration of objects in the cache, 19-19, 25-42explicit query refreshes, cache coordination, 87-7exporting

deployment XML, 18-14Java model, 18-14Java source, 18-14preferences, 4-12projects, 18-13

Expression Builder, 95-13, 95-15Expression Builder dialog box, 95-13Expression class, 95-1ExpressionMath class, 95-1expressions

about, 93-3, 95-1allows none, 25-18, 95-15allows null, 25-18, 95-15building, 95-13comparing with SQL, 95-1components, 95-2creating, 95-13data level queries, 95-12database functions, 95-3in relationships, 95-6in-memory queries, limitations, 93-31mathematical functions, 95-4multiple, 95-10one-to-one mappings, 95-5outer joins, 94-11parallel expressions, 95-11parameterized, 95-8platform functions, 95-16query keys, 95-10subqueries and subselects, 95-10user-defined functions, 95-5, 95-16using Boolean logic, 95-3

XML Type functions, 95-5see also queries

externalapplications, 99-27connection pools, 81-8controller, transaction, 97-1JDBC pools, 2-33transactions, 97-1

external transaction controllerconfiguration, sessions, 74-14session, 97-2

Ffactory name, JMS connection, 89-2failure, resuming unit of work after commit, 99-14features of Oracle TopLink, 1-4fetch groups

about, 23-5, 25-79configuring, 25-79, 96-3default, 25-79, 96-3disabling, 96-3dynamic, 96-4object level read query, 93-13read optimization, and, 25-79size, 11-18static, 96-3

field references, 34-8Field uses XML Schema "type" attribute

option, 30-12fields in database tables, 4-25Fields tab, 43-2field-to-object attribute transformation, 32-29, 32-31files

JAXB-specific, 17-10TopLink-specific, 17-11see also specific file name

final attributes, 4-45, 4-48findAll, using, 93-26finders

caching options, 93-37disabling cache, 93-38managing large result sets, 96-18refreshing results, 93-38see also EJB finders

flashback queriesabout, 93-18historical client sessions, 78-1

forceUpdateToVersionField(), 99-18foreign keys

about, 2-17, 34-8configuring in EIS mappings, 59-1EIS mappings, 60-1multiple tables, 26-14one-to-many mappings, 33-7one-to-one mappings, 32-34, 33-5parameterized expressions, 95-8references, 14-15, 14-23target, 33-5, 34-9troubleshooting, 14-15, 14-23

Index-12

full identity map, 87-3

Ggarbage collection, managing, 98-8General Preferences dialog, 4-13Generate Classes and Descriptors dialog, 4-30Generate EJB Entity Classes and Descriptors

dialog, 4-31generating

access method, 4-30deployment JARs, troubleshooting, 15-1deprecated direct mappings, 19-12see also exporting

getCatalogs(), 4-22getField(), 95-12getImportedKeys(), 4-22getParameter, 95-8getPrimaryKeys(), 4-22getTable(), 95-12getTables(), 4-22getTableTypes(), 4-22getValue(), 30-7getValue() method, 30-7

Hhard cache weak identity map

about, 87-4when to use, 87-5

helpabout, 4-12displaying, 4-12

Help button., 4-12Help Preferences, 4-14, 4-16hierarchical queries

about, 93-18described, 96-6

hints, Oracle Hints in queries, 93-18historical client sessions

about, 72-1, 72-25cache, 72-33limitations of, 72-25

historical queries, 96-2about, 93-21see also AsOfClause

history policy, configuring, 25-76holders, value, 30-7host URL, JMS topic, 89-3hosted

documentation, 4-14XSD files, 8-2, 8-4

hot deploymentabout, 10-4CMP applications, 10-4non-CMP applications, 10-4

HSQL platform, 81-3

IIBM Informix Database native sequencing, 17-19

IBM WebSpheredeploy tool, 10-5deploying to, 10-3deployment exceptions, 15-12setting classpath, 7-21

identityabout, 2-17, 87-3cache, and, 87-3using cache to preserve, 87-3see also identity map

identity map cachedisabling during a write query, 94-15refresh in read query, 93-35

identity mapsabout, 25-35, 25-38, 25-40, 72-29cascading refresh during read query, 93-36descriptors, 19-14, 25-35example, 93-36full, 87-3guidelines for choosing type, 87-4hard cache weak identity map, 87-4, 87-5isolated client sessions, 72-24no identity map, 87-4refreshing during read query, 93-35soft cache weak identity map, 87-4, 87-5soft cache weak identity map and read

optimization, 11-19specifying, 25-35, 25-38, 25-40weak, 87-3weak identity map and read optimization, 11-19

Identity tab. see Caching tabimpedance mismatch, solving, 1-2Implementors tab, 25-34Import Tables from Database dialog, 4-23importing

classes, 4-16preferences, 4-12

inactive descriptorsabout, 4-10mapping to, 34-6, 54-3

independent relationships, 32-16indexed records, 53-2indirection

about, 2-19, 30-5bidirectional relationships, 32-35choosing the correct type, 32-4configuring, 32-3EJB, 30-9EJB 2.x CMP, 30-9EJB 3.0 CMP, 30-9example, 30-6many-to-many mappings, 33-9nontransparent, 2-12one-to-many mappings, 32-34proxy indirection, 30-8remote sessions, 72-32serialization, 30-9transparent, 2-12, 30-8value holder, 30-7ValueHolderInterface, 2-12

Index-13

see also proxy indirection, transparent indirectionInformix platform, 81-3inheritance

about, 2-18, 23-3, 23-12aggregate classes, 23-17aggregate collection mappings, 33-10branch classes, 23-13child descriptors, 25-51class extraction, 23-15class indicator, 23-14, 23-15descriptors, 23-3, 23-12, 25-51, 25-52finding subclasses, 23-14instantiating subclasses, 23-14isolated client sessions, 72-24leaf classes, 23-13, 96-4primary keys, 23-16queries, 93-22querying on hierarchy, 96-4relational parent, 25-52root class, 23-13, 25-51, 25-53root class subclasses, finding in inheritance, 23-14supporting with multiple tables, 23-16supporting with one table, 23-16transformed to relational model, 11-11using with EJB, 23-4, 23-17

inheritance hierarchiesdescriptors, 23-23querying on, 96-4

Inheritance tab, 25-51, 25-53inherited subclasses, mapping, 25-58in-memory query

about, 87-6check cache using exact primary key, 93-30check cache using primary key, 93-30check database if not in cache, 93-30conform results in unit of work, 93-31expression limitations, 93-31supported, 93-31using, 93-30

inner join, 95-6insert operation, 94-3, 94-4insertObject(), 26-7instantiation policy

about, 25-70setting, 25-70

Instantiation tab, 25-70integrity checker, 24-6

about, 72-12configuring, 74-18

interactionsabout, 94-24creating, 28-6

interface aliasabout, 26-10creating, 26-11

Interface Alias tab, 26-11interfaces

classes, implementing, 4-43customizing, 4-13descriptors, 24-2, 25-31, 25-33

queries, 93-22query keys, 25-31querying on, 96-4

internal connection poolabout, 81-7named, 81-9read, 81-8sequence, 81-8write, 81-8

internal query object cacheabout, 93-36configuring, 96-20, 96-21expiration, 96-21restrictions, 93-37

internal transactions, 97-1invalidation of objects in the cache, 19-19, 25-42, 87-8IP address for multicast group, 88-4isolated client sessions

about, 72-1, 72-19, 77-1configuration, 77-1life cycle, 72-22limitations of, 72-24session event handlers, 72-21with Oracle Virtual Private Database

(VPD), 72-21isolated session

cache, 72-33ConnectionPolicy, 72-20exclusive connections, 72-20supported databases, 72-21

isolationcache, 87-6transaction levels, 97-2unit of work transactions, 97-4

Iterator interface, 96-16

JJ2C adapters

about, 81-4configuring for Oracle TopLink Workbench, 4-2EISLogin, 81-2selecting, 81-4with EIS, 18-3

<J2EE-Container>-ejb-jar.xml file, 8-5<J2EE-Container>-jar.xml file

EJB 3.0, 8-6J2EE

parameter binding, 11-16prepared statement caching, 11-16web applications, 1-4

Javadatabase tables, 18-15exporting to, 18-14integration with any datasource, 1-2iterators, 96-16object model, 2-11

Java applicationsdeploying, 10-1deployment files, 8-8

Index-14

packaging for deployment, 9-1Java Cryptography Extension, 18-13Java Management Extensions. see JMXJava Naming and Directory Interface. See JNDIJava Object Builder, 72-4Java streams

described, 96-17optimizing, 96-18support for, 96-17

Java Transaction APIand unit of work commit, 97-10and unit of work rollback, 97-11see also JTA

Java Transaction Service see JTAJAVA_HOME, 4-2java.security.AccessControlException, 15

-12, 15-13java.util.Collection interface, 32-26java.util.Map interface, 32-26java.util.Set interface, 32-26javax.ejbEntityBean interface, 4-31JAXB

creating projects from, 18-6files, 17-10generating project from the command line, 18-8jaxb:class, and EIS mappings, 53-3jaxb:class, and XML mappings, 62-4proxy configuration, 18-8tljaxb.cmd, 18-8tljaxb.sh, 18-8typesafe enumeration converter, 32-25understanding, 17-10validation, 17-14XML projects, 17-10

JAXB typesafe enumeration converterconfiguring, 32-25understanding, 30-24

JAXBContext, 17-13JCE. see Java Cryptography ExtensionJConnect, 11-14JDBC

adaptor for EIS, 53-5database gateway for EIS, 53-5driver classpath, 4-23JConnect, 11-14Sybase JConnect, 11-14

JDBC driversabout, 81-3configuring for Oracle TopLink Workbench, 4-2fetch size, 11-14, 11-18general properties, 11-14mapping LOBs, 31-3selecting, 81-3

JDBC poolsexternal with EJB Entity Beans with BMP

architecture, 2-33JDBC_CLASSPATH, 4-2JDeveloper. See Oracle JDeveloperJMS

connection factory name, 89-2

coordinated cache, 89-1Processing Exceptions, 13-66, 13-69topic host URL, 89-3topic name, 89-1

JMXaboutand DMS profilerDMS profiler, 11-7

JNDI naming service, 88-7joining

about, 93-12expressions, and, 95-6mappings, and, 37-1one-to-many, about, 94-12one-to-many, when not to use, 93-12one-to-one mappings, 37-1, 94-12optimizing reads, 11-20queries, and, 94-11, 94-12QueryManager expressions, 96-4read queries, 11-20, 94-11

JSP and Servlet applicationsdeploying, 10-1deployment files, 8-8packaging for deployment, 9-2

JTAabout, 97-3and unit of work, 97-3isolated client sessions, 72-25unit of work, 97-1

JTA/JTSusing with EJB Entity Beans with BMP

architecture, 2-33just-in-time reading. see indirection

KKey Converter tab, 44-3key pairs

database table reference, 4-28troubleshooting, 14-15, 14-23

keysabout, 2-17foreign, 2-17, 32-34, 33-5foreign, target, 33-5inheritance, 23-16multiple tables, 26-13primary, 23-16, 26-13, 32-2, 33-6, 33-9, 38-3read-only settings, 32-2reference key field, 33-11, 33-12variable class relationships, 33-6, 38-3

Llanguage, specifying, 4-3large result sets, managing in finders, 96-18lazy attribute loading and read optimization, 25-79lazy connection

acquisition, 74-20allocation, 72-19, 75-9

lazy loading. see indirection

Index-15

lazy reading. see indirectionleaf classes, 23-13, 96-4life cycle of unit of work, 97-5LOB

mapping to, 31-2local

documentation, 4-14transactions, 99-25

locked files, 6-6locking policy

AllFieldsLockingPolicy, 23-20ChangedFieldsLockingPolicy, 23-21configuring, 25-64field locking, 23-20optimistic, 23-9, 23-19, 23-20optimistic version locking, 23-18OptimisticLockException, 23-19, 23-21pessimistic locking policy, 23-9, 23-22SelectedFieldsLockingPolicy, 23-21stale data, and, 87-6three-tier architectures, optimistic locking

and, 23-22three-tier architectures, pessimistic locking

and, 23-23TimestampLockingPolicy, 23-18understanding, 23-9, 23-18version locking, 23-19VersionLockingPolicy, 23-18

Locking tab, 25-65log into database, 4-22Log Out of Database, 4-22log out of database, 4-22logging

application server, 72-9chained exceptions, 72-11java.util.logging, 72-9log level, 72-10Oracle Enterprise Manager 10g, 72-11output, 72-10permissions, 7-24sessions, 72-7, 74-4, 74-5TopLink native logging, 72-8types, 72-8

Logging tab, 74-5login

CMP deployment, 17-3database, 20-5, 20-7, 83-1deployment, 17-3development, 17-4platforms, and, 17-4projects, and, 17-3, 71-1, 81-2role in project, 17-3, 81-2session, 17-3, 74-4session role, non-CMP, 17-3

logMessages method, 72-7look and feel, specifying, 4-13

MManage Non-Descriptor Classes dialog, 4-51

management, source control, 6-3manager, session events, 72-5many-to-many mappings

relation table, 33-9relation tables, 40-1session broker limitations, 72-28

many-to-many relational mappingsconfiguring, 40-1EJB, 33-9understanding, 33-8

mapped records, 53-3mapping extensions

custom data types, 12-1JAXB typesafe enumeration converter, 30-24,

32-25object type converter, 30-12, 32-22serialized object converter, 30-10, 32-18simple type translator, 30-12, 32-23transformation mappings, 30-14type conversion converter, 30-11, 32-20

mappingsabout, 2-16, 2-17, 16-1, 16-2, 30-1, 31-1access types, 32-15aggregate collection mappings and EJB, 33-11anyType mapping, 63-3as part of the application development

process, 2-21automatic, 31-2batch options, 34-7class hierarchy, 30-25comments, 32-18configuring, 31-1, 32-1database field, 34-4default mapping, 30-4deprecated, generating, 19-12direct access, 11-13, 32-14directionality, 33-2EIS mappings, 17-8, 30-27, 53-1, 54-1EJB 2.0 entities, 19-6errors, 14-13example, 30-3extensions, about, 30-10hierarchy, 30-25inactive descriptors, 34-6, 54-3indirection, 11-13, 30-5, 32-3isolated client sessions, 72-24manually configuring, 31-1many-to-many, 33-9many-to-many, with EJB, 33-9method access, 32-14, 32-32null values, 32-12, 32-36object-relational, 46-1, 47-1one-to-many object, with EJB, 33-8one-to-one with EJB, 33-6optimizing, 11-13OX mappings, 30-27projects, and, 16-2read only, 32-2, 32-3relation tables, 40-1, 40-2relational, 33-1, 34-1

Index-16

removing, 31-6to tables, 25-3, 26-2TopLink Workbench, Navigator window, 4-9types of, 30-1XML mappings, 62-1, 63-1

mathematical functions, in TopLink expressions, 95-4

menu bar, 4-5menus

about, 4-4, 4-5context menus, 4-5menu bar, 4-5

mergingchanges in clones, 99-13Oracle TopLink Workbench project files, 6-4project files, 6-4

messages, error, 13-1, 14-1metadata

about, 2-13, 2-19advantages, 2-20creating, 2-20, 2-21mapping and configuration, 16-1project metadata, 2-20session metadata, 2-21

Metalink, 2-3method access

about, 19-4, 32-14setting, 32-32

methodsadding, 4-47getValue(), 30-7setValue(), 30-7wrapper policy, 25-79see also specific method name

Microsoft Accessplatform, 81-3schema manager type conversion, 5-3

Microsoft SQL Database native sequencing, 17-19migrating

error messages, 7-13OC4J persistence to TopLink, 7-5Oracle TopLink Workbench projects, 18-10troubleshooting, 7-13

Migration Utility Exception, 13-74model source, exporting, 18-14modifiers, class, 4-42multicast group address, coordinated cache, 88-4multicast port, coordinated cache, 88-5multiple sessions, 72-28, 75-2multiple tables

about, 26-13specifying for descriptors, 26-13

multiplicity in relationships, resolving, 7-14multi-processing, 11-29Multitable Info tab, 25-50, 26-13mutable mappings, 32-33.mwp file, 4-1, 18-2MySQL4

batch writing, 83-9platform, 81-3

primary key restrictions, 17-15schema manager type conversion, 5-3

Nnamed connection pools, 81-9named queries

about, 25-10, 74-21, 93-16configuring, 25-10, 74-21descriptor level, 25-10exclusive connections, 25-24options, advanced, 25-24parameter binding, 25-22prepared statement caching, 25-22redirect query, 93-16session level, 74-21using, 94-18when not to use, 93-17when to use, 93-16

namespacesabout, 17-5, 17-22configuring, 4-37

naming servicecoordinated cache, 88-7JNDI, 88-7RMI, 88-9

native sequencingIBM Informix Database, 17-19Microsoft SQL Database, 17-19Microsoft SQL Server, 5-6non-Oracle database, 17-19Oracle Database, 17-18, 17-20Oracle Database SEQUENCE object, 17-19Sybase Database, 5-6, 17-19

Navigator windowabout, 4-4, 4-9attribute and mapping, 4-9database, 4-9database tables in, 4-21descriptor, 4-9example, 4-9package, 4-9project, 4-9unsaved or changed item, 4-9

NCHAR, 30-12NCLOB, 30-12neediness warnings. See troubleshootingnested table object-relational mappings

configuring, 52-1understanding, 46-3

nested unit of work, 97-9, 99-15new projects, 18-2New Reference dialog box, 4-27New Session button, 73-4, 73-6, 73-8New Sessions Configuration, 73-2New Table dialog box, 4-22newInstance method, 99-2no identity map, 87-4non-cascading write queries

compared to cascading, 93-15, 94-14

Index-17

creating using dontCascadeParts () method, 93-15, 94-14

non-deferred writeconfiguring, 99-12dependent objects, 23-4understanding, 23-3, 99-7, 99-26

nonintrusive persistence, 2-19nonpersistent projects, 17-2nonrelational projects, 17-2nontransactional data sources, 81-1nontransparent indirection, 2-12nouns

DMS profiler, 11-4, 72-12null values

default, 32-12, 32-36, 82-5in expressions, 95-14login level, 82-5mapping level, 32-12

NVARCHAR2, 30-12

Oobject array object-relational mappings

configuring, 51-1understanding, 46-2

object cache, 93-36object cache, sessions, 72-3object change tracking

configuring, 25-73object identity, 72-29

about, 2-17, 87-3cache, and, 87-3using cache to preserve, 87-3see also identity map

object indirectionread optimization, as, 11-19

object level modify queryabout, 93-14, 93-15

object level read queryabout, 93-11, 93-13fetch groups, 93-13join reading, 93-12partial object query, 93-11read all query, 93-11read object query, 93-11

object modelabout, 2-16generating with tljaxb.cmd, 18-8optimization, 11-8Oracle TopLink requirements, 2-11

object type converterabout, 12-1, 30-12configuring, 32-22

object type mappingsconfiguring, 32-22

ObjectLevelChangeTrackingPolicy, 97-7object-relational descriptors

configuring, 27-1locking policy, 25-64understanding, 23-11

object-relational mappingsabout, 46-1array, understanding, 46-2configuring, 47-1nested table, 46-3, 52-1object array, 46-2, 51-1overview, 2-16reference, 46-2, 49-1, 50-1structure, 46-2, 48-1

object-relational projectsabout, 17-6sequencing, 17-5

objectscascading refresh in cache, 93-35creating and registering, 99-2query, 94-6refreshing in cache, 93-35registering and unregistering, 99-1

ObjectTypeMappingsee ObjectTypeConverter

OC4J. See Oracle Containers for J2EEone-to-many EIS mappings

configuring, 60-1key on source, 53-13key on target, 53-15understanding, 53-12

one-to-many relational mappingsconfiguring, 39-1understanding, 33-7

one-to-one EIS mappingsconfiguring, 59-1key on source, 53-9key on target, 53-10understanding, 53-8

one-to-one relational mappingsconfiguring, 37-1expressions, 95-5joining, 37-1understanding, 33-5with EJB, 33-6

online help, 4-14Open Project button, 18-10opening projects, 18-10operators

boolean logic, 95-3optimistic locking

about, 23-9application architecture, 2-11cascading locking policy, 23-19, 25-67database exception, 94-25exceptions, 13-29field locking policy, about, 23-20rollbacks, 23-20version locking policy, 23-18, 23-19, 25-67with forceUpdateToVersionField()

method, 99-18optimistic locking policy

field locking, about, 23-20version locking, 23-18, 23-19, 25-67

OptimisticLockException, 23-19, 23-21

Index-18

optimizationabout, 11-1application bottlenecks, 11-2application server, 11-30batch reading, 11-17batch writing, 11-15CMP partial object queries, 11-17code generation, 11-8data access, 11-14, 11-15data format, 11-15database, 11-30descriptors, 11-13DMS profiler, 11-4, 72-12existence checking, 11-13fetch groups, 11-17fetch size, JDBC, 11-18general, 11-8inheritance, 23-16instantiation, 11-13JDBC driver, 11-14, 11-18join reading, 11-17mappings, 11-13named queries, 11-17object model, 11-8overview, 2-15parameter binding, 11-15partial object queries, 11-17prepared statement caching, 11-15profiler, 11-4, 72-12

optimizationTopLink Profiler, 11-2

queries, 11-17reading, 11-19ReadQuery method setMaxRows, 11-18schema, 11-8setMaxRows, 11-18understanding, 11-1unit of work, 11-30writing, 11-26

Oracledevelopment support, 2-3remote session support, 72-31

Oracle Containers for J2EEcreating projects from, 7-9migrating to TopLink, 7-5

Oracle Databasedate and timestamp mappings, 34-3native sequencing, 17-20

Oracle DatabaseSEQUENCE object, 17-19

platform, 81-3schema manager type conversion, 5-3

Oracle extensionshierarchical queries, 96-6Oracle Hints, 96-6

Oracle Hints, using with TopLink queries, 96-6Oracle JDeveloper

configuring with Oracle TopLink, 6-1TopLink sessions, 6-3

Oracle TopLink

about, 1-1, 4-1application architectures, 1-4architectures, 1-1deploy tool for IBM WebSphere, 10-5development, 2-1, 3-1features, 1-4integrating with application server, 7-1, 7-2mapping types, 30-1optimization, 11-1packaging your application, 9-1public source, 12-2runtime components, 3-2understanding, 1-1

Oracle TopLink Sessions Editor. see sessionsOracle TopLink Workbench

about, 4-1Ant integration, 4-53classpath, 4-2creating projects, 18-1development process, 4-1DRIVER_CLASSPATH, 4-2environment, 4-2error messages, 14-1, 14-3JDBC_CLASSPATH, 4-2parts of, 4-3preferences, 4-12project, 4-1, 18-2proxy, 4-13, 4-14, 18-16sample, 4-3table creator, creating, 5-4upgrading projects, 18-10

Oracle Virtual Private Database (VPD)isolated client sessions, 72-21proxy authentication, 72-22, 81-6, 83-13

oracle.sql.TimeStamp, 34-3order

query keys, 34-8relational mappings, 34-8

OrderSibling, 96-7orion-ejb-jar.xml file

about, 8-9entity-deployment attribute pm-name, 8-10modifying for Oracle TopLink, 8-9persistence-manager attribute

class-name, 8-10persistence-manager attribute

descriptor, 8-10persistence-manager attribute name, 8-10persistence-manager subentry

forpm-propertiescache-synchronizations, 8-11customization-class, 8-11db-platform-class, 8-11default-mapping, 8-11project-class, 8-11remote-relationships, 8-11session-name, 8-11

OTN (Oracle Technology Network), 1-4, 2-3OTS (Object Transaction Service)

about, 97-3

Index-19

unit of work, 97-3outer joins

in expressions, 94-11inheritance, 25-49

output parameter event in stored procedures, 94-23OX mappings

about, 30-27extensions, simple type translator, 30-13, 30-14read conversions, 30-13write conversions, 30-14

Ppackage names

generating, 4-30renaming, 4-52TopLink Workbench, Navigator window, 4-9see also classes

packaging for deploymentabout, 9-1BMP applications, 9-5CMP applications, 9-4EJB 3.0, 9-1Java applications, 9-1JSP and Servlet applications, 9-2Session Bean applications, 9-3

packet time-to-live cache coordination, 88-15parallel

expressions, 95-11unit of work, 97-9

parameter bindingabout, 11-15byte arrays, 11-16configuring, 20-7, 25-22, 83-9, 94-17database login level, 83-9descriptor level, 25-22external connection pools, 11-16internal connection pools, 11-16J2EE, 11-16named queries, 25-22optimizing, 11-15project level, 20-7queries, 94-17streams, 11-16strings, 11-16trouble shooting, 11-16

parameterized batch writingabout, 11-15setMaxBatchWritingSize(), 11-15

parameterized expressionsabout, 95-8example, 95-9

parameterized SQLenabling on queries, 94-17Oracle TopLink optimization features, 11-27See also parameter binding

parser conflicts, XML, 7-3partial object reading optimization, 11-20passwords, encryption, 18-13performance optimization

about, 11-1application bottleneck, 11-2examples, 11-20JConnect method isClosed, 11-14using Performance Profiler, 11-2

Performance Profilerabout, 11-2class, 11-3

persistenceabout, 2-19BEA WebLogic deployment, 8-14by reachability, 98-6components of, 2-12descriptor, 8-13implementation options, 2-12manager, 7-4OC4J, 7-5projects, 17-2types, 19-5using a persistence layer, 2-14

persistence managerdefault, 7-4migration, 7-4restrictions, 7-4

persistent classesproject, 4-32requirements, 2-11, 2-12types, 19-7

pessimistic lockingabout, 23-9, 23-22application architecture, 2-11policy, 23-22

phantom reads, preventing, 99-31platforms

Attunity Connect database, 81-3Cloudscape database, 81-3data source, 81-3database, 18-3, 20-2, 21-2, 81-3, 83-1, 84-1DB2 database, 81-3EIS, 81-4functions in expressions, 95-16HSQL database, 81-3Informix database, 81-3J2C adapter, 81-4JDBC drivers, 81-3Microsoft Access database, 81-3MySQL4 database, 81-3Oracle database, 81-3Oracle8 database, 81-3Oracle9 database, 81-3parser, XML, 7-2PointBase database, 81-3projects, and, 17-4server, 74-15session configuration, 74-15SQLAnyWhere database, 81-3SQLServer database, 81-3SybasePlatform database, 81-3XML parser, 7-2see also target platforms

Index-20

PointBase platform, 81-3pop-up menus. see context menusports

multicast group, 88-5permissions, 7-23, 7-24

post-commit clones, avoiding, 99-31Potential EJB Descriptors dialog box, 18-10pre-allocating sequence numbers, 17-20, 20-4, 83-5,

84-2preferences

class import, 4-16database, 4-17EJB, 4-16general, 4-13help, 4-14importing and exporting, 4-13Oracle TopLink Workbench, 4-12sessions, 4-18, 4-19

Preferences - Class dialog, 4-16Preferences - EJB dialog, 4-16Preferences - General dialog, 4-13Preferences - Help dialog, 4-14Preferences - Mappings dialog, 4-15Preferences dialog, 4-13prepared statement caching

about, 11-15configuring, 20-7, 25-22, 83-9, 94-17database login level, 83-9descriptor level, 25-22external connection pools, 11-16internal connection pools, 11-16J2EE, 11-16named queries, 25-22optimizing, 11-15project level, 20-7queries, 94-17query level, 94-17

preserving XML documents, 29-6primary key

about, 2-17cache, 93-34composite, 33-9inheritance, 23-16multiple tables, 26-13primkey in ejb-jar.xml file, 18-15queries with compound, 93-34read-only settings, 32-2restrictions, 17-15setting, 4-26, 25-3, 26-2unit of work, 97-11unknown, 25-47variable class relationships, 33-6, 38-3

private relationships, 32-16Problems window

about, 4-4, 4-11sample, 4-11see also error messages

profilerabout, 74-10development tool, 11-2

DMS, 11-4, 72-12Oracle TopLink, 11-2, 11-3, 72-12selecting, 74-11, 74-14, 74-17, 74-20

Project - Multiple Projects tab, 74-10Project Status Report dialog box, 18-13projects

about, 16-1, 17-1, 17-2, 18-2architecture, 17-2cache type and size, 19-13, 25-35comments, 19-20configuring, 19-1copying objects, 6-6creating, 7-9, 18-1, 18-2, 18-3, 18-6deployment login, and, 17-3deployment overview, 2-15descriptors, 16-2development login, and, 17-4direct access to mapped fields, 19-4EIS, 17-7, 17-9, 21-1errors, 14-3existence checking, 19-8exporting, 18-13, 18-14for sessions, 74-9indexed records, 17-9Java, 18-3JAXB, 18-6locked, 6-6login, 17-3, 71-1, 81-2login, and, 17-3mapped field access, default, 19-4mapped records, 17-9mapping projects, creating, 18-2mappings, 16-2, 18-2merging, 6-4metadata, 2-20method access to mapped fields, 19-4model, exporting, 18-14.mwp file, 4-1nondescriptor classes, 4-51non-persistent, 17-2nonrelational, 17-2object-relational, types supported, 17-6OC4J, creating from, 7-9open, 18-10Oracle TopLink Workbench, 18-2packages, renaming, 4-52persistence type, 17-2, 19-7platforms, and, 17-4prior TopLink versions, 18-10recently opened, 18-10relational, 17-2, 17-6, 20-1renaming, 18-12reopening, 18-10saving, 18-11sequencing, 17-4, 17-5, 20-3, 83-4session login, and, 17-3sharing, 6-6status report, 18-12team development, 6-3TopLink Workbench, Navigator window, 4-9

Index-21

types of, 17-1, 18-2, 23-1updating from ejb-jar.xml, 18-16upgrading from 2.x or 3.x, 18-10writing ejb-jar.xml file, 18-16XML, 17-9, 22-1XML records, 17-9

projects.xml fileabout, 8-2EJB 3.0, 8-3, 8-5schema, 8-2XSD file, 8-2

propagation mode, cache, 88-2proxies. see wrapper policyproxy authentication

about, 81-5applications, 81-5Oracle Virtual Private Database, 72-22, 81-6,

83-13session events, 72-6use cases, 81-5

proxy indirectionabout, 30-8example, 32-9restrictions, 30-8

proxy settings, preferences, 4-13public source code, 12-2

Qqualified names, database tables, 4-23, 4-24queries

about, 93-1application development process, 2-13, 71-2building, 93-6cache, 93-29Call queries, 93-3, 93-17cascading, 93-15, 94-14concepts, 93-2conforming, 99-8database queries, 93-10, 94-4DatabaseQuery, 93-3descriptor query manager, 93-3EIS interactions, 93-5EJB finders, 93-24EJB QL query language, 93-5ejb-jar.xml file, 25-10, 26-6, 28-6executing, 93-6expressions, 93-3fetch groups, 93-13flashback queries, 78-1, 93-18hierarchical queries, Oracle extensions, 93-18hints, Oracle extensions, 93-18historical, 93-21, 96-2interface and inheritance queries, 93-22joining, 93-12languages, about, 93-4named queries, 93-16object level modify query, 93-14, 93-15object level read query, 93-11, 93-13on inheritance hierarchies, 96-4

on interfaces, 96-4optimizing, 11-17Oracle database features, 96-5Oracle extensions, 93-18, 93-19parameter binding, 94-17partial object query, 93-11performance, 11-17prepared statement caching, 94-17query keys, 93-4read all query, 93-11read object query, 93-11redirect queries, 93-20remote sessions, 72-32report, 11-21, 93-8report query, 93-15results, 93-8returning policy, 93-17session queries, 93-9, 94-1SQL query language, 93-4stored functions, Oracle extensions, 93-19subqueries, 95-10summary queries, 93-3timeout, 25-24, 25-26, 94-10types, 93-1UpdateAll, 93-14XML query language, 93-5

Queries tab, 25-26, 25-28query by example, 94-6query cache, 93-36Query Exception, 13-31query keys

about, 25-30, 25-33, 93-4adding, 25-31, 25-34and expressions, 95-10creating, 25-31, 25-34direct mappings, 25-30generating, 25-30in expressions, 95-10interface descriptors, 25-31, 25-33Java implementation, 25-31modifying, 25-31order, 34-8relationship mappings, 25-31specifying, 25-31, 25-34unmapped attributes, 25-30, 25-31

Query Keys tab, 25-31query object query. See DatabaseQueryquery objects

batch reading, 94-10cache expiration, 96-21caching results, 93-36, 96-20examples, 94-5ordering for ReadAll queries, 94-9report query, 11-21specifying collection class, 94-9

query resultsabout, 93-8caching, 93-36collections, 93-8cursors, 93-8

Index-22

reports, 93-8streams, 93-8

query timeout example, 94-10QueryManager

about, 23-8joining expressions, 96-4

QuerySequence, 83-8

Rread access

providing in sessions, 72-16read all operation, 94-2read conversions

simple type translator, 30-13read only

descriptors, 25-5files, 6-6mappings, 32-2, 32-3

read operation, 94-2read optimization

about, 11-19batch reading, 11-20fetch groups, 25-79joining, 11-20lazy attribute loading, 25-79object indirection, 11-19partial object reading, 11-20report query, 11-20soft cache weak identity map, 11-19unit of work, 11-19weak identity map, 11-19

read queriescascading refresh of identity maps, 93-36identity map cache refresh, 93-35refreshing identity maps, 93-35

ReadAll findersexecuting, 96-10

ReadAll queriesordering in query objects, 94-9

readAllObjects()about, 26-8example, 94-2

readingejb-jar.xml, 18-16just-in-time reading, 30-8whole XML documents, 36-1

reading through the write connection, 99-28read-locking, 23-9readObject()

example, 94-2recently opened projects, 18-10redirect queries

about, 93-20, 96-1creating, 96-1finders, 96-13using, 96-12

reference key field, 33-11, 33-12reference object-relational mappings

configuring, 49-1, 50-1

understanding, 46-2ReferenceMapping class, 46-2references

database tables, 4-26, 4-28foreign keys, 14-15, 14-23

Refresh from Database button, 4-24refresh policy

cache, 87-8EJB finders, 87-8

refreshingcache, 25-27classes, 4-50refreshObject(), 94-2remote sessions, 72-32sessions, 75-5

registering objects, 99-1registerNewObject method, 99-2reimporting schemas, 4-35relation tables

about, 33-9many-to-many mappings, 40-1mappings, 40-2

relational descriptorsassociated table, 26-2configuring, 26-1locking policy, 25-64understanding, 23-11

relational mappingsabout, 33-1aggregate collection, 33-10, 41-1aggregate object, 33-12, 43-1configuring, 34-1converters, 33-3direct collection, 33-11, 42-1direct map, 33-12, 44-1direct-to-field, 33-4, 35-1direct-to-XMLType, 33-4, 36-1many-to-many, 33-8, 40-1one-to-many, 33-7, 39-1one-to-one, 33-5, 37-1options, 34-1order, 34-8transformation, 33-3, 33-15, 45-1variable one-to-one, 33-6, 38-1

relational projectsabout, 17-2configuring, 20-1object-relational databases, 17-6relational databases, 17-6understanding, 17-6

relationshipsabout, 2-17bidirectional, 4-31, 32-34, 33-5expressions, 95-6in ejb-jar.xml file, 18-16unexpected multiplicity, 7-14

relative locationsabout, 19-2classpath, 19-3

Remote Command Manager Exception, 13-71

Index-23

remote connection using RMI, example, 73-10remote sessions

about, 72-2, 72-30application layer, 72-31creating, 73-10limitations of, 72-31securing access, 72-32server layer, 72-31transport layer, 72-31unit of work, 72-32

Remove Class button, 4-51Remove Table button, 4-24removing sessions from brokers, 79-1Rename dialog, 4-24renaming

packages, 4-52projects, 18-10, 18-12

reopening projects, 18-10report query

about, 93-15query objects, 11-21read optimization, and, 11-20using, 11-21, 93-8

reportsproject status, 18-12query results, 93-8see also status reports

resuming unit of workafter commit, 99-14after commit failure, 99-14

returning policyconfiguring, 25-67SQLCall, 93-17

Returning tab, 25-68RMI

coordinated cache, 90-1naming service, 88-9remote session support, 72-31

rollbackand Java Transaction API, 97-11overview, 97-11with optimistic locking, 23-20

root classabout, 23-13inheritance, 23-13

root EIS descriptor, 24-5root element, descriptor, 29-5runtime

acquiring sessions, 72-5components, 3-2services, configuring sessions, 74-14troubleshooting, 15-14

SSave All button, 18-11Save button, 18-11saving projects, 19-2schema context

descriptors without, 29-3

EIS descriptors, 28-2XML descriptors, 29-2

Schema Document Info tab, 4-36, 4-38schema manager

about, 5-1automatic table creation, 5-6creating a table creator, 5-4DB2, 5-3default table generator, 5-4Java table creator, 5-4MS Access, 5-3MySQL, 5-3Oracle, 5-3Oracle TopLink Workbench table creator, 5-4sequencing, 5-3, 5-6Sybase, 5-3table creator, 5-2, 5-4, 5-6table definition, 5-2type conversion, 5-3usage, 5-1

Schema Structure tab, 4-34schemas

about, 2-17context for EIS descriptors, 28-2context for XML descriptor, 29-2data storage, 2-17database, 4-22default root for EIS descriptors, 28-4details, 4-34document information, 4-36, 4-38errors, 14-23importing, 4-35optimizing, 11-8properties, 4-35reimporting, 4-35schema manager, 5-1structure, 4-34XML schemas, 4-33

SCM. see source control managementscripts

SQL, generating, 4-29see also SQL

scrollable cursortraversing, 96-16using for ReadAllQuery, 96-16

securitycache coordination, permissions, 7-23data source access, permissions, 7-24disabling doPrivileged(), 7-25doPrivileged(), 7-4EJB, permissions, 7-24enabling doPrivileged(), 7-25J2EE application, permissions, 7-24java.util.logging, permissions, 7-24loading project.xml, permissions, 7-23loading sessions.xml, permissions, 7-23logging, permissions, 7-24password encryption, 18-13permissions by feature, 7-23permissions when doPrivileged()

Index-24

disabled, 7-24port permissions, 7-23, 7-24SecurityManager integration, 7-4system properties, permissions, 7-23understanding permissions, 7-22with BEA WebLogic, 7-20

Select Classes dialog box, 4-50SelectedFieldsLockingPolicy, 23-21sensors, DMS profiler, 11-4, 72-12SEQ_COUNT column in sequence table, 17-20sequence connection pools, 81-8sequence numbers, write optimization

features, 11-27SEQUENCE objects in Oracle native

sequencing, 17-19sequencing

and relational projects, 17-14BEA WebLogic, 17-22BEA WebLogic single column sequence

table, 17-17, 20-3, 83-4configuring, 17-15connection pools, 81-8default, 83-6DefaultSequence class, 83-6descriptors, 23-9, 26-3entity beans, 17-21IBM WebSphere, 17-22isolated client sessions, 72-24Java configuration, 17-15Microsoft SQL Server, 5-6native, 17-18, 17-19, 17-20non-Oracle database native, 17-19Oracle Database native, 17-18, 17-20Oracle TopLink Workbench configuration, 17-15overriding default, 83-6platform default, 83-6preallocation, 11-29, 17-20QuerySequence class, 83-8schema manager, 5-6SEQ_COUNT, 17-20sequence type, configuring, 20-3, 83-4sessions, and, 72-13stored procedures, 17-18, 83-7Sybase Database, 5-6table, 17-16table, default column and table names, 17-17unary table, 17-17with stored procedures, 83-7

serializationdescriptor exceptions, 99-13EJB 1.x, 30-9EJB 2.x, 30-9EJB 3.0, 30-10indirection, 30-9merging into session cache with unit of

work, 99-13serialized object converter

about, 12-2, 30-10configuring, 32-18

serialized object mappings, 32-19

SerializedObjectMapping. see SerializedObjectConverter

server layer, 72-31server platform

external transaction controller, 74-14runtime services, 74-14session configuration, 74-14session event listener, 74-17

Server Platform tab, 74-15server sessions

about, 72-1, 72-14, 72-15cache, 72-33connection options, 72-18

service channel, coordinated cache, 88-3session beans

about, 2-26deploying, 8-9, 9-3, 10-1model, 2-24, 2-26remote session support for, 72-31

session brokersabout, 72-2, 72-26adding sessions to, 79-1alternatives, 72-28architecture, 72-26configuration, 79-1limitations of, 72-28renaming, 79-1two-phase commits, 72-27two-stage commits, 72-27

session configuration fileabout, 73-1loading alternative, 75-4preferences, 4-18, 4-19see also sessions.xml file

session customizer, 72-4Session Event Manager, 72-5session events

example, 72-5, 72-6isolated sessions, and, 72-5manager, 72-5proxy authentication, and, 72-6

Session Loader Exceptions, 13-64Session Manager

about, 75-1, 75-2acquiring, 75-2, 75-3defaults, 75-3destroying sessions, 75-11J2EE defaults, 75-3sessions, acquiring, 72-5storing sessions, 75-10

sessionsabout, 2-13, 71-1, 72-1, 72-2, 73-1acquiring at runtime, 72-5, 75-1adding to session brokers, 79-1additional mapping projects, 74-9API, 72-33application server logging, 72-9architecture, 72-2cache, 72-33, 87-2client, 72-14

Index-25

configuring, 74-1, 74-17connection policy, 74-19creating, 2-21, 73-1, 73-4, 73-6, 73-8, 85-1customization, 72-4database sessions, 72-29, 73-8destroying in Session Manager, 75-11errors, 14-23event listeners, 72-7, 74-17events, 72-6external transaction controller, 74-14, 97-2historical client sessions, 72-25in sessions.xml file, 72-4isolated client sessions, 72-19, 77-1loading with alternative class loader, 75-4logging, 72-7, 72-9, 72-10, 74-4, 74-5logging into, 75-10logging out of, 75-10logins, 74-4management of, 75-1metadata, about, 2-21multiple sessions, 72-28, 75-2named queries, 74-21object cache, 72-3optimizing, 11-13preferences, 4-18, 4-19queries, 93-6, 93-9, 94-1refreshing, 75-5registering descriptors, 72-13, 74-2, 74-3, 74-10remote sessions, 72-30, 73-10sequencing, about, 72-13server, 72-14server platform, 74-14, 74-15SQL and messages, 72-10storing in Session Manager, 75-10three-tier architecture, 72-14transformation mappings, 33-15types, 72-1unit of work, 72-1, 72-19

sessions.xml fileabout, 8-4acquiring, 72-5CMP applications, 8-4, 72-4configuring with JDeveloper, 6-3creating, 73-1default location, 72-5EJB 3.0, 8-5loading alternative configuration file, 75-4non-CMP applications, 8-4schema, 8-4sessions, 72-4XSD file, 8-4

setAdditionalJoinExpression(), 96-5setenv.cmd file, 4-2setenv.sh file, 4-2setMaxBatchWritingSize(), 11-15setMultipleTableJoinExpression(), 96-5setShouldPerformDeletesFirst(), 99-17Settings tab, 25-26, 25-28setValue() method, 30-7shared library

setting for BEA WebLogic, 7-15shared library for BEA WebLogic, 7-15simple type translators

about, 12-2, 30-12configuring, 32-23in Java, 32-25read conversions, 30-13write conversions, 30-14

soft cache weak identity mapabout, 87-4when to use, 87-5

sorting, in memory, 32-26source code, public, 12-2source control management

projects, 6-3with Oracle TopLink Workbench, 6-3see also team development

source table, reference, 4-28source.jar, 12-2splash screen, 4-13SQL

call, 94-19comparing with expressions, 95-1custom queries for basic persistence, per

descriptor, 26-6EJBQLCall, 94-24generating from database tables, 4-29parameter binding, 11-15parameterized, 11-27, 94-17prepared statement caching, 11-15queries, 93-4scripts with binding arguments, 26-6SQLCall, 94-19StoredFunctionCall, 94-23StoredProcedureCall, 94-21unit of work, 99-16

SQL Creation Script dialog box, 4-29SQL DISTINCT, 11-24SQL Exception, 13-27SQLAnyWhere platform, 81-3SQLCall

about, 93-17binding input parameters, 94-20input parameters, 94-20input-output parameters, specifying, 94-21output parameters, 94-20Returning Policy, 93-17using, 94-19

SQLServer platform, 81-3stages of development with Oracle TopLink, 2-2stale data

cache, 87-6, 87-7coordination, cache, 87-7invalidating the cache, 87-7locking policy, and, 87-6per-class cache configuration, 87-7per-query cache refresh, 87-7

StartWith, 96-7stateful

beans, 2-26

Index-26

comparing with stateless, 2-26stateless

comparing with stateful, 2-26static attributes, 4-45, 4-48static fetch groups, querying with, 96-3status report, generating, 18-12stored functions

about, 93-19using, 94-23

stored proceduresoutput parameter event, 94-23queries, 94-21sequencing, and, 17-18, 83-7

streamsas query results, 93-8cursored, 72-32, 96-18

string bindings, CLOB mappings, 31-4structure object-relational mappings

configuring, 48-1understanding, 46-2

StructureMapping class, 46-2subqueries

multiple expressions, 95-10subselects in expressions, 95-10

subselects, in expressions, 95-10summary queries, 93-3superclass, 4-41Sybase

database schema manager type conversion, 5-3native sequencing, 17-19platform, 81-3

synchronous change propagation, 88-2system properties

oracle.j2ee.security.usedoprivileged, 7-25oracle.j2ee.toplink.security.usedoprivileged, 7-25toplink.cts.collection.checkParameter

s, 7-25toplink.xml.platform, 7-3

Ttable creator

about, 5-2creating, 5-4using, 5-6

Table Creator dialog, 5-4table generation. see automatic table generationtable sequence

about, 17-16default column and table names, 17-17

tablesadding database, 4-22associating with relational descriptors, 26-2database, 4-21defining schema, 5-2errors, 14-17generating, automatic, 30-4import filter, 4-23mapping to descriptors, 25-3, 26-2merging files, 6-5

multiple, 26-13primary key, 4-26references, 34-8relation tables for mappings, 40-2TableDefinition class, 5-2see also database tables

target foreign keysabout, 33-5, 34-9configuring, 34-9

target platformsabout, 2-5choosing, 2-3

target tablesin direct collection mappings, 42-1reference, 4-28

team development, 6-3technical support, 2-3three-tier architecture

about, 1-4, 2-22authentication, 81-5migrating to scalable architecture, 72-29overview, 2-22sessions, 72-14

timestamp supportabout, 34-3direct to field mappings, 34-3Oracle Database, 34-3TIMESTAMP timezone, 34-4

TimestampLockingPolicy, 23-18timezone, with TIMESTAMP, 34-4tljaxb.cmd file, 18-8toolbars, 4-4, 4-6topic name, 89-1TopLink. see Oracle TopLinkTopLink expressions. see expressionsTopLink profiler

about, 11-2selecting, 74-11, 74-14, 74-17, 74-20

TopLink Workbench. see Oracle TopLink Workbenchtoplink-ejb-jar.xml file, 8-6, 16-2toplink-ejb.xml file, 8-7Transaction Exception, 13-73transactional data sources, 81-1transactions

client-controlled, 99-25CMP, 97-3, 99-25container-controlled, 99-25demarcation, 97-2external transaction controller, 74-14, 97-2external, integrating, 97-2, 99-21isolated client sessions, 72-25isolation, 97-2, 97-4JTA, 97-3JTS, 97-3local, 99-25local, CMP, 99-25OTS, 97-3overview, 2-14, 71-3, 97-1see also unit of work

transformation EIS mappings

Index-27

configuring, 61-1understanding, 53-17

transformation mappingsabout, 30-14attribute transformation, 32-29, 32-31mutable, 32-33

transformation relational mappingsconfiguring, 45-1understanding, 33-15

transformation XML mappingsconfiguring, 70-1understanding, 62-31

transient attributes, 4-45, 4-48transparent indirection

about, 30-8persistent class requirements, 2-12

transport layer, 72-31troubleshooting

BEA WebLogic deployment, 15-3data sources, 14-25deploy tool, 10-6deployment, 15-1ejbc, 10-3IBM WebSphere deployment, 15-12migration from OC4J persistence, 7-13Oracle TopLink Workbench, 14-1unit of work, 99-31, 99-35

two-phase commits, 72-27two-stage commits, 72-27two-tier architecture

about, 1-6, 2-24authentication, 81-5understanding, 2-24

type conversionautomatic, 34-2NCHAR, 30-12NCLOB, 30-12NVARCHAR2, 30-12oracle.sql.TimeStamp, 34-3schema manager, 5-3String to TIMESTAMP, 30-12TIMESTAMP to String, 30-12

type conversion converterabout, 12-2, 30-11configuring, 32-20provided by direct-to-field mappings, 34-3

TypeConversionMappingsee TypeConversionConverter

types of mappings, 30-1typesafe enumeration, in EIS mappings, 53-3

Uunary table sequence

about, 17-17BEA WebLogic single column sequence

table, 17-17, 20-3, 83-4undeployment, 10-4unexpected relationship multiplicity, 7-14unidirectional relationships, 33-2

unit of workabout, 97-1, 97-2, 97-4acquiring, 98-1API, 97-11architecture, 97-1auditing, 99-21benefits of, 97-4cache, 87-2change policy, 97-6clones, 97-9CMP integration, 97-3commit and Java Transaction API, 97-10commit, writing changes before, 99-7, 99-12,

99-24conform results of in-memory query, 93-31creating objects, 98-2deleting objects, 98-7example, 97-6external transaction controller, 74-14, 97-2external transactions, 97-2, 99-21integrating with CMP, 99-24isolation, 97-4JTA integration, 97-3JTS integration, 97-3life cycle, 97-5modifying objects, 98-2mutable mappings, 32-33nested, 97-9, 99-15newInstance method, 99-2optimization, 11-30, 97-11OTS integration, 97-3parallel, 97-9, 99-15pre-commit validation, 99-35primary keys, 97-11proxy indirection, 30-8queries, 97-12read optimization, 11-19read-only classes, 99-6, 99-7registerNewObject method, 99-2remote sessions, 72-32resuming, 99-14reverting, 99-15rollback, 97-11sessions, 72-1, 72-19transaction demarcation, 97-2transactions, 97-4

unit of workdemarcation, 97-2

troubleshooting, 99-31validating objects, 99-34with custom SQL, 99-16write optimization, 11-26writing changes before commit, about, 99-7writing changes before commit, and external

transaction exceptions, 99-24writing changes before commit, and external

transaction timeouts, 99-24writing changes before commit, as alternative to

conforming, 99-12unmapping, 31-6

Index-28

unregistering objects, 99-1unsaved items, displaying in TopLink Workbench

Navigator window, 4-9update

operation, 94-3, 94-4projects from prior versions, 18-10

UpdateAll query, 93-14updateObject(), 26-8Use XML Schema "type" attribute,

configuring, 32-23useBatchWriting(), 83-11user-defined functions, in expressions, 95-16

Vvalidating

descriptors, 24-6JAXB, 17-14projects, 18-12unit of work, 99-34

Validation Exceptions, 13-43Value Converter tab, 44-4value holders

about, 30-7ValueHolder class, 30-7

ValueHolderInterface class, 2-12, 30-7, 33-9variable one-to-one relational mappings

class indicator, 38-1configuring, 38-1primary key, unique, 38-3understanding, 33-6

VariableOneToOneMapping class, 33-6Varray in Oracle database. see array mappingsversion control, 6-6Version Control Assistance dialog box, 6-6VersionLockingPolicy, 23-18volatile attributes, 4-45, 4-48VPD. see Oracle Virtual Private Database

Wwarning icon, 4-10, 4-11weak identity map, 87-3web browser, specifying, 4-14web services architecture, 1-6, 2-35WebLogic. see BEA WebLogicweblogic-ejb-jar.xml file

described, 8-5modifying for Oracle TopLink, 8-13unsupported tags, 8-15

WebSphere. see IBM WebSpherewelcome screen, 4-14wildcard, 63-3wrapper policy

about, 25-78implementing in Java, 25-79

writeconversions, simple type translator, 30-14write all operation, 94-3

write query

disabling identity map cache, 94-15non-cascading, 94-14objects, 94-13overview, 94-13

write-locking, 23-9writing

batch, 11-26, 83-11ejb-jar.xml file, 18-16optimization, 11-26sessions write access, 72-17

Xxdb.jar file, 4-3XML

descriptor, schema context, 29-2generating deployment, 8-3mappings, concepts, 62-2preserving data, 29-6projects, 18-3query language, 93-5reading whole documents, 36-1records, 53-3schemas, 4-33

XML Conversion Exception, 13-74XML descriptors

configuring, 29-1schema context, 29-2understanding, 23-12

XML mappingsabout, 62-1any collection, 62-29, 69-1any object, 62-27, 68-1any type support, 62-4composite collection, 62-25, 67-1composite direct collection, 62-14, 65-1composite object, 62-21, 66-1concepts, 62-2configuring, 63-1default conversion pairs, customizing, 62-11direct, 62-5, 64-1extensions, 62-4jaxb:class support, 62-4list support, 62-3reference descriptor, configuring, 63-2transformation, 62-31, 70-1types of, 62-1union support, 62-3xsd:list, 62-3xsd:union, 62-3

XML parser platformabout, 7-2configuring, 7-3creating, 7-3Crimson, 7-3default, 7-3limitations, 7-3parser conflicts, 7-3toplink.xml.platform system property, 7-3used by, application server, 7-2

Index-29

used by, Oracle TopLink, 7-2XML Platform Exception, 13-83XML projects

configuring, 22-1JAXB support, 17-10sequencing, 17-5understanding, 17-9

XML queries, 93-5XML schema

jaxb:class, and EIS mappings, 53-3jaxb:class, and XML mappings, 62-4jaxb:class, understanding, 30-20type, 32-23xs:any, understanding, 62-4xs:anyType, understanding, 62-4xsd:list, understanding, 30-17xsd:union, understanding, 30-17see also schemas

XML Type functions, 95-5XMLMarshalException, 13-81XMLPlatformException, 13-83XPath

by name, 30-16by position, 30-15mapping Java attributes, 32-10support in OX mappings, 30-15support in XML mappings, 53-3, 62-3

XSD fileprojects.xml file, 8-2sessions.xml file, 8-4

Zzero-argument constructors

editing, 4-16

Index-30