Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documentation
• Conventions

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
    • Relational Database Usage
    • Object-Relational Database Usage
    • Oracle XML Database (XDB) Usage
    • Enterprise Information System (EIS) Usage
    • XML Usage
  • Understanding Target Platforms
• Selecting an Architecture With TopLink
  • Tiers
    • Three Tier
    • Two Tier
  • Service Layer
    • EJB Session Beans
    • EJB Entity Beans
    • EJB 3.0 JPA Entities
    • Plain Old Java Objects (POJO)
  • Data Access
    • Data Type
    • Multiple Data Sources
    • Isolating Data Access
    • Historical Data Access
  • Caching
    • Cache Type
    • Refreshing
    • Cache Coordination
  • Locking
    • Optimistic Locking
    • Pessimistic Locking
• Building and Using the Persistence Layer
  • Implementation Options
  • Persistent Class Requirements
  • Persistence Layer Components
    • Mapping Metadata
    • Session Metadata
    • Cache
    • Queries and Expressions
    • Transactions
  • 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
    • Descriptors and Mappings
    • Data Source Login Information
  • 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
    • External JDBC Pools
    • JTA/JTS Integration
    • Cache Coordination
    • Maintaining Bidirectional Relationships
    • Managing Dependent Objects
    • Managing Collections of EJBObject Objects
• Understanding the EJB Entity Beans With BMP Architecture
  • Example Implementations
  • Advantages and Disadvantages
  • Technical Challenges
    • External JDBC Pools
    • JTA/JTS Integration
    • Cache Coordination
• Understanding the EJB 3.0 JPA Entity Architecture
  • Example Implementations
  • Advantages and Disadvantages
• 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 TopLink Workbench

• Understanding TopLink Workbench
• Configuring the TopLink Workbench Environment
• Working With TopLink Workbench
  • Using the Menus
    • Menu Bar Menus
    • Context Menus
  • Using the Toolbars
    • Standard Toolbar
    • Context Toolbar
  • 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
    • Logging In and Out of a Database
    • Creating New Tables
    • Importing Tables From a Database
    • Removing Tables
    • Renaming Tables
    • Refreshing Tables From the Database
  • Working With Database Tables in the Editor Window
    • Working With Column Properties
    • Setting a Primary Key for Database Tables
    • Creating Table References
    • Creating Field Associations
  • Generating Data From Database Tables
    • Generating SQL Creation Scripts
    • Generating Classes and Descriptors From Database Tables
    • Generating EJB Entity Beans and Descriptors From Database Tables
    • Generating Tables on the Database
• Working With XML Schemas
  • Working With XML Schemas in the Navigator
  • Working With XML Schema Structure
  • Importing an XML Schema
  • Configuring XML Schema Reference
    • Using TopLink Workbench
    • Using Java
  • Configuring XML Schema Namespace
    • Using TopLink Workbench
    • Using Java
• Working With Classes
  • Creating Classes
    • Using TopLink Workbench
  • Configuring Classes
    • Configuring Class Information
    • Configuring Class Modifiers
    • Configuring Class Interfaces
    • Adding Attributes
    • Configuring Attribute Modifiers
    • Configuring Attribute Type Information
    • Configuring Attribute Accessing Methods
    • Adding Methods
    • Configuring Method Modifiers
    • Configuring Method Type Information
    • Configuring Method Parameters
  • Importing and Updating Classes
    • Using TopLink Workbench
  • Managing Nondescriptor Classes
  • Renaming Packages
    • Using TopLink Workbench
• Integrating TopLink Workbench With Apache Ant
  • Configuring Ant to Use TopLink Workbench Tasks
    • Library Dependencies
    • Declaring TopLink Workbench Tasks
  • Understanding TopLink Workbench Ant Task API
  • Creating TopLink Workbench Ant Tasks
  • mappings.validate
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • session.validate
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • mappings.export
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • classpath
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • ignoreerror
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • ignoreerrorset
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples
  • loginspec
    • Parameters
    • Parameters Specified as Nested Elements
    • Examples

5 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 a TableCreator Class
    • Creating a TableDefinition Class
    • Adding Fields to a TableDefinition
    • Defining Sybase and Microsoft SQL Server Native Sequencing
• Creating Tables With a Table Creator
• Automatic Database Table Creation

6 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
    • Merging Project Files
    • Merging Table, Descriptor, and Class Files
  • Sharing Project Objects
  • Managing the ejb-jar.xml File
  • Working With Locked Files

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
    • Configuring XML Parser Platform
    • Creating an XML Parser Platform
    • XML Parser Limitations
  • Security Permissions
  • Persistence Manager Migration
  • Clustering
