Skip navigation.

Configuring and Managing WebLogic JDBC

  Previous Next vertical dots separating previous/next from contents/index/pdf Contents View as PDF   Get Adobe Reader

Introduction and Roadmap

This section describes the contents and organization of this guide—Configuring and Managing WebLogic JDBC.


Document Scope and Audience

This document is a resource for software developers and system administrators who develop and support applications that use the Java Database Connectivity (JDBC) API. It also contains information that is useful for business analysts and system architects who are evaluating WebLogic Server. The topics in this document are relevant during the evaluation, design, development, pre-production, and production phases of a software project.

This document does not address specific JDBC programming topics. For links to WebLogic Server documentation and resources for this topic, see Related Documentation.

It is assumed that the reader is familiar with J2EE and JDBC concepts. This document emphasizes the value-added features provided by WebLogic Server JDBC.


Guide to this Document


Related Documentation

This document contains JDBC-specific configuration and administration information.

For comprehensive guidelines for developing, deploying, and monitoring WebLogic Server applications, see the following documents:


JDBC Samples and Tutorials

In addition to this document, BEA Systems provides a variety of JDBC code samples and tutorials that show JDBC configuration and API use, and provide practical instructions on how to perform key JDBC development tasks.

Avitek Medical Records Application (MedRec) and Tutorials

MedRec is an end-to-end sample J2EE application shipped with WebLogic Server that simulates an independent, centralized medical record management system. The MedRec application provides a framework for patients, doctors, and administrators to manage patient data using a variety of different clients.

MedRec demonstrates WebLogic Server and J2EE features, and highlights BEA-recommended best practices. MedRec is included in the WebLogic Server distribution, and can be accessed from the Start menu on Windows machines. For Linux and other platforms, you can start MedRec from the WL_HOME\samples\domains\medrec directory, where WL_HOME is the top-level installation directory for WebLogic Platform.

JDBC Examples in the WebLogic Server Distribution

WebLogic Server 9.0 optionally installs API code examples in WL_HOME\samples\server\examples\src\examples, where WL_HOME is the top-level directory of your WebLogic Server installation. You can start the examples server, and obtain information about the samples and how to run them from the WebLogic Server 9.0 Start menu.


New and Changed JDBC Features in This Release

The following sections describe new features and changes for JDBC in WebLogic Server 9.0:

JDBC 3.0 Support

WebLogic Server 9.0 is compliant with the JDBC 3.0 specification, which includes support for the following new features:

For more information, see the Java JDBC technology page on the Sun Web site at

RowSets Enhancements

In WebLogic Server 9.0, the RowSets implementation was enhanced to comply with the new JDBC RowSet Implementations Specification (JSR-114) and to provide extensions to the specification.

Support for JSR-114

The WebLogic Server RowSets implementation fully complies with the JDBC RowSet Implementations Specification (JSR-114), which includes support for the following objects:

For more information about rowsets, see the Java JDBC technology page on the Sun Web site at For more information about using rowsets and the WebLogic Server RowSets implementation, see "Using RowSets with WebLogic Server" in Programming WebLogic JDBC.

WebLogic RowSet Extensions and Enhancements

WebLogic Server 9.0 includes the following extensions to rowsets:

For more information about using JDBC RowSets and the WebLogic Server RowSets implementation, see "Using RowSets with WebLogic Server" in Programming WebLogic JDBC.

Modular Deployment of System and Stand-Alone JDBC Resources

JDBC configuration in WebLogic Server 9.0 is now stored in XML documents that conform to the new weblogic-jdbc.xsd schema. You create and manage JDBC resources either as system modules, similar to the way they were managed prior to version 9.0, or as application modules. JDBC application modules are a WebLogic-specific extension of J2EE modules and can be deployed either within a J2EE application or as stand-alone modules.

With modular deployment of JDBC resources, you can migrate your application and the required JDBC configuration from environment to environment, such as from a testing environment to a production environment, without opening an EAR file and without extensive manual JDBC reconfiguration.

JDBC System Modules

