Skip Headers
Oracle® Application Server TopLink Application Developer's Guide
10g Release 2 (10.1.2)
Part No. B15901-01
  Go To Documentation Library
Go To Product List
Solution Area
Go To Index



Title and Copyright Information

Send Us Your Comments


Intended Audience
Documentation Accessibility
Related Documentation

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
Session Management
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
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
General Terms and Concepts
Basic Mappings
Direct Mappings
Relationship Mappings
Primary Keys
Foreign Keys
Multiple Table Mappings
Mapping and Enterprise JavaBeans
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
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
Data Conversion
Database Platforms
JDBC-SQL and Native SQL
Custom Platforms
JDBC Connection Pools
Default Connection Pools
External Connection Pools
JDBC Datasources
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
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
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
Custom SQL
Stored Procedure Calls
Query by Example
Executing Queries
Session Queries
Query Objects
Predefined Queries
Queries Defined with OracleAS TopLink Mapping Workbench
Query Managers
Query Results
Java Streams
Report Query Results
Queries and the Cache
Cache Usage
Disabling the Identity Map Cache Update 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
Join Reading
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
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
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
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