• Oracle Containers for J2EE (OC4J)
  • CMP Integration
  • Migrating OC4J Orion Persistence to OC4J TopLink Persistence
    • Overview
    • Using the TopLink Migration Tool From TopLink Workbench
    • Using the TopLink Migration Tool From the Command Line
    • Post-Migration Changes
    • Troubleshooting Your Migration
  • JTA Integration
• BEA WebLogic Server
  • Classpath
  • CMP Integration
  • Migrating BEA WebLogic Persistence to OC4J TopLink Persistence
    • Overview
    • Using the TopLink Migration Tool From TopLink Workbench
    • Using the TopLink Migration Tool From the Command Line
  • JTA Integration
  • Security Manager
• IBM WebSphere Application Server
  • Classpath
    • Configuring Classpath for IBM WebSphere Application Server 4.0
    • Configuring Classpath for IBM WebSphere Application Server 5.0 and Later
  • CMP Integration
  • JTA Integration
  • Clustering on IBM WebSphere Application Server
• Understanding Security Permissions
  • Permissions Required by TopLink Features
    • System Properties
    • Loading project.xml or sessions.xml Files
    • Cache Coordination
    • Accessing a Data Source by Port
    • Logging With java.util.logging
    • J2EE Application Deployment
  • 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
    • XSD File Format
    • Non-CMP Applications and Project Metadata
    • CMP Applications and Project Metadata
    • Creating project.xml With TopLink Workbench
    • Creating project.xml Programatically
  • sessions.xml File
    • XSD File Format
    • Non-CMP Applications and Session Metadata
    • CMP Applications and Session Metadata
  • ejb-jar.xml File
  • <J2EE-Container>-ejb-jar.xml File
    • OC4J and the orion-ejb-jar.xml File
    • BEA WebLogic Server and the weblogic-ejb-jar.xml File
  • toplink-ejb-jar.xml File
    • OC4J and the toplink-ejb-jar.xml File
    • BEA WebLogic Server and the toplink-ejb-jar.xml File
    • IBM WebSphere Application Server and the 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 pm-properties
    • Configuring cache-synchronization Properties
    • Configuring default-mapping Properties
• 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
    • Troubleshooting ejbc
  • Deploying a CMP Application to IBM WebSphere Application Server 4.0
    • Starting the Entity Bean
• 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
    • Troubleshooting

Part IV Optimizing and Customizing a TopLink Application

11 Optimization

• Understanding Optimization
• Sources of Application Performance Problems
• Measuring TopLink Performance With the TopLink Profiler
  • Configuring the TopLink Performance Profiler
  • Accessing the TopLink Profiler Results
• Measuring TopLink Performance With the Oracle Dynamic Monitoring System (DMS)
  • Configuring the Oracle DMS Profiler
    • OC4J Applications
    • Non-OC4J Applications
  • 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
    • Reading Case 1: Displaying Names in a List
    • Reading Case 2: Batch Reading Objects
    • Reading Case 3: Using Complex Custom SQL Queries
    • Reading Case 4: Using View Objects
    • Reading Case 5: Inheritance Views
  • Write Optimization Examples
    • Writing Case: Batch Writes
• 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 – 201)
• Concurrency Exceptions (2001 – 2009)
• Conversion Exceptions (3001– 3008)
• Database Exceptions (4002 – 4018)
• Optimistic Lock Exceptions (5001 – 5009)
• Query Exceptions (6001 – 6129)
• Validation Exceptions (7001 – 7200)
• EJB QL Exceptions (8001 – 8010)
• Session Loader Exceptions (9000 - 9010)
• Communication Exceptions (12000 - 12003)
• EIS Exceptions (17007 – 17025), 90000, 91000
• JMS Processing Exceptions (18001 - 18004)
• Default Mapping Exceptions (20001 - 20008)
• Discovery Exceptions (22001 - 22004)
• Remote Command Manager Exceptions (22101 - 22111)
• Transaction Exceptions (23001 - 23015)
• XML Conversion Exceptions (25501)
• Migration Utility Exceptions (26001 - 26020)
• EJB JAR XML Exceptions (72000 – 72023)
• Entity Manager Setup Exceptions (28001 – 28007)
• XML Marshal Exceptions (25001 – 25020)
• XML Platform Exceptions (27001 – 27006, 27101 – 27103, 27201 – 27202)

14 TopLink Workbench Error Reference

