Contents

Title and Copyright Information

Send Us Your Comments

Preface

Intended Audience

Documentation Accessibility

Organization

Related Documentation

Conventions

1 Understanding OracleAS TopLink

Advantages of OracleAS TopLink

OracleAS TopLink Problem Space

OracleAS TopLink Solution

OracleAS TopLink Components

OracleAS TopLink Development Components

OracleAS TopLink Mapping Workbench

Oracle Application Server TopLink Foundation Library

OracleAS TopLink Metadata

Application Development With OracleAS TopLink

Mapping

Session Management

Querying

Transactions

Packaging and Deployment

Monitoring and Performance Tuning

OracleAS TopLink Architectures Overview

Three-Tier Application

EJB Session Bean Facade

EJB Entity Beans with CMP

EJB Entity Beans with BMP

Two-Tier Application

General Terms and Concepts

2 OracleAS TopLink Architectures

How to Use This Chapter

Architectural Concepts

Persistent Entity Types

Multi-Tier Enterprise Applications

Session Components

Five Key Architectures

Entity Bean Versus Non-Entity Bean Architectures

Three-Tier Architecture

EJB Session Bean Facade Architecture

EJB Entity Beans Using CMP Architecture

EJB Entity Beans Using BMP Architecture

Two-Tier

Architecture Details

Selecting an Architecture

Three-Tier Architecture Features

EJB Session Bean Facade Architecture Features

EJB Entity Beans with CMP Architecture Features

EJB Entity Beans with BMP Architecture Features

Two-Tier Architecture Features

3 Mapping

Introduction to Mapping Concepts

Persistent Entities

Metadata Model

OracleAS TopLink Mapping Workbench

Objects and the Database

Indirection

Serialization

General Terms and Concepts

Basic Mappings

Direct Mappings

Relationship Mappings

Indirection

Serialization

Primary Keys

Sequencing

Foreign Keys

Multiple Table Mappings

Mapping and Enterprise JavaBeans

Inheritance

Understanding Object Inheritance

Representing Inheritance in the Database

Class Types

Class Indicators

Class Extraction Methods

Entity Bean Inheritance Restrictions

Mapping EJB Entity Beans

Terminology and Definitions

Overview of Bean-Managed Persistence

Overview of Container-Managed Persistence

Maintaining Bidirectional Relationships

Managing Dependent Objects Under EJB 1.1

Managing Dependent Objects Under EJB 2.0

Managing Collections of EJBObjects Under EJB 1.1

Descriptor Validation

Advanced Mappings

Transformation Mappings

Serialized Object Mappings

Variable One-to-One Mappings

Object Relational Mappings

Direct Map Mappings

Customizing the Project

Customizing OracleAS TopLink Descriptors with Amendment Methods

Using After Load Methods

Descriptor Events

Descriptor Copy Policy

Descriptor Query Manager

Instantiation Policy

Setting the Wrapper Policy Using Java Code

Creating EJB Projects and OracleAS TopLink Descriptors in Java

Writing Mappings in Code

Implementing Object-Relational Descriptors in Java

Implementing Primary Keys in Java

Implementing Inheritance in Java

Implementing Indirection in Java

Implementing Interfaces in Java

Setting the Copy Policy in Java

Implementing Multiple Tables in Java

Implementing Sequence Numbers in Java

Implementing Locking in Java

Implementing oracle.sql.TimeStamp

4 Sessions

Introduction to Session Concepts

sessions.xml File

Session Types

Session Manager

Connection Pool

Caching

Profiling

Session Architectures

Server Session

Client Session

Database Session

Remote Session

Session Broker

Configuring Sessions with the sessions.xml File

Navigating the sessions.xml File

XML Header

toplink-configuration Element

session Element

session-broker Element

JTA Configuration

Registering Descriptors

Registering Descriptors after Login

Caching Objects

Session Manager

Retrieving a Session from a Session Manager

Storing Sessions in the Session Manager Instance

Destroying Sessions in the Session Manager Instance

Session Querying

Simple Query API

Query Objects

Predefined Queries

Session Types

Server Session and Client Session

Database Session

Session Broker

Remote Session

