Advanced Topics

JDBC on the Server: the Server Driver

This section has the following subsections:

Any Java program, Enterprise JavaBean (EJB), or Java stored procedure that runs in the database, can use the Server driver to access the SQL engine.

The Server driver is intrinsically tied to the 8.1 database and to the Java VM. The driver runs as part of the same process as the database. It also runs within the default session: this is the same session in which the Java VM was invoked.

The Server driver is optimized to run within the database server and provide direct access to SQL data and PL/SQL subprograms on the local database. The entire Java VM operates in the same address space as the database and the SQL engine. Access to the SQL engine is a function call; there is no network. This enhances the performance of your JDBC programs and is much faster than executing a remote Net8 call to access the SQL engine.

The server-side driver supports the same features, APIs, and Oracle extensions as the client-side drivers. This makes application partitioning very straight forward. For example, if you have a Java application that is data-intensive, you can easily move it into the database server for better performance, without having to modify the application-specific calls.

Connecting to the Database with the Server Driver

As described in the preceding section, the Server driver runs within a default session. You are already "connected". You can use either the Oracle-specific API defaultConnection() method or the standard Java DriverManager.getConnection() method to access the default connection.

Connecting with defaultConnection()

The defaultConnection() method of the oracle.jdbc.driver.OracleServerDriver class is an Oracle extension and always returns the same connection object. You do not need to include a connect string with the statement. For example:

import java.sql.*; 
import oracle.jdbc.driver.*; 
  
class JDBCConnection { 
  public static Connection connect() throws SQLException { 
    Connection conn = null; 
    try {  
      // connect with the Server driver
         OracleDriver ora = new OracleDriver(); 
         conn = ora.defaultConnection(); 
      } 
 
    } catch (SQLException e) 
    return conn; 
  } 
}

Note that there is no conn.close statement. You cannot close a default connection made by the Server driver. Calling close() on the connection is just a no-op.

Connecting with DriverManager.getConnection()

The DriverManager.getConnection() method returns a new Java Connection object every time you call it. Note that although the method is not creating a new connection, it is returning a new object.

The fact that DriverManager.getConnection() returns a new connection object every time you call it is significant if you are working with object maps (or "type maps"). A type map is associated with a specific Connection object and with any state that is part of the object. If you want to use multiple type maps as part of your program, then you can call getConnection() to create a new Connection object for each type map.

If you connect to the database with the DriverManager.getConnection() method, then use the connect string jdbc:oracle:kprb:. For example:

DriverManager.getConnection("jdbc:oracle:kprb:");

Note that you could include a user name and password in the string, but because you are connecting from the server, they would be ignored.

Session and Transaction Context for the Server Driver

The server-side driver operates within a default session and default transaction context. The default session is the session in which the Java VM was invoked. In effect, you are already connected to the database on the server. This is different from the client side where there is no default session: you must explicitly connect to the database.

If you run Java application code in the server, then you can manage the transaction (COMMITs and ROLLBACKs) explicitly.

Testing JDBC on the Server

Almost any JDBC program that can run on a client can also run on the server. All of the programs in the samples directory can be run on the server with only minor modifications. Usually, these modifications concern only the connection statement.

For example, consider the test program JdbcCheckup.java described in "Testing JDBC and the Database Connection: JdbcCheckup". If you want to run this program on the server and connect with the DriverManager.getConnection() method, then open the file in your favorite text editor and change the driver name in the connection string from "oci8" to "kprb". For example:

Connection conn =
     
DriverManager.getConnection ("jdbc:oracle:kprb:@" + 
                              database, user, password);

The advantage of using this method is that you need to change only a short string in your original program. The disadvantage is that you still must provide the user, password, and database information even though the driver will discard it. In addition, if you issue the getConnection() method again, the driver will create another new (and unnecessary) connection object.

However, if you connect with defaultConnection(), the preferred method of connecting to the database from the Server driver, you do not have to enter any user, password, or database information. You can delete these statements from your program.

For the connection statement, use:

Connection conn =  new oracle.jdbc.driver.OracleDriver ().defaultConnection ();

The following example is a rewrite of the JdbcCheckup.java program which uses the defaultConnection() connection statement. The connection statement is printed in bold. The unnecessary user, password, and database information statements, along with the utility function to read from standard input, have been deleted.

/*
 * 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
{
     
Connection conn =  new oracle.jdbc.driver.OracleDriver 
().defaultConnection ();  

// 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));
System.out.println ("Your JDBC installation is correct.");
     
}

           }

Server Driver Support for NLS

For a description of how the Server driver handles database character set conversions for Java programs, see "Server Driver and NLS".

Character Set Conversion of oracle.sql.CHAR Data

The Server driver performs character set conversions for oracle.sql.CHAR in C; this is a different implementation than for the client-side drivers. The client-side drivers perform character set conversions for oracle.sql.CHAR in Java. For more information on the oracle.sql.CHAR class, see "Class oracle.sql.CHAR".