• Miscellaneous Errors (1 – 89, 106 – 133)
• Project Errors (100 – 102)
• Descriptor Errors (200 – 399)
• 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 Mapping and Configuration Overview

16 Understanding TopLink Mapping and Configuration Concepts

• Mapping and Configuration Concepts
  • Projects
  • Descriptors
  • Mappings

Part VII Projects

17 Understanding Projects

• TopLink Project Types
• Project Concepts
  • Project Architecture
  • Relational and Nonrelational Projects
  • Persistent and Nonpersistent Projects
  • Projects and Login
    • Non-CMP Session Role: Session Login
    • CMP Deployment Role: Deployment Login
    • Development Role: Development Login
  • Projects and Platforms
  • Projects and Sequencing
    • Configuring how to Obtain Sequence Values
    • Configuring Where to Write Sequence Values
  • 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)
    • Understanding JAXB-Specific Generated Files
    • Understanding TopLink-Specific Generated Files
    • Using TopLink JAXB Compiler Generated Files at Run Time
  • JAXB Validation
• Understanding the Project API
  • Project Inheritance Hierarchy
• Understanding Sequencing in Relational Projects
  • Sequencing Configuration Options
  • Sequencing Types
    • Table Sequencing
    • Unary Table Sequencing
    • Query Sequencing
    • Default Sequencing
    • Native Sequencing With an Oracle Database Platform
    • Native Sequencing With a Non-Oracle Database Platform
  • Sequencing and Preallocation Size
  • Sequencing With Entity Beans WIth Container-Managed Persistence
• Understanding XML Namespaces
  • TopLink Workbench Namespace Resolution
  • Element and Attribute Form Options
    • Element Form Default Qualified and Attribute Form Default Unqualified
    • Element and Attribute Form Default Unqualified
    • Element and Attribute Form Default Qualified
  • TopLink Runtime Namespace Resolution

18 Creating a Project

• Project Creation Overview
  • Using TopLink Workbench
    • Creating New TopLink Workbench Projects
  • 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 CMP EAR at Deployment Time
• Working With Projects
  • Opening Existing Projects
  • Saving Projects
    • Saving Projects With a New Name or Location
  • 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

19 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

20 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
    • Logging in to the Database
• 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

21 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

22 Configuring an XML Project

• XML Project Configuration Overview

Part VIII Descriptors

23 Understanding Descriptors

• Descriptor Types
• Descriptor Concepts
  • Descriptor Architecture
  • Descriptors and Inheritance
  • Descriptors and EJB
    • Nondeferred Changes
    • Creating a New Entity Bean and ejbCreate / ejbPostCreate Methods
    • Inheritance
  • Fetch Groups
  • Amendment and After-Load Methods
  • Descriptors and Aggregation
    • Aggregate and Composite Descriptors in Relational Projects
    • Root and Composite Descriptors in EIS Projects
    • Composite Descriptors in XML Projects
  • 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
    • Using Class Indicator Fields
    • Using Class Extraction Methods
  • Inheritance and Primary Keys (Relational and EIS Only)
  • Single and Multi-Table Inheritance (Relational Only)
    • Single Table Inheritance
    • Multitable Inheritance
  • 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
    • Optimistic Locking in a Three-Tier Application
    • Pessimistic Locking in a Three-Tier Application
• Understanding the Descriptor API
  • Descriptor Inheritance Hierarchy

24 Creating a Descriptor

• Descriptor Creation Overview
• Creating a Relational Descriptor
  • Using TopLink Workbench
    • Relational Class Descriptors
    • Relational Aggregate Descriptors
    • Relational Interface Descriptors
  • Using Java
• Creating an Object-Relational Descriptor
  • Using Java
• Creating an EIS Descriptor
  • Using TopLink Workbench
    • EIS Root Descriptors
    • EIS Composite Descriptors
  • Using Java
• Creating an XML Descriptor
  • Using TopLink Workbench
  • Using Java
• Validating Descriptors
• Generating Java Code for Descriptors

25 Configuring a Descriptor

• Configuring Common Descriptor Options
• Configuring Primary Keys
  • Using TopLink Workbench
  • Using Java
    • Relational Projects
    • EIS Projects
• 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
    • Adding Named Queries
    • Configuring Named Query Type and Parameters
    • Configuring Named Query Selection Criteria
    • Configuring Read All Query Order
    • Configuring Named Query Optimization
    • Configuring Named Query Attributes
    • Configuring Named Query Group/Order Options
    • Creating an EIS Interaction for a Named Query
    • Configuring Named Query Options
    • Configuring Named Query Advanced Options
  • 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 Unit of Work Cache Isolation at the Descriptor Level
  • 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 CMP Information
    • Configuring BMP Information
