Oracle® Application Server TopLink

Getting Started Guide

10g Release 3 (10.1.3) for Microsoft Windows (64-Bit) on Intel
Itanium
B28116-01

February 2006
Oracle Application Server TopLink Getting Started Guide, 10g Release 3 (10.1.3) for Microsoft Windows
(64-Bit) on Intel Itanium
B28116-01

Copyright © 1997, 2006, Oracle. All rights reserved.

Primary Author: Brintha Bennet

Contributing Author: Preeti Shukla, Divya Shankar

The Programs (which include both the software and documentation) contain proprietary information; they
are provided under a license agreement containing restrictions on use and disclosure and are also protected
by copyright, patent, and other intellectual and industrial property laws. Reverse engineering, disassembly,
or decompilation of the Programs, except to the extent required to obtain interoperability with other
independently created software or as specified by law, is prohibited.

The information contained in this document is subject to change without notice. If you find any problems in
the documentation, please report them to us in writing. This document is not warranted to be error-free.
Except as may be expressly permitted in your license agreement for these Programs, no part of these
Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any
purpose.

If the Programs are delivered to the United States Government or anyone licensing or using the Programs on
behalf of the United States Government, the following notice is applicable:

U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data
delivered to U.S. Government customers are "commercial computer software" or "commercial technical data"
pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As
such, use, duplication, disclosure, modification, and adaptation of the Programs, including documentation
and technical data, shall be subject to the licensing restrictions set forth in the applicable Oracle license
agreement, and, to the extent applicable, the additional rights set forth in FAR 52.227-19, Commercial
Computer Software--Restricted Rights (June 1987). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA
94065.

The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy and other measures to ensure the safe use of such applications if the Programs are used for such
purposes, and we disclaim liability for any damages caused by such use of the Programs.

Oracle, JD Edwards, and PeopleSoft are registered trademarks of Oracle Corporation and/or its affiliates.
Other names may be trademarks of their respective owners.

The Programs may provide links to Web sites and access to content, products, and services from third
parties. Oracle is not responsible for the availability of, or any content provided on, third-party Web sites.
You bear all risks associated with the use of such content. If you choose to purchase any products or services
from a third party, the relationship is directly between you and the third party. Oracle is not responsible for:
(a) the quality of third-party products or services; or (b) fulfilling any of the terms of the agreement with the
third party, including delivery of products or services and warranty obligations related to purchased
products or services. Oracle is not responsible for any loss or damage of any sort that you may incur from
dealing with any third party.
 Contents

Preface ................................................................................................................................................................. v
Intended Audience...................................................................................................................................... v
Documentation Accessibility ..................................................................................................................... v
Organization ................................................................................................................................................ vi
Related Documentation .............................................................................................................................. vi
Conventions ................................................................................................................................................ vii

1 Prerequisites for Installing Oracle TopLink

1.1 System Requirements and Certifications ................................................................................ 1-1
1.2 Supported Databases.................................................................................................................. 1-1
1.3 License Information .................................................................................................................... 1-2
1.3.1 Third-Party License Information ....................................................................................... 1-2
1.3.1.1 Antlr................................................................................................................................ 1-2
1.3.1.2 DOM ............................................................................................................................... 1-2
1.3.1.3 Java Runtime Environment......................................................................................... 1-3
1.3.1.4 ASM ................................................................................................................................ 1-3

2 Installing and Configuring TopLink

2.1 TopLink Installation Types........................................................................................................ 2-1
2.2 Installing TopLink....................................................................................................................... 2-1
2.2.1 Using Oracle Universal Installer ....................................................................................... 2-1
2.2.2 Installing Silently ................................................................................................................. 2-2
2.3 Configuring TopLink Runtime Environment......................................................................... 2-3
2.4 Configuring TopLink Workbench Environment.................................................................... 2-3
2.4.1 JRE Version ........................................................................................................................... 2-3
2.4.2 Online Help and Documentation ...................................................................................... 2-3
2.4.3 Driver Classpath Environment Variable .......................................................................... 2-3
2.4.4 Third-party Libraries........................................................................................................... 2-4
2.5 Starting TopLink Workbench.................................................................................................... 2-4
2.6 TopLink Tutorial ......................................................................................................................... 2-4
2.7 Installation Troubleshooting ..................................................................................................... 2-5
2.8 Installing Patch Sets .................................................................................................................... 2-5

