2
Getting Started

This chapter guides you through the basics of testing your installation and configuration and running a simple application. The following topics are discussed:

• Oracle JDBC Drivers

• Requirements and Compatibilities for Oracle JDBC Drivers

• Verifying a JDBC Client Installation

Oracle JDBC Drivers

This section has the following subsections:

• Introducing the Oracle JDBC Drivers

• Choosing the Appropriate Driver

Oracle offers two different drivers for client-side use (one of which can also be used in a middle tier) and one for server-side use. Most of the information in the following chapters focuses on the client-side drivers. The server-side driver is described in detail in "JDBC on the Server: the Server Driver".

Introducing the Oracle JDBC Drivers

This section describes the Oracle JDBC drivers and provides scenarios for how you would use them. Oracle produces JDBC drivers for use in clients and in the server. The client-side drivers can be used in Java applications or Java applets that run either on the client or in the middle tier of a three-tier configuration. The server-side driver provides server-side JDBC support which allows the Java VM to communicate with the SQL engine.

Common Features of Oracle JDBC Drivers

The server-side and client-side Oracle JDBC drivers provide the same functionality. They all support the following standards and features:

• JDBC 1.22

• most of the JDBC 2.0 features

• the same syntax and APIs

• the same Oracle extensions

• full support for multi-threaded applications

The only differences between the drivers are in how they connect to the database and how they transfer data.

JDBC Thin Driver

The Oracle JDBC Thin driver is a 100% Pure Java implementation that complies with the JDBC 1.22 standard. The JDBC Thin driver uses Java Sockets to connect directly to the Oracle Server and is typically used for Java applets in either a two-tier or three-tier configuration, though it can also be used for Java applications. The JDBC Thin driver provides its own implementation of a TCP/IP version of Oracle's Net8. Because it is written entirely in Java, this driver is platform-independent. When the JDBC Thin driver is used with an applet, the client browser must have the capability to support Java sockets.

The JDBC Thin driver does not require Oracle software on the client side; it can be downloaded into a browser simultaneously with the Java applet being run. From the client (usually a browser), you select a URL from an HTML page that contains a Java applet tag. The web server downloads the Java applet and the JDBC Thin driver to the client. The JDBC Thin driver then establishes a direct connection to the database server using Java Sockets.

The JDBC Thin driver connects to any Oracle database of version 7.2.3 and higher. The JDBC Thin driver allows a direct connection to the database by emulating Net8 and TTC (the wire protocol used by OCI) on top of Java sockets. The driver supports only TCP/IP protocol and requires a TNS listener to be listening on TCP/IP sockets from the database server.

For a discussion of relevant firewall, browser, and security issues, see "Working with Applets".

JDBC OCI Driver

The JDBC OCI driver provides an implementation of the JDBC interfaces using the Oracle Call Interface (OCI). The OCI driver makes use of the OCI cache, C entry points to OCI, and the OCI library. The use of native methods to call C entry points makes the driver platform-specific. The JDBC OCI driver also requires an Oracle client installation including Net8.

The JDBC OCI driver is compatible with all Oracle versions because it interfaces to Oracle databases through OCI. The driver also supports all installed Net8 adapters, including IPC, named pipes, TCP/IP, and IPX/SPX.

Because the JDBC OCI driver contains C code, it is not suitable for use in applets. However, it is an excellent choice for Java applications or Java middle tiers such as the Oracle Web Application Server. You can use the JDBC OCI driver in these configurations:

• with a Java application running on a client machine in a two-tier configuration

• with a Java application running on a middle tier in a three-tier configuration

• with a Java servlet running on a middle tier in a three-tier configuration

JDBC Server Driver

Oracle's JDBC Server driver is for server-side use only. The Server driver provides server-side JDBC support for any Java program used in the database, Java stored procedure, Enterprise Java Beans (EJB) and for communication with SQL and PL/SQL programs. The Server driver is fully consistent with, and supports the same features and extensions as the client-side drivers. For more information on the server-side driver, see "JDBC on the Server: the Server Driver".

Choosing the Appropriate Driver

Four main considerations that you must bear in mind when choosing which JDBC driver to use for your application or applet are:

• If you are writing an applet, you must use the JDBC Thin driver. JDBC OCI-based driver classes cannot be downloaded to a Web browser, because they call native (C language) methods.

  Notes: JDBC Thin drivers use a subset of the Net8 protocol, written entirely in Java, and connect using the TCP/IP protocol. There are other restrictions on applets besides your choice of JDBC driver. For information on these restrictions, see "Browser Security and JDK Version Considerations".

• If you desire maximum portability, then choose the JDBC Thin driver. You can connect to an Oracle8 data server from either an application or an applet using the JDBC Thin driver.