• 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 an Optimistic Locking Policy
    • Configuring Optimistic Locking Policy Cascading
    • Configuring a Pessimistic Locking Policy
• 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 Deferred Change Detection Policy
    • Configuring Object Change Tracking Policy
    • Configuring Attribute Change Tracking Policy
• Configuring a History Policy
  • Using Java
    • Configuring Write Responsibility
• Configuring Wrapper Policy
  • Using Java
• Configuring Fetch Groups
  • Using Java
• Configuring Amendment Methods
  • Using TopLink Workbench

26 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 a Sequence by Name
    • Configuring the Same Sequence for Multiple Descriptors
    • Configuring the Platform Default Sequence
• 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

27 Configuring an Object-Relational Descriptor

• Object-Relational Descriptor Configuration Overview
• Configuring Field Ordering
  • Using Java

28 Configuring an EIS Descriptor

• EIS Descriptor Configuration Overview
• Configuring Schema Context for an EIS Descriptor
  • Using TopLink Workbench
    • Choosing a Schema Context
  • Using Java
• Configuring Default Root Element
  • Using TopLink Workbench
    • Choosing a Root Element
  • 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

29 Configuring an XML Descriptor

• XML Descriptor Configuration Overview
• Configuring Schema Context for an XML Descriptor
  • Using TopLink Workbench
    • Choosing a Schema Context
  • Using Java
• Configuring for Complex Type of anyType
  • Using TopLink Workbench
• Configuring Default Root Element
  • Using TopLink Workbench
    • Choosing a Root Element
• Configuring Document Preservation
  • Using TopLink Workbench
  • Using Java

Part IX Mappings

30 Understanding Mappings

• Mapping Types
• Mapping Concepts
  • Mapping Architecture
  • Example Mapping
  • Automatic Mappings
    • Automapping With TopLink Workbench at Development Time
    • Default Mapping in CMP Projects Using OC4J at Run Time
    • JAXB Project Generation at Development Time
  • Indirection
    • Value Holder Indirection
    • Transparent Indirect Container Indirection
    • Proxy Indirection
    • Indirection and EJB
    • Indirection, Serialization, and Detachment
  • Method Accessors and Attribute Accessors
  • Mapping Converters and Transformers
    • Serialized Object Converter
    • Type Conversion Converter
    • Object Type Converter
    • Simple Type Translator
    • Transformation Mappings
  • Mappings and XPath
    • XPath by Position
    • XPath by Path and Name
    • XPath by Name
    • Self XPath
  • Mappings and xsd:list and xsd:union Types
    • Mapping an xsd:union Type
    • Mapping an xsd:list Type
    • Mapping a List of Unions
    • Mapping a Union of Lists
    • Mapping a Union of Unions
  • Mappings and the jaxb:class Customization
    • all, choice, or sequence Structure
    • group Structure
    • sequence or choice Structure Containing a group
    • group Structure Containing a sequence or choice
    • group Structure Containing a group
    • Limitations of jaxb:class Customization Support
  • Mappings and JAXB Typesafe Enumerations
• Understanding the Mapping API
• Relational Mappings
• Object-Relational Mappings
• XML Mappings
• EIS Mappings

31 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
• Creating Mappings to Oracle LOB Database Objects
  • Using the Oracle JDBC OCI Driver or Server Driver
  • Using the Oracle JDBC Thin Driver
• Removing Mappings
  • Using TopLink Workbench

32 Configuring a Mapping

• Configuring Common Mapping Options
• Configuring Read-Only Mappings
  • Using TopLink Workbench
  • Using Java
• Configuring Indirection
  • Using TopLink Workbench
  • Using Java
    • Configuring ValueHolder Indirection
    • Configuring ValueHolder Indirection With Method Accessing
    • Configuring ValueHolder Indirection With EJB 3.0 on OC4J
    • Configuring IndirectContainer Indirection
    • Configuring Proxy Indirection
• Configuring XPath
  • Using TopLink Workbench
    • Choosing the XPath
• 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
    • Specifying Field-to-Transformer Associations
  • 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

Part X Relational Mappings

33 Understanding Relational Mappings

• Relational Mapping Types
• Relational Mapping Concepts
  • Directionality
  • Converters and Transformers
    • Using a Direct Mapping
    • Using a Converter Mapping
    • Using a Transformation Mapping
  • 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

