Using WebLogic Type 4 JDBC Drivers

BEA WebLogic Type 4 JDBC drivers provide JDBC access through Weblogic Server. They deliver high-performance access to industry-leading data stores across the Internet and intranets. The BEA WebLogic Type 4 JDBC drivers are optimized for the Java environment, allowing you to incorporate Java technology and extend the functionality and performance of your existing system.

The following sections provide more information about the BEA WebLogic Type 4 JDBC drivers:

 

JDBC Specification Compliance

BEA WebLogic Type 4 JDBC drivers are compliant with the JDBC 3.0 specification. They also support several JDBC 2.0 Standard Extension Features. For details, see Appendix A, "JDBC Support.

 

Installation

WebLogic Type 4 JDBC drivers are installed with WebLogic Server in the WL_HOME\server\lib folder, where WL_HOME is the directory in which you installed WebLogic Server. Driver class files are included in the manifest classpath in weblogic.jar, so the drivers are automatically added to your classpath on the server.

The WebLogic Type 4 JDBC drivers are not included in the manifest classpath of the WebLogic client jar files (e.g., wlclient.jar). To use the drivers with a WebLogic client, copy the following files to the client and add them to the classpath on the client:

  • wlbase.jar
  • wlutil.jar
  • The DBMS-specific JAR file:

    • For DB2: wldb2.jar
    • For Informix: wlinformix.jar
    • For MS SQL Server: wlsqlserver.jar
    • For Oracle: wloracle.jar
    • For Sybase: wlsybase.jar

 

License Requirements

BEA WebLogic Type 4 JDBC drivers are licensed for use with WebLogic Server and with WebLogic Server clients only. At least one of the following files must be in your classpath for the license check to succeed:

  • weblogic.jar
  • wlclient.jar

 

Supported Databases

Table 1-1 shows the databases supported by each of the BEA WebLogic Type 4 JDBC drivers.

Driver

Supported Databases

DB2 DB2 Universal Database (UDB) 7.1, 7.2, and 8.1 running on Windows NT, Windows 2000, UNIX, Linux, and Linux/s390 via DRDADB2 6.1 and DB2 UDB 7.1 running on OS/390 and z/OS via DRDADB2 UDB V4R5, V5R1, and V5R2 running on iSeries and AS/400
Informix Informix Dynamic Server with Universal Data Option 9.2 and higher running on Windows and UNIX via SQLIInformix Dynamic Server 2000 9.2, 9.3, and 9.4 running on Windows and UNIX via SQLI
MS SQL Server Microsoft SQL Server 7.0 and SQL Server 2000 (including SP1, SP2, and SP3) on Windows via Tabular DataStream (TDS)
Oracle Oracle 8i R3 (8.1.7) and Oracle 9i running on Windows and UNIX.
Sybase ASE Sybase Adaptive Server Enterprise 12.0 and 12.5 running on Windows and UNIX via TDS (XA and non-XA)Sybase Adaptive Server 11.5 and 11.9 running on Windows and UNIX via TDS (non-XA only)

 

Connecting Through Data Sources and Connection Pools

To use the WebLogic Type 4 JDBC drivers, you create a JDBC connection pool in your WebLogic Server configuration and select the JDBC driver to create the physical database connections in the connection pool. Then create a data source and point it to the connection pool. Applications can then look up the data source on the JNDI tree and request a connection.

See the following related information:

 

Specifying Connection Properties

You specify connection properties for connections in a connection pool using the WebLogic Server Administration Console, command line interface, or JMX API. Connection properties vary by DBMS. For the list of the connection properties specific to each BEA WebLogic Type 4 JDBC driver, see the appropriate driver chapter:

 

Limiting Connection Creation Time with LoginTimeout

When creating database connections in a JDBC connection pool, if the database is unavailable, the request may hang until the default system timeout expires. On some systems this can be as long as 9 minutes. The request will hang for each connection in the JDBC connection pool. To minimize this hang time, you can specify a LoginTimeout value for the connection. All WebLogic Type 4 JDBC Drivers support the LoginTimeout connection property. When you specify a LoginTimeout connection property, if the connection is not created immediately, the request waits for the time you specify. If the connection cannot be created within the time specified, the driver throws an SQL exception.

 

Connection Failover with AlternateServers

All WebLogic Type 4 JDBC drivers support connection failover with the AlternateServers connection option in the connection URL. With the AlternateServers connection option, you can specify a list of additional database servers to connect to in case of connection creation failure.

The value of the AlternateServers connection option is a string that specifies the server name and port number of alternate servers to connect to if the primary server is not accepting connections. The AlternateServers string must be in the following format: 

jdbc:bea:dbms://server1:1521;AlternateServers=(servername2:port2,servername3:port3, ..., servernameN:portN)