An Administrator can create JDBC resources directly using the Administration Console or using WLST, similar to the way resources were created prior to WebLogic Server 9.0. JDBC resources created this way are stored as system resource modules in the config/jdbc subdirectory of the domain directory, and are referenced in the domain's config.xml file. After they are created, these JDBC resources are also accessible as a JDBCSystemResourceMBean through JMX.

System modules are globally available for targeting to servers and clusters configured in the domain, and therefore are available to all applications deployed on the same targets and to client applications. System resource modules are owned by the Administrator, who can delete, modify, or add similar resources at any time.

Application Modules

JDBC resources can also be managed as application modules, similar to standard J2EE modules. A JDBC descriptor can be deployed as a standalone resource using the weblogic.Deployer utility, in which case the resource is available to the server or cluster targeted during the deployment process. JDBC resources deployed in this manner can be reconfigured using the Administration Console, but are unavailable through JMX or WLST.

Packaged JDBC Resource Modules

Resource modules can also be included as part of an Enterprise Application as a packaged module. Packaged modules are bundled with an EAR or exploded EAR directory, and are referenced in the weblogic-application.xml deployment descriptor. The resource module is deployed along with the Enterprise Application, and can be configured to be available only to the enclosing application or to all applications. Using packaged modules ensures that an application always has access to required resources and simplifies the process of moving the application into new environments.

In contrast to system resource modules, packaged modules are owned by the developer who created and packaged the module, rather than the Administrator who deploys the module. This means that the Administrator has more limited control over packaged modules. When deploying a resource module, an Administrator can change resource properties that were specified in the module, but the Administrator cannot add or delete resources. (As with other J2EE modules, deployment configuration changes for a resource module are stored in a deployment plan for the module, leaving the original module untouched.)

JDBC Schema

In support of the new modular deployment model for JDBC resources in WebLogic Server 9.0, BEA now provides a schema for WebLogic JDBC objects. When you create JDBC resource modules (descriptors), the modules must conform to the schema. IDEs and other tools can validate JDBC resource modules based on the schema.

Simplified JDBC Resource Configuration

In WebLogic Server 9.0, the number of JDBC resource types was reduced to simplify JDBC configuration and to reduce the likelihood of configuration errors. Instead of configuring a JDBC connection pool and then configuring a data source or tx data source to point to the connection pool and bind to the JNDI tree, you configure a data source that encompasses a connection pool.

Note: Because of the new configuration design, you can no longer have multiple data sources that point to a single connection pool. Instead, you can create additional data sources, each with its own pool of connections, or you can bind a single data source to the JNDI tree with multiple names. See Binding a Data Source to the JNDI Tree with Multiple Names for more information.

MultiPool configuration has also been simplified in WebLogic Server 9.0. MultiPools are replaced by multi data sources. Like MultiPools, multi data sources include a list of other JDBC resources. However, in this release you do not have to configure a separate data source to point to a multi data source to bind it to the JNDI tree. Also, if you configure the multi data source through the Administration Console, you can configure the multi data source and all encompassed data sources in one step.

As part of the JDBC resource redefinition, some new MBeans have been introduced and others have been deprecated:

For more information about configuring JDBC resources, see Configuring WebLogic JDBC Resources.

Support for the J2EE Management Model (JSR-77)

WebLogic Server 9.0 JDBC supports JSR-77, which defines the J2EE Management Model. The J2EE Management Model is used for monitoring the runtime state of a J2EE Web application server and its resources. You can access the J2EE Management Model to monitor resources, including the Weblogic JDBC system as a whole, JDBC drivers loaded into memory, and JDBC data sources.

For more details, see JDBC Management Objects in the J2EE Management Model (JSR-77 Support).

Support for Logging Last Resource and Other Transaction Options

In WebLogic Server 9.0, you can configure a JDBC data source to enable the Logging Last Resource (LLR) transaction optimization, which enables one non-XA resource to participate in a global transaction with the same ACID guarantee as XA, and can improve performance compared to XA.

The LLR optimization can improve performance by:

