Configuring and Managing WebLogic JDBC
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.
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.
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.
WebLogic Server 9.0 optionally installs API code examples in
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.
For more information, see the Java JDBC technology page on the Sun Web site at http://java.sun.com/products/jdbc/.
javax.sql.rowset.spi.SyncResolverinterface and is used to resolve conflicts that occur when data updates in the database conflict with data updates in the rowset.
For more information about rowsets, see the Java JDBC technology page on the Sun Web site at http://java.sun.com/products/jdbc/. For more information about using rowsets and the WebLogic Server RowSets implementation, see "Using RowSets with WebLogic Server" in Programming WebLogic JDBC.
javax.sql.rowset.Predicateinterface. that you can use to define a filter for a FilteredRowSet using SQL-like WHERE clause syntax.
For more information about using JDBC RowSets and the WebLogic Server RowSets implementation, see "Using RowSets with WebLogic Server" in Programming WebLogic JDBC.
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.
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.
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.
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.)
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.
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.
JDBCTxDataSourceMBeantypes, which are now deprecated.
JDBCConnectionPoolRuntimeMBeantype, which is now deprecated.
For more information about configuring JDBC resources, see Configuring WebLogic JDBC Resources.
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.
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.
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 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.
For more information, see Configuring Credential Mapping for a Data Source.
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:
StatementTimeout—The time in seconds after which a statement executing on a pooled JDBC connection times out. When set to -1, (the default) statements do not time out.
TestStatementTimeout—The time in seconds after which a statement executing on a pooled JDBC connection for connection initialization or testing times out. When set to -1, (the default) statements do not time out.
For more information, see Limiting Statement Processing Time with Statement Timeout.
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:
SecondsToTrustAnIdlePoolConnection—Enables WebLogic Server to skip testing a database connection if the connection was successfully used within the period of time specified. This feature can increase performance by minimizing database connection testing.
See Connection Testing Options for a Data Source for more information.
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.
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.
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.
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.
The WebLogic Server Transaction Manager now supports setting a transaction branch timeout value on a participating XA resource if the resource manager supports the
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.
XASetTransactionTimeout—A boolean property. When set to true, the WebLogic Server Transaction Manager calls
XAResource.start, and passes either the
XATransactionTimeoutor the global transaction timeout in seconds. When set to false, the Transaction Manager does not call
setTransactionTimeout(). The default value is false.
XATransactionTimeout—The number of seconds to pass as the transaction timeout value in the
setTransactionTimeout()method. When this property is set to
0, the WebLogic Server Transaction Manager passes the global WebLogic Server transaction timeout in seconds in the method. The default value for this parameter is
0. If set, this value should be greater than or equal to the global Weblogic Server transaction timeout.
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.
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.
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.
See Multi Data Source Failover Enhancements for more details.
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.
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.
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
postInvokeCallback() methods of the registered callback handler before and after invoking any method inside the JDBC driver.
See Monitoring WebLogic JDBC Resources, for more information.
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.
For a complete list of removed APIs, see "Deprecated and Removed APIs" in Upgrading WebLogic Application Environments.
weblogic.jdbc.pool.driver. The pool driver is obsolete. You should use a data source to get a database connection.
WebLogic Server now manages these attributes internally. See Connection Testing Options for a Data Source.