Index

iii
iv
 Preface

This document provides installation procedures to install and configure Oracle

TopLink. It also introduces the concepts with which you should be familiar to get the
most out of TopLink.
This preface contains these topics:
■ Intended Audience
■ Documentation Accessibility
■ Organization
■ Related Documentation
■ Conventions

Intended Audience
The Oracle TopLink Getting Started Guide is intended for new users who need to install
and configure TopLink.
This document assumes that you are familiar with the concepts of object-oriented
programming, the Enterprise JavaBeans (EJB) specification, and with your own
particular Java development environment.
The document also assumes that you are familiar with your particular operating
system (such as Windows or UNIX). The general operation of any operating system is
described in the user documentation for that system, and is not repeated in this
manual.

Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation
accessible, with good usability, to the disabled community. To that end, our
documentation includes features that make information available to users of assistive
technology. This documentation is available in HTML format, and contains markup to
facilitate access by the disabled community. Accessibility standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For more information, visit the Oracle Accessibility
Program Web site at
http://www.oracle.com/accessibility/

v
 Accessibility of Code Examples in Documentation
Screen readers may not always correctly read the code examples in this document. The
conventions for writing code require that closing braces should appear on an
otherwise empty line; however, some screen readers may not always read a line of text
that consists solely of a bracket or brace.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or
organizations that Oracle does not own or control. Oracle neither evaluates nor makes
any representations regarding the accessibility of these Web sites.

TTY Access to Oracle Support Services

Oracle provides dedicated Text Telephone (TTY) access to Oracle Support Services
within the United States of America 24 hours a day, seven days a week. For TTY
support, call 800.446.2398.

Organization
Oracle TopLink Getting Started Guide
This document includes the following chapters:

Chapter 1, "Prerequisites for Installing Oracle TopLink"

This chapter contains important prerequisites information.

Chapter 2, "Installing and Configuring TopLink"

This chapter contains instructions for installing and configuring TopLink.

Related Documentation
For more information, see these Oracle resources:
■ Oracle TopLink Release Notes
■ Oracle Application Server Release Notes
■ Oracle TopLink API Reference
■ Oracle TopLink Developer’s Guide
■ Oracle TopLink Release Notes
■ Oracle Application Server Release Notes
■ Oracle TopLink API Reference
■ Oracle TopLink Developer’s Guide
Printed documentation is available for sale in the Oracle Store at:
http://oraclestore.oracle.com
To download free release notes, installation documentation, white papers, or other
collateral, please visit the Oracle Technology Network (OTN). You must register online
before using OTN; registration is free and can be done at:
http://www.oracle.com/technology/membership

vi
 If you already have a username and password for OTN, then you can go directly to the
documentation section of the OTN Web site at:
http://www.oracle.com/technology/docs

Feedback
If you have questions about TopLink, you can consult the TopLink user’s forum at:
http://forums.oracle.com/forums/forum.jspa?forumID=48
http://forums.oracle.com/forums/forum.jspa?forumID=48
If you have questions or feedback about this documentation, you can consult the
documentation feedback forum at
http://forums.oracle.com/forums/forum.jspa?forumID=165
http://forums.oracle.com/forums/forum.jspa?forumID=165

Conventions
This section describes the conventions used in the text and code examples of this
documentation set. It describes:
■ Conventions in Text
■ Conventions in Code Examples

Conventions in Text
We use various conventions in text to help you more quickly identify special terms.
The following table describes those conventions and provides examples of their use.

Convention Meaning Example

