Corporate Info  |  News  |  Solutions  |  Products  |  Partners  |  Services  |  Events  |  Download  |  How To Buy
	e-docs   |   Site Map   |   Search   |   Contact   |   Glossary   |   WebLogic Server Documentation

Introduction

WebLogic JDBC/RMI driver

Overview

Setting up WebLogic Server to use the WebLogic JDBC/RMI driver

Setting up the client to use the WebLogic JDBC/RMI driver

Obtaining a client connection with a JNDI lookup

Obtaining a client connection with only the JDBC/RMI driver

Using the connection

Additional information

WebLogic Clustered JDBC

Overview

Setting up WebLogic Clustered JDBC

Additional information

The WebLogic JDBC/RMI driver is a multi-tier, type-3, Java Data Base Connectivity (JDBC) driver that runs in WebLogic Server and can be used with any two-tier JDBC driver to provide database access. Additionally, when configured in a cluster of WebLogic Servers, the WebLogic JDBC/RMI driver can be used for clustered JDBC, allowing JDBC clients the benefits of load balancing and fail-over provided by WebLogic Clusters. This document describes how to set up your WebLogic Server(s) and JDBC clients to use the WebLogic JDBC/RMI driver and WebLogic Clustered JDBC.

The BEA WebLogic JDBC/RMI driver operates within WebLogic Server and provides connectivity from JDBC clients to a Database Management System (DBMS). This DBMS connection is made by means of the WebLogic JDBC/RMI driver, a DataSource object, and a connection pool operating in WebLogic Server.

The DataSource object defines the connection to the DBMS. The connection parameters are specified in the weblogic.properties by pointing to a connection pool that is also defined in the weblogic.properties file. This connection pool is in turn configured for two-tier JDBC access to a DBMS.

JDBC/RMI clients make their connection to the DBMS by looking up this DataSource object. This look up is accomplished by using a Java Naming and Directory Service (JNDI) lookup, or by directly calling the WebLogic JDBC/RMI driver which performs the JNDI lookup on behalf of the client.

BEA implements the DataSource interface as a clusterable RMI object. This implementation allows JDBC clients access to the fail-over and load balancing features of WebLogic Clusters. For more information on Clustered JDBC, see WebLogic Clustered JDBC.

The WebLogic JDBC/RMI driver is similar in functionality to the WebLogic JDBC/T3 driver or the WebLogic pool driver (both included with WebLogic Server), but uses the Java standard Remote Method Invocation (RMI) to connect to WebLogic Server, rather than the proprietary T3 protocol. Since the details of the RMI implementation are taken care of automatically by the driver, a knowledge of RMI is not required to use the WebLogic JDBC/RMI driver. Note that BLOB/CLOB's are not serializable and therefore not supported with the JDBC/RMI Driver used with WebLogic 5.1.

To set up WebLogic Server to use the WebLogic JDBC/RMI driver:

1. Define a connection pool to connect to your DBMS. To use a connection pool you must have a two-tier JDBC driver with which to connect to the DBMS. Connection pools are defined in the weblogic.properties file by defining a name for the pool and various parameters associated with the connection to the DBMS.

   For more information on setting up a connection pool to connect to your own DBMS, see Using connection pools in the WebLogic Server documentation.

   Here is an example from the weblogic.properties file of a connection pool called "eng" that is set up to access an Oracle DBMS:

   weblogic.jdbc.connectionPool.eng=\
       url=jdbc:weblogic:oracle,\
       driver=weblogic.jdbc.oci.Driver,\
       loginDelaySecs=1,\
       initialCapacity=4,\
       maxCapacity=10,\
       capacityIncrement=2,\
       allowShrinking=true,\
       shrinkPeriodMins=15,\
       refreshTestMinutes=10,\
       testTable=dual,\
       props=user=SCOTT;password=tiger;server=DEMO

   weblogic.allow.reserve.weblogic.jdbc.connectionPool.eng=\
       guest,joe,jill

   weblogic.allow.reset.weblogic.jdbc.connectionPool.eng=\
       joe,jill

   weblogic.allow.shrink.weblogic.jdbc.connectionPool.eng=\
       joe,jill

2. Define a DataSource object in the weblogic.properties file. The DataSource object may be defined to have Java Transaction Services (JTS) enabled in which case it will behave like a JTS connection, with transactional support, or the DataSource may be defined without JTS support.

   To define a JTS-enabled DataSource named "myJtsDataSource" for the connection pool "mypool" you would make the following entry in the weblogic.properties file:

   weblogic.jdbc.TXDataSource.myJtsDataSource=mypool

   To define a DataSource named "myNonJtsDataSource" for the connection pool "mypool" that is not JTS-enabled, you would make the following entry in the weblogic.properties file:

   weblogic.jdbc.DataSource.myNonJtsDataSource=mypool

   Note that you may define multiple DataSources to use a single connection pool. A practical application of this would be to define both a JTS-enabled and non-JTS-enabled DataSource that share the same database.

3. Re-start your WebLogic Server, after making the above edits to your weblogic.properties file.

To make a client connection, first import the following packages:

javax.sql.DataSource 

java.sql.*

java.util.*

javax.naming.*

A WebLogic JDBC/RMI client obtains its connection to a DBMS from the DataSource object that was defined in the weblogic.properties file. There are two ways the client can obtain a DataSource object:

• Using a JNDI lookup. This is the preferred and most direct procedure.

• Passing the DataSource name to the JDBC/RMI driver with the Driver.connect()method. In this case, the WebLogic JDBC/RMI driver performs the JNDI look up on behalf of the client.

Obtaining a client connection with a JNDI lookup

To access the WebLogic JDBC/RMI driver using JNDI, obtain a Context from the JNDI tree by looking up the name of your DataSource object. For example, to access a DataSource called "myDataSource" that is defined in the weblogic.properties file of a WebLogic Server:

Context ctx = null;
  Hashtable ht = new Hashtable();
  ht.put(Context.INITIAL_CONTEXT_FACTORY,
         "weblogic.jndi.WLInitialContextFactory");
  ht.put(Context.PROVIDER_URL,
         "t3://hostname:port");

  try {
    ctx = new InitialContext(ht);
    javax.sql.DataSource ds 
      = (javax.sql.DataSource) ctx.lookup ("myDataSource");
   java.sql.Connection conn = ds.getConnection();

   // You can now use the conn object to create 
   //  a Statement object to execute
   //  SQL statements and process result sets:

Statement stmt = conn.createStatement();
stmt.execute("select * from someTable");
ResultSet rs = stmt.getResultSet();  

   // Do not forget to close the statement and connection objects
   //  when you are finished:

   stmt.close();
   conn.close();  
 }
  catch (NamingException e) {
    // a failure occurred
  }
  finally {
    try {ctx.close();}
    catch (Exception e) {
      // a failure occurred
    }
  }

(Where hostname is the name of the machine running your WebLogic Server and port is the port number where that machine is listening for connection requests.)

In this example a Hashtable object is used to pass the parameters required for the JNDI lookup. There are other ways to perform a JNDI look up. These are discussed under Using WebLogic JNDI from a client.

Notice that the JNDI lookup is wrapped in a try/catch block in order to catch a failed look up and also that the context is closed in a finally block.

You can also access the WebLogic JDBC/RMI driver using the Driver.connect() method, in which case the JDBC/RMI driver performs the JNDI lookup. To access the WebLogic JDBC/RMI driver, pass the parameters defining the URL of your WebLogic Server and the name of the DataSource object to the Driver.connect() method. For example, to access a DataSource called "myDataSource" that is defined in the weblogic.properties file of a WebLogic Server:

java.sql.Driver myDriver = (java.sql.Driver)
  Class.forName("weblogic.jdbc.rmi.Driver").newInstance();

String url =  "jdbc:weblogic:rmi";

java.util.Properties props = new java.util.Properties();
props.put("weblogic.server.url", "t3://hostname:port");
props.put("weblogic.jdbc.datasource", "myDataSource");

java.sql.Connection conn = myDriver.connect(url, props);

(Where hostname is the name of the machine running your WebLogic Server and port is the port number where that machine is listening for connection requests.)

You can also define the following properties which will be used to set the JNDI user information:

• weblogic.user - specifies a user name

• weblogic.credential - specifies the password for the weblogic.user.

Using the connection

Once you have obtained a connection using one of the two procedures described above, you can use it to make standard JDBC calls such as execute and update, and to access result sets. For example:

Statement stmt = conn.createStatement();
stmt.execute("select * from sometable");
ResultSet rs = stmt.getResultSet(); 

For more information on using BEA WebLogic JDBC drivers see:

• WebLogic JDBC Options

For more information on using BEA WebLogic Server:

• Using WebLogic RMI

• Using WebLogic JNDI

WebLogic Clustered JDBC

Clustered JDBC allows JDBC clients to access the fail-over and load balancing features of clustered WebLogic Servers. To use Clustered JDBC, you use the WebLogic JDBC/RMI driver to connect to the DBMS, as described earlier in this document. The only change you need to make to use Clustered JDBC is to define identical DataSource objects in each of the per-server weblogic.properties files for each WebLogic Server in the cluster.

When a client looks up a DataSource object whose name is replicated in the per-server weblogic.properties files of a WebLogic cluster, the load balancing and fail-over logic is used to determine which WebLogic Server in the cluster will handle the connection. Once a connection is obtained, the connection will be pinned to the server in the cluster that first made the connection, maintaining the DBMS context.

To set up WebLogic Clustered JDBC:

1. Set up the DataSource objects and connection pools for the WebLogic JDBC/RMI driver as described in Setting up WebLogic Server to use the WebLogic JDBC/RMI driver

2. Define an identical DataSource object in the per-server weblogic.properties file of each WebLogic Server in the cluster.

3. Write your client code to access the DataSource object as described in Setting up the client to use the WebLogic JDBC/RMI driver.

Note also the following:

• Clustered JDBC allows you to define the DataSource objects in each server in a WebLogic Cluster to point to a different connection pool, and for each connection pool to point to a different DBMS. In most cases, you will want the DataSources and connection pools to be identical in each server, obtaining a connection to the same instance of the DBMS. For maximum flexibility, however, you can arrange these objects as needed. Care should be taken to make sure the configuration you specify is the correct one for your applications.

• You may define the pool size and other properties of the connection pool differently for each server, in order to maximize the use of each server in the cluster.

Additional information

For more information on WebLogic Clusters, see Setting up a WebLogic Cluster, in the WebLogic Server Administrators guides.