bea.com | products | dev2dev | support | askBEA |
|
e-docs > WebLogic Server > Programming WebLogic JDBC > Using WebLogic Multitier JDBC Drivers |
Programming WebLogic JDBC |
Using WebLogic Multitier JDBC Drivers
BEA recommends that you use DataSource objects to get database connections in new applications. DataSource objects, along with the JNDI, provide access to connection pools for database connectivity. For existing or legacy applications that use the JDBC 1.x API, you can use the WebLogic multitier drivers to get database connectivity.
The following sections describe how to use multitier JDBC drivers with WebLogic Server:
The WebLogic RMI driver is a multitier Type 3 JDBC driver WebLogic Server uses to pass database connections from a connection pool to a DataSource or TxDataSource. The DataSource object provides access to database connections for applications through the WebLogic RMI driver. The database connection parameters are set in the connection pool using the Administration Console or the WebLogic Management API, including the two-tier JDBC driver used to access the DBMS. See Figure 1-1.
RMI driver clients make their connection to the DBMS by looking up the DataSource object. This lookup is accomplished by using a Java Naming and Directory Service (JNDI) lookup, or by directly calling 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) and the Pool driver, and uses the Java standard Remote Method Invocation (RMI) to connect to WebLogic Server rather than the proprietary t3 protocol.
Because 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.
Setting Up WebLogic Server to Use the WebLogic RMI Driver
The RMI driver is accessible only through DataSource objects, which are created in the Administration Console. You must create DataSource objects in your WebLogic Server configuration before you can use the RMI driver in your applications. For instructions to create a DataSource, see the Administration Console Online Help.
Sample Client Code for Using the RMI Driver
The following code samples show how to use the RMI driver to get and use a database connection from a WebLogic Server connection pool.
Before you can use the RMI driver to get and use a database connection, you must import the following packages:
javax.sql.DataSource
java.sql.*
java.util.*
javax.naming.*
The WebLogic JDBC/RMI client obtains its connection to a DBMS from the DataSource object that you defined in the Administration Console. There are two ways the client can obtain a DataSource object:
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 lookup. 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 a Database Connection
Instead of looking up a DataSource object to get a database connection, you can access 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:
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 Server fetches a single row from the DBMS and transmits it 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. To enable row caching and to set the row prefetch size attribute for a DataSource or TxDataSource, follow these steps:
Important Limitations for Row Caching with the WebLogic RMI Driver
Keep the following limitations in mind if you intend to implement row caching with the RMI 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 begins, all database operations in an execute thread that get their connection from the same connection pool share the same connection from that pool. These operations can 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 is 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 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.
Sample Client Code for Using 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 Configuring and Using Connection Pools.
This explanation demonstrates creating and using a JTS transaction from a server-side application and uses a connection pool named "myConnectionPool."
import javax.transaction.UserTransaction;
import java.sql.*;
import javax.naming.*;
import java.util.*;
import weblogic.jndi.*;
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");
tx.begin();
Driver myDriver = (Driver)
Class.forName("weblogic.jdbc.jts.Driver").newInstance();
Properties props = new Properties();
props.put("connectionPoolID", "myConnectionPool");
conn = myDriver.connect("jdbc:weblogic:jts", props);
conn.close();
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 about using the Pool driver, see "Accessing Databases" in Programming Tasks in Programming WebLogic HTTP Servlets.