Italics Italic typeface indicates book titles or Oracle10i Database Concepts
emphasis.
Ensure that the recovery catalog and target
database do not reside on the same disk.
UPPERCASE Uppercase monospace typeface indicates You can specify this clause only for a NUMBER
monospace elements supplied by the system. Such column.
(fixed-width) font elements include parameters, privileges,
You can back up the database by using the
datatypes, RMAN keywords, SQL
BACKUP command.
keywords, SQL*Plus or utility commands,
packages and methods, as well as Query the TABLE_NAME column in the USER_
system-supplied column names, database TABLES data dictionary view.
objects and structures, usernames, and
Use the DBMS_STATS.GENERATE_STATS
roles.
procedure.
lowercase Lowercase monospace typeface indicates Enter sqlplus to open SQL*Plus.
monospace executables, filenames, directory names,
The password is specified in the orapwd file.
(fixed-width) font and sample user-supplied elements. Such
elements include computer and database Back up the datafiles and control files in the
names, net service names, and connect /disk1/oracle/dbs directory.
identifiers, as well as user-supplied
The department_id, department_name, and
database objects and structures, column
location_id columns are in the
names, packages and classes, usernames
hr.departments table.
and roles, program units, and parameter
values. Set the QUERY_REWRITE_ENABLED initialization
parameter to true.
Note: Some programmatic elements use a
mixture of UPPERCASE and lowercase. Connect as oe user.
Enter these elements as shown.
The JRepUtil class implements these methods.

vii
Convention Meaning Example
lowercase italic Lowercase italic monospace font represents You can specify the parallel_clause.
monospace placeholders or variables.
Run Uold_release.SQL where old_release
(fixed-width) font
refers to the release you installed prior to
upgrading.

Conventions in Code Examples

Code examples illustrate SQL, PL/SQL, SQL*Plus, or other command-line statements.
They are displayed in a monospace (fixed-width) font and separated from normal text
as shown in this example:
SELECT username FROM dba_users WHERE username = ’MIGRATE’;

The following table describes typographic conventions used in code examples and
provides examples of their use.

Convention Meaning Example

[] Brackets enclose one or more optional DECIMAL (digits [ , precision ])
items. Do not enter the brackets.
{} Braces enclose two or more items, one of {ENABLE | DISABLE}
which is required. Do not enter the braces.
| A vertical bar represents a choice of two or {ENABLE | DISABLE}
more options within brackets or braces.
[COMPRESS | NOCOMPRESS]
Enter one of the options. Do not enter the
vertical bar.
... Horizontal ellipsis points indicate either:
■ That we have omitted parts of the CREATE TABLE ... AS subquery;
code that are not directly related to the
example
SELECT col1, col2, ... , coln FROM
■ That you can repeat a portion of the
employees;
code
. Vertical ellipsis points indicate that we
have omitted several lines of code not
.
directly related to the example.
.
Other notation You must enter symbols other than acctbal NUMBER(11,2);
brackets, braces, vertical bars, and ellipsis
acct CONSTANT NUMBER(4) := 3;
points as shown.
Italics Italicized text indicates placeholders or CONNECT SYSTEM/system_password
variables for which you must supply
DB_NAME = database_name
particular values.
UPPERCASE Uppercase typeface indicates elements SELECT last_name, employee_id FROM
supplied by the system. We show these employees;
terms in uppercase in order to distinguish
SELECT * FROM USER_TABLES;
them from terms you define. Unless terms
appear in brackets, enter them in the order DROP TABLE hr.employees;
and with the spelling shown. However,
because these terms are not case sensitive,
you can enter them in lowercase.

viii
Convention Meaning Example
lowercase Lowercase typeface indicates SELECT last_name, employee_id FROM
programmatic elements that you supply. employees;
For example, lowercase indicates names of
sqlplus hr/hr
tables, columns, or files.
CREATE USER mjones IDENTIFIED BY
Note: Some programmatic elements use a
ty3MU9;
mixture of UPPERCASE and lowercase.
Enter these elements as shown.

ix
x
 1
Prerequisites for Installing Oracle TopLink

This chapter provides information that you should review before installing Oracle
TopLink (TopLink). It contains the following topics:
■ System Requirements and Certifications
■ Supported Databases
■ License Information

1.1 System Requirements and Certifications

The complete product requirements list and the latest certification information for 10g
Release 3 (10.1.3) is available at:
http://www.oracle.com/technology/software/products/ias/files/as_
certification_r3_1013.html