When a connection from a data source configured for LLR participates in a global transaction, the WebLogic Server transaction manager calls prepare on all other (XA-compliant) transaction participants, writes the commit record on the LLR participant in a database table while committing the transaction on the LLR participant as a one-phase commit, then calls commit on all other transaction participants.

The Logging Last Resource optimization maintains data integrity by writing the transaction log on the LLR participant. If the transaction fails during the one-phase commit, the WebLogic Server transaction manager will roll back the transaction on all other transaction participants.

For more information about the Logging Last Resource option, seeUnderstanding the Logging Last Resource Transaction Option.

Credential Mapping for WebLogic Server User IDs to Database User IDs

Credential mapping for a JDBC data source is the process in which WebLogic Server user IDs are mapped to database user IDs. If credential mapping is enabled on the data source, when an application requests a database connection from the data source, WebLogic Server determines the current WebLogic Server user ID and then sets the mapped database ID as a light-weight client ID on the database connection.

This feature relies on features in the JDBC driver and DBMS. It is only supported for use with Oracle and DB2 databases and with the Oracle Thin and DB2 UDB JDBC drivers, respectively.

For more information, see Configuring Credential Mapping for a Data Source.

Other Data Source/Connection Pool Enhancements

SQL Statement Timeout Enhancements for Pooled JDBC Connections

In WebLogic Server 9.0, the following attributes were added to JDBC data source pool of connections to enable you to limit the amount of time that a statement can execute on a pooled database connection:

For more information, see Limiting Statement Processing Time with Statement Timeout.

Connection Testing Enhancements

In WebLogic Server 9.0, along with some internal connection testing enhancements, the following feature was added to JDBC data source pool of connections to improve the functionality of database connection testing for pooled connections and to minimize delays in connection request handling:

See Connection Testing Options for a Data Source for more information.

Clean Server Shutdown When Database Connections are In Use

In WebLogic Server 9.0, the IgnoreInUseConnections attribute was added to JDBC data sources to enable WebLogic Server to ignore database connections that are in use when shutting down a server instance. When this attribute is set to true, WebLogic Server ignores any database connections in use and shuts down the server without issue. When set to false, WebLogic Server waits for in-use connections to be returned to the pool of connections.

PinnedToThread Property

To minimize the time it takes for an application to reserve a database connection from a data source and to eliminate contention between threads for a database connection, you can add the PinnedToThread property in the connection Properties list for the data source, and set its value to true. See Using Pinned-To-Thread Property to Increase Performance.

Support for Oracle Virtual Private Databases

WebLogic Server 9.0 provides support for Oracle Virtual Private Databases (VPDs). A VPD is means to control access to data based on the user's identity. WebLogic Server uses JDBC extensions in the Oracle thin driver to set the user credentials on a database connection.

See "Programming with Oracle Virtual Private Databases" in Programming WebLogic JDBC for more information.

Multiple JNDI Names for Data Sources

You can configure a data source so that it binds to the JNDI tree with multiple names. You can use a data source with multiple JNDI names to replace a configuration from previous WebLogic Server releases in which more than one data source pointed to a single JDBC connection pool.

For more details, see Binding a Data Source to the JNDI Tree with Multiple Names.

Support for XAResource Transaction Timeout

The WebLogic Server Transaction Manager now supports setting a transaction branch timeout value on a participating XA resource if the resource manager supports the javax.transaction.xa.XAResource.setTransactionTimeout() method. You may want to set a transaction branch timeout if you have long-running transactions that exceed the default timeout value on the XA resource.

For the WebLogic Server Transaction Manager to set the transaction timeout on a JDBC XA resource, specify a value for the following properties in the JDBC data source:

These properties apply to data sources that use an XA JDBC driver to create database connections only. They are ignored if a non-XA JDBC driver is used.

When these values are set, the WebLogic Server Transaction Manager calls XAResource.setTransactionTimeout() as described above. The implementation of the method in the XA resource manager (for example, an XA JDBC driver) or the XA resource determines how the value is used. For example, for Oracle, the setTransactionTimeout() method sets the Session Timeout (SesTm), which acts as a maximum idle time for a transaction. The behavior may be different for other XA Resources.

