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

• Use the OracleDataSource.getConnection method, with any of the following forms as the URL string:

  • jdbc:oracle:kprb

  • jdbc:default:connection

  • jdbc:oracle:kprb:

  • jdbc:default:connection:

• Use the Oracle-specific defaultConnection method of the OracleDriver class.

Using defaultConnection is generally recommended.

Connecting with the OracleDriver Class defaultConnection Method

The defaultConnection method of the oracle.jdbc.OracleDriver class is an Oracle extension and always returns the same connection object. Even if you call this method multiple times, assigning the resulting connection object to different variable names, then only a single connection object is reused.

You need not include a connection string in the defaultConnection call. For example:

import java.sql.*; 
import oracle.jdbc.*; 
  
class JDBCConnection 
{ 
  public static Connection connect() throws SQLException 
  { 
    Connection conn = null; 
    try {  
      // connect with the server-side internal driver

         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 not be closed.

OracleDriver has a static variable to store a default connection instance. The method OracleDriver.defaultConnection returns this default connection instance if the connection exists and is not closed. Otherwise, it creates a new, open instance and stores it in the static variable and returns it to the caller.

Typically, you should use the OracleDriver.defaultConnection method. This method is faster and uses less resources. Java stored procedures should be carefully written. For example, to close statements before the end of each call.

Typically, you should not close the default connection instance because it is a single instance that can be stored in multiple places, and if you close the instance, each would become unusable. If it is closed, a later call to the OracleDriver.defaultConnection method gets a new, open instance.

Connecting with the OracleDataSource.getConnection Method

To connect to the internal server connection from code that is running within the target server, you can use the OracleDataSource.getConnection method with either of the following URLs:

OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:oracle:kprb");
Connection conn = ods.getConnection();

or:

OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:default:connection");
Connection conn = ods.getConnection();

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

The OracleDataSource.getConnection method returns a new Java Connection object every time you call it. The fact that OracleDataSource.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.

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

conn.commit();

or:

conn.rollback();

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.

Consider the following code fragment which obtains a connection to a database:

ods.setUrl(
"jdbc:oracle:oci:@(DESCRIPTION=
  (ADDRESS=(PROTOCOL=TCP)(HOST=cluster_alias)
    (PORT=5221))
    (CONNECT_DATA=(SERVICE_NAME=orcl)))");
ods.setUser("HR");
ods.setPassword("hr");
Connection conn = ods.getConnection();  

We can modify this code fragment for use in the server-side internal driver. In the server-side internal driver, no user, password, or database information is necessary. For the connection statement, you use:

ods.setUrl(
"jdbc:oracle:kprb:@");
Connection conn = ods.getConnection();  

However, the most convenient way to get a connection is to call the OracleDriver.defaultConnection method, as follows:

Connection conn = OracleDriver.defaultConnection();  

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 automatically compiled on the server.