Sessions and the Cache

Session Utilities

Logging SQL and Messages

Using the Profiler

Using the Integrity Checker

Using Exception Handlers

Customizing Session Events

Session Event Listeners

Session Event Manager

Implementing Events Using Java

OracleAS TopLink Support for Java Data Objects (JDO)

Understanding the JDO API

JDO Implementation

5 Data Access

Introduction to Data Access Concepts

JDBC Connections

JTA

Data Conversion

Database Platforms

JDBC-SQL and Native SQL

Custom Platforms

JDBC Connection Pools

Default Connection Pools

External Connection Pools

JDBC Datasources

JTA

Database Login Information

Creating a Login Object

Specifying Driver Information

Setting Login Parameters

Database Login Advanced Features

OracleAS TopLink Conversion Manager

Creating Custom Types with the Conversion Manager

Conversion Manager Class Loader

Resolving Class Loader Exceptions

Performance

Data Optimization

Batch Writing

Binding and Parameterized SQL

Prepared Statement Caching

Table Qualifier

Locking Policy

Using Optimistic Locking

Optimistic Read Locking

Pessimistic Locking

Two Different Locking Policies

Using the OracleAS TopLink SDK

Step One: Define an Accessor

Step Two: Create the Application Calls

Step Three: Build Descriptors and Mappings

Step Four: Deploy the Application Using Sessions

OracleAS TopLink XML Support

Getting Started

Customizations

Implementation Details

XML File Accessor

XML Call

XMLTranslator Implementations

XML Descriptor

XML Platform

XML File Login

XML Schema Manager

XML Accessor

XML Translator

XML ZIP File Extension

6 Queries

Introduction to Query Concepts

Query Types

Query Components

Query Configuration Options

Query Development Options

Using Predefined Queries

Building EJB Finders

Query Keys

Query Building Basics

Expressions

Custom SQL

Stored Procedure Calls

EJB QL

Query by Example

Executing Queries

Session Queries

Query Objects

Predefined Queries

Queries Defined with OracleAS TopLink Mapping Workbench

Query Managers

Query Results

Objects

Collections

Java Streams

Report Query Results

Queries and the Cache

Cache Usage

Disabling the Identity Map Cache Update During a Read Query

Refresh

Caching Query Results

Query Objects and Write Operations

Write Query Overview

Non-Cascading Write Queries

Disabling the Identity Map Cache During a Write Query

Using Query Objects to Customize the Default Database Operations

Query Object Performance Options

Batch Reading

Join Reading

ReportQuery

Partial Attribute Reading

Cache Results In Query Objects

Oracle Extension Support

Oracle Hints and the OracleAS TopLink Query Framework

Hierarchical Queries

Advanced Querying

Creating Additional Query Keys

Querying on Interfaces

Querying on an Inheritance Hierarchy

Cursors and Streams

Querying Across Variable One-to-One Mappings

EJB Finders

Defining Finders in OracleAS TopLink

ejb-jar.xml Finder Options

Call Finders

Expression Finders

EJB QL Finders

SQL Finders

Dynamic Finders

ReadAll Finders

Choosing the Best Finder Type for Your Query

ejbSelect

Advanced Finder Options

Exception Handling

7 Transactions

Introduction to Transaction Concepts

Database Transactions

OracleAS TopLink Unit of Work Transactions

Understanding the Unit of Work

Unit of Work Benefits

Unit of Work Life Cycle

Clones and the Unit of Work

Nested and Parallel Units of Work

Reading and Querying Objects with the Unit of Work

Commit and Roll Back

Primary Keys

Example Object Model and Schema

Unit of Work Basics

Acquiring a Unit of Work

Creating an Object

Modifying an Object

Associations: New Target to Existing Source Object

Associations: New Source to Existing Target Object

Associations: Existing Source to Existing Target Object

Deleting Objects

Advanced Unit of Work

Troubleshooting a Unit of Work

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

Using Conforming Queries and Descriptors

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

Using a Unit of Work with Custom SQL

Validating a Unit of Work

Controlling the Order of Deletes

Improving Unit of Work Performance

J2EE Integration

External Connection Pooling

External Transaction Controllers