use-xa-data-source-interface Property for Data Sources

In WebLogic Server 9.0, the use-xa-data-source-interface data source property was introduced to enable you to specify the use of the XA version of a JDBC driver if the driver uses the same classname for both XA and non-XA use.

Multi Data Source Enhancements

The following multi data source enhancements were added in WebLogic Server 9.0:

XA Support in Multi Data Sources

In WebLogic Server 9.0, JDBC multi data sources are supported for use in XA transactions with Oracle Real Application Clusters (RAC).

For more information about configuring multi data sources, see Configuration Options in WebLogic Server with Oracle RAC and XA Considerations and Limitations with Oracle RAC.

JDBC Multi Data Source Failover Enhancements

In WebLogic Server 9.0, the following enhancements were made to JDBC multi data sources:

See Multi Data Source Failover Enhancements for more details.

HIGH AVAILABILITY Multi Data Source Algorithm Renamed FAILOVER

In WebLogic Server 9.0, the multi data source HIGH AVAILABILITY algorithm option was renamed to FAILOVER. The new name is more indicative of the behavior of the multi data source with this algorithm selection.

New WLST Script Examples for JDBC Administration

WebLogic Server 9.0 ships with a WLST script example that shows how to perform administrative tasks previously available in the weblogic.Admin utility. For example, creating a data source, resetting the pooled database connections in a data source, and so forth.

JDBC Monitoring and Diagnostics Enhancements

The following enhancements for monitoring JDBC activity and diagnosing JDBC issues were added in WebLogic Server 9.0 to help you easily monitor JDBC resources and diagnose problems:

New Monitoring Statistics and Profile Information for JDBC Data Sources

In WebLogic Server 9.0, new data source usage information was made available through the Administration Console or through JMX to help you monitor and tune your environment, including:

In WebLogic Server 9.0, the following new prepared statement cache statistics and usage profile information is available through the Administration Console or through JMX:

Callbacks for Monitoring Driver-Level Statistics

WebLogic Server 9.0 provides callbacks for methods called on a JDBC driver. You can use these callbacks to monitor and profile JDBC driver usage, including methods being executed, any exceptions thrown, and the time spent executing driver methods.

To enable the callback feature, you specify the fully qualified path of the callback handler for the driver-interceptor element in the JDBC data source descriptor (module). Your callback handler must implement the weblogic.jdbc.extensions.DriverInterceptor interface. When JDBC driver callbacks are enabled, WebLogic Server calls the preInvokeCallback(), postInvokeExceptionCallback(), and postInvokeCallback() methods of the registered callback handler before and after invoking any method inside the JDBC driver.

JDBC Debugging Enhancements

In Weblogic Server 9.0, the JDBC subsystem uses the new debugging and diagnostics system for centralized debug access and logging. The following JDBC debugging options are available:

See Monitoring WebLogic JDBC Resources, for more information.

Updated WebLogic Type 4 JDBC Drivers

WebLogic Server includes updates to the WebLogic Type 4 JDBC drivers. The updated drivers resolve some important issues and include some notable enhancements. See WebLogic Type 4 JDBC Drivers for more information.

Removed, Deprecated, and Changed JDBC Features, Methods, Interfaces, and MBeans

In WebLogic Server 9.0, many changes were made to the JDBC subsystem, including the removal of some drivers and classes and the deprecation of some MBeans.


The following items were removed in WebLogic Server 9.0:

For a complete list of removed APIs, see "Deprecated and Removed APIs" in Upgrading WebLogic Application Environments.

The following configuration attributes have been removed:

Functionality from the following attributes has been moved to other attributes. These attributes have been removed to help simplify JDBC data source configuration:

Deprecated Features

The following items were deprecated in WebLogic Server 9.0:

Deprecated MBeans

The following MBeans were deprecated in WebLogic Server 9.0:

Changed Features and Behavior

The following changes were made to JDBC data source and connection pool features:


Skip navigation bar  Back to Top Previous Next