2 Installing and Configuring OracleAS TopLink

This chapter contains information about installing OracleAS TopLink. It contains the following topics:

• OracleAS TopLink Installation Types

• Installing OracleAS TopLink

• Configuring the OracleAS TopLink Examples

• Configuring OracleAS TopLink for Oracle JDeveloper

• Sun JDK and JRE

• Installing Patch Sets

• General Troubleshooting

OracleAS TopLink Installation Types

The Oracle Universal Installer (OUI) for OracleAS TopLink provides four different installation types. Each installation type is a predefined component set within the OUI that automatically selects the components to install. The installation types that appear on the OUI screen depend on the list that the installation developer specifies for the product.

The four installation types are as follows:

• Complete: This option installs the entire product, including OracleAS TopLink Foundation Library, OracleAS TopLink Mapping Workbench, OracleAS TopLink Sessions Editor, and OracleAS TopLink Examples.

• Mapping and Code Development: This option installs the OracleAS TopLink Foundation Library, OracleAS TopLink Mapping Workbench, and OracleAS TopLink Sessions Editor.

• Code Development: This option installs the OracleAS TopLink Foundation Library for development without the OracleAS TopLink Mapping Workbench and OracleAS TopLink Sessions Editor.

• Runtime: This option installs only the packaged run-time classes.

Installing OracleAS TopLink

This section describes the procedures to install OracleAS TopLink including the OracleAS TopLink Foundation Library and OracleAS TopLink Mapping Workbench.

This section contains the following topics:

• Installing OracleAS TopLink on Microsoft Windows Operating System

• Performing Silent Installation on Microsoft Windows Operating System

• Installing OracleAS TopLink on UNIX or Other Non-Windows Operating System

• Silent Installation on UNIX or Other Non-Windows Operating System

Note: Before installing OracleAS TopLink, back up the existing project data.

Installing OracleAS TopLink on Microsoft Windows Operating System

To start the OUI and install OracleAS TopLink:

1. Ensure that you are logged in to the computer as a member of the Microsoft Windows Administrators group.

   
   

   Note: When you configure OracleAS TopLink for use with (Java 2 Platform, Enterprise Edition) J2EE containers, you need to modify the system variables, not the User Variables. Java package names are case-sensitive. When you install them on Microsoft Windows, ensure that case sensitivity is turned on. For more information, refer to the Microsoft Windows documentation.

   
   

2. Insert the OracleAS TopLink installation disk into the CD-ROM drive to launch OUI.

   • If your computer supports the auto-run feature, then the installer will automatically launch on your computer.

   • If your computer does not support the auto-run feature, then perform the following steps to launch the installer:

   1. Locate the following file:

      G:\setup.exe, where G is the letter for your CD-ROM drive

   2. Launch the setup.exe program to start the installer.

      The Oracle Universal Installer Welcome screen appears. It provides information about the OUI.

3. Click Next. The Specify File Locations screen appears.

4. Enter the following information in the fields provided:

   1. Source Path: The default value appears. Do not change this value.

   2. Destination Name: Enter the required Oracle home name.

   3. Destination Path: Browse or enter the path to the directory where you want to install the Oracle Application Server Middle Tier.

5. Click Next. The Select Installation Type screen appears.

6. Select Complete to install the entire package. The other options available on the screen allow you to perform a partial install. The products that can be installed are mentioned with the options.

7. Click Next. The Summary screen appears.

8. After reviewing the Summary screen, click Install. This completes the installation and the End of Installation screen appears.

9. Click Exit and then click Yes. This completes the installation.

10. When the installation is complete, verify and if necessary, edit the JDBC_CLASSPATH variable in the ORACLE_HOME\toplink\bin\setenv.cmd file. The JDBC_CLASSPATH variable must specify the path to the preferred JDBC drivers.

    If the path to your JDBC driver(s) contains spaces, then the path must be enclosed in double-quotes in the setenv.cmd file. For example:

    set JDBC_CLASSPATH="C:\Program Files\some directory\driver.jar\"
    
    

    
    

    Note: The JDBC_CLASSPATH variable must not include any Java classes for your persistent business objects that are specified in an OracleAS TopLink Mapping Workbench project. Paths for persistent business objects are set within an OracleAS TopLink Mapping Workbench project. For more information on how to set up a path for a project, refer to Oracle Application Server TopLink Mapping Workbench User's Guide.

    
    
    
    

    See Also: Refer to ORACLE_HOME\toplink\doc\index.htm for the latest OracleAS TopLink Release Notes

    
    

