Oracle Application Server TopLink Application Developer's Guide -- Contents

Advantages of OracleAS TopLink

OracleAS TopLink Problem Space

OracleAS TopLink Solution

Other OracleAS TopLink Advantages

OracleAS TopLink Components

OracleAS TopLink Development Components

OracleAS TopLink Mapping Workbench

Oracle Application Server TopLink Sessions Editor

Oracle Application Server TopLink Foundation Library

OracleAS TopLink Metadata

Application Development With OracleAS TopLink

Packaging and Deployment

Monitoring and Performance Tuning

OracleAS TopLink Architectures Overview

Three-Tier

EJB Session Bean Facade

EJB Entity Beans with CMP

EJB Entity Beans with BMP

Two-Tier

General Terms and Concepts

How to Use This Chapter

Architectural Concepts

Persistent Entity Types

Java Objects

EJB Entity Beans

Multi-Tier Enterprise Applications

Five Key Architectures

Entity Bean Versus Non-Entity Bean Architectures

Three-Tier

EJB Session Bean Facade

EJB Entity Beans Using CMP

EJB Entity Beans Using BMP

Two-Tier

Architecture Details

Introduction to Mapping Concepts

Persistent Entities

Metadata Model

OracleAS TopLink Mapping Workbench

Deployment XML Generation

Project Class Generation

OracleAS TopLink Mapping Types

Inheritance

Objects and the Database

Primary Keys

Sequencing

Foreign Keys and Object Relationships

Indirection

Serialization

General Terms and Concepts

Primitive Versus Complex Data

Java Objects

Basic Mappings

Direct Mappings

Direct-to-Field Mappings

Type Conversion Mappings

Object Type Mappings

Relationship Mappings

Relationships and Entity Beans

One-to-One Mappings

Aggregate Object Mappings

One-to-Many Mappings

Aggregate Collections

Direct Collection Mappings

Many-to-Many Mappings

Indirection

Valueholder Indirection

Proxy Indirection

Transparent Indirection

Choosing Your Indirection Type

Indirection and EJBs

Serialization

Serialization and Indirection

Merging Clones on Deserialization

Limitations on Merge

Primary Keys

Primary Keys and EJB Entity Beans

Sequencing

Sequencing and Database Tables

Sequencing and Preallocation Size

Table Sequencing

Oracle Native Sequencing

Native Sequencing with Other Databases

Sequencing with CMP Entity Beans

Sequencing with Stored Procedures

Foreign Keys

Multiple Table Mappings

Mapping and Enterprise JavaBeans

EJBs and the OracleAS TopLink Mapping Workbench

Inheritance

Understanding Object Inheritance

Representing Inheritance in the Database

Class Indicator Field

Class Indicators and Mappings

Class Extraction Methods

Entity Bean Inheritance Restrictions

Mapping EJB Entity Beans

Terminology and Definitions

Overview of Bean-Managed Persistence

BMP Support with EJB 2.0

Overview of Container-Managed Persistence

Understanding CMP

OracleAS TopLink and CMP Entity Beans

Java Objects and Entity Beans

Maintaining Bidirectional Relationships

One-to-Many Relationship

Managing Dependent Objects Under EJB 1.1

Serializing Java Objects Between Client and Server

Managing Dependent Objects Under EJB 2.0

Managing Collections of EJBObjects Under EJB 1.1

Descriptor Validation

Advanced Mappings

Transformation Mappings

Implementing Transformation Mappings in Java

Serialized Object Mappings

Variable One-to-One Mappings

Object Relational Mappings

Array Mappings

Object Array Mappings

Structure Mappings

Reference Mappings

Nested Table Mappings

Direct Map Mappings

Customizing the Project

Customizing OracleAS TopLink Descriptors with Amendment Methods

Using After Load Methods

Descriptor Events

Receiving Descriptor Events

Supported Events

Descriptor Copy Policy

Descriptor Query Manager

Replacing Descriptor Queries

Instantiation Policy

Overriding the Instantiation Policy Using Java Code

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

Queries for Inherited Superclasses and Multiple Tables

Customizing Inheritance

Implementing Indirection in Java

