Skip Headers
Oracle TopLink Developer's Guide
10
g
Release 3 (10.1.3)
B13593-01
Home
Solution Area
Index
Next
Contents
Title and Copyright Information
Preface
Audience
Documentation Accessibility
Related Documentation
Conventions
Volume 1: Understanding TopLink
Part I Building a TopLink Application
1
Understanding TopLink
What is TopLink?
Solving the Object-Persistence Impedance Mismatch
TopLink Key Features
TopLink Application Architectures
2
Understanding TopLink Application Development
Developing Your Application With TopLink
Typical Development Stages
Oracle Development Support
Designing Your Application With TopLink
Understanding TopLink Usage
Understanding Target Platforms
Selecting an Architecture With TopLink
Tiers
Service Layer
Data Access
Caching
Locking
Building and Using the Persistence Layer
Implementation Options
Persistent Class Requirements
Persistence Layer Components
Using the Persistence Layer
Deploying the Application
Understanding Deployments
TopLink in a J2EE Application
Optimizing and Customizing the Application
Troubleshooting the Application
Understanding Object Persistence
Application Object Model
Data Storage Schema
Primary Keys and Object Identity
Mappings
Foreign Keys and Object Relationships
Inheritance
Concurrency
Caching
Nonintrusive Persistence
Indirection
Understanding TopLink Metadata
Advantages of the TopLink Metadata Architecture
Creating Project Metadata
Creating Session Metadata
Deploying Metadata
Understanding the Three-Tier Architecture
Example Implementations
Advantages and Disadvantages
Variation Using Remote Sessions
Technical Challenges
Understanding the Two-Tier Architecture
Example Implementations
Advantages and Disadvantages
Technical Challenges
Understanding the EJB Session Bean Facade Architecture
Example Implementation
Advantages and Disadvantages
Understanding Session Beans
Technical Challenges
Unit of Work Merge
Understanding the EJB Entity Beans with CMP Architecture
Example Implementation
Advantages and Disadvantages
Technical Challenges
Understanding the EJB Entity Beans With BMP Architecture
Example Implementations
Advantages and Disadvantages
Technical Challenges
Understanding the Web Services Architecture
Example Implementations
Advantages and Disadvantages
Technical Challenges
Part II Using TopLink Development Tools
3
Understanding TopLink Development Tools
Development Environment
TopLink Run-Time Environment
4
Using an Integrated Development Environment
Configuring TopLink for Oracle JDeveloper
Using TopLink Mappings
Using TopLink Sessions
Configuring TopLink Workbench With Source Control Management Software
Using a Source Control Management System
Merging Files
Sharing Project Objects
Managing the ejb-jar.xml File
Working With Locked Files
5
Using TopLink Workbench
Understanding TopLink Workbench
Configuring the TopLink Workbench Environment
Working With TopLink Workbench
Using the Menus
Using the Toolbars
Using the Navigator
Using the Editor
Using the Problems Window
Using the Online Help
Working With TopLink Workbench Preferences
General Preferences
Help Preferences
Mappings Preferences
Class Preferences
EJB Preferences
Database Preferences
Sessions Configuration Preferences
New Names Preferences
Platform Preferences
Working With Databases
Working With Database Tables in the Navigator Window
Working With Database Tables in the Editor Window
Generating Data From Database Tables
Working With XML Schemas
Working With XML Schemas in the Navigator
Working With XML Schema Structure
Importing an XML Schema
Configuring XML Schema Reference
Configuring XML Schema Namespace
Working With Classes
Creating Classes
Configuring Classes
Importing and Updating Classes
Managing Nondescriptor Classes
Renaming Packages
Integrating TopLink Workbench With Apache Ant
Configuring Ant to Use TopLink Workbench Tasks
Understanding TopLink Workbench Ant Task API
Creating TopLink Workbench Ant Tasks
mappings.validate
session.validate
mappings.export
classpath
ignoreerror
ignoreerrorset
loginspec
6
Using the Schema Manager
Understanding the Schema Manager
Schema Manager Java and Database Type Conversion
Sequencing
Creating a Table Creator
Using TopLink Workbench During Development
Using the Default Table Generator at Run Time
Using Java
Creating Tables With a Table Creator
Automatic Database Table Creation
Part III Deploying a TopLink Application
7
Integrating TopLink With an Application Server
Application Server Support
Application Server Integration Concepts
Software Requirements
XML Parser Platform Configuration
Security Permissions
Persistence Manager Migration
Clustering
Oracle Containers for J2EE (OC4J)
CMP Integration
Migrating OC4J Orion Persistence to OC4J TopLink Persistence
JTA Integration
BEA WebLogic Server
Classpath
CMP Integration
Migrating BEA WebLogic Persistence to OC4J TopLink Persistence
JTA Integration
Security Manager
IBM WebSphere Application Server
Classpath
CMP Integration
JTA Integration
Clustering on IBM WebSphere Application Server
Understanding Security Permissions
Permissions Required by TopLink Features
Permissions Required When doPrivileged is Disabled
Disabling doPrivileged Operation
Configuring Miscellaneous EJB Options
Setter Parameter Type Checking
Unknown Primary Key Class Support
Single-Object Finder Return Type Checking
8
Creating TopLink Files for Deployment
Understanding TopLink Deployment File Creation
project.xml File
sessions.xml File
ejb-jar.xml File
<J2EE-Container>
-ejb-jar.xml File
toplink-ejb-jar.xml File
Java Applications
JavaServer Pages and Servlet Applications
Session Bean Applications
CMP Applications
BMP Applications
Configuring the orion-ejb-jar.xml File for OC4J
Configuring persistence-manager Entries
Configuring the weblogic-ejb-jar.xml File for BEA WebLogic Server
Configuring persistence-descriptor Entries
Unsupported weblogic-ejb-jar.xml File Tags
9
Packaging a TopLink Application
Java Applications
JavaServer Pages and Servlet Applications
TopLink Domain JAR
Session Bean Applications
TopLink Domain JAR
EJB JAR
CMP Applications
EJB JAR
BMP Applications
TopLink Domain JAR
EJB JAR
Packaging With TopLink Metadata File Resource Paths
10
Deploying a TopLink Application
Java Applications
JavaServer Pages and Servlets
Session Bean Applications
CMP Applications
Deploying a CMP Application to OC4J
Deploying a CMP Application to BEA WebLogic Server
Deploying a CMP Application to IBM WebSphere Application Server 4.0
BMP Applications
Hot Deployment of EJB
Hot Deployment in a CMP Application
Hot Deployment in a non-CMP Application
Using the WebSphere Deploy Tool
Using the Deploy Tool on its Own
Using the Deploy Tool With WebSphere Studio Application Developer
Part IV Optimizing and Customizing a TopLink Application
11
Optimization
Understanding Optimization
Sources of Application Performance Problems
Measuring Performance With the TopLink Profiler
Configuring the TopLink Performance Profiler
Accessing the TopLink Profiler Results
Measuring Performance With the Oracle Dynamic Monitoring System (DMS)
Configuring the Oracle DMS Profiler
Accessing Oracle DMS Profiler Data Using JMX
Accessing Oracle DMS Profiler Data Using the DMS Spy Servlet
General Performance Optimization
Schema Optimization
Schema Case 1: Aggregation of Two Tables into One
Schema Case 2: Splitting One Table Into Many
Schema Case 3: Collapsed Hierarchy
Schema Case 4: Choosing One out of Many
Mapping and Descriptor Optimization
Session Optimization
Cache Optimization
Data Access Optimization
JDBC Driver Properties Optimization
Data Format Optimization
Batch Writing
Parameterized SQL (Binding) and Prepared Statement Caching
Query Optimization
Parameterized SQL and Prepared Statement Caching
Named Queries
Batch and Join Reading
Partial Object Queries and Fetch Groups
JDBC Fetch Size
Cursored Streams and Scrollable Cursors
Read Optimization Examples
Write Optimization Examples
Unit of Work Optimization
Application Server and Database Optimization
12
Customization
Overview
Creating Custom Data Types
Using Public Source
Part V Troubleshooting a TopLink Application
13
TopLink Exception Reference
Descriptor Exceptions (1 – 200)
Concurrency Exceptions (2001 – 2006)
Conversion Exceptions (3001– 3008)
Database Exceptions (4002 – 4018)
Optimistic Lock Exceptions (5001 – 5008)
Query Exceptions (6001 – 6121)
Validation Exceptions (7001 – 7147)
EJB QL Exceptions (8001 – 8010)
Session Loader Exceptions (9000 - 9010)
EJB Exception Factory Exceptions (10001 - 10069)
Communication Exceptions (12000 - 12003)
XML Data Store Exceptions (13000 - 13020)
Deployment Exceptions (14001 - 14033)
Synchronization Exceptions (15001 - 15025)
SDK Data Store Exceptions (17001 - 17006)
EIS Exceptions (17007 – 17025)
JMS Processing Exceptions (18001 - 18002)
SDK Descriptor Exceptions (19001 - 19003)
Default Mapping Exceptions (20001 - 20008)
Discovery Exceptions (22001 - 22004)
Remote Command Manager Exceptions (22101 - 22111)
Transaction Exceptions (23001 - 23011)
XML Conversion Exceptions (25001 - 25016)
Migration Utility Exceptions (26001 - 26017)
EJB JAR XML Exceptions (72000 – 72022)
14
TopLink Workbench Error Reference
Miscellaneous Errors (1 – 89)
Project Errors (100 – 126)
Descriptor Errors (200 – 350)
Mapping Errors (400 – 483)
Table Errors (500 – 610)
XML Schema Errors (700 – 706)
Session Errors (800 – 812)
Common Classpath Problems
Data Source Problems
Database Connection Problems
15
Troubleshooting Application Deployment
Generating Deployment JAR Files
Common J2SE Deployment Exceptions
Classpath Exceptions
Communication Exceptions
Descriptor Validation Exceptions
Common BEA WebLogic Server Deployment Exceptions
Common BEA WebLogic Server 6.1 Exceptions
Development Exceptions
Deployment and Run Time Exceptions
Common BEA WebLogic 7.0 Exceptions
Development Exceptions
Deployment Exceptions
Common BEA WebLogic 8.1 Exceptions
Development Exceptions
Deployment Exceptions
Common IBM WebSphere Application Server Exceptions
Problems at Run Time
Common TopLink for IBM WebSphere Deploy Tool Exceptions
Part VI TopLink Tutorial
16
Planning the Tutorial Project
Overview
Before you Begin
Understanding the Tutorial Project
Source Files
Data Model
17
Building the Tutorial Project
Step 1: Creating a Project
TopLink Workbench Project
Adding Java Classes
Step 2: Adding a Data Source
Creating a Database Development Login
Importing Database Tables
Project-Level Sequencing
Step 3: Associating Descriptors to Tables
Associating With Multiple Tables
Descriptor-Level Sequencing
Step 4: Mapping Attributes
Direct-to-Field Mappings
One-to-One Mappings
One-to-Many Mappings
Object Type Mappings
Aggregate Object Mappings
Direct Collection Mappings
Many-to-Many Mappings
Transformation Mappings
Step 5: Using Advanced Descriptor Properties
Inheritance
Locking Policy
Named Queries
Step 6: Verifying the Project
18
Deploying the Tutorial Project
Step 1: Generating Deployment Information
Creating the project.xml File
Step 2: Creating Sessions Configuration
Creating the sessions.xml File
Creating a Server Session
Associating the Project With the Session
Updating the data-sources.xml File
Creating a Database Deployment Login
Configuring Logging Options
Step 3: Packaging for Deployment
Domain JAR File
WAR File
EAR File
Step 4: Deploying to an Application Server
Step 5: Running the Tutorial Application
Volume 2: Understanding Mappings
Part VII Mapping and Configuration Overview
19
Understanding TopLink Mapping and Configuration
Mapping and Configuration Concepts
Projects
Descriptors
Mappings
Part VIII Projects
20
Understanding Projects
TopLink Project Types
Project Concepts
Project Architecture
Relational and Nonrelational Projects
Persistent and Nonpersistent Projects
Projects and Login
Projects and Platforms
Projects and Sequencing
XML Namespaces
Relational Projects
Building Relational Projects for a Relational Database
Building Relational Projects for an Object-Relational Database
EIS Projects
Building EIS Projects with XML Records
Building EIS Projects With Indexed or Mapped Records
XML Projects
TopLink Support for Java Architecture for XML Binding (JAXB)
JAXB Validation
Understanding the Project API
Project Inheritance Hierarchy
Understanding Sequencing in Relational Projects
Sequencing Configuration Options
Sequencing Types
Sequencing and Preallocation Size
Sequencing With CMP Entity Beans
Understanding XML Namespaces
TopLink Workbench Namespace Resolution
Element and Attribute Form Options
TopLink Runtime Namespace Resolution
21
Creating a Project
Project Creation Overview
Using TopLink Workbench
Using Java
Creating a Project for an Existing Object and Data Model
Using TopLink Workbench
Creating a Project From an Existing Object Model
Using TopLink Workbench
Creating a Project From an Existing Data Model
Using TopLink Workbench
Creating an XML Project From an XML Schema
Using TopLink Workbench
Using the Command Line
Creating a Project by Migrating an EAR to OC4J
Creating a Project From an OC4J EJB 2.0 CMP EAR at Deployment Time
Working With Projects
Opening Existing Projects
Saving Projects
Generating the Project Status Report
Exporting Project Information
Exporting Deployment XML Information
Exporting Model Java Source
Exporting Project Java Source
Exporting Table Creator Files
Working With the ejb-jar.xml File
Writing to the ejb-jar.xml File
Reading From the ejb-jar.xml File
22
Configuring a Project
Configuring Common Project Options
Configuring Project Save Location
Using TopLink Workbench
Configuring Project Classpath
Using TopLink Workbench
Configuring Mapped Field Access at the Project Level
Using TopLink Workbench
Configuring Persistence Type
Using TopLink Workbench
Configuring Default Descriptor Advanced Properties
Using TopLink Workbench
Configuring Existence Checking at the Project Level
Using TopLink Workbench
Configuring Project Deployment XML Options
Using TopLink Workbench
Configuring Model Java Source Code Options
Using TopLink Workbench
Configuring Deprecated Direct Mappings
Using TopLink Workbench
Configuring Cache Type and Size at the Project Level
Using TopLink Workbench
Configuring Cache Isolation at the Project Level
Using TopLink Workbench
Configuring Cache Coordination Change Propagation at the Project Level
Using TopLink Workbench
Configuring Cache Expiration at the Project Level
Using TopLink Workbench
Configuring Project Comments
Using TopLink Workbench
23
Configuring a Relational Project
Relational Project Configuration Overview
Configuring Relational Database Platform at the Project Level
Using TopLink Workbench
Configuring Sequencing at the Project Level
Using TopLink Workbench
Using Java
Configuring Login Information
Using TopLink Workbench
Configuring Development and Deployment Logins
Using TopLink Workbench
Configuring Named Query Parameterized SQL and Statement Caching at the Project Level
Using TopLink Workbench
Configuring Table Generation Options
Using TopLink Workbench
Configuring Table Creator Java Source Options
Using TopLink Workbench
Configuring Project Java Source Code Options
Using TopLink Workbench
24
Configuring an EIS Project
EIS Project Configuration Overview
Configuring EIS Data Source Platform at the Project Level
Using TopLink Workbench
Configuring EIS Connection Specification Options at the Project Level
Using TopLink Workbench
25
Configuring an XML Project
XML Project Configuration Overview
Part IX Descriptors
26
Understanding Descriptors
Descriptor Types
Descriptor Concepts
Descriptor Architecture
Descriptors and Inheritance
Descriptors and EJB
Fetch Groups
Amendment and After-Load Methods
Descriptors and Aggregation
Descriptor Event Manager
Descriptor Query Manager
Descriptors and Sequencing
Descriptors and Locking
Default Root Element
Relational Descriptors
Object-Relational Descriptors
EIS Descriptors
XML Descriptors
Understanding Descriptors and Inheritance
Specifying a Class Indicator
Inheritance and Primary Keys (Relational and EIS Only)
Single and Multi-Table Inheritance (Relational Only)
Aggregate and Composite Descriptors and Inheritance
Inheritance and EJB
Understanding Descriptors and Locking
Optimistic Version Locking Policies
Optimistic Version Locking Policies and Cascading
Optimistic Locking and Rollbacks
Optimistic Field Locking Policies
Pessimistic Locking Policy
Locking in a Three-Tier Application
Understanding the Descriptor API
Descriptor Inheritance Hierarchy
27
Creating a Descriptor
Descriptor Creation Overview
Creating a Relational Descriptor
Using TopLink Workbench
Using Java
Creating an Object-Relational Descriptor
Using Java
Creating an EIS Descriptor
Using TopLink Workbench
Using Java
Creating an XML Descriptor
Using TopLink Workbench
Using Java
Validating Descriptors
Generating Java Code for Descriptors
28
Configuring a Descriptor
Configuring Common Descriptor Options
Configuring Primary Keys
Using TopLink Workbench
Using Java
Configuring Read-Only Descriptors
Using Read-Only Entity Beans
Using TopLink Workbench
Using Java
Configuring Unit of Work Conforming at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Descriptor Alias
Using TopLink Workbench
Using Java
Configuring Descriptor Comments
Using TopLink Workbench
Configuring Named Queries at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Query Timeout at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Cache Refreshing
Using TopLink Workbench
Using Java
Configuring Query Keys
Using TopLink Workbench
Using Java
Configuring Interface Query Keys
Using TopLink Workbench
Using Java
Configuring Cache Type and Size at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Cache Isolation at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Cache Coordination Change Propagation at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Cache Expiration at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Cache Existence Checking at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring a Descriptor With EJB Information
Using TopLink Workbench
Using Java
Configuring Reading Subclasses on Queries
Using TopLink Workbench
Using Java
Configuring Inheritance for a Child (Branch or Leaf) Class Descriptor
Using TopLink Workbench
Using Java
Configuring Inheritance for a Parent (Root) Descriptor
Using TopLink Workbench
Using Java
Configuring Inheritance Expressions for a Parent (Root) Class Descriptor
Using Java
Configuring Inherited Attribute Mapping in a Subclass
Using TopLink Workbench
Using Java
Configuring a Domain Object Method as an Event Handler
Using TopLink Workbench
Using Java
Configuring a Descriptor Event Listener as an Event Handler
Using Java
Configuring Locking Policy
Using TopLink Workbench
Using Java
Configuring Returning Policy
Using TopLink Workbench
Using Java
Configuring Instantiation Policy
Using TopLink Workbench
Using Java
Configuring Copy Policy
Using TopLink Workbench
Using Java
Configuring Change Policy
Using Java
Configuring a History Policy
Using Java
Configuring Wrapper Policy
Using Java
Configuring Fetch Groups
Using Java
Configuring Amendment Methods
Using TopLink Workbench
29
Configuring a Relational Descriptor
Relational Descriptor Configuration Overview
Configuring Associated Tables
Using TopLink Workbench
Using Java
Configuring Sequencing at the Descriptor Level
Using TopLink Workbench
Using Java
Configuring Custom SQL Queries for Basic Persistence Operations
Using TopLink Workbench
Using Java
Configuring Interface Alias
Using TopLink Workbench
Using Java
Configuring a Relational Descriptor as a Class or Aggregate Type
Using TopLink Workbench
Using Java
Configuring Multitable Information
Using TopLink Workbench
Using Java
30
Configuring an Object-Relational Descriptor
Object-Relational Descriptor Configuration Overview
Configuring Field Ordering
Using Java
31
Configuring an EIS Descriptor
EIS Descriptor Configuration Overview
Configuring Schema Context for an EIS Descriptor
Using TopLink Workbench
Using Java
Configuring Default Root Element
Using TopLink Workbench
Using Java
Configuring Record Format
Using Java
Configuring Custom EIS Interactions for Basic Persistence Operations
Using TopLink Workbench
Using Java
Configuring an EIS Descriptor as a Root or Composite Type
Using TopLink Workbench
Using Java
32
Configuring an XML Descriptor
XML Descriptor Configuration Overview
Configuring Schema Context for an XML Descriptor
Using TopLink Workbench
Using Java
Configuring for Complex Type of anyType
Using TopLink Workbench
Configuring Default Root Element
Using TopLink Workbench
Configuring Document Preservation
Using TopLink Workbench
Using Java
Part X Mappings
33
Understanding Mappings
Mapping Types
Mapping Concepts
Mapping Architecture
Example Mapping
Automatic Mappings
Indirection
Method Accessors and Attribute Accessors
Mapping Converters and Transformers
Mappings and XPath
Mappings and xsd:list and xsd:union Types
Mappings and the jaxb:class Customization
Mappings and JAXB Typesafe Enumerations
Understanding the Mapping API
Relational Mappings
Object-Relational Mappings
XML Mappings
EIS Mappings
34
Creating a Mapping
Mapping Creation Overview
Creating Mappings Manually During Development
Using TopLink Workbench
Creating Mappings Automatically During Development
Using TopLink Workbench
Creating Mappings Automatically During Deployment
Removing Mappings
Using TopLink Workbench
35
Configuring a Mapping
Configuring Common Mapping Options
Configuring Read-Only Mappings
Using TopLink Workbench
Using Java
Configuring Indirection
Using TopLink Workbench
Using Java
Configuring XPath
Using TopLink Workbench
Configuring a Default Null Value at the Mapping Level
Using TopLink Workbench
Using Java
Configuring Method Accessing
Using TopLink Workbench
Using Java
Configuring Private or Independent Relationships
Using TopLink Workbench
Using Java
Configuring Mapping Comments
Using TopLink Workbench
Configuring a Serialized Object Converter
Using TopLink Workbench
Using Java
Configuring a Type Conversion Converter
Using TopLink Workbench
Using Java
Configuring an Object Type Converter
Using TopLink Workbench
Using Java
Configuring a Simple Type Translator
Using TopLink Workbench
Using Java
Configuring a JAXB Typesafe Enumeration Converter
Using Java
Configuring Container Policy
Using TopLink Workbench
Using Java
Configuring Attribute Transformer
Using TopLink Workbench
Using Java
Configuring Field Transformer Associations
Using TopLink Workbench
Using Java
Configuring Mutable Mappings
Using TopLink Workbench
Using Java
Configuring Bidirectional Relationship
Using TopLink Workbench
Configuring the Use of a Single Node
Using TopLink Workbench
Using Java
Volume 3: Understanding Relational Mappings
Part XI Relational Mappings
36
Understanding Relational Mappings
Relational Mapping Types
Relational Mapping Concepts
Directionality
Converters and Transformers
Relational Mappings and EJB
Direct-to-Field Mapping
Direct to XMLType Mapping
One-to-One Mapping
One-to-One Mappings and EJB
Variable One-to-One Mapping
One-to-Many Mapping
One-to-Many Mappings and EJB
Many-to-Many Mapping
Many-to-Many Mappings and EJB
Aggregate Collection Mapping
Aggregate Collection Mappings and Inheritance
Aggregate Collection Mappings and EJB
Implementing Aggregate Collection Mappings
Direct Collection Mapping
Direct Map Mapping
Aggregate Object Mapping
Aggregate Object Mappings with a Single Source Object
Aggregate Object Mappings With Multiple Source Objects
Implementing an Aggregate Object Relationship Mapping
Transformation Mapping
37
Configuring a Relational Mapping
Configuring Common Relational Mapping Options
Configuring a Database Field
Using TopLink Workbench
Configuring Reference Descriptor
Using TopLink Workbench
Configuring Batch Reading
Using TopLink Workbench
Using Java
Configuring Query Key Order
Using TopLink Workbench
Configuring Table and Field References (Foreign and Target Foreign Keys)
Using TopLink Workbench
38
Configuring a Relational Direct-to-Field Mapping
Relational Direct-to-Field Mapping Configuration Overview
39
Configuring a Relational Direct-to-XMLType Mapping
Relational Direct-to-XMLType Mapping Overview
Configuring Read Whole Document
Using TopLink Workbench
40
Configuring a Relational One-to-One Mapping
Relational One-to-One Mapping Configuration Overview
Configuring Joining at the Mapping Level
Using TopLink Workbench
41
Configuring a Relational Variable One-to-One Mapping
Relational Variable One-to-One Mapping Configuration Overview
Configuring Class Indicator
Using TopLink Workbench
Configuring Unique Primary Key
Understanding Unique Primary Key
Using TopLink Workbench
Using Java
Configuring Query Key Association
Using TopLink Workbench
42
Configuring a Relational One-to-Many Mapping
Relational One-to-Many Mapping Configuration Overview
43
Configuring a Relational Many-to-Many Mapping
Relational Many-to-Many Mapping Configuration Overview
Configuring a Relation Table
Using TopLink Workbench
44
Configuring a Relational Aggregate Collection Mapping
Relational Aggregate Collection Mapping Configuration Overview
45
Configuring a Relational Direct Collection Mapping
Relational Direct Collection Mapping Configuration Overview
Configuring Target Table
Using TopLink Workbench
Configuring Direct Value Field
Using TopLink Workbench
46
Configuring a Relational Direct Map Mapping
Relational Direct Map Mapping Configuration Overview
Configuring Direct Value Field
Using TopLink Workbench
Configuring Direct Key Field
Using TopLink Workbench
Configuring Key Converters
Using TopLink Workbench
Configuring Value Converters
Using TopLink Workbench
47
Configuring a Relational Aggregate Object Mapping
Relational Aggregate Object Mapping Configuration Overview
Configuring Aggregate Fields
Using TopLink Workbench
Configuring Allowing Null Values
Using TopLink Workbench
48
Configuring a Relational Transformation Mapping
Relational Transformation Mapping Configuration Overview
Part XII Object-Relational Mappings
49
Understanding Object-Relational Mappings
Object-Relational Mapping Types
Object-Relational Structure Mapping
Object-Relational Reference Mapping
Object-Relational Array Mapping
Object-Relational Object Array Mapping
Object-Relational Nested Table Mapping
50
Configuring an Object-Relational Mapping
Configuring Common Object-Relational Mapping Options
Configuring Reference Class
Using Java
Configuring Attribute Name
Using Java
Configuring Field Name
Using Java
Configuring Structure Name
Using Java
51
Configuring an Object-Relational Structure Mapping
Object-Relational Structure Mapping Configuration Overview
52
Configuring an Object-Relational Reference Mapping
Object-Relational Reference Mapping Configuration Overview
53
Configuring an Object-Relational Array Mapping
Object-Relational Array Mapping Configuration Overview
54
Configuring an Object-Relational Object Array Mapping
Object-Relational Object Array Mapping Configuration Overview
55
Configuring an Object-Relational Nested Table Mapping
Object-Relational Nested Table Mapping Configuration Overview
Volume 4: Understanding Non-Relational Mappings
Part XIII EIS Mappings
56
Understanding EIS Mappings
EIS Mapping Types
EIS Mapping Concepts
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 Direct Mapping
EIS Composite Direct Collection Mapping
EIS Composite Object Mapping
EIS Composite Collection Mapping
EIS One-to-One Mapping
EIS One-to-One Mappings With Key on Source
EIS One-to-One Mappings With Key on Target
EIS One-to-Many Mapping
EIS One-to-Many Mappings With Key on Source
EIS One-to-Many Mappings With Key on Target
EIS Transformation Mapping
57
Configuring an EIS Mapping
Configuring Common EIS Mapping Options
Configuring Reference Descriptors
Using TopLink Workbench
Configuring Selection Interaction
Using TopLink Workbench
58
Configuring an EIS Direct Mapping
EIS Direct Mapping Configuration Overview
59
Configuring an EIS Composite Direct Collection Mapping
EIS Composite Direct Collection Mapping Configuration Overview
60
Configuring an EIS Composite Object Mapping
EIS Composite Object Mapping Configuration Overview
61
Configuring an EIS Composite Collection Mapping
EIS Composite Collection Mapping Configuration Overview
62
Configuring an EIS One-to-One Mapping
EIS One-to-One Mapping Configuration Overview
Configuring Foreign Key Pairs
Using TopLink Workbench
63
Configuring an EIS One-to-Many Mapping
EIS One-to-Many Mapping Configuration Overview
Configuring Foreign Key Pairs
Using TopLink Workbench
Configuring Delete All Interactions
Using TopLink Workbench
64
Configuring an EIS Transformation Mapping
EIS Transformation Mapping Configuration Overview
Part XIV XML Mappings
65
Understanding XML Mappings
XML Mapping Types
XML Mapping Concepts
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
XML Direct Mapping
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
XML Composite Direct Collection Mapping
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
XML Composite Object Mapping
Mapping Into the Parent Record
Mapping to an Element
Mapping to Different Elements by Element Name
Mapping to Different Elements by Element Position
XML Composite Collection Mapping
XML Any Object Mapping
XML Any Collection Mapping
XML Transformation Mapping
66
Configuring an XML Mapping
Configuring Common XML Mapping Options
Configuring Reference Descriptor
Using TopLink Workbench
Configuring Maps to Wildcard
Using TopLink Workbench
67
Configuring an XML Direct Mapping
XML Direct Mapping Configuration Overview
68
Configuring an XML Composite Direct Collection Mapping
XML Composite Direct Collection Mapping Configuration Overview
69
Configuring an XML Composite Object Mapping
XML Composite Object Mapping Configuration Overview
70
Configuring an XML Composite Collection Mapping
XML Composite Collection Mapping Configuration Overview
71
Configuring an XML Any Object Mapping
XML Any Object Mapping Configuration Overview
72
Configuring an XML Any Collection Mapping
XML Any Collection Mapping Configuration Overview
73
Configuring an XML Transformation Mapping
XML Transformation Mapping Configuration Overview
Volume 5: Using TopLink in Your Application
Part XV Using TopLink Overview
74
Understanding the Persistence Layer
Overview of the Persistence Layer
Sessions
Data Access
Cache
Queries and Expressions
Transactions
Part XVI TopLink Sessions
75
Understanding TopLink Sessions
Session Types
Session Concepts
Session Architecture
Session Configuration and the sessions.xml File
Session Customization
Acquiring a Session at Run Time With the Session Manager
Managing Session Events With the Session Event Manager
Logging
Profiler
Integrity Checker
Exception Handlers
Registering Descriptors
Sessions and CMP
Sessions and Sequencing
Server and Client Sessions
Three-Tier Architecture Overview
Advantages of the TopLink Three-Tier Architecture
Unit of Work Sessions
Isolated Client Sessions
Isolated Client Sessions and Oracle Virtual Private Database (VPD)
Isolated Client Session Limitations
Historical Client Sessions
Historical Client Session Limitations
Session Broker and Client Sessions
Session Broker Architecture
Committing a Transaction with a Session Broker
Session Broker Session Limitations
Session Broker Alternatives
Database Sessions
Remote Sessions
Architectural Overview
Remote Session Concepts
Sessions and the Cache
Server and Database Session Cache
Isolated Session Cache
Historical Session Cache
Understanding the Session API
76
Creating Sessions
Session Creation Overview
Creating a Sessions Configuration
Using TopLink Workbench
Configuring a Sessions Configuration
Using TopLink Workbench
Creating a Server Session
Using TopLink Workbench
Using Java
Creating Session Broker and Client Sessions
Using TopLink Workbench
Using Java
Creating Database Sessions
Using TopLink Workbench
Using Java
Creating Remote Sessions
Using Java
77
Configuring a Session
Configuring Common Session Options
Configuring a Primary Mapping Project
Using TopLink Workbench
Using Java
Configuring a Session Login
Configuring Logging
Using TopLink Workbench
Using Java
Configuring Multiple Mapping Projects
Using TopLink Workbench
Using Java
Configuring a Performance Profiler
Using TopLink Workbench
Using Java
Configuring an Exception Handler
Using TopLink Workbench
Using Java
Configuring Customizer Class
Using TopLink Workbench
Configuring the Server Platform
Using TopLink Workbench
Using Java
Configuring Session Event Listeners
Using TopLink Workbench
Using Java
Configuring the Integrity Checker
Using Java
Configuring Connection Policy
Using TopLink Workbench
Using Java
Configuring Named Queries at the Session Level
Using Java
78
Acquiring and Using Sessions at Run Time
Session Acquisition Overview
Understanding the Session Manager
Multiple Sessions
Acquiring the Session Manager
Acquiring a Session from the Session Manager
Loading a Session from sessions.xml Using Defaults
Loading a Session from sessions.xml with an Alternative Class Loader
Loading a Session from an Alternative Session Configuration File
Loading a Session Without Logging In
Reloading and Refreshing Session Configuration
Refreshing a Session when the Class Loader Changes
Acquiring a Client Session
Acquiring an Isolated Client Session
Acquiring a Historical Client Session
Acquiring a Client Session That Uses Exclusive Connections
Acquiring a Client Session that Uses Connection Properties
Acquiring a Client Session that Uses a Named Connection Pool
Acquiring a Client Session that Does Not Use Lazy Connection Allocation
Logging In to a Session
Using Session API
Logging Out of a Session
Storing Sessions in the Session Manager Instance
Destroying Sessions in the Session Manager Instance
79
Configuring Server Sessions
Server Session Configuration Overview
Configuring Internal Connection Pools
Configuring External Connection Pools
80
Configuring Isolated Client Sessions
Isolated Client Session Configuration Overview
PostAcquireExclusiveConnection Event Handler
Using Java
PreReleaseExclusiveConnection Event Handler
Using Java
NoRowsModifiedSessionEvent Event Handler
Using Java
ValidationException Handler
81
Configuring Historical Client Sessions
Historical Client Session Configuration Overview
Configuring Historical Client Sessions Using an Oracle Platform
Configuring Historical Client Sessions Using a TopLink HistoryPolicy
82
Configuring Session Broker and Client Sessions
Session Broker and Client Session Configuration Overview
Removing, Renaming, or Adding Sessions
Using TopLink Workbench
83
Configuring Database Sessions
Database Session Configuration Overview
Configuring External Connection Pools
Part XVII Data Access
84
Understanding Data Access
Data Access Concepts
Externally Managed Transactional Data Sources
Data Source Login Types
Data Source Platform Types
Authentication
Connections
Connection Pools
Understanding Data Access API
Login Inheritance Hierarchy
Platform Inheritance Hierarchy
85
Configuring a Data Source Login
Configuring Common Data Source Login Options
Configuring User Name and Password
Configuring Password Encryption
Using Java
Configuring External Connection Pooling
Using TopLink Workbench
Configuring Properties
Using TopLink Workbench
Using Java
Configuring a Default Null Value at the Login Level
Using Java
86
Configuring a Database Login
Database Login Configuration Overview
Configuring a Relational Database Platform at the Session Level
Using TopLink Workbench
Configuring Database Login Connection Options
Using TopLink Workbench
Configuring Sequencing at the Session Level
Using TopLink Workbench
Using Java
Configuring a Table Qualifier
Using TopLink Workbench
Configuring JDBC Options
Using TopLink Workbench
Using Java
Configuring Advanced Options
Using TopLink Workbench
Configuring Oracle Database Proxy Authentication
Using Java
87
Configuring an EIS Login
EIS Login Configuration Overview
Configuring an EIS Data Source Platform at the Session Level
Using TopLink Workbench
Configuring EIS Connection Specification Options at the Session Level
Using TopLink Workbench
88
Creating an Internal Connection Pool
Internal Connection Pool Creation Overview
Using TopLink Workbench
89
Configuring an Internal Connection Pool
Internal Connection Pool Configuration Overview
Configuring a Connection Count
Using TopLink Workbench
Configuring Properties
Using TopLink Workbench
Using Java
Configuring a Nontransactional Read Login
Using TopLink Workbench
Configuring Connection Pool Connection Options
Using TopLink Workbench
Configuring Exclusive Read Connections
Using TopLink Workbench
Part XVIII Cache
90
Understanding the Cache
Cache Architecture
Session Cache
Unit of Work Cache
Cache Concepts
Cache Type and Object Identity
Querying and the Cache
Handling Stale Data
Explicit Query Refreshes
Cache Invalidation
Cache Coordination
Cache Isolation
Cache Locking and Transaction Isolation
Cache Optimization
Understanding Cache Coordination
When to use Cache Coordination
Coordinated Cache Architecture
Coordinated Cache Types
Custom Coordinated Cache
Understanding the Cache API
Object Identity API
Cache Refresh API
Cache Invalidation API
Cache Coordination API
91
Configuring a Coordinated Cache
Configuring Common Coordinated Cache Options
Configuring the Synchronous Change Propagation Mode
Using TopLink Workbench
Configuring a Service Channel
Using TopLink Workbench
Configuring a Multicast Group Address
Using TopLink Workbench
Configuring a Multicast Port
Using TopLink Workbench
Configuring a Naming Service Type
Configuring JNDI Naming Service Information
Using TopLink Workbench
Configuring RMI Registry Naming Service Information
Using TopLink Workbench
Configuring an Announcement Delay
Using TopLink Workbench
Configuring Connection Handling
Using TopLink Workbench
Configuring Context Properties
Using TopLink Workbench
Configuring a Packet Time-to-Live
Using TopLink Workbench
92
Configuring a JMS Coordinated Cache
JMS Coordinated Cache Configuration Overview
Configuring a Topic Name
Using TopLink Workbench
Configuring a Topic Connection Factory Name
Using TopLink Workbench
Configuring a Topic Host URL
Using TopLink Workbench
93
Configuring an RMI Coordinated Cache
RMI Coordinated Cache Configuration Overview
94
Configuring a CORBA Coordinated Cache
CORBA Coordinated Cache Configuration Overview
95
Configuring a Custom Coordinated Cache
Custom Coordinated Cache Configuration Overview
Configuring Transport Class
Using TopLink Workbench
Part XIX Queries
96
Understanding TopLink Queries
Query Types
Query Concepts
Call
DatabaseQuery
Data-Level and Object-Level Queries
Summary Queries
Descriptor Query Manager
TopLink Expressions
Query Keys
Query Languages
Building Queries
Executing Queries
Handling Query Results
Collection Query Results
Report Query Results
Stream and Cursor Query Results
Session Queries
Read-Object Session Queries
Create, Update, and Delete Object Session Queries
Database Queries
Object-Level Read Query
Data-Level Read Query
Object-Level Modify Query
Data-Level Modify Query
Report Query
Named Queries
Call Queries
SQL Calls
EJB QL Calls
Enterprise Information System (EIS) Interactions
Redirect Queries
Historical Queries
Using an ObjectLevelReadQuery With an AsOfClause
Using an ObjectLevelReadQuery With Expression Operator asOf
Using an ObjectLevelReadQuery in a Historical Session
Interface and Inheritance Queries
Descriptor Query Manager Queries
Configuring Named Queries
Configuring Default Query Implementations
Configuring Additional Join Expressions
EJB Finders
Predefined Finders
Default Finders
Call Finders
DatabaseQuery Finders
Named Query Finders
Primary Key Finders
Expression Finders
EJB QL Finders
SQL Finders
Redirect Finders
The ejbSelect Method
Queries and the Cache
Configuring the Cache
Using In-Memory Queries
Primary Key Queries and the Cache
Disabling the Identity Map Cache Update During a Read Query
Refreshing the Cache
Caching Query Results in the Session Cache
Caching Query Results
Caching and EJB Finders
Understanding the Query API
97
Understanding TopLink Expressions
Understanding the Expression Framework
Expressions Compared to SQL
Expression Components
Boolean Logic
Database Functions
Mathematical Functions
XMLType Functions
Platform and User-Defined Functions
Expressions for One-to-One and Aggregate Object Relationships
Expressions for Joining and Complex Relationships
Parameterized Expressions
Expression Method getParameter
Expression Method getField
Query Keys and Expressions
Using Multiple Expressions
Subselects and Subqueries
Parallel Expressions
Data Queries and Expressions
getField
getTable
Creating an Expression
Using TopLink Workbench
Using Java
Creating and Using a User-Defined Function
Making a User-Defined Function Available to All Platforms
Making a User-Defined Function Available to a Specific Platform
Using a User-Defined Function
98
Using Basic Query API
Using Session Queries
Reading Objects with a Session Query
Creating, Updating, and Deleting Objects with a Session Query
Using DatabaseQuery Queries
Reading Objects Using a DatabaseQuery
Creating, Updating, and Deleting Objects with a DatabaseQuery
Reading Data with a DatabaseQuery
Updating Data With a DatabaseQuery
Specifying a Custom SQL String in a DatabaseQuery
Specifying a Custom EJB QL String in a DatabaseQuery
Using Parameterized SQL and Statement Caching in a DatabaseQuery
Using Named Queries
Using SQL Calls
Using an SQLCall
Using a StoredProcedureCall
Using a StoredFunctionCall
Using EJB QL Calls
Using EIS Interactions
Handling Exceptions
Handling Collection Query Results
Handling Report Query Results
99
Using Advanced Query API
Using Redirect Queries
Creating a Redirect Query
Using Historical Queries
Using Queries with Fetch Groups
Configuring Default Fetch Group Behavior
Querying with a Static Fetch Group
Querying with a Dynamic Fetch Group
Querying on Interfaces
Querying on an Inheritance Hierarchy
Appending Additional Join Expressions
Using Java
Using Queries on Variable One-to-One Mappings
Using Oracle Database Features
Oracle Hints
Hierarchical Queries
Stored Procedure Cursor Output Parameters
Using EJB Finders
Creating a Finder
Using Call Finders
Using DatabaseQuery Finders
Using Named Query Finders
Using Primary Key Finders
Using Expression Finders
Using EJB QL Finders
Using SQL Finders
Using Redirect Finders
Using the ejbSelect Method
Handling Cursor and Stream Query Results
Cursors and SQLCall
Cursors and StoredProcedureCall
Cursors and Java Iterators
Java Streams
Optimizing Streams
Using Cursors and Streams With EJB Finders
Using Queries and the Cache
Caching Results in a ReadQuery
Configuring Cache Expiration at the Query Level
Part XX Transactions
100
Understanding TopLink Transactions
Unit of Work Architecture
Unit of Work Transaction Context
Unit of Work Transaction Demarcation
Unit of Work Transaction Isolation
Unit of Work Concepts
Unit of Work Benefits
Unit of Work Life Cycle
Unit of Work and Change Policy
Clones and the Unit of Work
Nested and Parallel Units of Work
Commit and Rollback Transactions
Primary Keys
Unit of Work Optimization
Understanding the Unit of Work API
Unit of Work as Session
Example Model Object and Schema
101
Using Basic Unit of Work API
Acquiring a Unit of Work
Creating an Object
Modifying an Object
Associating a New Target to an Existing Source Object
Associating Without Reference to the Cache Object
Associating With Reference to the Cache Object
Associating a New Source to an Existing Target Object
Associating an Existing Source to an Existing Target Object
Deleting Objects
Using privateOwnedRelationship
Explicitly Deleting from the Database
Understanding the Order in Which Objects Are Deleted
102
Using Advanced Unit of Work API
Registering and Unregistering Objects
Creating and Registering an Object in One Step
Using registerNewObject
Using registerAllObjects
Using Registration and Existence Checking
Working with Aggregates
Unregistering Working Clones
Declaring Read-Only Classes
Configuring Read-Only Classes for a Single Unit of Work
Configuring Default Read-Only Classes
Read-Only Descriptors
Writing Changes Before Commit Time
Using Conforming Queries and Descriptors
Guidelines for Using Conforming
Using Conforming Queries
Using Conforming Descriptors
Conforming Query Alternatives
Merging Changes in Working Copy Clones
Resuming a Unit of Work After Commit
Reverting a Unit of Work
Using a Nested or Parallel Unit of Work
Parallel Unit of Work
Nested Unit of Work
Using a Unit of Work With Custom SQL
Controlling the Order of Delete Operations
Using the Unit of Work setShouldPerformDeletesFirst Method
Using the Descriptor addConstraintDependencies Method
Using deleteAllObjects Without addConstraintDependencies
Using deleteAllObjects with addConstraintDependencies
Using Optimistic Read Locking with forceUpdateToVersionField
Forcing a Check of the Optimistic Read Lock
Forcing a Version Field Update
Disabling forceUpdateToVersionField
Implementing User and Date Auditing with the Unit of Work
Integrating the Unit of Work With an External Transaction Service
Acquiring a Unit of Work with an External Transaction Service
Using a Unit of Work When an External Transaction Exists
Using a Unit of Work When No External Transaction Exists
Using the Unit of Work to Handle External Transaction Timeouts and Exceptions
Integrating the Unit of Work with CMP
CMP Transaction Attribute
Local Transactions
Nondeferred Changes
Database Transaction Isolation Levels
General Factors Affecting Transaction Isolation Level
Read Uncommitted Level
Read Committed Level
Repeatable Read Levels
Serializable Read Levels
Troubleshooting a Unit of Work
Avoiding the Use of Post-Commit Clones
Determining Whether or Not an Object Is the Cache Object
Dumping the Contents of a Unit of Work
Handling Exceptions
Validating a Unit of Work
Glossary
Index
