Oracle8i JDBC Developer's Guide and Reference
Release 3 (8.1.7)

Part Number A83724-01


Solution Area



Go to previous page Go to beginning of chapter Go to next page

JDBC in the Server: the Server-Side Internal Driver

This section covers the following topics:

Any Java program, Enterprise JavaBean (EJB), or Java stored procedure that runs inside the target database must use the server-side internal driver to access the local SQL engine.

This driver is intrinsically tied to the Oracle8i database and to the Java virtual machine (JVM). The driver runs as part of the same process as the database. It also runs within the default session--the same session in which the JVM was invoked.

The server-side internal 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 JVM 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 internal driver supports the same features, APIs, and Oracle extensions as the client-side drivers. This makes application partitioning very straightforward. 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.

For general information about the Oracle Java platform server-side configuration or functionality, see the Oracle8i Java Developer's Guide.

Connecting to the Database with the Server-Side Internal Driver

As described in the preceding section, the server-side internal driver runs within a default session. You are already "connected". There are two methods you can use to access the default connection:

Using defaultConnection() is generally recommended.

The remainder of this section provides more information.


With Oracle8i release 8.1.6 and higher, you are no longer required to register the OracleDriver class for connecting with the server-side internal driver, although there is no harm in doing so. This is true whether you are using getConnection() or defaultConnection() to make the connection.  

Connecting with the OracleDriver Class defaultConnection() Method

The oracle.jdbc.driver.OracleDriver class defaultConnection() method is an Oracle extension and always returns the same connection object. Even if you invoke this method multiple times, assigning the resulting connection object to different variable names, just a single connection object is reused.

You do not need to include a connect string in the defaultConnection() call. 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-side internal driver
         OracleDriver ora = new OracleDriver(); 
         conn = ora.defaultConnection(); 
    } catch (SQLException e) {...}
    return conn; 

Note that there is no conn.close() call in the example. When JDBC code is running inside the target server, the connection is an implicit data channel, not an explicit connection instance as from a client. It should typically not be closed.

If you do call the close() method, be aware of the following:

Connecting with the DriverManager.getConnection() Method

To connect to the internal server connection from code that is running within the target server, you can use the static DriverManager.getConnection() method with either of the following connect strings:




Any user name or password you include in the URL string is ignored in connecting to the server default connection.

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 physical connection (only a single implicit connection is used), 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.

Exception-Handling Extensions for the Server-Side Internal Driver

The server-side internal driver, in addition to having standard exception-handling capabilities such as getMessage(), getErrorCode(), and getSQLState() (as described in "Processing SQL Exceptions"), offers extended features through the oracle.jdbc.driver.OracleSQLException class. This class is a subclass of the standard java.sql.SQLException class and is not available to the client-side JDBC drivers or the server-side Thin driver.

When an error condition occurs in the server, it often results in a series of related errors being placed in an internal error stack. The JDBC server-side internal driver retrieves errors from the stack and places them in a chain of OracleSQLException objects.

You can use the following methods in processing these exceptions:


Following is an example of server-side error processing:

   // should get "ORA-942: table or view does not exist"
   stmt.execute("drop table no_such_table");
catch (OracleSQLException e)
   // prints "ORA-942: table or view does not exist"

   // prints "1"

   Object[] params = e.getParameters();
   // prints "NO_SUCH_TABLE"

Session and Transaction Context for the Server-Side Internal Driver

The server-side driver operates within a default session and default transaction context. The default session is the session in which the JVM 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.

Auto-commit mode is disabled in the server. You must manage transaction COMMIT and ROLLBACK operations explicitly by using the appropriate methods on the connection object:




Testing JDBC on the Server

Almost any JDBC program that can run on a client can also run on the server. All 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 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 must 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-side internal 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 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 to be able to read from the command line

class JdbcCheckup
   public static void main (String args []) throws SQLException, IOException
      // Load the Oracle JDBC driver
      DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());
      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 ( ())
          System.out.println (rset.getString (1));
       System.out.println ("Your JDBC installation is correct.");

Loading an Application into the Server

When loading an application into the server, you can load .class files that you have already compiled on the client, or you can load .java source files and have them compiled automatically in the server.

In either case, use the Oracle loadjava client-side utility to load your files. You can either specify source file names on the command line (note that the command line understands wildcards), or put the files into a JAR file and specify the JAR file name on the command line. The loadjava utility is discussed in detail in the Oracle8i Java Developer's Guide.

The loadjava script, which runs the actual utility, is in the bin subdirectory under your [Oracle Home] directory. This directory should already be in your path once Oracle has been installed.


As of Oracle8i release 8.1.6, the loadjava utility does support compressed files.  

Loading Class Files into the Server

Consider a case where you have three class files in your application: Foo1.class, Foo2.class, and Foo3.class. The following three examples demonstrate: 1) specifying the individual class file names; 2) specifying the class file names using a wildcard; and 3) specifying a JAR file that contains the class files.

Each class is written into its own class schema object in the server.

These three examples use the default OCI8 driver in loading the files:

loadjava -user scott/tiger Foo1.class Foo2.class Foo3.class


loadjava -user scott/tiger Foo*.class


loadjava -user scott/tiger Foo.jar

Or use the following command to load with the Thin driver (specifying the -thin option and an appropriate URL):

loadjava -thin -user scott/tiger@localhost:1521:ORCL Foo.jar

(Whether to use an OCI driver or the Thin driver to load classes depends on your particular environment and which performs better for you.)


Because the server-side embedded JVM uses JDK 1.2.x, it is advisable to compile classes under JDK 1.2.x if they will be loaded into the server. This will catch incompatibilities during compilation, instead of at runtime (for example, JDK 1.1.x artifacts such as leftover use of the oracle.jdbc2 package).  

Loading Source Files into the Server

If you enable the loadjava -resolve option in loading a .java source file, then the server-side compiler will compile your application as it is loaded, resulting in both a source schema object for the original source code, and one or more class schema objects for the compiled output.

If you do not specify -resolve, then the source is loaded into a source schema object without any compilation. In this case, however, the source is implicitly compiled the first time an attempt is made to use a class defined in the source.

For example, run loadjava as follows to load and compile, using the default OCI driver:

loadjava -user scott/tiger -resolve

Or use the following command to load with the Thin driver (specifying the -thin option and an appropriate URL):

loadjava -thin -user scott/tiger@localhost:1521:ORCL -resolve

Either of these will result in appropriate class schema objects being created in addition to the source schema object.


Oracle generally recommends compiling source on the client whenever possible, and loading the .class files instead of the source files into the server.  

Server-Side Character Set Conversion of oracle.sql.CHAR Data

The server-side internal driver performs character set conversions for oracle.sql.CHAR in C. This is a different implementation than for the client-side drivers, which perform character set conversions for oracle.sql.CHAR in Java, and offers better performance. For more information on the oracle.sql.CHAR class, see "Class oracle.sql.CHAR".

Go to previous page
Go to beginning of chapter
Go to next page
Copyright © 1996-2000, Oracle Corporation.

All Rights Reserved.


Solution Area