3 Basic Features

3.1.1 Importing Packages

Regardless of which Oracle JDBC driver you use, include the import statements shown in Table 3-1 at the beginning of your program.

The Oracle packages listed as optional provide access to the extended functionality provided by the Oracle JDBC drivers, but are not required for the example presented in this section.

3.1.2 Opening a Connection to a Database

First, you must create an OracleDataSource instance. Then, open a connection to the database using OracleDataSource.getConnection. The properties of the retrieved connection are derived from the OracleDataSource instance. If you set the URL connection property, then all other properties, including TNSEntryName, DatabaseName, ServiceName, ServerName, PortNumber, Network Protocol, and driver type are ignored.

Specifying a Database URL, User Name, and Password

The following code sets the URL, user name, and password for a data source:

OracleDataSource ods = new OracleDataSource();
ods.setURL(url);
ods.setUser(user);
ods.setPassword(password);

The following example connects user scott with password tiger to a database with service orcl through port 1521 of the host myhost, using the JDBC Thin driver.

OracleDataSource ods = new OracleDataSource();
String url = "jdbc:oracle:thin:@//myhost:1521/orcl",
ods.setURL(url);
ods.setUser("scott");
ods.setPassword("tiger");
Connection conn = ods.getConnection();

Specifying a Database URL That Includes User Name and Password

The following example connects user scott with password tiger to a database host whose TNS entry is myTNSEntry, using the JDBC Oracle Call Interface (OCI) driver. In this case, the URL includes the user name and password and is the only input parameter.

String url = "jdbc:oracle:oci:scott/tiger@myTNSEntry");
ods.setURL(url);
Connection conn = ods.getConnection();

If you want to connect using the Thin driver, then you must specify the port number. For example, if you want to connect to the database on myhost that has a TCP/IP listener on port 1521 and the service identifier is orcl, then provide the following code:

String URL = "jdbc:oracle:thin:scott/tiger@//myhost:1521/orcl");
ods.setURL(URL);
Connection conn = ods.getConnection();

3.1.3 Creating a Statement Object

Once you connect to the database and, in the process, create a Connection object, the next step is to create a Statement object. The createStatement method of the JDBC Connection object returns an object of the JDBC Statement type. To continue the example from the previous section, where the Connection object conn was created, here is an example of how to create the Statement object:

Statement stmt = conn.createStatement();

3.1.4 Running a Query and Retrieving a ResultSet Object

To query the database, use the executeQuery method of the Statement object. This method takes a SQL statement as input and returns a JDBC ResultSet object.

To continue the example, once you create the Statement object stmt, the next step is to run a query that returns a ResultSet object with the contents of the ENAME column of a table of employees named EMP:

ResultSet rset = stmt.executeQuery ("SELECT ename FROM emp");

3.1.5 Processing the ResultSet Object

Once you run your query, use the next() method of the ResultSet object to iterate through the results. This method steps through the result set row by row, detecting the end of the result set when it is reached.

To pull data out of the result set as you iterate through it, use the appropriate getXXX methods of the ResultSet object, where XXX corresponds to a Java data type.

For example, the following code will iterate through the ResultSet object, rset, from the previous section and will retrieve and print each employee name:

while (rset.next())
   System.out.println (rset.getString(1));

The next() method returns false when it reaches the end of the result set. The employee names are materialized as Java String values.

3.1.6 Closing the ResultSet and Statement Objects

You must explicitly close the ResultSet and Statement objects after you finish using them. This applies to all ResultSet and Statement objects you create when using the Oracle JDBC drivers. The drivers do not have finalizer methods. The cleanup routines are performed by the close method of the ResultSet and Statement classes. If you do not explicitly close the ResultSet and Statement objects, serious memory leaks could occur. You could also run out of cursors in the database. Closing both the result set and the statement releases the corresponding cursor in the database. If you close only the result set, then the cursor is not released.

For example, if your ResultSet object is rset and your Statement object is stmt, then close the result set and statement with the following lines of code:

rset.close();
stmt.close();

When you close a Statement object that a given Connection object creates, the connection itself remains open.

3.1.7 Making Changes to the Database

To write changes to the database, such as for INSERT or UPDATE operations, you create a PreparedStatement object. This enables you to run a statement with varying sets of input parameters. The prepareStatement method of the JDBC Connection object lets you define a statement that takes variable bind parameters and returns a JDBC PreparedStatement object with your statement definition.

Use the setXXX methods on the PreparedStatement object to bind data to the prepared statement to be sent to the database.

The following example shows how to use a prepared statement to run INSERT operations that add two rows to the EMP table.

// Prepare to insert new names in the EMP table
    PreparedStatement pstmt = 
      conn.prepareStatement ("insert into EMP (EMPNO, ENAME) values (?, ?)");

    // Add LESLIE as employee number 1500
    pstmt.setInt (1, 1500);          // The first ? is for EMPNO
    pstmt.setString (2, "LESLIE");   // The second ? is for ENAME
    // Do the insertion
    pstmt.execute ();

    // Add MARSHA as employee number 507
    pstmt.setInt (1, 507);           // The first ? is for EMPNO
    pstmt.setString (2, "MARSHA");   // The second ? is for ENAME
    // Do the insertion
    pstmt.execute ();

    // Close the statement
    pstmt.close();

3.1.8 Committing Changes

By default, data manipulation language (DML) operations are committed automatically as soon as they are run. This is known as the auto-commit mode. However, you can disable auto-commit mode with the following method call on the Connection object:

conn.setAutoCommit(false);

If you disable the auto-commit mode, then you must manually commit or roll back changes with the appropriate method call on the Connection object:

conn.commit();

or:

conn.rollback();

A COMMIT or ROLLBACK operation affects all DML statements run since the last COMMIT or ROLLBACK.

3.1.9 Closing the Connection

You must close the connection to the database after you have performed all the required operation and no longer require the connection. You can close the connection by using the close method of the Connection object, as follows:

conn.close();

3.3.1 PL/SQL Stored Procedures

Oracle JDBC drivers support the processing of PL/SQL stored procedures and anonymous blocks. They support Oracle PL/SQL block syntax and most of SQL92 escape syntax. The following PL/SQL calls would work with any Oracle JDBC driver:

// SQL92 syntax
CallableStatement cs1 = conn.prepareCall
                       ( "{call proc (?,?)}" ) ; // stored proc
CallableStatement cs2 = conn.prepareCall
                       ( "{? = call func (?,?)}" ) ; // stored func
// Oracle PL/SQL block syntax
CallableStatement cs3 = conn.prepareCall
                       ( "begin proc (?,?); end;" ) ; // stored proc
CallableStatement cs4 = conn.prepareCall
                       ( "begin ? := func(?,?); end;" ) ; // stored func

As an example of using the Oracle syntax, here is a PL/SQL code snippet that creates a stored function. The PL/SQL function gets a character sequence and concatenates a suffix to it:

create or replace function foo (val1 char)
return char as
begin
   return val1 || 'suffix';
end;

The function invocation in your JDBC program should look like:

OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:oracle:oci:@<hoststring>");
ods.setUser("scott");
ods.setPassword("tiger");
Connection conn = ods.getConnection();

CallableStatement cs = conn.prepareCall ("begin ? := foo(?); end;");
cs.registerOutParameter(1,Types.CHAR);
cs.setString(2, "aa");
cs.executeUpdate();
String result = cs.getString(1);

3.3.2 Java Stored Procedures

You can use JDBC to call Java stored procedures through the SQL and PL/SQL engines. The syntax for calling Java stored procedures is the same as the syntax for calling PL/SQL stored procedures, presuming they have been properly published. That is, you have written call specifications to publish them to the Oracle data dictionary. Applications can call Java stored procedures using the Native Java Interface for direct invocation of static Java methods.