Skip Headers

Oracle® Database JDBC Developer's Guide and Reference
10g Release 1 (10.1)

Part Number B10979-02
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page

Go to previous page
Go to next page
View PDF

2 Getting Started

This chapter begins by discussing compatibilities between Oracle JDBC driver versions, database versions, and JDK versions. It then guides you through the basics of testing your installation and configuration, and running a simple application. The following topics are discussed:

2.1 Compatibilities for Oracle JDBC Drivers

This section discusses general JDBC version compatibility issues.

2.1.1 Backward Compatibility

The JDBC drivers are certified to work with the currently supported versions of the database. (You can find a complete up-to-date list of supported databases at, Note 203849.1.) For example, the 10g Release 1 (10.1) JDBC Thin drivers are certified to work with the 9.2.x, 9.0.1.x, and 8.1.7 database releases. The 10g Release 1 (10.1) JDBC thin drivers are not certified to work with older, unsupported database releases, such as 8.0.x and 7.x.

2.1.2 Forward Compatibility

Existing supported JDBC drivers (Oracle8i and Oracle9i JDBC drivers) are certified to work against Oracle Database 10g; known limitations will be documented.


  • Starting with 10g Release 1 (10.1), the Oracle JDBC drivers no longer support JDK 1.1.x or earlier versions.

  • You can find a complete, up-to-date list of supported databases at, Note 203849.

2.2 Verifying a JDBC Client Installation

This section covers the following topics:

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. It assumes that you have already installed the driver of your choice.

If you have installed the JDBC Thin driver, no further installation on the client machine is necessary (the JDBC Thin driver requires a TCP/IP listener to be running on the database machine).

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

2.2.1 Check Installed Directories and Files

This section assumes that you have already installed the Sun Microsystems Java Developer's Kit (JDK) on your system (although other forms of Java are also supported). Oracle offers JDBC drivers compatible with the JDK1.4, 1.3.x, and 1.2.x versions.

Installing the Oracle Java products creates, among other things, an ORACLE_HOME/jdbc directory and an ORACLE_HOME /jlib directory.

The ORACLE_HOME/jdbc directory contains these subdirectories and files:

  • demo: Contains a compressed file, either (Windows) or (UNIX) demo.tar in the demo directory. When you unpack the appropriate file, it creates a samples subdirectory and a Samples-Readme.txt file. The samples subdirectory contains sample programs, including examples of how to use SQL92 and Oracle SQL syntax, PL/SQL blocks, streams, user-defined types, additional Oracle type extensions, and Oracle performance extensions.

  • doc: Contains a file which is the Oracle JDBC API documentation.

  • lib: The lib directory contains these required Java classes:

    • orai18n.jar: Contains classes for globalization and supporting multibyte character sets

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

    • ocrs12.jar: Contains additional support for Rowset.

  • Readme.txt: Contains late-breaking and release-specific information about the drivers that might not be in this manual.

The ORACLE_HOME /jlib directory contains the following files:

  • jta.jar and jndi.jar: Contain classes for the Java Transaction API and the Java Naming and Directory Interface for JDK 1.2.x, 1.3.x, and 1.4. These are only required if you will be 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, but we recommend using the versions supplied by Oracle, which have been tested with the Oracle drivers.)

Check that all these directories have been created and populated.

2.2.2 Check 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 Microsystems 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 for full globalization support ORACLE_HOME/jdbc/lib/orai18n.jar
1.3.x, 1.2.x ORACLE_HOME/jdbc/lib/classes12.jar

ORACLE_HOME/jdbc/lib/orai18n.jar for full globalization support

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 JTA features or JNDI features, then you must also put jta.jar and jndi.jar in your CLASSPATH. JDBC OCI Driver

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

  • On Solaris, set LD_LIBRARY_PATH as follows:


    This directory contains the shared object library.


    If you are running a 32-bit JVM against a 64-bit client or database, you must also add ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
  • On 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 Instant Client mode by including the JDBC OCI Instant Client Data Shared Library on the OS Library Path Variable. See Chapter 20, "OCI Instant Client" for details. JDBC Thin Driver

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

2.2.3 Make Sure You Can Compile and Run Java

To further ensure that Java is set up properly on your client system, go to the samples directory (ORACLE_HOME/jdbc/demo/samples), then see if javac (the Java compiler) and java (the Java interpreter) will run without error. Enter:


then enter:


Each should give you 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.

2.2.4 Determine the Version of the JDBC Driver

If at any time you must determine the version of the JDBC driver that you installed, you can invoke the getDriverVersion() method of the OracleDatabaseMetaData class.

Here is sample code showing how to do it:

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());

2.2.5 Testing JDBC and the Database Connection: JdbcCheckup

The samples directory contains sample programs for a particular Oracle JDBC driver. One of the programs,, is designed to test JDBC and the database connection. The program queries you for your user name, password, and the name of a 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.

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

Although is a simple program, it demonstrates several important functions by executing the following:

  • imports the necessary Java classes, including JDBC classes

  • creates a DataSource instance

  • connects to the database

  • executes a simple query

  • outputs the query results to your screen

"First Steps in JDBC" describes these functions in greater detail. A listing of for the JDBC OCI driver appears below.

 * 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 to be able to read from the command line

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 (
      // 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 =;
         while (c != '\n' && c != -1)
            c =;
         return buffer.toString().trim();
      catch(IOException e)
         return "";