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:
This section discusses the general JDBC version compatibility issues.
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.
Existing and supported JDBC drivers are certified to work with Oracle Database 10g.
Notes:
In Oracle Database 10g, 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 http://www.oracle.com/technology/tech/java/sqlj_jdbc/htdocs/jdbc_faq.htm
.
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.
Note:
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.
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.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
:
JDK Version | 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
.
Note:
If you use the JTA features and the JNDI features, then you must specifyjta.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:
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 addORACLE_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.
If you are installing the JDBC Thin driver, then you do not have to set any other environment variables.
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
.
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()); } }
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 ""; } } }