Using WebLogic Multitier JDBC Drivers

 

The following sections describe how to use multitier JDBC drivers with WebLogic Server:

• Overview of WebLogic Multitier Drivers

• Using the WebLogic RMI Driver

• Using the WebLogic JTS Driver

• Using the WebLogic Pool Driver

 

---

Overview of WebLogic Multitier Drivers

You can access multitier drivers in the following ways:

• New applications. BEA recommends using DataSource objects for new applications. DataSource objects, along with the JNDI, provide access to connection pools for database connectivity. Each data source requires a separate DataSource object, which may be implemented as a DataSource class that supports either connection pooling, or distributed transactions. For more information, see Configuring WebLogic JDBC Features.

• Existing applications. For existing applications that use the JDBC 1.x API, refer to the following sections.

 

---

Using the WebLogic RMI Driver

The WebLogic RMI driver is a multitier, Type 3, JDBC driver that runs in WebLogic Server, used with:

• Two-tier JDBC drivers, including drivers in the WebLogic jDriver family, to provide database access for local transactions

• Two-tier JDBC XA drivers, including the WebLogic jDriver for Oracle/XA, for distributed transactions. For additional information, see Oracle Thin Driver Extensions, regarding information about using Oracle Thin Driver 8.1.7.

The BEA WebLogic RMI driver operates with WebLogic Server. The DBMS connection is made by means of the WebLogic Server, a DataSource object, and a connection pool operating in WebLogic Server.

The DataSource object provides access to RMI driver connections. The connection parameters are set in the Administration Console. This connection pool is in turn configured for two-tier JDBC access to a DBMS.

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

The RMI driver replaces the functionality of both the WebLogic t3 driver (deprecated in the last release) and the Pool driver, and 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.

Limitations When Using the WebLogic RMI Driver

Please be aware of the following:

• You cannot use Batch updates (addBatch()) with the callableStatement or preparedStatement SQL statements when using the RMI driver in conjunction with the WebLogic jDriver for Oracle or compliant third-party 2-Tier drivers.

Setting Up WebLogic Server to Use the WebLogic RMI Driver

RMI drivers are accessible only through DataSource objects, which are created in the Administration Console.

Setting Up the Client to Use the WebLogic Server

The following code samples shows how to obtain and use the connection.

Import the Following Packages

javax.sql.DataSource 
java.sql.*
java.util.*
javax.naming.*

Obtain the Client Connection

WebLogic JDBC/RMI client obtains its connection to a DBMS from the DataSource object that was defined in the Administration Console. 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 RMI driver with the Driver.connect()method. In this case, the WebLogic Server performs the JNDI look up on behalf of the client.

Using a JNDI Lookup to Obtain the Connection

To access the WebLogic 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 Administration Console:

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. For more information, see Programming WebLogic JNDI .

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.

Using Only the WebLogic RMI Driver to Obtain the Connection

You can also access the WebLogic Server using the Driver.connect() method, in which case the JDBC/RMI driver performs the JNDI lookup. To access the WebLogic Server, 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" as defined in the Administration Console:

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 username

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

Row Caching with the WebLogic RMI Driver

Row caching is a WebLogic Server JDBC feature that improves the performance of your application. Normally, when a client calls ResultSet.next(), WebLogic fetches a single row from the DBMS and transmits them to the client JVM. With row caching enabled, a single call to ResultSet.next() retrieves multiple DBMS rows, and caches them in client memory. By reducing the number of trips across the wire to retrieve data, row caching improves performance.

Note: WebLogic Server will not perform row caching when the client and WebLogic Server are in the same JVM.

You can enable and disable row caching and set the number of rows fetched per ResultSet.next() call with the Data Source attributes Row Prefetch Enabled and Row Prefetch Size, respectively. You set Data Source attributes via the Administration Console.

Important Limitations to Using Row Caching with the WebLogic RMI Driver

Keep the following limitations in mind if you intend to implement row caching with the RMI driver:

• WebLogic Server will only perform row caching on if the result set type is both TYPE_FORWARD_ONLY and CONCUR_READ_ONLY.

• Certain data types in a result set may disable caching for that result set. These include the following:

  • LONGVARCHAR/LONGVARBINARY

  • NULL

  • BLOB/CLOB

  • ARRAY

  • REF

  • STRUCT

  • JAVA_OBJECT

• Certain ResultSet methods are not supported if row caching is enabled and active for that result set. Most pertain to streaming data, scrollable result sets or data types not supported for row caching. These include the following:

  • getAsciiStream()

  • getUnicodeStream()

  • getBinaryStream()

  • getCharacterStream()

  • isBeforeLast()

  • isAfterLast()

  • isFirst()

  • isLast()

  • getRow()

  • getObject (Map)

  • getRef()

  • getBlob()/getClob()

  • getArray()

  • getDate()

  • getTime()

  • getTimestamp()

 