Additional Requirements
TopLink requires a Java Virtual Machine (JVM) compatible with JDK 1.5 (or higher).
TopLink also requires internet access to use URL-based schemas and hosted
documentation.

1.2 Supported Databases

TopLink is an infrastructure-based solution that simplifies the integration of Java
objects to any JDBC (Java Database Connectivity) compliant database. TopLink
supports JDBC 3.0 drivers that comply with JDBC 3.0 object-relational extensions.
Contact your database and JDBC vendor to determine which object-relational
extensions they support.
For TopLink Workbench to retrieve table information from the database, the database
driver must support the following JDBC methods:
■ getTables ( )
■ getTablesTypes ( )
■ getImportedKeys ( )
■ getCatalogs ( )
■ getPrimaryKeys ( )

Prerequisites for Installing Oracle TopLink 1-1

License Information

1.3 License Information

TopLink does not require a license file for TopLink Foundation Library or TopLink
Workbench; however, you are not allowed to ship the TopLink Workbench or expose
any of the TopLink APIs as part of an end-user application. Refer to the software
license agreement for information about the limitations on including the Oracle
TopLink Foundation Library JAR files, as part of a packaged end-user application.
Licensing information is available at
http://oraclestore.oracle.com

1.3.1 Third-Party License Information

TopLink uses and includes the following software:
■ Antlr
■ DOM
■ Java Runtime Environment
■ ASM

1.3.1.1 Antlr
http://www.antlr.org/rights.html
TopLink uses Antlr for EJB QL parsing. Antlr (ANother Tool for Language
Recognition), is a language tool that provides a framework for constructing
recognizers, compilers, and translators from grammatical descriptions containing C++
or Java actions. The ANTLR parser and translator generator is fully in the public
domain.

1.3.1.2 DOM
http://www.w3.org/Consortium/Legal/copyright-software.html
The Document Object Model (DOM) is a specification that defines some programming
language-neutral interfaces that can be used to manipulate XML and HTML
documents. W3C maintains this specification. W3C also provides a Java "binding" for
these interfaces. TopLink uses this "binding" to parse and manipulate XML documents.
This program contains third-party code from the World Wide Web Consortium
("W3C"). Under the terms of the W3C license, Oracle is required to provide the
following notices. Note, however, that the Oracle program license that accompanied
this product determines your right to use the Oracle program, including the W3C
software, and the terms contained in the following notices do not change those rights.
This work (and included software, documentation such as READMEs, or other related
items) is being provided by the copyright holders under the following license. By
obtaining, using and/or copying this work, you (the licensee) agree that you have
read, understood, and will comply with the following terms and conditions.
Permission to copy, modify, and distribute this software and its documentation, with
or without modification, for any purpose and without fee or royalty is hereby granted,
provided that you include the following on ALL copies of the software and
documentation or portions thereof, including modifications:
1. The full text of this NOTICE in a location viewable to users of the redistributed or
derivative work.

1-2 Oracle Application Server TopLink Getting Started Guide

 License Information

2. Any pre-existing intellectual property disclaimers, notices, or terms and

