2 Getting Started

This chapter provides a discussion on the compatibilities between Oracle Java Database Connectivity (JDBC) driver versions, database versions, and Java Development Kit (JDK) versions. It also describes the basics of testing a client installation and configuration and running a simple application. This chapter contains the following sections:

Compatibilities for Oracle JDBC Drivers

This section discusses the general JDBC version compatibility issues.

Backward Compatibility

The JDBC drivers are certified to work with the currently supported versions of the Oracle Database. For example, the JDBC Thin drivers in Oracle Database 10g are certified to work with the 9.2.x, 9.0.1.x, and 8.1.7 Oracle Database releases. However, they are not certified to work with older, unsupported database releases, such as 8.0.x and 7.x.

Forward Compatibility

Existing and supported JDBC drivers are certified to work with Oracle Database 10g.


Verifying a JDBC Client Installation

Verifying a JDBC client installation involves:

Installation of an Oracle JDBC driver is platform-specific. Follow the installation instructions for the driver you want to install in your platform-specific documentation.

This section describes the steps of verifying an Oracle client installation of the JDBC drivers, assuming that you have already installed the driver of your choice.

If you have installed the JDBC Thin driver, then no further installation on the client computer is necessary.


The JDBC Thin driver requires a TCP/IP listener to be running on the computer where the database is installed.

If you have installed the JDBC Oracle Call Interface (OCI) driver, then you must also install the Oracle client software. This includes Oracle Net and the OCI libraries.

Checking Installed Directories and Files

Installing the Oracle Java products creates, among other things, the following directories:

  • ORACLE_HOME/jdbc

  • ORACLE_HOME /jlib

Check whether the following directories have been created and populated in the ORACLE_HOME/jdbc directory:

  • demo

    This directory contains a compressed file, demo.zip or demo.tar. When you uncompress this compressed file, the samples directory and the Samples-Readme.txt file is created. The samples directory contains sample programs, including examples of how to use JDBC escape syntax and Oracle SQL syntax, PL/SQL blocks, streams, user-defined types, additional Oracle type extensions, and Oracle performance extensions.

  • doc

    This directory contains the javadoc.zip file, which is the Oracle JDBC application programming interface (API) documentation.

  • lib

    The lib directory contains the following required Java classes:

    • orai18n.jar

      Contains classes for globalization and multibyte character sets support

    • classes12.jar and classes12_g.jar

      Contain the JDBC driver classes for use with JDK releases after 1.2 and before 1.4

    • ojdbc14.jar and ojdbc14_g.jar

      Contain the JDBC driver classes for use with JDK 1.4

  • Readme.txt

    This file contains late-breaking and release-specific information about the drivers, which may not have been included in other documentation on the product.

Check whether the following directories have been created and populated in the ORACLE_HOME /jlib directory:

  • jta.jar and jndi.jar

    These files contain classes for the Java Transaction API (JTA) and the Java Naming and Directory Interface (JNDI) for JDK 1.2.x, 1.3.x, and 1.4. These are only required if you are using JTA features for distributed transaction management or JNDI features for naming services.


    These files can also be obtained from the Sun Microsystems Web site. However, it is recommend to use the versions supplied by Oracle, which have been tested with the Oracle drivers.

Checking the Environment Variables

This section describes the environment variables that must be set for the JDBC OCI driver and the JDBC Thin driver, focusing on the Sun Solaris and Microsoft Windows platforms.

You must set the CLASSPATH for your installed JDBC OCI or Thin driver. Depending on which JDK version you use, you must set one of these values for the CLASSPATH:

1.4 ORACLE_HOME/jdbc/lib/ojdbc14.jar


1.3.x, 1.2.x ORACLE_HOME/jdbc/lib/classes12.jar


Ensure that there is only one JDBC class file, such as classes12.jar, classes12_g.jar, or ojdbc14.jar, and one globalization classes file, orai18n.jar, in your CLASSPATH.


If you use the JTA features and the JNDI features, then you must specify jta.jar and jndi.jar in your CLASSPATH.