Implementing Interfaces in Java

Setting the Copy Policy in Java

Implementing Multiple Tables in Java

Primary Keys Match

Primary Keys are Named Differently

Non Standard Table Relationships

Implementing Sequence Numbers in Java

Implementing Locking in Java

Java Implementation of Optimistic Locking

Introduction to Session Concepts

Session Architectures

Configuring Sessions with the sessions.xml File

Navigating the sessions.xml File

XML Header

toplink-configuration Element

session Element

session-type Element

login Element

event-listener-class Element

profiler-class Element

external-transaction-controller-class Element

exception-handler-class Element

connection-pool Element

enable-logging Element

session-broker Element

JTA Configuration

Registering Descriptors

Caching Objects

Session Manager

Retrieving a Session from a Session Manager

Loading a Session with an Alternative Class Loader

Loading an Alternative Session Configuration File

Storing Sessions in the Session Manager Instance

Destroying Sessions in the Session Manager Instance

Session Querying

Simple Query API

Using Expressions in Session Queries

Custom SQL Queries

Query Objects

Predefined Queries

Session Types

Server Session and Client Session

Three-Tier Architecture Overview

EJBs and Server Session

General Concepts for the OracleAS TopLink Three-Tier Design

Reference

Customizing Server Session and Database Login

Working with Login

Registering Event Listeners for EJB 1.1

Database Session

Creating a Database Session

Connecting to the Database

Logging Out of the Database

Using Manual Transaction Control

Creating Database Sessions: Examples

Reference

Session Broker

Multiple Sessions

Configuring the Session Broker in Code

Committing a Transaction with a Session Broker

Using the Session Broker in a Three-tier Architecture

Architectural Overview

Securing Remote Session Access

Creating a Remote Connection Using RMIConnection

Sessions and the Cache

Session Utilities

Logging SQL and Messages

Logging Chained Exceptions

Logging and the Oracle Enterprise Manager

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

JDOPersistenceManagerFactory

JDOPersistenceManager

JDOQuery

JDOTransaction

Running the OracleAS TopLink JDO Example

Introduction to Data Access Concepts

JDBC Connections

Individual JDBC Connections

JDBC Connection Pools

JTA

Data Conversion

Database Platforms

JDBC-SQL and Native SQL

Custom Platforms

JDBC Connection Pools

Default Connection Pools

External Connection Pools

JDBC Datasources

Container-Managed Persistence and Datasources

JTA

Database Login Information

Creating a Login Object

Specifying Driver Information

Using the Sun Microsystems JDBC-ODBC Bridge

Using a Different Driver

Setting Login Parameters

User Information

Database Information

Additional JDBC Properties

Database Login Advanced Features

Setting Sequencing at Login

Setting Direct Connect Drivers

Using JDBC 2.0 Datasources

Using Custom Database Connections

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

Prepared Statement Caching for a Query

Prepared Statement Caching for a Session

Table Qualifier

Locking Policy

Using Optimistic Locking

Advantages and Disadvantages of Optimistic Locking

Advanced Optimistic Locking Policies

Optimistic Read Locking

Pessimistic Locking

Pessimistic Locking and the Cache

Pessimistic Locking and Database Transactions

WAIT and NO_WAIT Options

Advantages of Pessimistic Locking

Reference

Two Different Locking Policies

Field Locking Policies

Version Locking Policies

Using the OracleAS TopLink SDK

OracleAS TopLink XML Support

Introduction to Query Concepts

Query Building Basics

Executing Queries

Session Queries

Reading Objects from the Database

Writing Objects to the Database

Query Objects

Query Object Components

Creating a Query Object

Read Query Object Examples

Specialized Query Object Options

EJBs and Redirect Finders

Queries Defined with the OracleAS TopLink Mapping Workbench

Query Managers

Customize the Default Query Methods

Define Additional Join Expressions

Customize the Existence Check

Query Results

Queries and the Cache

Cache Usage

Cache and the Database

In-Memory Query Cache Usage

Cache and the Primary Key

Disabling the Identity Map Cache Update During a Read Query

Refresh

Object Refresh

Cascading Object Refresh