conditions. If none exist, the W3C Software Short Notice
(http://www.w3.org/Consortium/Legal/2002/copyright-software-s
hort-notice-20021231.html) should be included (hypertext is preferred, text
is permitted) within the body of any redistributed or derivative code.
3. Notice of any changes or modifications to the files, including the date changes
were made. (We recommend you provide URLs to the location from which the
code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND
COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY
THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT,
SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE
SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or
publicity pertaining to the software without specific, written prior permission. Title to
copyright in this software and any associated documentation will at all times remain
with copyright holders.

1.3.1.3 Java Runtime Environment

http://java.sun.com/j2se/
The Java Runtime Environment is maintained by Sun Microsystems, Inc. The Oracle
TopLink installation includes JRE 1.5 by default. You may configure TopLink to run
using any other compliant Java 2 VM. Java and all Java-based trademarks and logos
are trademarks or registered trademarks of Sun Microsystems, Inc., in the U.S. and
other countries.

1.3.1.4 ASM
ASM is a Java bytecode manipulation framework. It can be used to dynamically
generate stub classes or other proxy classes, directly in binary form, or to dynamically
modify classes at load time, that is, just before they are loaded into the Java Virtual
Machine.
http://asm.objectweb.org/license.html
Copyright (c) 2000-2005 INRIA, France Telecom
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are
permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list
of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
3. Neither the name of the copyright holders nor the names of its contributors may
be used to endorse or promote products derived from this software without
specific prior written permission.

Prerequisites for Installing Oracle TopLink 1-3

License Information

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND

CONTRIBUTORS "AS IS"AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THEIMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSEARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BELIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, ORCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OFSUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER INCONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OFTHE
POSSIBILITY OF SUCH DAMAGE.

1-4 Oracle Application Server TopLink Getting Started Guide

 2
Installing and Configuring TopLink

This chapter includes the following information to install and configure Oracle
TopLink:
■ TopLink Installation Types
■ Installing TopLink
■ Configuring TopLink Runtime Environment
■ Configuring TopLink Workbench Environment
■ Starting TopLink Workbench
■ TopLink Tutorial
■ Installation Troubleshooting
■ Installing Patch Sets

2.1 TopLink Installation Types

The Oracle Universal Installer includes TopLink with the basic Oracle Application
Server installation.To install only TopLink, select the Advanced installation type, then
choose Oracle TopLink. This will install the TopLink Foundation Library and TopLink
Workbench.

2.2 Installing TopLink

Use the following procedures to install TopLink (including TopLink Foundation
Library and TopLink Workbench). Before you install TopLink, back up all existing
project data.
This section includes information on:
■ Using Oracle Universal Installer
■ Installing Silently

2.2.1 Using Oracle Universal Installer

Use this procedure to start the Oracle Universal Installer and install TopLink 10g
Release 3 (10.1.3).
1. For Windows operating systems:
■ Ensure that you are logged in to the computer as a member of the Windows
Administrators group.

Installing and Configuring TopLink 2-1

Installing TopLink

■ When configuring TopLink for use with J2EE containers, you must modify the
System Variables—not the User Variables.
2. Insert the TopLink installation disk into the CD-ROM drive to launch Oracle
Universal Installer, or download the installer from:
http://www.oracle.com/technology/products/ias/toplink/index.html

For Windows operating systems:

■ If your computer supports the auto run feature, the installer will automatically
launch on your computer.
■ If your computer does not support the auto run feature, execute the
G:\setup.exe program (where G is the letter for your CD-ROM drive) to
start the installer.
3. Insert the TopLink installation disk into the CD-ROM drive to launch Oracle
Universal Installer, or download the installer from:
4. Complete each screen of the installer.
5. When the installation is complete, you must configure the TopLink Workbench
environment.
For more information, see "Configuring the TopLink Workbench Environment" in
the Oracle TopLink Developer’s Guide.
6. Refer to ORACLE_HOME\toplink\doc\index.htm for the latest Oracle TopLink
Release Notes.

2.2.2 Installing Silently

Silent installation mode is available for all installation types. You can use the silent
installation when you wish to make multiple installations simultaneously or when you
perform installations from a remote location. Silent installation eliminates the need to
monitor the installation because there is no graphical output and no input by the user.
1. Insert the TopLink installation disk into the CD-ROM drive.
2. Open the \Stage\Response directory and select the
oracle.as.j2ee.top.toplink.rsp file.
3. Copy the oracle.as.j2ee.top.toplink.rsp file to a temporary (c:\temp)
location.
4. Edit the following parameters in the oracle.as.j2ee.top.toplink.rsp file:
ORACLE_HOME
ORACLE_HOME_NAME
FROM_LOCATION

5. Start the installer.

Open a command prompt window and enter:
setup.exe -responseFile c:\temp\oracle.as.j2ee.top.toplink.rsp -silent

To check if the installation was successful, search for the following line in the
silentInstall.log file:
"The installation of Oracle Application Server 10g was successful."

2-2 Oracle Application Server TopLink Getting Started Guide

 Configuring TopLink Workbench Environment

2.3 Configuring TopLink Runtime Environment

At runtime, the TopLink Foundation Library requires the Java Runtime
Environment 1.5 (or higher). By default, the TopLink installation includes the JRE
1.5.0_04.
To configure TopLink for a different version of the JRE, change the ORACLE_
HOME\toplink\bin\setenv.cmd file to point JAVA_HOME to the alternate
directory.

2.4 Configuring TopLink Workbench Environment

After installing TopLink Workbench, you must configure the following:
■ JRE Version
■ Online Help and Documentation

2.4.1 JRE Version

TopLink Workbench requires the Java Runtime Environment 1.4.2_06 (or higher). By
default, the TopLink installation includes the JRE 1.5.
To configure TopLink for a different version of the JRE, change the ORACLE_
HOME\toplink\bin\setenv file to point JAVA_HOME to the alternate directory.

Java Cryptography Extension (JCE)

The TopLink Workbench uses JCE to encrypt database login information. JCE is
included with JDK 1.4 (or higher).

2.4.2 Online Help and Documentation

By default, TopLink installs only a portion of TopLink Workbench online Help system
on your computer. To access the complete documentation from Oracle, ensure that
your computer is connected to the internet and the proxy information (if necessary) is
correct.
For more information on how to specify the help mode, see the Oracle TopLink
Developer’s Guide.
From the TopLink Workbench menu, select Tools, Preferences. On the Preferences
dialog, select General to configure your proxy information.

2.4.3 Driver Classpath Environment Variable

Depending on the TopLink Workbench project, you are required to update the
DRIVER_CLASSPATH environment variable to add the location of the following (if
necessary):
■ JDBC drivers – If you are using relational projects.
■ J2EE Connector Architecture (J2C) adapters – If you are using TopLink Workbench
Enterprise Information System (EIS) projects.
■ Oracle Database <ORACLE_HOME>\rdbms\jlib\xdb.jar file – If you are
using direct to XML type mappings with an Oracle10g or higher database.
■ Custom Collection class that you use to override the default Collection class
that TopLink uses with a mapping container policy.

Installing and Configuring TopLink 2-3

Starting TopLink Workbench

For more information on how to update the DRIVER_CLASSPATH environment

variable, see "Configuring the TopLink Workbench Environment" section in the Using
TopLink Workbench chapter in the Oracle TopLink Developer’s Guide.

2.4.4 Third-party Libraries

If you plan to use additional, third-party libraries (such as XMLType Mappings or EIS
with Attunity), when deploying your Oracle TopLink project, you must copy the
appropriate JAR file to ORACLE_HOME\toplink\jlib. Additionally, you must
include the libraries on the server’s classpath.

2.5 Starting TopLink Workbench

To start TopLink Workbench, simply execute the workbench.cmd file in the
INSTALL_DIR\toplink\bin directory. The TopLink Welcome Screen appears.
If you receive a "Cannot Find Main Class" error, ensure that you have configured
JAVA_HOME correctly. See "JRE Version" on page 2-3.

Note: On Microsoft Windows XP platforms with mapped network

drives, the TopLink Workbench File Chooser dialogs (such as Save
File or Open File) may experience slow responses for opening and
traversing directory trees. Unmapping the network drives
eliminates this behavior.

2.6 TopLink Tutorial

TopLink provides a tutorial with which you can create an Employment Management
System for your company to be deployed in a three-tier environment using JSP
servlets. The tutorial shows you how to store data from a Java class into a relational
database and access existing database information from Java classes.
Specifically, you will learn how to:
■ Create a new TopLink Workbench project
■ Enable and add Java classes
■ Create and import database tables
■ Associate descriptors to tables
■ Implement direct and relationship mappings (including self-relationships)
■ Use indirection and value holders
■ Apply several advanced features such as multiple tables and optimistic locking
■ Write TopLink queries
■ Create and manage database sessions
■ Package and deploy a TopLink application

See Also:
■ Oracle TopLink Developer’s Guide
■ http://www.oracle.com/technology/products/ias/topli
nk/doc/1013/MAIN/_html/prt_tut.htm

2-4 Oracle Application Server TopLink Getting Started Guide

 Installing Patch Sets

2.7 Installation Troubleshooting

After you install TopLink, if you encounter problems either starting the application or
connecting to a database, try the following solutions:
■ Ensure that the driver class name is correct. Many vendors have several different
driver classes to choose from.
■ Check your login information.
■ Ensure that your path includes all .dll files your driver requires.
■ Check with your database administrator that:
■ Any drivers that require special set-up in the database server (such as Sybase
JConnect) have been set up correctly.
■ Any drivers that require special permissions in the database server have been
set up correctly.
■ You are not exceeding the number of available concurrent connections to your
database. This may occur during development time, when many people are
testing connections.
■ If you use database servers that requires an extra Windows NT service to be
running for JDBC connections, ensure that one is running.
■ Check with your vendor to ensure that you are using the latest version of both
your JDBC driver and the database to which it is connecting.
■ If it takes an extremely long time to start TopLink Workbench after the splash
screen appears (for example, more than 30 seconds), ensure that your proxy help
mode and proxy information is correct. See "Online Help and Documentation" on
page 2-3 for details.

2.8 Installing Patch Sets

When available, you can download the latest patch sets for 10g Release 3 (10.1.3) from
OracleMetaLink at:
http://metalink.oracle.com
OracleMetaLink is the Oracle Support Services site where customers can get
information about released patches and outstanding bugs.

Installing and Configuring TopLink 2-5

Installing Patch Sets

2-6 Oracle Application Server TopLink Getting Started Guide

 Index

A I
additional requirements, 1-1 installation, 2-1
Antlr log, 2-2
licensing, 1-2 Oracle Universal Installer (OUI), 2-1
overview, 1-1
prerequisites, 2-1
C
silent, 2-2
case-sensitive, 2-1 types, 2-1
certification, 1-1 installation types, Oracle TopLink, 2-1
classpath
configuring JDBC_CLASSPATH, 2-3
custom Collection class, 2-3
J
DRIVER_CLASSPATH, Oracle TopLink Java
Workbench, 2-3 Java 2, 2-3
JCA adapter, 2-3 Java Cryptography Extension (JCE), 2-3
JDBC driver, 2-3 Java Runtime Environment (JRE)
Oracle TopLink Workbench DRIVER_ licensing, 1-3
CLASSPATH, 2-3 requirements, 1-1
xdb.jar, 2-3 JCA adapter, 2-3
configuring JDBC drivers
setenv.cmd file, 2-2 classpath, 2-2
Sun JDK and JRE, 2-3 environment variables, 2-3
container policy requirements, 1-1
custom Collection class, 2-3 JDBC_CLASSPATH, 2-2, 2-3
JVM (Java Virtual Machine), 1-1
D
databases L
supported, 1-1 license information
troubleshooting, 2-5 Antlr, 1-2
DOM DOM, 1-2
licensing, 1-2 Java Runtime Environment (JRE), 1-3
DRIVER_CLASSPATH Oracle TopLink, 1-2
Oracle TopLink Workbench environment, 2-3 log, installation, 2-2

E O
encryption, password, 2-3 Oracle Metalink, 2-5
environment Oracle Support Services, 2-5
JDBC_CLASSPATH, 2-3 Oracle TopLink Workbench
JRE, 2-3 DRIVER_CLASSPATH, 2-3
environment, 2-3
JDBC_CLASSPATH, 2-3
H
Oracle Universal Installer (OUI), 2-1
help system OUI. see Oracle Universal Installer
configuring, 2-3

Index-1
P
package names, case sensitivity, 2-1
password encryption, 2-3
patch sets, 2-5
proxy
configuring, 2-3

R
requirements
additional, 1-1
JDBC driver, 1-1

S
setenv.cmd file, 2-2
silent installation
about, 2-2
log, 2-2
silentInstall.log file, 2-2
system variables, 2-1

T
tutorial
about, 2-4
planning, 2-4

U
user variables, 2-1

W
Windows
administrator group, 2-1

X
xdb.jar<DefaultParaFont>, 2-3

Index-2