If you are installing the JDBC OCI driver, then you must also set the following value for the library path environment variable:

  • On Sun Solaris, set LD_LIBRARY_PATH as follows:


    This directory contains the libocijdbc10.so shared object library.


    If you are running a 32-bit Java virtual machine (JVM) against a 64-bit client or database, then you must also add ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
  • On Microsoft Windows, set PATH as follows:


    This directory contains the ocijdbc10.dll dynamic link library.

All of the JDBC OCI demonstration programs can be run in the Instant Client mode by including the JDBC OCI Instant Client data shared library on the library path environment variable.

JDBC Thin Driver

If you are installing the JDBC Thin driver, then you do not have to set any other environment variables.

Ensuring that the Java Code Can Be Compiled and Run

To further ensure that Java is set up properly on your client system, traverse to the samples directory under ORACLE_HOME/jdbc/demo and see if the Java compiler, javac, and the Java interpreter, java, run without error. Run the following commands on the command line, one after the other:



Each of the preceding commands should output a list of options and parameters and then exit. Ideally, verify that you can compile and run a simple test program, such as jdbc/demo/samples/generic/SelectExample.

Determining the Version of the JDBC Driver

You can determine the version of the JDBC driver that you installed, by calling the getDriverVersion method of the OracleDatabaseMetaData class.

Following is a sample code illustrating how to determine the driver version:

import java.sql.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.OracleDataSource;

class JDBCVersion
  public static void main (String args[]) throws SQLException
    OracleDataSource ods = new OracleDataSource();
    Connection conn = ods.getConnection();

    // Create Oracle DatabaseMetaData object
    DatabaseMetaData meta = conn.getMetaData();

    // gets driver info:
    System.out.println("JDBC driver version is " + meta.getDriverVersion());

Testing JDBC and the Database Connection

The samples directory contains sample programs for a particular Oracle JDBC driver. One of the programs, JdbcCheckup.java, is designed to test JDBC and the database connection. The program queries for the user name, password, and the name of the database to which you want to connect. The program connects to the database, queries for the string "Hello World", and prints it to the screen.

Traverse to the samples directory, and compile and run JdbcCheckup.java. If the results of the query print without error, then your Java and JDBC installations are correct.

Although JdbcCheckup.java is a simple program, it demonstrates several important functions by performing the following:

  • Imports the necessary Java classes, including JDBC classes

  • Creates a DataSource instance

  • Connects to the database

  • Runs a simple query

  • Outputs the query results to your screen

The JdbcCheckup.java program, which uses the JDBC OCI driver, is as follows:

 * This sample can be used to check the JDBC installation.
 * Just run it and provide the connect information. It will select
 * "Hello World" from the database.

// You need to import the java.sql and JDBC packages to use JDBC
import java.sql.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.OracleDataSource;

// We import java.io to be able to read from the command line
import java.io.*;

class JdbcCheckup
  public static void main(String args[]) throws SQLException, IOException

    // Prompt the user for connect information
    System.out.println("Please enter information to test connection to 
                          the database");
    String user;
    String password;
    String database;

    user = readEntry("user: ");
    int slash_index = user.indexOf('/');
    if (slash_index != -1)
      password = user.substring(slash_index + 1);
      user = user.substring(0, slash_index);
      password = readEntry("password: ");
    database = readEntry("database(a TNSNAME entry): ");

    System.out.print("Connecting to the database...");
    // Open an OracleDataSource and get a connection
    OracleDataSource ods = new OracleDataSource();
    ods.setURL("jdbc:oracle:oci:@" + database);
    Connection conn = ods.getConnection();

    // Create a statement
    Statement stmt = conn.createStatement();

    // Do the SQL "Hello World" thing
    ResultSet rset = stmt.executeQuery("select 'Hello World' from dual");

    while (rset.next())
    // close the result set, the statement and connect
    System.out.println("Your JDBC installation is correct.");

  // Utility function to read a line from standard input
  static String readEntry(String prompt)
      StringBuffer buffer = new StringBuffer();
      int c = System.in.read();
      while (c != '\n' && c != -1)
        c = System.in.read();
      return buffer.toString().trim();
    catch(IOException e)
      return "";