Contents

Title and Copyright Information

Send Us Your Comments

Preface

Intended Audience

Documentation Accessibility

Organization

Related Documentation

Conventions

1 Understanding the OracleAS TopLink Mapping Workbench

Starting the OracleAS TopLink Mapping Workbench

Working with the OracleAS TopLink Mapping Workbench

Using the Menus

Menu Bar Menus

Pop-Up Menus

Using the Toolbars

Standard Toolbar

Mapping Toolbar

OracleAS TopLink Sessions Editor Navigator Toolbar

Using the Navigator Pane

Using the Editor Pane

Working with Workbench Preferences

General Preferences

Warning and Confirmation Preferences

Class Preferences

EJB Preferences

Database Preferences

Help Preferences

Working with the OracleAS TopLink Mapping Workbench in a Team Environment

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

2 Understanding Projects

Working with Projects

Creating new Projects

Opening Existing Projects

Saving Projects

Refreshing the Navigator Pane

Generating the Project Status Report

Working with Project Properties

Working with General Project Properties

Mapping EJB 2.0 Entities

Working with Sequencing Properties

Working with Default Properties

Renaming Packages

Working with Project Options

Setting Default Advanced Properties

Working with Classes

Creating Classes

Updating Classes

Exporting Project Information

Exporting Project to Java Source

Exporting Deployment XML

Exporting Table Creator Files

Exporting Java Model Source

Working with the ejb-jar.xml File

Writing to the ejb-jar.xml File

Reading from the ejb-jar.xml File

3 Understanding Databases

Working with Databases

Database Properties

Logging into the Database

Working with Database Tables in the Navigator Pane

Creating New Tables

Importing Tables from Database

JDBC Driver Requirements

Removing Tables

Renaming Tables

Working with Database Tables in the Editor Pane

Working with Field Properties

Setting a Primary Key for Database Tables

Working with Reference Properties

Creating Table References

Creating Field References

Generating Data from Database Tables

Generating SQL Creation Scripts

Generating Descriptors and Classes from Database Tables

Generating EJB Entities from Database Tables

Generating Tables on the Database

4 Understanding Descriptors

Working with Descriptors

Understanding Persistent Classes

Specifying Descriptor Types

Mapping Descriptors

Automapping Descriptors

Generating Java Code for Descriptors

Working with Descriptor Properties

Setting Descriptor Information

Setting Class Information

Class Tab

Attributes Tab

Methods Tab

Specifying Queries and Named Finders

Custom SQL Queries

Named Queries

Building Expressions

Adding Arguments

Query Keys

Specifying Query Keys

Displaying EJB descriptor Information

Working with Advanced Properties

Amending Descriptors After Loading

Specifying Events

Specifying Identity Mapping

Specifying Inheritance

Creating a Root Class

Creating Branch and Leaf Classes

Specifying Optimistic Locking

Specifying an Interface Alias

Working with Primary Keys

Setting a Primary Key for Descriptors

Working with Sequencing

Using Sequence Numbers with Entity Beans

Using Native Sequencing

Using Sequence Tables

Pre-allocating Sequence Numbers

Creating the Sequence Table on the Database

Working with Inheritance

Using Inheritance with EJBs

Mapping Inherited Attributes in One Descriptor

Supporting Inheritance Using One Table

Supporting Inheritance Using Multiple Tables

Finding Subclasses

Providing a Class Indicator Field

Understanding Root, Branch, and Leaf Classes in an Inheritance Hierarchy

Specifying Primary Keys in an Inheritance Hierarchy

Mapping Inherited Attributes in a Subclass

Working with Interfaces

Understanding Interface Descriptors

Single Implementor Interfaces

Implementing an Interface

Working with Multiple Tables

Specifying Multi-table Info

Primary Keys Match

Primary Keys are Named Differently

Tables are Related by Foreign Key in Primary Table

Working with a Copy Policy

Setting the Copy Policy

Working with Instantiation Policy

Setting Instantiation Policy

Working with a Wrapper Policy

Setting the Wrapper Policy Using Java Code

Working with Optimistic Locking

Using Version Locking Policies

Using Field Locking Policies

Specifying Advanced Optimistic Locking Policies

Working with Identity Maps

Identity Map Size

Design Guidelines

Using Object Identity

Caching Objects

Working with Query Keys

Automatically-generating Query Keys

Using Query Keys in Interface Descriptors

Relationship Query Keys

Defining Relationship Query Keys by Amending a Descriptor

Working with Events

Registering an Event with a Descriptor

Supported Events

Working with Finders

Working with Object-relational Descriptors

Effect on OracleAS TopLink

Databases OracleAS TopLink Supports

Defining Object-Relational Descriptors

Working with Mappings

Working with Common Mapping Properties

Specifying Direct Access and Method Access

Setting the Access Type

Specifying Read-Only Settings

Defaulting Null Values

Maintaining Bidirectional Relationships