Refreshing the Identity Map Cache During a Read Query

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

Guidelines for Implementing 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

Implementing Query Keys in Java

Querying on Interfaces

Querying on an Inheritance Hierarchy

Cursors and Streams

Cursors and Java Iterators

Java Streams

Optimizing Streams

Querying Across Variable One-to-One Mappings

EJB Finders

Exception Handling

Introduction to Transaction Concepts

Database Transactions

OracleAS TopLink Unit of Work Transactions

Transaction Context

Transaction Demarcation

Transaction Isolation

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

Nested Unit of Work

Parallel Unit of Work

Reading and Querying Objects with the Unit of Work

Reading Objects with the Unit of Work

Querying Objects with the Unit of Work

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

Associating without Reference to the Cache Object

Associating with Reference to the Cache Object

Associations: New Source to Existing Target Object

Associations: Existing Source to Existing Target Object

Deleting Objects

Using privateOwnedRelationship

Explicitly Deleting from the Database

Understanding the Order in which Objects are Deleted

Advanced Unit of Work

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

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 Non-existence

Working with Aggregates

Unregistering Working Clones

Declaring Read-Only Classes

Setting Read-Only Classes for a Single Unit of Work

Setting Read-Only Classes for All Units of Work

Read-Only Descriptors

Using Conforming Queries and Descriptors

Using Conforming Queries

Conforming Query Alternatives

Using Conforming 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

Parallel Unit of Work

Nested Unit of Work

Using a Unit of Work with Custom SQL

Validating a Unit of Work

Validating the Unit of Work Before Commit

Controlling the Order of Deletes

Using the Unit of Work setShouldPerformDeletesFirst Method

Using the Descriptor addConstraintDependencies Method

Using deleteAllObjects without addConstraintDependencies

Using deleteAllObjects with addConstraintDependencies

Improving Unit of Work Performance

J2EE Integration

External Connection Pooling

When to Use External Connection Pools

Configuring an External Connection Pool in sessions.xml

Configuring an External Connection Pool in Java

External Transaction Controllers

Configuring an External Transaction Controller in sessions.xml

Configuring an External Transaction Controller in Java

Acquiring a Unit of Work in a JTA Environment

Using a Unit of Work When an External Transaction Exists

Using a Unit of Work When No External Transaction Exists

Introduction to Cache Concepts

Distributed Cache Synchronization

Cache Locking and Isolation

Configuring the Cache

Distributed Cache Synchronization

Configuring Cache Synchronization in the sessions.xml File

Clustering Service

Discovery

Name Service

Using the Java Message Service

Synchronous and Asynchronous Propagation

Error Handling

Explicit Query Refreshes

Refresh Policy

EJB Finders and Refresh Policy

Remote Command Manager

RCM Implementation Requirements

RCM Structure

Transmitting Commands From OracleAS TopLink with RCM

Using Commands on a Non-OracleAS TopLink Application

RCM Channels

Configuring the RCM

Configuring the RCM for OracleAS TopLink Applications

Configuring RCM for Non-OracleAS TopLink Applications

Error Handling

Guidelines for Using RCM

Custom Remote Commands

Introduction to Packaging and Deployment Concepts

OracleAS TopLink Approach to Deployment

OracleAS TopLink in an Enterprise Application

Road to Deployment

XML Versus Java Source Deployment

Creating OracleAS TopLink Deployment Files

XML Deployment Files

Project.xml File

Sessions.xml File

Configuring the toplink-ejb-jar.xml File with the IBM WebSphere Server 4.0

Configuring the toplink-ejb-jar.xml File with the BEA WebLogic Server

Using Java Source Deployment Files

XML Files for Java Deployment

Configuring Additional Files for CMP Deployment

Configuring the ejb-jar.xml File

Configuring the [J2EE-Container]-ejb-jar.xml

Packaging an OracleAS TopLink Application

Java Applications

Packaging the Java Application

Deploying the Application to a Client

Java Server Pages and Servlets Applications

Packaging Applications with JSPs and Servlets

Deploying the Application to a Client

Session Bean Applications

Packaging Applications with Session Beans