Performing Silent Installation on Microsoft Windows Operating System

The silent installation mode is available for all installation types. You can make use of 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.

To perform a silent installation:

1. Insert the OracleAS TopLink installation disk into the CD-ROM drive.

2. Open the \Stage\Response directory and select the oracle.toplink.Installation_Type.rsp response file. For example, if you select the Complete installation type, then the response file would be complete.rsp.

3. Copy the oracle.toplink.Installation_Type.rsp file to a temp folder.

4. Edit the following parameters in the oracle.toplink.Installation_Type.rsp file:

   • ORACLE_HOME

   • ORACLE_HOME_NAME

5. Open a command prompt window and run the following commands:

   setup.exe -responseFile C:\temp\oracle.toplink.complete.rsp -silent and press Enter.

6. If your installation is successful, then the log file for the silent installation will contain the following line:

   The installation of OracleAS TopLink was successful.

Installing OracleAS TopLink on UNIX or Other Non-Windows Operating System

To start OUI and install OracleAS TopLink on UNIX or other non-Windows operating system, proceed as follows:

1. Insert the OracleAS TopLink installation disk into the CD-ROM.

2. Run OUI from the CD-ROM and follow the OUI instructions.

   
   

   Note: Ensure you are not logged in as the root user when you start the OUI. If you are, then only the root user will have permissions to manage OracleAS TopLink.

   
   

   1. Log in as the oracle user.

   2. To start the installer, enter the following command at the command prompt:

      prompt> mount_point/as_1012disk/runInstaller.

      This launches the OUI with which you install OracleAS TopLink.

      
      

      Note: 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. When the installation is complete, verify and, if necessary, edit the JDBC_CLASSPATH variable in the setenv.sh file. The JDBC_CLASSPATH variable must specify the path to the preferred JDBC driver.

   You can find the setenv.sh file in the ORACLE_HOME/toplink/bin directory.

   
   

   Note: The JDBC_CLASSPATH variable must not include any Java classes for your persistent business objects that are specified in an OracleAS TopLink Mapping Workbench project. Paths for persistent business objects are set within an OracleAS TopLink Mapping Workbench project.

   
   
   
   

   See Also: Oracle Application Server TopLink Mapping Workbench User's Guide for more information on how to set up a path for a project

   
   

4. Refer to ORACLE_HOME/toplink/doc/index.htm for the latest OracleAS TopLink Release Notes.

Silent Installation on UNIX or Other Non-Windows Operating System

The steps for a silent installation on UNIX or other non-Windows operating systems are:

1. Insert the OracleAS TopLink installation disk into the CD-ROM drive.

2. Open the /Stage/Response directory and select the  oracle.toplink.Installation_Type.rsp file.

3. Copy the oracle.toplink.Installation_Type.rsp file to a temp folder.

4. Edit the following parameters in the oracle.toplink.Installation_Type.rsp file:

   • ORACLE_HOME

   • ORACLE_HOME_NAME

   • GROUP_NAME

   • FROM_LOCATION

5. Open a command prompt window and enter ./runInstaller -responseFile /tmp/oracle.toplink.Installation_Type.rsp -silent and press Enter.

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

   The installation of OracleAS TopLink was successful.

Configuring the OracleAS TopLink Examples

The complete OracleAS TopLink installation includes the OracleAS TopLink examples. These examples help you explore and learn how to use the OracleAS TopLink features with different architectures and different technologies. They are designed to be as simple as possible while still effectively demonstrating the target architecture, technology, or feature.

There are two types of examples, Oracle Application Server and OracleAS TopLink Foundation Library (non-server) examples.

• Oracle Application Server examples vary from server to server, depending on the server-specific features. Although OracleAS TopLink provides instructions for certain servers, you can run many of the examples (for example, the Session Bean and Servlet JSP examples) on other application servers with some configuration changes.

• OracleAS TopLink Foundation Library (non-server) examples are configured to run in a simple Java Virtual Machine (JVM), but the features and technologies they demonstrate can also be used in an application server environment.