• If you are writing an application and need maximum performance, then choose the JDBC OCI driver.

• If you are running in the Oracle database server using the Oracle 8.1.5 Java VM, then choose the JDBC Server driver.

Requirements and Compatibilities for Oracle JDBC Drivers

Table 2-1 lists the compatibilities between versions of the Oracle database and the JDBC drivers.

Table 2-1 JDBC Driver-Database Compatibility

Database Version	Driver Version	Remarks
8.1.5	JDBC Thin Driver JDBC OCI Driver JDBC Server Driver	Both client- and server-side drivers offer full object support when run against an 8.1.5 database.
8.1.4	JDBC Thin Driver JDBC OCI Driver JDBC Server Driver	Both client- and server-side drivers offer full object support when run against an 8.1.4 database.
8.0.x	JDBC Thin Driver JDBC OCI Driver Note: the JDBC Server driver is not available for version 8.0.x	The JDBC OCI and Thin drivers do not support objects when run against an 8.0.x database. This is because JDBC depends on PL/SQL functions that did not exist in 8.0.x.
7.x	JDBC Thin Driver JDBC OCI Driver Note: the JDBC Server driver is not available for version 7.x	The JDBC OCI and Thin drivers do not support objects when run against a 7.x database. This is because JDBC depends on PL/SQL functions that did not exist in 7.x The JDBC OCI driver does not support LOBs.

Verifying a JDBC Client Installation

This section has the following subsections:

• Check Installed Directories and Files

• Check the Environment Variables

• Make Sure You Can Compile and Run Java

• Testing JDBC and the Database Connection: JdbcCheckup

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 Net8 and the OCI libraries.

Check Installed Directories and Files

This section assumes that you have already installed the Sun Microsystems Java Developer's Kit (JDK) on your system. The Oracle JDBC drivers are compatible with JDK versions 1.0.2 and 1.1.x. The Oracle JDBC drivers for version 8.1.5 do not support the JDK 1.2.

Directories for JDBC

Installing the Oracle Java server products creates, among other things, a jdbc directory under [ORACLE_HOME], containing these subdirectories and files:

• demo/samples: The samples directory contains sample programs, including examples of how to use SQL92 and Oracle SQL syntax, PL/SQL blocks, streams, and the Oracle JDBC type and performance extensions. The demo directory contains only the samples subdirectory.

• doc: The doc directory contains documentation about the JDBC drivers.

• lib: The lib directory contains.zip files with required Java classes: classes111.zip for JDK 1.1.1 and classes102.zip for JDK 1.0.2.

• readme.txt: The readme.txt file contains up to the minute facts about the drivers that might not be in the manual.

Check that all these directories have been created and populated.

Check the Environment Variables

This section describes the environment variables that must be set for the JDBC OCI driver and the JDBC Thin driver.

Solaris and Windows NT Platforms

You must set the CLASSPATH for your installed JDBC OCI or Thin driver. Depending on whether you are using the JDK version 1.0.2 or version 1.1.1, you must set one of these values for the CLASSPATH:

• [Oracle Home]/jdbc/lib/classes102.zip

OR

• [Oracle Home]/jdbc/lib/classes111.zip

JDBC OCI Drivers:

If you are installing the JDBC OCI driver, you must also set the following value for the library path environment variable (this will be LD_LIBRARY_PATH on Solaris or PATH on Windows NT).

• [Oracle Home]/lib

On Solaris, this directory contains the shared object library libocijdbc8.so.

JDBC Thin Drivers:

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

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 (for example, C:\oracle\ora81\jdbc\demo\samples if you are using the JDBC driver on a Windows NT machine), then see if javac (the Java compiler) and java (the Java interpreter) will run without error. Enter:

javac

then enter:

java

Each should give you a list of options and parameters and then exit.

Determining the Version of the JDBC Driver

If at any time you need to 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.driver.*;

class JDBCVersion
{
public static void main (String args [])
throws SQLException
{
// Load the Oracle JDBC driver
DriverManager.registerDriver
(new oracle.jdbc.driver.OracleDriver());
Connection conn = DriverManager.getConnection
("jdbc:oracle:thin:@host:port:sid","scott","tiger");

// 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: JdbcCheckup

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 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 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 illustrates several important functions:

• imports the necessary Java classes, including JDBC classes

• registers the JDBC driver

• 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 JdbcCheckup.java 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 package to use JDBC
import java.sql.*;

// 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
{
     
// Load the Oracle JDBC driver
DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());

                 
     
// 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...");
Connection conn =
   DriverManager.getConnection ("jdbc:oracle:oci8:@" + database,  
                               user, password);

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 "";

     }
      }
     
}

---