Deploying the Application to a Client

Container-Managed Persistence Applications

General Deployment

Deploying the Application to BEA WebLogic Server

Deploying the Application to IBM WebSphere 4.x Server

Bean-Managed Persistence Applications

Deploying the Application

Hot Deployment of EJBs

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

Browsing the Profiler Results

General Tuning Tips

Basic Performance Optimization

OracleAS TopLink Reading Optimization Features

Reading Case 1: Displaying Names in a List

Partial Object Reading

ReportQuery

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

Cursors and Batch Writes

Sequence Number Preallocation

Batch Writing

Parameterized SQL

Multiprocessing

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

OracleAS TopLink -- Web Client

Configuring the Web Client

Building the Web Client EAR File

Configuring the Application Server

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)

Troubleshooting

Schema Manager

Using the Schema Manager to Create Tables

Creating a Table Definition

Adding Fields to a Table Definition

Defining Sybase and Microsoft SQL Server Native Sequencing

Creating Tables on the Database

Creating the Sequence Table

Managing Java and Database Type Conversions

Session Management Services

Runtime Services

Development Services

Using Session Management Services

Stored Procedure Generator

Generating Stored Procedures

Sequencing and Stored Procedures

Attaching the Stored Procedures to the Descriptors

Software Requirements

Non-CMP Configuration

Oracle Application Server Containers for J2EE Support

IBM WebSphere Application Server 4.0

Configuring IBM WebSphere Module Visibility Setting

IBM WebSphere Application Server 5.0

BEA WebLogic Application Server (6.1, 7.0 or 8.1)

Using a Security Manager with BEA WebLogic Server

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

Static Partitioning

Pinning

Cache Synchronization and the Cluster

Configuring Cache Synchronization

OracleAS TopLink Exceptions

Runtime Exceptions

Development Exceptions

Format of Exceptions

Exception Error Code Numbers

Exception Error Codes and Descriptions

Descriptor Exception

Error Codes 1 - 176

Builder Exceptions

Error Codes 1001 - 1042

Concurrency Exception

Error Codes 2001 - 2006

Conversion Exception

Error Codes 3001 - 3007

Database Exception

Error Codes 4002 - 4018

Optimistic Lock Exception

Error Codes 5001 - 5008

Query Exception

Error Codes 6001 - 6098

Validation Exception

Error Codes 7001 - 7104

EJB QL Exception

Error Codes 8001 - 8010

Session Loader Exception

Error Codes 9000 - 9009

EJB Exception Factory

Error Codes 10001 - 10048

Communication Exception

Error Codes 12000 - 12004

XML Data Store Exception

Error Codes 13000 - 13020

Deployment Exception

Error Codes 14001 - 14027

Synchronization Exception

Error Codes 15001 - 15025

JDO Exception

Error Codes 16001 - 16006

SDK Data Store Exception

Error Codes 17001 - 17006

JMS Processing Exception

Error Codes 18001 - 18002

SDK Descriptor Exception

Error Codes 19001 - 19003

SDK Query Exception

Error Codes 20001 - 20004

Discovery Exception

Error Codes 22001 - 22004

Remote Command Manager Exception

Error Codes 22101 - 22105

XML Conversion Exception

Error Code 25001

EJB JAR XML Exception

Error Codes 72000 - 72023

Entity Deployment

Generating Deployment JARs

Common BEA WebLogic Deployment Exceptions

Common IBM WebSphere Server Exceptions

Problems at Runtime

Common OracleAS TopLink for IBM WebSphere Deploy Tool Exceptions

Common BEA WebLogic 6.1 Exceptions

Common BEA WebLogic 7.0 Exceptions

Common BEA WebLogic 8.1 Exceptions

Contents

Title and Copyright Information

Send Us Your Comments

Preface

1 Understanding OracleAS TopLink

2 OracleAS TopLink Architectures

3 Mapping

4 Sessions

5 Data Access

6 Queries

7 Transactions

8 Cache

9 Packaging for Deployment

10 Tuning for Performance

A Application Development Tools

B Configuring OracleAS TopLink for J2EE Containers

C Error Codes and Messages

Index