When you run the examples, useful information is written to standard output, including details about what the example is doing and what SQL is generated. You may find it useful to redirect standard output to a file when you run an example.

Although the OracleAS TopLink examples require little configuration, ensure that you read and verify the configuration details included in the Configuring the Examples document before you run the examples.

See Also: Configuring the Examples document, which can be accessed at ORACLE_HOME\toplink\doc\examples\config\config.htm

When the configuration is complete, each of the OracleAS TopLink examples has a readme file with specific information on how to build and run the example.

For known issues with OracleAS TopLink examples, refer to "Troubleshooting Known Issues" sections in the Oracle Application Server TopLink Application Developer's Guide.

Configuring OracleAS TopLink for Oracle JDeveloper

This section contains information on how to configure OracleAS TopLink for Oracle JDeveloper.

Oracle JDeveloper is a J2EE development environment with end-to-end support to develop, debug, and deploy e-business applications and Web Services.

When you use OracleAS TopLink with Oracle JDeveloper, use the following procedures to add the OracleAS TopLink JAR files to your JDeveloper projects:

Creating an OracleAS TopLink JDeveloper Library:

1. Select a JDeveloper project in the System Navigator pane.

2. Select Project, click Project Settings.

   The Project Settings pane appears.

3. Click Configurations, Development, and then Libraries. A list of predefined and user-defined libraries appears.

4. Click New to create a new library, which will contain the OracleAS TopLink .jar files.

   The New Library dialog box appears.

5. Enter a name for the new library, for example, OracleAS TopLink. Ensure that the default choice for libraries remains as User Libraries.

6. To edit the classpath and add the OracleAS TopLink .jar files, click the Edit button.

   Add the following to the beginning of the classpath:

   ORACLE_HOME\toplink\jlib\toplink.jar
   ORACLE_HOME\toplink\jlib\antlr.jar
   ORACLE_HOME\lib\xmlparserv2.jar
   
   

7. Click OK. On the Project Settings pane click OK.

Use an Existing User-Defined OracleAS TopLink Library:

After a user library is created, it can be re-referenced by any other project. Revisit the Libraries window of the Project Settings, and add the OracleAS TopLink Library to any project with which you want to use OracleAS TopLink.

Sun JDK and JRE

On a Microsoft Windows-based platform, OracleAS TopLink includes the Java Runtime Environment (JRE) 1.4.2. OracleAS TopLink is certified with Sun JDK 1.4.2_06 for use by the OracleAS TopLink Mapping Workbench.

At runtime, the OracleAS TopLink Foundation Library requires a JVM compatible with JDK 1.4.2 or later. OracleAS TopLink is certified with Sun JDK 1.4.2_06 for use by the OracleAS TopLink Foundation Library.

To configure OracleAS TopLink for a different version of the JRE, change the setenv.cmd file to point JRE_HOME to the alternate directory.

To compile and run the OracleAS TopLink Examples, you must have a Java 2 SDK installed.

See Also: Chapter2, "Configuring the OracleAS TopLink Examples" for more information about how to configure and run the OracleAS TopLink Examples

JCE

The OracleAS TopLink Mapping Workbench and OracleAS TopLink Sessions Editor use Java Cryptography Extension (JCE) to encrypt database login information. JCE is included with JDK 1.4.2. If you use JDK 1.1.3 or higher, then select one of the following options:

• Download and install the Sun JCE plug-in from http://java.sun.com/products/jce/

• Do not store password information in OracleAS TopLink Mapping Workbench or OracleAS TopLink Sessions Editor. Instead, manually add the password in the code or edit the generated project file.

Installing Patch Sets

The 10g Release 2 (10.1.2) release includes changes introduced in all previously released patch sets for Release 2 (9.0.4) up to and including patch set Release 2 (9.0.4.7).

When available, you can download the latest patch sets for 10g Release 2 (10.1.2) 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.

General Troubleshooting

After you install OracleAS TopLink, if you encounter problems either starting the application or connecting to a database, then try the following solutions:

• Ensure that the driver class name is correct. Many vendors have several driver classes to choose from.

• Check your login information.

• Ensure that your path includes all the.dll files that your driver requires.

• Check with your database administrator that:

  • drivers that require special setup in the database server have been set correctly.

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

  • 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 require an extra Microsoft Windows service to be running for JDBC connections, then ensure that the service is running.