34 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

35 Configuring a Relational Direct-to-Field Mapping

• Relational Direct-to-Field Mapping Configuration Overview

36 Configuring a Relational Direct-to-XMLType Mapping

• Relational Direct-to-XMLType Mapping Overview
• Configuring Read Whole Document
  • Using TopLink Workbench

37 Configuring a Relational One-to-One Mapping

• Relational One-to-One Mapping Configuration Overview
• Configuring Joining at the Mapping Level
  • Using TopLink Workbench

38 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

39 Configuring a Relational One-to-Many Mapping

• Relational One-to-Many Mapping Configuration Overview

40 Configuring a Relational Many-to-Many Mapping

• Relational Many-to-Many Mapping Configuration Overview
• Configuring a Relation Table
  • Using TopLink Workbench

41 Configuring a Relational Aggregate Collection Mapping

• Relational Aggregate Collection Mapping Configuration Overview

42 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

43 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

44 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

45 Configuring a Relational Transformation Mapping

• Relational Transformation Mapping Configuration Overview

Part XI Object-Relational Mappings

46 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

47 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

48 Configuring an Object-Relational Structure Mapping

• Object-Relational Structure Mapping Configuration Overview

49 Configuring an Object-Relational Reference Mapping

• Object-Relational Reference Mapping Configuration Overview

50 Configuring an Object-Relational Array Mapping

• Object-Relational Array Mapping Configuration Overview

51 Configuring an Object-Relational Object Array Mapping

• Object-Relational Object Array Mapping Configuration Overview

52 Configuring an Object-Relational Nested Table Mapping

• Object-Relational Nested Table Mapping Configuration Overview

Part XII EIS Mappings

53 Understanding EIS Mappings

• EIS Mapping Types
• EIS Mapping Concepts
  • EIS Record Type
    • Indexed Records
    • Mapped Records
    • XML Records
  • XPath Support
  • xsd:list and xsd:union Support
  • jaxb:class Support
  • Typesafe Enumeration Support
  • Composite and Reference EIS Mappings
    • Composite EIS Mappings
    • 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

54 Configuring an EIS Mapping

• Configuring Common EIS Mapping Options
• Configuring Reference Descriptors
  • Using TopLink Workbench
• Configuring Selection Interaction
  • Using TopLink Workbench

55 Configuring an EIS Direct Mapping

• EIS Direct Mapping Configuration Overview

56 Configuring an EIS Composite Direct Collection Mapping

• EIS Composite Direct Collection Mapping Configuration Overview

57 Configuring an EIS Composite Object Mapping

• EIS Composite Object Mapping Configuration Overview

58 Configuring an EIS Composite Collection Mapping

• EIS Composite Collection Mapping Configuration Overview

59 Configuring an EIS One-to-One Mapping

• EIS One-to-One Mapping Configuration Overview
• Configuring Foreign Key Pairs
  • Using TopLink Workbench

60 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

61 Configuring an EIS Transformation Mapping

• EIS Transformation Mapping Configuration Overview

Part XIII XML Mappings

62 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 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 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 a Simple Sequence
    • Mapping to a Sequence in a Subelement
  • 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

63 Configuring an XML Mapping

• Configuring Common XML Mapping Options
• Configuring Reference Descriptor
  • Using TopLink Workbench
• Configuring Maps to Wildcard
  • Using TopLink Workbench

64 Configuring an XML Direct Mapping

• XML Direct Mapping Configuration Overview

65 Configuring an XML Composite Direct Collection Mapping

• XML Composite Direct Collection Mapping Configuration Overview

66 Configuring an XML Composite Object Mapping

• XML Composite Object Mapping Configuration Overview

67 Configuring an XML Composite Collection Mapping

• XML Composite Collection Mapping Configuration Overview

68 Configuring an XML Any Object Mapping

• XML Any Object Mapping Configuration Overview

69 Configuring an XML Any Collection Mapping

• XML Any Collection Mapping Configuration Overview

70 Configuring an XML Transformation Mapping

• XML Transformation Mapping Configuration Overview

Part XIV Using TopLink Overview

71 Understanding the Persistence Layer

• Overview of the Persistence Layer
• Sessions
• Data Access
• Cache
• Queries and Expressions
• Transactions

Part XV TopLink Sessions

72 Understanding TopLink Sessions

