|
|
|
|
|
|
| | | |
Using Third-Party Drivers with WebLogic Server
The following sections describe how to set up and use third-party JDBC drivers:
Overview of Third-Party JDBC Drivers
WebLogic Server works with third-party JDBC drivers that offer the following functionality:
This section describes how to set up and use the following third-party two-tier, Type 4 drivers with WebLogic Server:
The Sybase jConnect Driver (versions 4.2/5.2 and 5.5) and Oracle Thin Driver (version 9.2.0) are bundled with your WebLogic Server distribution; the weblogic.jar file contains the Oracle Thin Driver and Sybase jConnect classes. Additional information about these Oracle and Sybase drivers is available at their respective Web sites.
Note: With the release of WebLogic Server 6.1 Service Pack 4, the version of the Oracle Thin Driver bundled in weblogic.jar is version 9.2.0. Previous releases of WebLogic Server 6.1 included the 8.1.7 version of the Oracle Thin Driver.
Limitations
Please be aware of the following:
Setting the Environment for Your Third-Party Driver
If you use a third-party JDBC driver other than the Oracle Thin Driver or Sybase jConnect Driver included in weblogic.jar, you must add the path for the JDBC driver classes to your CLASSPATH. The following topics describe how to set your CLASSPATH for Windows and UNIX when using a third-party JDBC driver.
CLASSPATH for Third-Party Driver on Windows
Add the path to JDBC driver classes and to weblogic.jar to your CLASSPATH as follows:
set CLASSPATH=DRIVER_CLASSES;WL_HOME\lib\weblogic.jar;%CLASSPATH%
Where DRIVER_CLASSES is the path to the JDBC driver classes and WL_HOME is the directory where you installed WebLogic Server.
CLASSPATH for Third-Party Driver on UNIX
Add the path to JDBC driver classes and to weblogic.jar to your CLASSPATH as follows:
export CLASSPATH=DRIVER_CLASSES:WL_HOME/lib/weblogic.jar:
$CLASSPATH
Where DRIVER_CLASSES is the path to the JDBC driver classes and WL_HOME is the directory where you installed WebLogic Server.
To update the Oracle Thin Driver bundled with WebLogic Server, you must add the path for the new driver classes to your CLASSPATH in front of the path to weblogic.jar. For example:
set CLASSPATH=%ORACLE_HOME%\jdbc\lib\classes12.zip;
%WL_HOME%\lib\weblogic.jar;%CLASSPATH% (Windows)
Or
export CLASSPATH=$ORACLE_HOME/jdbc/lib/classes12.zip:
$WL_HOME/lib/weblogic.jar:$CLASSPATH (UNIX)
Use this procedure for updates to Oracle Thin Driver version 9.2.0 bundled in weblogic.jar or to use a new version of the driver.
The Oracle Thin Driver is included with the Oracle DBMS software. You can also download driver updates from the Oracle Web site at http://otn.oracle.com/software/content.html.
Using the Oracle 10g Thin Driver
The Oracle 10g Thin driver is installed with WebLogic Server 6.1 Service Pack 7 (and later service packs) in the WL_HOME\lib\oracle\10g folder. BEA provides the 10g driver so that you can optionally use it with WebLogic Server. However, the Oracle 9.2.0 Thin driver remains the default version of the driver. The 9.2.0 version is included in weblogic.jar and is included in your CLASSPATH when you run the server.
To use the Oracle10g Thin driver, you must add the driver classes to your CLASSPATH in front of weblogic.jar, preferably in your scripts to start WebLogic Server. For example, in the WL_HOME\config\mydomain\startWeblogic.cmd (.sh on UNIX), change the following line:
set CLASSPATH=.;.\lib\weblogic_sp.jar;.\lib\weblogic.jar
To this:
set CLASSPATH=.;WL_HOME\lib\oracle\10g\classes12.zip; .\lib\weblogic_sp.jar;.\lib\weblogic.jar
Note: Line break added for readability.
In this example, WL_HOME is the directory in which WebLogic Server is installed, typically C:\bea\wlserver6.1.
Note: Oracle removed some methods and classes from the 10g Thin driver that were in previous versions of the driver. If you use any of the extension methods that were removed, you will see errors in your application.
Package Change for Oracle Thin Driver 9.x and 10g
For Oracle 8.x and previous releases, the package that contained the Oracle Thin driver was oracle.jdbc.driver. When configuring a JDBC connection pool that uses the Oracle 8.1.7 Thin driver, you specify the DriverName (Driver Classname) as oracle.jdbc.driver.OracleDriver. For Oracle 9.x and 10g, the package that contains the Oracle Thin driver is oracle.jdbc. When configuring a JDBC connection pool that uses the Oracle 9.x or 10g Thin driver, you specify the DriverName (Driver Classname) as oracle.jdbc.OracleDriver. You can use the oracle.jdbc.driver package and the oracle.jdbc.driver.OracleDriver class with the 9.x and 10g drivers, but Oracle may not make future feature enhancements to that class.
See the Oracle documentation for more details about the Oracle Thin driver.
Note: The package change does not apply to the XA version of the driver. For the XA version of the Oracle Thin driver, use oracle.jdbc.xa.client.OracleXADataSource as the DriverName (Driver Classname) in a JDBC connection pool.
Updating Sybase jConnect Driver
To update the Sybase jConnect Driver bundled with WebLogic Server, you must add the path for the jConnect driver to your CLASSPATH in front of the path to weblogic.jar. For example:
set CLASSPATH=%SYBASE_HOME%\jConnect-5_5\classes\jconn2.jar;
%WL_HOME%\lib\weblogic.jar;%CLASSPATH% (Windows)
Or
export CLASSPATH=$SYBASE_HOME/jConnect-5_5/classes/jconn2.jar:
$WL_HOME/lib/weblogic.jar:$CLASSPATH (UNIX)
The Sybase jConnect Driver (jConnect.jar) is included with the Sybase DBMS software. You can also download driver updates from the Sybase Web site.
Installing and Using the IBM Informix JDBC Driver
If you want to use Weblogic Server with an Informix database, BEA recommends that you use the IBM Informix JDBC driver, available from the IBM Web site at http://www.informix.com/evaluate/. The IBM Informix JDBC driver is available to use for free without support. You may have to register with IBM to download the product. Download the driver from the JDBC/EMBEDDED SQLJ section, and follow the instructions in the install.txt file included in the downloaded zip file to install the driver.
After you download and install the driver, follow these steps to prepare to use the driver with WebLogic Server:
INFORMIX_INSTALL is the root directory where you installed the Informix JDBC driver, and
WL_HOME is the folder where you installed WebLogic Server, typically c:\bea\wlserver6.1.
set CLASSPATH=%WL_HOME%\server\lib\ifxjdbc.jar;%WL_HOME%\server\lib \ifxjdbcx.jar;%CLASSPATH%
You can also add the path for the driver files to the set CLASSPATH statement in your start script for WebLogic Server.
Connection Pool Attributes when using the IBM Informix JDBC Driver
Use the attributes as described in Table 6-1 and Table 6-2 when creating a connection pool that uses the IBM Informix JDBC driver.
An entry in the config.xml file may look like the following:
<JDBCConnectionPool
DriverName="com.informix.jdbc.IfxDriver"
InitialCapacity="3"
LoginDelaySeconds="1"
MaxCapacity="10"
Name="ifxPool"
Password="xxxxxxx"
Properties="informixserver=ifxserver;user=informix"
Targets="examplesServer"
URL="jdbc:informix-sqli:ifxserver:1543"
/>
Note: In the Properties string, there is a space between portNumber and =.
An entry in the config.xml file may look like the following:
<JDBCConnectionPool CapacityIncrement="2"
DriverName="com.informix.jdbcx.IfxXADataSource"
InitialCapacity="2" MaxCapacity="10"
Name="informixXAPool"
Properties="user=informix;url=jdbc:informix-sqli:
//111.11.11.11:1543/db1:informixserver=lcsol15;
password=informix;portNumber =1543;databaseName=db1;
serverName=dbserver1;ifxIFXHOST=111.11.11.11"
SupportsLocalTransaction="true" Targets="examplesServer"
TestConnectionsOnReserve="true" TestTableName="emp"/>
Note: If you create the connection pool using the Administration Console, you may need to stop and restart the server before the connection pool will deploy properly on the target server. This is a known issue.
Programming Notes for the IBM Informix JDBC Driver
Consider the following limitations when using the IBM Informix JDBC driver:
Getting a Connection with Your Third-Party Driver
The following topics describe two ways to get a connection using a third-party, Type 4 driver, such as the Oracle Thin Driver and Sybase jConnect Driver. BEA recommends you use connection pools, data sources, and JNDI Lookup to establish your connection. As an alternative, you can get a simple connection directly between the Java client and the database.
Using Connection Pools with a Third-Party Driver
First, you create the connection pool and data source using the Administration Console, then establish a connection using a JNDI Lookup.
Creating the Connection Pool and DataSource
See Managing JDBC Connectivity in the Administration Guide for information on how to use the Administration Console to:
Using a JNDI Lookup to Obtain the Connection
To access the driver using JNDI, obtain a Context from the JNDI tree by providing the URL of your server, and then use that context object to perform a lookup using the DataSource Name.
For example, to access a DataSource called "myDataSource" that is defined in the 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.
Getting a Physical Connection from a Connection Pool
When you get a connection from a connection pool, WebLogic Server provides a logical connection rather than a physical connection so that WebLogic Server can manage the connection with the connection pool. This is necessary to enable connection pool features and to maintain the quality of connections provided to applications. In some cases, you may want to use a physical connection, such as if you need to pass the connection to a DBMS vendor-specific method that requires the vendor's connection class. WebLogic Server includes the getVendorConnection() method in the weblogic.jdbc.extensions.WLConnection interface that you can use to get the underlying physical connection from a logical connection. See the WebLogic Javadocs.
Note: BEA strongly discourages using a physical connection instead of a logical connection from a connection pool. See Limitations for Using a Physical Connection.
You should only use the physical database connection for vendor-specific needs. Your code should continue to make most JDBC calls to the logical connection.
When you are finished with the connection, you should close the logical connection. Do not close the physical connection in your code.
Whenever a physical database connection is exposed to application code, the connection pool cannot guarantee that the next user of that connection will be the only user with access to it. Therefore, when the logical connection is closed, WebLogic Server returns the logical connection to the connection pool, but discards the underlying physical connection and opens a new physical connection for the logical connection in the pool. This is safe, but it is also slow. It is possible that every request to the connection pool will entail making a new database connection.
Code Sample for Getting a Physical Connection
To get a physical database connection, you first get a connection from a connection pool as described in Using a JNDI Lookup to Obtain the Connection, then do one of the following:
For example:
//Import this additional class and any vendor packages
//you may need.
import weblogic.jdbc.extensions.WLConnection
.
.
.
myJdbcMethod()
{
// Connections from a connection pool should always be // method-level variables, never class or instance methods. Connection conn = null;
try {
ctx = new InitialContext(ht);
// Look up the data source on the JNDI tree and request
// a connection.
javax.sql.DataSource ds
= (javax.sql.DataSource) ctx.lookup ("myDataSource");
// Always get a pooled connection in a try block where it is
// used completely and is closed if necessary in the finally
// block.
conn = ds.getConnection();
// You can now cast the conn object to a WLConnection
// interface and then get the underlying physical connection.
java.sql.Connection vendorConn =
((WLConnection)conn).getVendorConnection();
// do not close vendorConn
// You could also cast the vendorConn object to a vendor
// interface, such as:
// oracle.jdbc.OracleConnection vendorConn = (OracleConnection)
// ((WLConnection)conn).getVendorConnection();
// If you have a vendor-specific method that requires the
// physical connection, it is best not to obtain or retain
// the physical connection, but simply pass it implicitly
// where needed, eg:
//vendor.special.methodNeedingConnection(((WLConnection)conn)).ge tVendorConnection());
// As soon as you are finished with vendor-specific calls,
// nullify the reference to the connection.
// Do not keep it or close it.
// Never use the vendor connection for generic JDBC.
// Use the logical (pooled) connection for standard JDBC.
vendorConn = null;
... do all the JDBC needed for the whole method...
// close the logical (pooled) connection to return it to
// the connection pool, and nullify the reference.
conn.close();
conn = null;
}
catch (Exception e)
{
// Handle the exception.
}
finally
{
// For safety, check whether the logical (pooled) connection
// was closed.
// Always close the logical (pooled) connection as the
// first step in the finally block.
if (conn != null) try {conn.close();} catch (Exception ignore){}
}
}
Limitations for Using a Physical Connection
BEA strongly discourages using a physical connection instead of a logical connection from a connection pool. However, if you must use a physical connection, for example, to create a STRUCT, consider the following costs and limitations:
Obtaining a Direct (Non-pooled) JDBC Connection
This simple example shows you how to establish a connection directly between the your Java code running on WebLogic Server and the database. Use driver.connect() to set your direct connection. Do not use DriverManager to get a JDBC connection because the DriverManager methods are overly synchronized for a multi-threaded application, and can cause WebLogic Server to become single-threaded or to lock up.
The following example shows how to get a direct connection using a third-party driver.
Obtaining a Direct Connection Using the Oracle Thin Driver
The following example shows how to set a direct connection using the Oracle Thin Driver:
// ThinDriver driver
driver = (Driver)Class.forName
("oracle.jdbc.driver.OracleDriver").newInstance();
Properties props = new Properties();
props.put("user", "scott");
props.put("password", "tiger");
// Thin driver connection
con = driver.connect
("jdbc:oracle:thin:@myHost.mydomain.com:1521:DEMO", props);
Obtaining a Direct Connection Using the Sybase jConnect Driver
The following example shows how to set a direct connection using the Sybase jConnect Driver:
// Sybase jConnect driver
driver = (Driver)Class.forName
("com.sybase.jdbc.SybDriver").newInstance()
Properties props = new Properties();
props.put("user", "scott");
props.put("password", "tiger");
// Sybase jConnect
con = driver.connect
("jdbc:sybase:Tds:myDB@myhost:myport), props);
BEA supports the following extensions to the Oracle Thin Driver for use with the RMI, JTS and Pool drivers:
Oracle Standard Extensions
Oracle Blobs and Clobs
The following sections provide code samples for Oracle extensions and tables of supported methods. For more information, please refer to the Oracle documentation.
Sample Code for Accessing Oracle Extensions to JDBC Interfaces
The following code examples show how to access the WebLogic Oracle extensions to standard JDBC interfaces. The following example uses the OracleConnection and OracleStatement extensions. You can use the syntax of this example for the OracleResultSet, OraclePreparedStatement and OracleCallableStatement interfaces, when using methods supported by WebLogic Server. For supported methods, see Tables of Oracle Interfaces.
For examples showing how to access the OracleThinBlob and OracleThinClob interfaces, see Oracle Blob/Clob Extensions and Supported Methods.
Import Packages to Access Oracle Extensions
Import the Oracle interfaces used in this example. The OracleConnection and Oracle Statement interfaces are counterparts to oracle.jdbc.OracleConnection and oracle.jdbc.OracleStatement and can be used in the same way as the Oracle interfaces when using the methods supported by WebLogic Server.
import java.sql.*; import java.util.*; import javax.naming.Context; import javax.naming.InitialContext; import weblogic.jdbc.vendor.oracle.OracleConnection; import weblogic.jdbc.vendor.oracle.OracleStatement;
Establish the Connection
Establish the connection using JNDI, DataSource and connection pool objects. For information, see Using a JNDI Lookup to Obtain the Connection.
// Get a valid DataSource object for a connection pool. // Here we assume that getDataSource() takes // care of those details. javax.sql.DataSource ds = getDataSource(args);
// get a java.sql.Connection object from the DataSource java.sql.Connection conn = ds.getConnection();
Retrieve the Default Row Prefetch Value
The following code fragment shows how to use the Oracle Row Prefetch method available through the Oracle Thin Driver.
// Cast to OracleConnection and retrieve the // default row prefetch value for this connection.
int default_prefetch =
((OracleConnection)conn).getDefaultRowPrefetch();
System.out.println("Default row prefetch
is " + default_prefetch);
java.sql.Statement stmt = conn.createStatement();
// Cast to OracleStatement and set the row prefetch
// value for this statement. Note that this
// prefetch value applies to the connection between
// WebLogic Server and the database.
((OracleStatement)stmt).setRowPrefetch(20);
// Perform a normal sql query and process the results...
String query = "select empno,ename from emp";
java.sql.ResultSet rs = stmt.executeQuery(query);
while(rs.next()) {
java.math.BigDecimal empno = rs.getBigDecimal(1);
String ename = rs.getString(2);
System.out.println(empno + "\t" + ename);
}
rs.close();
stmt.close();
conn.close();
conn = null;
}
Sample Code for Accessing Oracle Blob/Clob Interfaces
This section contains sample code that demonstrates how to access the OracleThinBlob interface. You can use the syntax of this example for the OracleThinBlob interface, when using methods supported by WebLogic Server. See Tables of Oracle Interfaces.
Note: When working with Blobs and Clobs (referred to as "LOBs"), you must take transaction boundaries into account; for example, direct all read/writes to a particular LOB within a transaction. For additional information, refer to Oracle documentation about "LOB Locators and Transaction Boundaries" at the Oracle Web site.
Import Packages to Access Blob and Clob Extensions
Include the WebLogic Server Oracle Blob with the imported classes:
import weblogic.jdbc.vendor.oracle.OracleThinBlob;
Query to Select Blob Locator from the DBMS
The Blob Locator, or handle, is a reference to an Oracle Thin Driver Blob:
String selectBlob = "select blobCol from myTable where blobKey = 666"
Declare the WebLogic Server java.sql Objects
The following code presumes the Connection is already established:
ResultSet rs = null; Statement myStatement = null; java.sql.Blob myRegularBlob = null; java.io.OutputStream os = null;
Begin SQL Exception Block
In this try catch block, you get the Blob locator and access the Oracle Blob extension.
try {
// get our Blob locator..
myStatement = myConnect.createStatement();
rs = myStatement.executeQuery(selectBlob);
while (rs.next()) {
myRegularBlob = rs.getBlob("blobCol");
}
// Access the underlying Oracle extension functionality for
// writing. Cast to the OracleThinBlob interface to access
// the Oracle method.
os = ((OracleThinBlob)myRegularBlob).getBinaryOutputStream();
.....
........
} catch (SQLException sqe) {
System.out.println("ERROR(general SQE): " +
sqe.getMessage());
}
Once you cast to the Oracle.ThinBlob interface, you can access the BEA supported methods.
Updating a CLOB Value Using a Prepared Statement
If you use a prepared statement to update a CLOB and the new value is shorter than the previous value, the CLOB will retain the characters that were not specifically replaced during the update. For example, if the current value of a CLOB is abcdefghij and you update the CLOB using a prepared statement with zxyw, the value in the CLOB is updated to zxywefghij. To correct values updated with a prepared statement, you should use the dbms_lob.trim procedure to remove the excess characters left after the update. See the Oracle documentation for more information about the dbms_lob.trim procedure.
Tables of Oracle Interfaces
The following tables list the Oracle interfaces.
Oracle Extensions and Supported Methods
The following tables describe the Oracle interfaces and supported methods you use with the Oracle Thin Driver to extend java.sql.* interfaces. See Oracle Blob/Clob Extensions and Supported Methods for the Blob/Clob interfaces.
Note: The following method was removed in Service Pack 04:
Note: The following methods were removed in Service Pack 04:
Note: The following method was removed in Service Pack 04:
.
.
Oracle Blob/Clob Extensions and Supported Methods
The following tables list the extensions to the java.sql.* interfaces.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|