---

Using the WebLogic JTS Driver

The Java Transaction Services or JTS driver is a server-side Java Database Connectivity (JDBC) driver that provides access to both connection pools and SQL transactions from applications running in WebLogic Server. Connections to a database are made from a connection pool and use a two-tier JDBC driver running in WebLogic Server to connect to the Database Management System (DBMS) on behalf of your application.

Once a transaction is begun, all of the database operations in a execute thread that get their connection from the same connection pool will share the same connection from that pool. These operations may be made through services such as Enterprise JavaBeans (EJB), or Java Messaging Service (JMS), or by directly sending SQL statements using standard JDBC calls. All of these operations will, by default, share the same connection and participate in the same transaction.When the transaction is committed or rolled back, the connection will be returned to the pool.

Although Java clients may not register the JTS driver themselves, they may participate in transactions via Remote Method Invocation (RMI). You can begin a transaction in a thread on a client and then have the client call a remote RMI object. The database operations executed by the remote object will become part of the transaction that was begun on the client. When the remote object is returned back to the calling client, you can then commit or roll back the transaction. The database operations executed by the remote objects must all use the same connection pool to be part of the same transaction.

When you select Enable Two Phase Commit (enableTwoPhaseCommit = true) for a Tx Data Source with a non-XA JDBC driver, WebLogic Server uses the JTS driver internally to enable the non-XA resource to emulate two-phase commit (2PC) and participate in global transactions. For more information about enabling non-XA resources to participate in global transactions and how the JTS driver is used, see "Configuring Non-XA JDBC Drivers for Distributed Transactions" in the Administration Guide.

Implementing with the JTS Driver

To use the JTS driver, you must first use the Administration Console to create a connection pool in WebLogic Server. For more information, see Connection Pools in Managing JDBC Connectivity in Administration Guide.

This explanation demonstrates creating and using a JTS transaction from a server-side application and uses a connection pool named "myConnectionPool."

1. Import the following classes:

   import javax.transaction.UserTransaction;
   import java.sql.*;
   import javax.naming.*;
   import java.util.*;
   import weblogic.jndi.*;
   

2. Establish the transaction by using the UserTransaction class. This class can be looked up in the Java Naming and Directory Service (JNDI). The UserTransaction class controls the transaction on the current execute thread. Note that this class does not represent the transaction itself. The actual context for the transaction is associated with the current execute thread.

   Context ctx = null;
   Hashtable env = new Hashtable();
    
   env.put(Context.INITIAL_CONTEXT_FACTORY,
            "weblogic.jndi.WLInitialContextFactory");
    
   // Parameters for the WebLogic Server. 
   // Substitute the correct hostname, port number 
   // user name, and password for your environment:
   env.put(Context.PROVIDER_URL, "t3://localhost:7001"); 
   env.put(Context.SECURITY_PRINCIPAL, "Fred");
   env.put(Context.SECURITY_CREDENTIALS, "secret");
    
   ctx = new InitialContext(env);
    
   UserTransaction tx = (UserTransaction)
     ctx.lookup("javax.transaction.UserTransaction");
   

3. Start a transaction on the current thread:

   tx.begin();
   

4. Load the JTS driver:

   Driver myDriver = (Driver)
    Class.forName("weblogic.jdbc.jts.Driver").newInstance();
   

5. Get a connection from the connection pool:

   Properties props = new Properties();
   props.put("connectionPoolID", "myConnectionPool");
    
   conn = myDriver.connect("jdbc:weblogic:jts", props); 
   

6. Execute your database operations. These operations may be made by any service that uses a database connection. These include EJB, JMS, or standard JDBC statements. If these operations use the JTS driver to access the same connection pool as the transaction begun in step 3, they will participate in that transaction.

   If the additional database operations using the JTS driver use a different connection pool than the one specified in step 5, an exception will be thrown when you try to commit or roll back the transaction.

7. Close your connection objects. Note that closing the connections does not commit the transaction nor return the connection to the pool:

   conn.close();
   

8. Execute any other database operations. If these operations are made by connecting to the same connection pool, the operations will use the same connection from the pool and become part of the same UserTransaction as all of the other operations in this thread.

9. Complete the transaction by either committing the transaction or rolling it back. The JTS driver will commit all the transactions on all connection objects in the current thread and return the connection to the pool.

   tx.commit();
    
   // or:
    
   tx.rollback();
   

 

---

Using the WebLogic Pool Driver

The WebLogic Pool driver enables utilization of connection pools from server-side applications such as HTTP servlets or EJBs. For information on using the Pool driver, see Accessing Databases in Programming Tasks in Programming WebLogic HTTP Servlets.