• Session Types
• Session Concepts
  • Session Architecture
    • Object Cache
    • Connection Pools
    • Query Mechanism
    • Java Object Builder
  • 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
    • Session Event Manager Events
    • Session Event Listeners
  • Logging
    • Log Types
    • Log Output
    • Log Level
    • Logging SQL
    • Logging Chained Exceptions
    • Viewing TopLink Log Messages From the Application Server Control Console
  • Profiler
    • TopLink Profiler
    • Oracle Dynamic Monitoring System (DMS)
  • 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
    • Shared Resources
    • Providing Read Access
    • Providing Write Access
    • Security and User Privileges
    • Concurrency
    • Connection Allocation
• Unit of Work Sessions
• Isolated Client Sessions
  • Isolated Client Sessions and Oracle Virtual Private Database (VPD)
    • VPD With Oracle Database Proxy Authentication
    • VPD Without Oracle Database Proxy Authentication
    • Isolated Client Session Life Cycle
  • Isolated Client Session Limitations
• Historical Sessions
  • Historical Session Limitations
• Session Broker and Client Sessions
  • Session Broker Architecture
  • Committing a Transaction with a Session Broker
    • Committing a Session with a JTA Driver: Two-Phase Commits
    • Committing a Session Without a JTA Driver: Two-Stage Commits
  • Session Broker Session Limitations
    • Many-to-Many Join Tables and Direct Collection Tables
  • Session Broker Alternatives
    • Database Linking
    • Multiple Sessions
• Database Sessions
• Remote Sessions
  • Architectural Overview
    • Application Layer
    • Transport Layer
    • Server Layer
  • Remote Session Concepts
    • Securing Remote Session Access
    • Queries
    • Refreshing
    • Indirection
    • Cursored Streams
    • Unit of Work
• Sessions and the Cache
  • Server and Database Session Cache
  • Isolated Session Cache
  • Historical Session Cache
• Understanding the Session API

73 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
    • Server
    • Client

74 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
    • Using Session Logging API
    • Configuring a Session to use java.util.logging Package
    • Configuring Logging in a CMP Application
• 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

75 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 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
• Acquiring a Historical Session
• 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

76 Configuring Server Sessions

• Server Session Configuration Overview
• Configuring Internal Connection Pools
• Configuring External Connection Pools

77 Configuring Exclusive Isolated Client Sessions for Virtual Private Database

• Exclusive Isolated Client Session Configuration Overview
• PostAcquireExclusiveConnection Event Handler
  • Using Java
• PreReleaseExclusiveConnection Event Handler
  • Using Java
• NoRowsModifiedSessionEvent Event Handler
  • Using Java
• ValidationException Handler

78 Configuring Historical Sessions

• Historical Session Configuration Overview
  • Configuring Historical Sessions Using an Oracle Platform
  • Configuring Historical Sessions Using a TopLink HistoryPolicy

79 Configuring Session Broker and Client Sessions

• Session Broker and Client Session Configuration Overview
• Removing, Renaming, or Adding Sessions
  • Using TopLink Workbench

80 Configuring Database Sessions

• Database Session Configuration Overview
• Configuring External Connection Pools

Part XVI Data Access

81 Understanding Data Access

• Data Access Concepts
  • Externally Managed Transactional Data Sources
  • Data Source Login Types
    • DatabaseLogin
    • EISLogin
  • Data Source Platform Types
    • Database Platforms
    • EIS Platforms
  • Authentication
    • Simple JDBC Authentication
    • Oracle Database Proxy Authentication
    • Auditing
  • Connections
  • Connection Pools
    • Internal Connection Pools
    • External Connection Pools
    • Default (Write) and Read Connection Pools
    • Sequence Connection Pools
    • Application-Specific Connection Pools
• Understanding Data Access API
  • Login Inheritance Hierarchy
  • Platform Inheritance Hierarchy

82 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

83 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
    • Using the Platform Default Sequence
    • Configuring Multiple Sequences
    • Configuring Query Sequencing
• 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

84 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

85 Creating an Internal Connection Pool

• Internal Connection Pool Creation Overview
  • Using TopLink Workbench

86 Configuring an Internal Connection Pool

• Internal Connection Pool Configuration Overview
• Configuring Connection Pool Sizes
  • 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 XVII Cache

87 Understanding the Cache

• Cache Architecture
  • Session Cache
  • Unit of Work Cache
