WebLogics Wrapper Drivers

WebLogic s Wrapper Drivers

In this section, we examine how you can use WebLogic's wrapper drivers to access preconfigured connection pools. Even though a data source is the recommended way for accessing a connection pool, you may need to use wrapper drivers for existing or legacy applications that are based on the JDBC 1.x API. WebLogic supports three kinds of wrapper drivers:

WebLogic RMI Driver

Client-side applications can use the RMI Driver to access server-side connection pools.

WebLogic Pool Driver

Server-side applications can use the Pool Driver to access the connection pools directly.

WebLogic JTS Driver

The JTS Driver is identical to the Pool Driver, except that the database connections also can participate in distributed transactions.

Each driver provides vendor-neutral access to connection pools already configured in WebLogic. The J2EE standard recommends that you use a data source to access the pool.

5.3.1 The RMI Driver

WebLogic's RMI Driver is a Type 3 JDBC driver that enables client-side applications to access connection pools configured on WebLogic Server. The RMI Driver returns JDBC connections through the data source configured for the pool. The connection pool is configured as usual using a two-tier JDBC driver. As its name suggests, the RMI Driver provides RMI access to a server-side JDBC pool.

Let's look at how a client application obtains a JDBC connection from a connection pool:

java.sql.Driver wlDriver = (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://localhost:7001");
props.put("weblogic.jdbc.datasource", "myds");

//if a security policy applies to the data source, 
//you need to set the following two properties as well
props.put("weblogic.user", "system");
props.put("weblogic.credential", "wlpassword");

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

First, you need to create an instance of the WebLogic RMI Driver. Then you must specify a set of properties before you can invoke the connect( ) method on the driver. These properties include the T3 URL for the server, the name of the data source, and optional user credentials. The connect( ) method also takes a JDBC URL as a parameter; the value jdbc:weblogic:rmi is specific to the RMI Driver.

Once you invoke the connect( ) method, the RMI Driver on behalf of the client application contacts the server, performs the JNDI lookup using the name of the data source, and then invokes the getConnection( ) method on the data source obtained. Make sure that you include the WL_HOMEserverlibweblogic.jar in your system classpath so that the RMI Driver classes are accessible to the external client.

Just like the data source, a client application that uses the RMI Driver benefits from row prefetching. Caching multiple rows on the client's end saves costly round trips to WebLogic whenever the client application scrolls through a ResultSet. However, row prefetching is enabled only if the type of the ResultSet is TYPE_FORWARD_ONLY or CONCUR_READ_ONLY. It is disabled when the client application runs in the same VM as the server. It also may be disabled if the ResultSet includes columns of types LONGVARCHAR, LONGVARBINARY, NULL, BLOB, CLOB, ARRAY, REF, STRUCT, or JAVA_OBJECT. In addition, certain methods of the ResultSet may not be supported if row prefetching is enabled. These methods relate to the streaming datatypes, datatypes not supported when row prefetching is enabled, and indiscriminate scrolling across the ResultSet. A data source has to be configured explicitly to use prefetching. Remember, row prefetching is not used if the client and server are running in the same JVM.

5.3.2 The Pool Driver

WebLogic's Pool Driver is a JDBC driver that provides access to connection pools for server-side applications (such as servlets, EJBs, etc.) running on WebLogic Server. The Pool Driver obtains connections from a JDBC pool that uses a two-tier JDBC driver installed on WebLogic Server. Just like the RMI Driver, you create an instance of the Pool Driver and then create a connection by supplying the URL for the Pool Driver and the name of a connection pool. You can either append the name of the JDBC pool to the driver URL or specify the name of the connection pool in a java.util.Properties object.

Here's how a servlet could request access to a connection pool using the Pool Driver:

java.sql.Driver wlDriver = (java.sql.Driver)
 Class.forName("weblogic.jdbc.pool.Driver").newInstance( );

String url = "jdbc:weblogic:pool";
Properties props = new Properties( );
props.put("connectionPoolID", "myPool");
Connection con = wlDriver.connect(url, props);

//this would have worked as well...
//Connection con = wlDriver.connect("jdbc:weblogic:pool:myPool", null);

Notice how we use the connect( ) method on the Driver object to obtain a database connection, instead of using the connect( ) method on DriverManager. This approach yields better performance because the connect( ) method on the Driver object is not synchronized. When you are done, you should invoke the close( ) method on the Connection object so that it can be released back to the pool.

We recommend that you use a data source instead of a Pool Driver. Data sources are a standard J2EE feature and provide a more portable way of accessing connections.

 

5.3.3 The JTS Driver

Like the Pool Driver, WebLogic's JTS Driver is a server-side JDBC driver that returns connections from a JDBC pool that can participate in distributed transactions. The JTS Driver obtains connections from a JDBC pool that uses a two-tier JDBC driver configured for WebLogic Server. Here's an example of how you can access a connection pool using the JTS Driver:

//set up a transaction context before you use the JTS Driver
UserTransaction tx = (UserTransaction) ctx.lookup("java:comp/UserTransaction");
tx.begin( );

//load the JTS driver
java.sql.Driver wlDriver = (java.sql.Driver)
 Class.forName("weblogic.jdbc.jts.Driver").newInstance( );

// obtain a tx-aware connection from the pool
String url = "jdbc:weblogic:jts";
Properties props = new Properties( );
props.put("connectionPoolID", "myPool");
Connection con = wlDriver.connect(url, props);

//this would have worked as well...
//Connection con = wlDriver.connect("jdbc:weblogic:jts:myPool", null);

// use the connection to perform any updates...
// close the connection when you're done...
con.close( );

// commit all changes
tx.commit( );

Once you've loaded the JTS Driver, you create a connection by supplying the URL for the JTS Driver and the name of the JDBC pool. You can either append the name of the JDBC pool to the driver URL, or specify the name in a java.util.Properties object.

Notice how we set up a transaction context before we use the JTS Driver to obtain a connection from the pool. Because the JTS Driver avoids two-phase commit, the distributed transaction may perform only those updates that use the JTS Driver to access the same connection pool. If you attempt to access another connection pool within the same transaction, you will get an exception when you later commit or roll back the transaction. Note that the connection isn't returned to the pool when you invoke the close( ) method. This happens only when the transaction commits or rolls back. In case of a transaction commit, WebLogic returns the connections to the pool after it commits the local transactions on all connections obtained during the lifetime of the distributed transaction in the current thread.

We recommend that you use a data source backed by an XA-aware JDBC driver instead of a JTS Driver. Data sources are a standard J2EE feature and provide a more portable way of accessing connections.