8 Cache

Introduction to Cache Concepts

Cache Architecture

Cache Locking

Distributed Cache Synchronization

Cache Locking and Isolation

Configuring the Cache

Distributed Cache Synchronization

Configuring Cache Synchronization in the sessions.xml File

Explicit Query Refreshes

Remote Command Manager

RCM Implementation Requirements

RCM Structure

RCM Channels

Configuring the RCM

Error Handling

Guidelines for Using RCM

Custom Remote Commands

9 Packaging for Deployment

Introduction to Packaging and Deployment Concepts

OracleAS TopLink Approach to Deployment

XML Versus Java Source Deployment

Creating OracleAS TopLink Deployment Files

XML Deployment Files

Using Java Source Deployment Files

Configuring Additional Files for CMP Deployment

Packaging an OracleAS TopLink Application

Java Applications

Java Server Pages and Servlets Applications

Session Bean Applications

Container-Managed Persistence Applications

Bean-Managed Persistence Applications

Hot Deployment of EJBs

10 Tuning for Performance

Introduction to Tuning Concepts

OracleAS TopLink as Part of a Larger Application

An Effective Tuning Approach

Profiling Performance

Using the Profiler in the Web Client

Using the Profiler in Java

General Tuning Tips

Basic Performance Optimization

OracleAS TopLink Reading Optimization Features

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

OracleAS TopLink Writing Optimization Features

Writing Case 1: Batch Writes

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

A Application Development Tools

OracleAS TopLink—Web Client

Configuring the Web Client

Connecting to OracleAS TopLink Sessions

Searching for Objects

Creating and Editing Objects

Performing SQL Queries

Using the Performance Profiler

Setting Web Client Preferences

Configuring OracleAS TopLink for Oracle JDeveloper

Deploy Tool for WebSphere Server

Using the Deploy Tool with WebSphere Studio Application Developer (WSAD)

Schema Manager

Using the Schema Manager to Create Tables

Managing Java and Database Type Conversions

Session Management Services

Runtime Services

Development Services

Using Session Management Services

Stored Procedure Generator

Generating Stored Procedures

Attaching the Stored Procedures to the Descriptors

B Configuring OracleAS TopLink for J2EE Containers

Software Requirements

Non-CMP Configuration

Classpath

Datasource

JTA integration

Oracle Application Server Containers for J2EE (OC4J) Support

IBM WebSphere Application Server 4.0

IBM WebSphere Application Server 5.0 and 5.1

BEA WebLogic Application Server (6.1, 7.0, or 8.1)

OracleAS TopLink CMP Configuration

IBM WebSphere Application Server 4.0

BEA WebLogic Application Server (6.1, 7.0, and 8.1)

OracleAS TopLink in a BEA WebLogic Cluster

Collocation

Cache Synchronization and the Cluster

C Troubleshooting

OracleAS TopLink Exceptions

Runtime Exceptions

Development Exceptions

Format of Exceptions

Exception Error Code Numbers

Exception Error Codes and Descriptions

Descriptor Exceptions (1 - 179)

Builder Exceptions (1001 - 1042)

Concurrency Exceptions (2001 - 2006)

Conversion Exceptions (3001 - 3007)

Database Exceptions (4002 - 4018)

Optimistic Lock Exceptions (5001 - 5008)

Query Exceptions (6001 - 6105)

Validation Exceptions (7001 - 7108)

EJB QL Exception

Session Loader Exception (9000 - 9009)

EJB Exception Factory

Communication Exception

XML Data Store Exception

Deployment Exception

Synchronization Exception

JDO Exception

SDK Data Store Exception

JMS Processing Exception

SDK Descriptor Exception

SDK Query Exception

Discovery Exception

Remote Command Manager Exception

XML Conversion Exception

EJB JAR XML Exception

Entity Deployment

Generating Deployment JARs

Common IBM WebSphere Server Exceptions

Common BEA WebLogic 6.1 Exceptions

Common BEA WebLogic 7.0 Exceptions

Common BEA WebLogic 8.1 Exceptions

Troubleshooting Known Issues

XML Parser Dependencies

OracleAS TopLink Examples

Index