• Cache Concepts
  • Cache Type and Object Identity
    • Full Identity Map
    • Weak Identity Map
    • Soft and Hard Cache Weak Identity Maps
    • No Identity Map
    • Guidelines for Configuring the Cache and Identity Maps
    • Understanding the Internals of Soft and Hard Cache Weak Identity Map
  • Querying and the Cache
  • Handling Stale Data
    • Configure a Locking Policy
    • Configure the Cache on a Per-Class Basis
    • Force a Cache Refresh When Required on a Per-Query Basis
    • Configure Cache Invalidation
    • Configure Cache Coordination
  • Explicit Query Refreshes
    • Refresh Policy
    • EJB Finders and Refresh Policy
  • Cache Invalidation
  • Cache Coordination
  • Cache Isolation
  • Cache Locking and Transaction Isolation
  • Cache Optimization
• Understanding Cache Coordination
  • When to use Cache Coordination
  • Coordinated Cache Architecture
    • Session
    • Descriptor
    • Unit of Work
  • Coordinated Cache Types
    • JMS Coordinated Cache
    • RMI Coordinated Cache
    • CORBA Coordinated Cache
  • Custom Coordinated Cache
• Understanding the Cache API
  • Object Identity API
  • Cache Refresh API
  • Cache Invalidation API
  • Cache Coordination API

88 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

89 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

90 Configuring an RMI Coordinated Cache

• RMI Coordinated Cache Configuration Overview

91 Configuring a CORBA Coordinated Cache

• CORBA Coordinated Cache Configuration Overview

92 Configuring a Custom Coordinated Cache

• Custom Coordinated Cache Configuration Overview
• Configuring Transport Class
  • Using TopLink Workbench

Part XVIII Queries

93 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
    • SQL Queries
    • EJB QL Queries
    • XML Queries
    • EIS Interactions
    • Query-by-Example
• 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
    • ReadObjectQuery
    • ReadAllQuery
    • Partial Object Queries
    • Join Reading and Object-Level Read Queries
    • Fetch Groups and Object-Level Read Queries
  • Data-Level Read Query
    • DataReadQuery
    • DirectReadQuery
    • ValueReadQuery
  • Object-Level Modify Query
    • WriteObjectQuery
    • UpdateObjectQuery
    • InsertObjectQuery
    • DeleteObjectQuery
    • UpdateAllQuery
    • Object-Level Modify Queries and Privately Owned Parts
  • Data-Level Modify Query
  • Report Query
• Named Queries
• Call Queries
  • SQL Calls
    • SQLCall
    • StoredProcedureCall
    • StoredFunctionCall
    • Oracle Extensions
  • EJB QL Calls
  • Enterprise Information System (EIS) Interactions
    • IndexedInteraction
    • MappedInteraction
    • XMLInteraction
    • XQueryInteraction
    • QueryStringInteraction
• 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
    • Predefined CMP Finders
    • Predefined BMP 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
    • Configuring Cache Usage for In-Memory Queries
    • Expression Options for In-Memory Queries
    • Handling Exceptions Resulting From In-Memory Queries
  • Primary Key Queries and the Cache
  • Disabling the Identity Map Cache Update During a Read Query
  • Refreshing the Cache
    • Object Refresh
    • Cascading Object Refresh
    • Refreshing the Identity Map Cache During a Read Query
  • Caching Query Results in the Session Cache
  • Caching Query Results in the Query Cache
    • Internal Query Cache Restrictions
  • Caching and EJB Finders
    • Caching Options
    • Disabling Cache for Returned Finder Results
    • Refreshing Finder Results
• Understanding the Query API

94 Using Basic Query API

• Using Session Queries
  • Reading Objects With a Session Query
    • Reading an Object With a Session Query
    • Reading All Objects With a Session Query
    • Refreshing an Object With a Session Query
  • Creating, Updating, and Deleting Objects With a Session Query
    • Writing a Single Object to the Database With a Session Query
    • Writing All Objects to the Database With a Session Query
    • Adding New Objects to the Database With a Session Query
    • Modifying Existing Objects in the Database With a Session Query
    • Deleting Objects in the Database With a Session Query
• Using DatabaseQuery Queries
  • Reading Objects Using a DatabaseQuery
    • Basic DatabaseQuery Read Operations
    • Reading Objects Using Partial Object Queries
    • Reading Objects Using Report Queries
    • Reading Objects Using Query-By-Example
    • Specifying Read Ordering
    • Specifying a Collection Class
    • Specifying the Maximum Rows Returned
    • Configuring Query Timeout at the Query Level
    • Using Batch Reading
    • Using Join Reading
  • Creating, Updating, and Deleting Objects With a DatabaseQuery
    • Write Query Overview
    • UpdateAll Queries
    • Noncascading Write Queries
    • Disabling the Identity Map Cache During a Write Query
  • Reading Data With a DatabaseQuery
    • Using a DataReadQuery
    • Using a DirectReadQuery
    • Using a ValueReadQuery
  • 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
    • Specifying a SQLCall Input Parameter
    • Specifying a SQLCall Output Parameter
    • Specifying a SQLCall Input / Output Parameter
  • Using a StoredProcedureCall
    • Specifying an Input Parameter
    • Specifying an Output Parameter
    • Specifying an Input / Output Parameter
    • Using an Output Parameter Event
  • Using a StoredFunctionCall
