Skip Headers

Oracle® TopLink Getting Started Guide 10g Release 3 (10.1.3) Part No. B13594-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 2 Installing and Configuring TopLink

This chapter includes the following information to install and configure Oracle TopLink on your computer:

- TopLink Installation Types

- Installing TopLink

- Configuring TopLink Runtime Environment

- Configuring TopLink Workbench Environment

- Starting TopLink Workbench

- TopLink Tutorial

- Installation Troubleshooting

- Installing Patch Sets

## TopLink Installation Types

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

## 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.

Warning: If you are upgrading from a pre-Release 1 (9.0.3), you must convert the package names before you open your TopLink project(s) in 10g Release 3 (10.1.3). Refer to "Package Rename" for more information after installing TopLink.

This section includes information on:

- Using Oracle Universal Installer

- Installing Silently

### 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.

   - When configuring TopLink for use with J2EE containers, you must modify the System Variables—not the User Variables.

   For Unix or other non-Windows operating systems:

   - Ensure that you are not logged in as the root user when you start the Oracle Universal Installer. If you are, then only the root user will have permissions to manage TopLink.

   - Log in as the `oracle` user.

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.

   For UNIX or other non-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, enter: `prompt> mount_point/as_1013disk/runInstaller` to launch the installer.

     Caution: Do not start the installation inside the `mount_point` directory. If you do, then you may not be able to eject the installation disk.

3. Complete each screen of the installer.

4. 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.

5. Refer to `<ORACLE_HOME>``\toplink\doc\index.htm` for the latest Oracle TopLink Release Notes.

### 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 (`tmp`) location.

4. Edit the following parameters in the `oracle.as.j2ee.top.toplink.rsp` file:

     ORACLE_HOME
     ORACLE_HOME_NAME
     GROUP_NAME (for Unix or other non-Windows operation systems only)
     FROM_LOCATION

5. Start the installer.

   For Windows operating systems, open a command prompt window and enter:

       setup.exe -responseFile c:/oracle.as.j2ee.top.toplink.rsp -silent

   For UNIX and other non-Windows operating systems, open a command prompt window and enter:

       ./runInstaller -responseFile /tmp/oracle.as.j2ee.top.toplink.rsp -silent

If your installation was successful, the `silentInstall.log` file contains the line:

"The installation of TopLink was successful."

## Configuring TopLink Runtime Environment

At runtime, the TopLink Foundation Library requires the Java Runtime Environment 1.3 (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.

## Configuring TopLink Workbench Environment

After installing TopLink Workbench, you must configure the following:

- JRE Version

- Online Help and Documentation

### 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).

### Online Help and Documentation

By default, TopLink installs only a portion of TopLink Workbench online help system on your PC. To access the complete documentation from Oracle, ensure that your PC is connected to the internet and the your 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.

### 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 Oracle9i or higher database.

- Custom `Collection` class that you use to override the default `Collection` class that TopLink uses with a mapping container policy.

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.

### 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 you server's classpath.

## Starting TopLink Workbench

To start TopLink Workbench, simply execute the `workbench.cmd` or `.sh` 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".

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.

## 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

For more information about the tutorial, see the Oracle TopLink Developer's Guide. See also the TopLink Tutorial at:

    http://download.oracle.com/otn_hosted_doc/toplink/1013/MAIN/_html/prt_tut.htm

## 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" for details.

## 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.