WebObjects 5: How to Use Oracle JDBC drivers

This document describes the Oracle JDBC drivers and how to use them with WebObjects 5.
This article has been archived and is no longer updated by Apple.

Applicable products

  • WebObjects 5.0
  • WebObjects 5.1
  • WebObjects 5.2
  • WebObjects 5.3

Types of JDBC Drivers

Only the thin JDBC driver has been qualified for Mac OS X, Windows 2000, and Solaris.

WebObjects 5.0 and WebObjects 5.1

  • Oracle Thin JDBC driver

WebObjects 5.2

  • Oracle Thin JDBC driver
  • Oracle Thin JDBC driver

WebObjects 5.3

  • Oracle Thin JDBC Driver 10.1.0.x

See technical document 72598 "WebObjects Compatibility Guide" for all other database JDBC support.

Where to Obtain Oracle JDBC Drivers

The Oracle JDBC drivers are available from Oracle's website (http://otn.oracle.com/software/content.html). You need an Oracle technet account to download the drivers. (You can set up an account on Oracle's website for free.)

Windows 2000

Download the thin JDBC drivers for both JDK 1.3.x and JDK 1.1.x.

The files are:

  • For JDK 1.1.x , the thin driver is: classes111.zip
  • For JDK 1.3.x, the thin driver is: classes12.zip

Mac OS X

Mac OS X 10.0.x

  • Download the Oracle 8i 8.1.7 JDBC thin driver for Solaris (JDK 1.2.x only)(classes 12.zip).

Mac OS X 10.2

  • Follow the instructions from the Oracle download site to download either the Oracle 8i or Oracle 9i thin JDBC driver for Mac OS X 10.2.

Please note that you should use the Oracle 9i thin JDBC driver when accessing the Oracle 9i database to avoid the possible ORA-00600 error.

Mac OS X 10.4

Follow the instructions from the Oracle download site to download the Oracle 10 g thin JDBC driver for JDK 1.4 (ojdbc14.jar).

Solaris 2.8

  • Follow the instructions from the Oracle download site to download either the Oracle 8i or Oracle 9i thin JDBC driver.
  • The Oracle 9i thin JDBC driver has been qualified for WebObjects 5.2 only.

Where to Install the Oracle JDBC drivers

This section contains the proper location for the Oracle JDBC drivers. The applicable platform is listed in bold.

  1. The JDBC driver (classes 12.zip) must be installed where the Java VM can find it. The simplest procedure is to add the JDBC driver (zip file) to the Java VM's "extensions".

    (All Platforms)


    Windows 2000
    The Java VM "extension" directory is generally C:\\jdk1.3.x\\jre\\lib\\ext\\ . However, the exact directory depends on where JDK 1.3.x is installed on your computer.

    Mac OS X - WebObjects 5.1 to 5.3
    Place the JDBC file in /Library/Java/Extensions

    Mac OS X - WebObjects 5.0 only
    Place the JDBC file in /Library/Java/Home/lib/ext/

    Place the JDBC file in /usr/java/jre/lib/ext

  2. Install the JDK 1.1 driver in $NEXT_ROOT/Library/Java and modify the JavaConfig.plist file accordingly.

    Windows 2000 only

    When doing development on Windows 2000, the situation is somewhat more complicated. The WebObjects 5 runtime uses a Java 2 VM and requires a JDK 1.3.x compatible JDBC driver just like Mac OS X and other platforms. However, EOModeler uses the Java Bridge, which only supports JDK 1.1 on Windows and therefore requires a JDK 1.1 compatible driver. Consequently, in order to do development and testing on Windows 2000, two versions of a particular JDBC driver are needed. One that is JDK 1.3 compatible for the WebObjects 5 runtime, and another that is JDK 1.1 compatible for use by EOModeler and the Java Bridge.

    To use a JDBC 1.1 driver with EOModeler on Windows 2000, you should add it to the JavaConfig.plist. This is the Oracle driver classes111.zip in this case. If your WebObjects installation is not in C:/Apple, substitute the appropriate path below. The Unix notation of "/" for the directory separator is used in the samples

    1. Log in with an administrator account.
    2. Copy classes111.zip to C:/Apple/Library/Java/
    3. Edit the file C:/Apple/Library/Java/JavaConfig.plist
    4. Add $NEXT_ROOT/Library/Java/classes111.zip to the entry for the "DefaultClasspath". Items in the list should be separated by a semicolon ";". Use the term "$NEXT_ROOT" literally, following the pattern of the other entries.

    Note: If Windows is used only as a deployment platform, then the JDK 1.1 compatible driver is not needed.

Setting up the proper connection dictionary for EOModeler and Oracle JDBC drivers

The EOModeler login panel shows three textfields:

Username: Enter the username such as scott

Password: Enter the password such as tiger

URL: By definition, the JDBC URL has the following format:


drivertype - Is thin for the Oracle thin driver, or oci8 if you have downloaded the OCI driver that includes the jdbcoci8.dll file. The oci8 driver can access either an Oracle7 or an Oracle8 server.

user/password - Is not needed in the EOModeler URL textfield, since it is already specified in the two other textfields.

@database - For JDBC OCI drivers: An entry in the tnsnames.ora file.

For JDBC Thin: A string of the form host:port:sid

Example 1: Oracle JDBC Thin driver

Username: scott

Password: tiger

URL: jdbc:oracle:thin:@myServer:1521:myServerID

myServer is the hostname

myServerID is an Oracle sid defined in your tnsnames.ora file.

Note: If you installed the OCI client libraries on Windows, the tnsnames.ora file resides in: $ORACLE_HOME/network/admin

Troubleshooting connection errors

  • If your connection dictionary is incorrect, you may see the following error:
    SQLException raised when connecting : java.sql.SQLException: ORA-06401: NETCMN: invalid driver designator
    Check if you have the proper drivertype in your URL, or if the @database entry matches an alias in your tnsnames.ora file, and so forth.

  • Windows 2000 - If you did not update your Default Classpath in the file JavaConfig.plist to include the classes111.zip (JDBC driver), you may see the following error:<
    JDBC connection failed for driver :'oracle.jdbc.driver.OracleDriver'. Driver not found in Java Runtime! Please verify your CLASSPATH environment variable. The current CLASSPATH for your application is :C:\\Apple\\Library\\Frameworks\\JDBCEOAdaptor.framework\\Resources\\Java\\.;/Library/Java;

  • WebObjects 5.2 - If you use an old Oracle 8i JDBC driver to access an Oracle 9i database server, you may see the following error:
    ORA-00600: internal error code, arguments: [19944], [], [], [], [], [], [], []
    Make sure that you are using an Oracle 9i JDBC driver to access the Oracle 9i database server.

Published Date: Feb 20, 2012