Specifying Field Names and Multiple Tables

Specifying Collection Properties

Specifying Mapping information in ejb-jar.xml File

5 Understanding Direct Mappings

Working with Direct Mappings

Working with Direct-to-Field Mappings

Creating Direct-to-Field Mappings

Working with Type Conversion Mappings

Creating Type Conversion Mappings

Working with Object Type Mappings

Creating Object Type Mappings

Working with Serialized Object Mappings

Creating Serialized Object Mappings

Working with Transformation Mappings

Creating Transformation Mappings

Specifying Advanced Features Available by Amending the Descriptor

6 Understanding Relationship Mappings

Working with Relationship Mappings

Specifying Private or Independent Relationships

Working with Foreign Keys

Understanding Foreign Keys

Specifying Foreign Keys

Working with a Container Policy

Overriding the Default Container Policy

Working with Indirection

Understanding Indirection

Using Value Holder Indirection

Specifying Indirection

Changing Java Classes to Use Indirection

Working with Transparent Indirection

Specifying Transparent Indirection

Working with Proxy Indirection

Implementing Proxy Indirection in Java

Optimizing for Queries

Working with Aggregate Object Mappings

Creating a Target Descriptor

Creating an Aggregate Object Mapping

Working with One-to-One Mappings

Creating One-to-One Mappings

Specifying Advanced Features Available by Amending the Descriptor

Working with Variable One-to-One Mappings

Specifying Class Indicator

Specifying Unique Primary Key

Creating Variable One-to-One Mappings

Working with Direct Collection Mappings

Creating Direct Collection Mappings

Working with Aggregate Collection Mappings

Working with One-to-Many Mappings

Creating One-to-Many Mappings

Working with Many-to-Many Mappings

Creating many-to-many Mappings

Specifying Advanced Features by Amending the Descriptor

Working with Custom Relationship Mappings

Creating Custom Mapping Queries in Java Code

7 Understanding Object-Relational Mappings

Working with Object-Relational Mappings

Working with Array Mappings

Implementing Array Mappings in Java

Reference

Working with Object Array Mappings

Implementing Object Array Mappings in Java

Reference

Working with Structure Mappings

Implementing Structure Mappings in Java

Reference

Working with Reference Mappings

Implementing Reference Mappings in Java

Reference

Working with Nested Table Mappings

Implementing Nested Table Mappings in Java

Reference

8 Understanding the OracleAS TopLink Sessions Editor

Starting the OracleAS TopLink Sessions Editor

Working with the OracleAS TopLink Sessions Editor

Using the Navigator Pane

Renaming Elements

Understanding Configurations

Working with Configurations

Creating New Configurations

Opening Existing Configurations

Saving Configurations

Working with Session Brokers

Working with Sessions

Working with Session Properties

Setting General Properties

Setting Logging Properties

Working with Advanced Session Properties

Setting Login Properties

Setting Clustering Properties

Working with Connection Pools

Setting General Properties

Setting Login Properties

Working with the Source

A Object Model Requirements

Persistent Class Requirements

Constructor Requirements

Remote Session Requirements

B Tutorials

Introductory Tutorial

Overview

Creating the Database Schema

Creating a New Project

Setting the Project's Class Path

Enabling Your Java Classes

Generating the Class Definitions

Logging Into the Database

Creating Tables

Creating Tables Using the OracleAS TopLink Mapping Workbench

Creating the Table Definitions

Creating the Tables on the Database

Importing Tables from the Database

Mapping Classes and Tables in the Descriptor

Mappings

Descriptors

Mapping Classes to Tables

Preparing the Primary Keys

Setting the Sequence Table

Implementing Direct-to-Field Mappings

Setting the Sequence Name

Creating One-to-One Mappings Between Objects

Foreign Key References

Creating One-to-Many Mappings

Setting Up Database Sessions

Logging Into a Database

Creating the Tables in Code

Using Descriptors in an Application

Transactions and Units of Work

Reading and Writing Java Class Instances

Using a Unit of Work to Write an Object

Using a Session to Read an Object

Conclusion

Advanced Tutorial

Creating the Database Schema

Creating a New Project

Mapping Classes to Tables

Using the Automap Tool

Implementing Indirection

Preparing Java Code for Indirection

Implementing Indirection in the OracleAS TopLink Mapping Workbench

Implementing Indirection in the Tutorial

Implementing a One-to-One Self Relationship

Creating Other One-to-one Mappings

Implementing a One-to-Many Self-Relationship

Creating Other One-to-Many Mappings

Using Multiple Tables

Implementing Object Type Mapping

Implementing an Aggregate Object

Implementing a Direct Collection Mapping

Implementing a Many-to-Many Mapping

Implementing Inheritance

Implementing a Transformation Mapping

Mapping the Remaining Attributes

Completing the Tutorials

Generating Code

C Troubleshooting

Error Messages

Class Path Issues

Database Connections

Troubleshooting Descriptors

Index