When creating database connections, the driver attempts to connect to the primary server identified by the ServerName and PortNumber connection options specified in the connection URL (server1:1521 in the example above). If that connection attempt fails, the driver attempts to connect to the first server identified by servername and port in the AlternateServers connection option. If that connection attempt fails, the driver tries the next server in the list. The connection attempts continue until a connection is successfully established or until all the servers in the list have been tried. If a connection is not established after trying all the specified servers, a SQLException is generated. Note that the driver fails over to the next alternate server only if it cannot establish communication with the current server. If the driver successfully establishes communication with a server and the connection request is rejected by the server because the login information is invalid (for example, an invalid user name or password is specified) the driver will not try to connect to the next server in the list and generates a SQLException containing the error information returned by the database.

For example: 

jdbc:bea:oracle://server1:1521;SID=TEST;AlternateServers=(server2:1521,server3:1521,server4:1521)

With this URL, the driver attempts to connect to the TEST database on server1 using port 1521. If that connection attempt fails, the driver tries to connect to the TEST database on server2. If that attempt fails, the driver attempts to connect to server3, and so forth, until a connection is successfully created or until exhausting the list of alternate servers.

Note: To use the AlternateServers connection option, specify the primary ServerName and PortNumber values in the URL. If you do not specify the primary ServerName and PortNumber values, the driver will not attempt to create connections.

 

Connection Failover with MS SQL Server Named Instances

The SQL Server driver supports named instance entries in the AlternateServers string in addition to servername:port entries. For SQL Server only, the value of the AlternateServers connection option can be in either of the following formats: 

(servername2:port2,servername3:port3, ..., servernameN:portN)

or 

(servername2\\instance2,servername3\\instance3, ..., servernameN\\instanceN)

For example: 

jdbc:bea:sqlserver://server1\\TEST;AlternateServers=(server2\\TEST,server3\\TEST,server4\\TEST)

With this URL, the driver attempts to connect to the TEST instance on server1. If that connection attempt fails, the driver tries to connect to the TEST instance on server2. If that attempt fails, the driver attempts to connect to server3, and so forth, until a connection is successfully created or until exhausting the list of alternate servers.

 

Using AlternateServers with WebLogic Server JDBC Connection Pools

When you specify AlternateServers for connections in a WebLogic Server JDBC connection pool, the connection pool follows the same procedure when creating each connection in the connection pool: attempt to create a connection to the primary server; if that fails, then attempt to connect to the next alternate server until a connection is successfully created. If database servers start up or shut down before all connections are created, it is possible to have connections in a connection pool that connect to various database servers. Therefore, it is best to use the AlternateServers option with replicated databases or for read-only data.

Consider the following notes when configuring your JDBC connection pool with AlternateServers:

  • Attempts to create a connection to a non-responding database will wait until the default system timeout before attempting to create a connection to an alternate server. On some systems, this can be as long as 9 minutes. To avoid this delay, set the LoginTimeout property for the connection. See the list of connection properties for the driver you are using.
  • After database connections are initially created in a connection pool, if you want the connection pool to automatically recreate connections after a database fails, set connection testing options for the connection pool. See "Connection Testing Options in the Administration Console Online Help.
  • If connections from the connection pool participate in global transactions, select Keep XA Connection Till Transaction Complete in the Administration Console (or set KeepXAConnTillTxComplete=true in the config.xml file). For more information, see "Additional XA Connection Pool Properties in the Administration Console Online Help.

 

XA Support

Although the WebLogic Type 4 JDBC drivers support XA, you may need to configure your database to support XA with the drivers. See the following sections for more details:

 

Unicode Support

Multi-lingual applications can be developed on any operating system platform with JDBC using the BEA WebLogic Type 4 JDBC drivers to access both Unicode and non-Unicode enabled databases. Internally, Java applications use UTF-16 Unicode encoding for string data. When fetching data, the WebLogic Type 4 JDBC drivers automatically perform the conversion from the character encoding used by the database to UTF-16. Similarly, when inserting or updating data in the database, the drivers automatically convert UTF-16 encoding to the character encoding used by the database.

The JDBC API provides mechanisms for retrieving and storing character data encoded as Unicode (UTF-16) or ASCII. Additionally, the Java string object contains methods for converting UTF-16 encoding of string data to or from many popular character encodings.

 

Error Handling

The BEA WebLogic Type 4 JDBC drivers report errors to the calling application by throwing SQLExceptions. Each SQLException contains the following information:

  • Description of the probable cause of the error, prefixed by the component that generated the error
  • Native error code (if applicable)
  • String containing the XOPEN SQLstate

 

Driver Errors

An error generated by a WebLogic Type 4 JDBC driver has the following format: 

[BEA][WebLogic Type 4 JDBC driver name]message

For example: 

[BEA][SQLServer JDBC Driver]Timeout expired.

You may, at times, need to check the last JDBC call your application made and refer to the JDBC specification for the recommended action.

 

Database Errors

An error generated by the database has the following format: 

[BEA][WebLogic Type 4 JDBC driver name][DBMS name] message

For example: 

[BEA][SQL Server JDBC Driver][SQL Server] Invalid Object Name.

Use the native error code to look up details about the possible cause of the error. For these details, refer to your database documentation.

Skip navigation bar  Back to Top Previous Next