2 Getting Started

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.

  Note:

  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:

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.

JDBC OCI Driver

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:

  ORACLE_HOME/lib
  

  This directory contains the libocijdbc10.so shared object library.

  Note:

  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:

  ORACLE_HOME\bin
  

  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:

javac

java

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();
    ods.setURL("jdbc:oracle:thin:scott/tiger@host:port:service");
    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);
    }
    else
      password = readEntry("password: ");
    database = readEntry("database(a TNSNAME entry): ");

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

    // 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())
      System.out.println(rset.getString(1));
    // close the result set, the statement and connect
    rset.close();
    stmt.close();
    conn.close();
    System.out.println("Your JDBC installation is correct.");
  }

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