• Using EJB QL Calls
• Using EIS Interactions
• Handling Exceptions
• Handling Collection Query Results
• Handling Report Query Results

95 Understanding TopLink Expressions

• Understanding the Expression Framework
  • Expressions Compared to SQL
• Expression Components
  • Boolean Logic
  • Database Functions and Operators
  • Mathematical Functions
  • XMLType Functions
  • Platform and User-Defined Functions
  • Expressions for One-to-One and Aggregate Object Relationships
  • Expressions for Joining and Complex Relationships
    • Understanding Joins
    • Using TopLink Expression API For Joins
• 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
    • Adding Arguments
  • Using Java
• Creating and Using a User-Defined Function
  • Making a User-Defined Function Available to a Specific Platform
  • Making a User-Defined Function Available to All Platforms
    • Using a User-Defined Function

96 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
    • startWith Parameter
    • connectBy Parameter
    • orderSibling Parameter
• Using EJB Finders
  • Creating a Finder
    • ejb-jar.xml Finder Options
  • Using DatabaseQuery Finders
  • Using Named Query Finders
  • Using Primary Key Finders
  • Using EJB QL Finders
  • Using SQL Finders
  • Using Redirect Finders
  • Using the ejbSelect Method
• Handling Cursor and Stream Query Results
  • Cursors and Java Iterators
    • Traversing Data With Scrollable Cursors
  • Java Streams
    • Cursored Stream Support
  • Optimizing Streams
  • Using Cursors and Streams With EJB Finders
    • Building the Query
    • Executing the Finder From the Client
• Using Queries and the Cache
  • Caching Results in a ReadQuery
  • Configuring Cache Expiration at the Query Level

Part XIX Transactions

97 Understanding TopLink Transactions

• Unit of Work Architecture
  • Unit of Work Transaction Context
  • Unit of Work Transaction Demarcation
    • JTA Controlled Transactions
    • OTS Controlled Transactions
    • CMP Controlled Transactions
  • Unit of Work Transaction Isolation
• Unit of Work Concepts
  • Unit of Work Benefits
  • Unit of Work Life Cycle
  • Unit of Work and Change Policy
    • Deferred Change Detection Policy
    • Object-Level Change Tracking Policy
    • Attribute Change Tracking Policy
    • Change Policy Mapping Support
  • Clones and the Unit of Work
  • Nested and Parallel Units of Work
    • Nested Unit of Work
    • Parallel Unit of Work
  • Commit and Rollback Transactions
    • Commit Transactions
    • Rollback Transactions
  • Primary Keys
  • Unit of Work Optimization
• Understanding the Unit of Work API
  • Unit of Work as Session
    • Reading and Querying Objects with the Unit of Work
    • Locking and the Unit of Work
• Example Model Object and Schema

98 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

99 Using Advanced Unit of Work API

• Registering and Unregistering Objects
  • Creating and Registering an Object in One Step
  • Using registerNewObject
    • Registering a New Object With registerNewObject
    • Associating New Objects With One Another
  • Using registerAllObjects
  • Using Registration and Existence Checking
    • Check Database
    • Assume Existence
    • Assume Nonexistence
  • 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
    • Ensure That the Query Supports Conforming
    • Consider how Conforming Affects Database Results
    • Register New Objects and Instantiate Relationships
  • Using Conforming Queries
  • Using Conforming Descriptors
  • Conforming Query Alternatives
    • Using Unit of Work Method writeChanges Instead of Conforming
    • Using Unit of Work Properties Instead of Conforming
• 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
    • External Transaction Commit Timeouts
    • External Transaction Commit 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
    • External Applications
    • TopLink Coordinated Cache
    • DatabaseLogin Method setTransactionIsolation
    • Reading Through the Write Connection
    • Managing Cache Access
    • CMP and External Transactions
  • 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
    • Exceptions at Commit Time
    • Exceptions During Conforming
  • Validating a Unit of Work
    • Validating the Unit of Work Before Commit Time

Glossary

Index