3 Configuring JDBC Data Sources

In WebLogic Server, you configure database connectivity by adding JDBC data sources to your WebLogic domain. Configuring data sources requires several steps including choosing a type of data source, creating the data source, configuring connection pools and Oracle database parameters and so on.

This chapter describes the steps required to create and configure JDBC connection pools. It includes the following topics:

Understanding JDBC Data Sources

In WebLogic Server, you configure database connectivity by adding data sources to your WebLogic domain. WebLogic JDBC data sources provide database access and database connection management.

Each data source contains a pool of database connections that are created when the data source is created and at server startup. Applications reserve a database connection from the data source by looking up the data source on the JNDI tree or in the local application context and then calling getConnection(). When finished with the connection, the application should call connection.close() as early as possible, which returns the database connection to the pool for other applications to use.

Types of WebLogic Server JDBC Data Sources

WebLogic Server provides five types of data sources such as Generic data source, Active GridLink (AGL) data source, Multi data source (MDS), Proxy data source and Universal Connection Pool (UCP) data source.
  • Generic data sources—Generic data sources and their connection pools provide connection management processes that help keep your system running efficiently.You can set options in the data source to suit your applications and your environment.

  • Active GridLink (AGL) data sources—A datasource that provides a connection pool that spans one or more nodes in one or more Oracle RAC clusters. It supports dynamic load balancing of connections across the nodes and handles events that indicates nodes that are added and removed from the cluster(s). See Using Active GridLink Data Sources.

  • Multi data sources (MDS)—A multi data source is an abstraction around a group of generic data sources that provides load balancing or failover processing. See Configuring JDBC Multi Data Sources.

  • Proxy data source—A data source that provides the ability to switch between databases in a WebLogic Server Multitenant environment. See Using Proxy Data Sources..

  • Universal Connection Pool (UCP) data source—A UCP data source is provided as an option for users who wish to use Oracle Universal Connection Pooling (UCP) to connect to Oracle Databases. UCP provides an alternative connection pooling technology to Oracle WebLogic Server connection pooling. See Using Universal Connection Pool Data Sources.

Creating a JDBC Data Source

WebLogic JDBC data sources provide database access and database connection management. You can create JDBC data sources in your WebLogic domain using the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST).

To create JDBC data sources using the WebLogic Server Administration Console or the WebLogic Scripting Tool (WLST):

  • Create a JDBC Data Source in the Oracle WebLogic Server Administration Console Online Help.
  • WebLogic Server JDBC Data Sources in Administering Oracle WebLogic Server with Fusion Middleware Control.
  • The sample WLST script EXAMPLES_HOME\wl_server\examples\src\examples\wlst\online\jdbc_data_source_creation.py, where EXAMPLES_HOME represents the directory in which the WebLogic Server code examples are configured. See WLST Online Sample Scripts in Understanding the WebLogic Scripting Tool.

Data source configuration in the Weblogic Server Administration Console is done using the Data Source configuration wizard. The following sections provide an overview of the information required by the wizard to create a data source.

JDBC Data Source Properties

JDBC Data Source Properties include options that determine the identity of the data source and the way the data is handled on a database connection.

Data Source Names

JDBC data source names are used to identify the data source within the WebLogic domain. For system resource data sources, names must be unique among all other JDBC system resources. To avoid naming conflicts, data source names should also be unique among other configuration object names, such as servers, applications, clusters, and JMS queues, topics, and servers. For JDBC application modules packaged in an application, data source names must be unique among JDBC data sources that are similarly scoped.

Data Source Scope

Select the scope for the data source from the list of available scopes. You can set the scope to Global (at the domain level), or to any existing Resource Group or Resource Group Template.

JNDI Names

You can configure a data source so that it binds to the JNDI tree with a single or multiple names. See Developing JNDI Applications for Oracle WebLogic Server.

Selecting a Database Type

Select a DBMS. For information about supported databases, see Supported Configurations in What's New in Oracle WebLogic Server.

Selecting a JDBC Driver

When creating a JDBC data source using the WebLogic Server Administration Console, you are prompted to select a JDBC driver class. The WebLogic Server Administration Console provides most of the more common driver class names and in most cases tries to help you construct the URL as required by the driver. You should verify, however, that the URL is as you want it before asking the console to test it. The driver you select must be in the classpath on all servers on which you intend to deploy the data source. Some but not all JDBC drivers listed in the WebLogic Server Administration Console are shipped (and/or are already in the classpath) with WebLogic Server:

  • Oracle Thin Drivers

    This table lists the nine Oracle Thin Drivers, a sample of the URL format that is generated from the input provided by the user, and the class name of the driver configured.
    Oracle Drivers URL Format Description Driver Class Name
    Oracle’s Driver (Thin XA) for Application Continuity; Versions: Any jdbc:oracle:thin:@hostname:port/service Database is used as service name. oracle.jdbc.replay.OracleXADataSourceImpl
    Oracle’s Driver (Thin XA) for Instance connections; Versions: Any jdbc:oracle:thin:@hostname:port:SID Database is used as SID, the use of SID is deprecated. Use service name instead of SID in this format. oracle.jdbc.xa.client.OracleXADataSource
    Oracle’s Driver (Thin XA) for RAC Service-Instance connections; Versions: Any jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=hostname))) (CONNECT_DATA=(SERVICE_NAME=service)(INSTANCE_NAME=instance))) Use this format when the service is available on multiple instances and the URL should map to a single instance for Generic and Multi Datasource. A long format URL is generated so that you can specify instance name. oracle.jdbc.xa.client.OracleXADataSource
    Oracle’s Driver (Thin XA) for Service connections; Versions: Any jdbc:oracle:thin:@//hostname:port/service Database is used as service, slash precedes the service name. oracle.jdbc.xa.client.OracleXADataSource
    Oracle’s Driver (Thin) for Application Continuity; Versions: Any jdbc:oracle:thin:@//hostname:port/ service Database is used as service. oracle.jdbc.replay.OracleDataSourceImpl
    Oracle’s Driver (Thin) for Instance connections; Versions: Any jdbc:oracle:thin:@hostname:port:SID Database is used as SID, the use of SID is deprecated. Use the service name instead of SID in this format. oracle.jdbc.OracleDriver
    Oracle’s Driver (Thin) for Service connections; Versions: Any jdbc:oracle:thin:@//hostname:port/service Database is used as service. This is the default and most popular format for Generic data sources. The service should be available on a single instance for Generic and Multi Datasource. oracle.jdbc.OracleDriver
    Oracle’s Driver (Thin) for Service-Instance connections; Versions: Any jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=port))) (CONNECT_DATA=(SERVICE_NAME=service)(INSTANCE_NAME=instance)) Database is used as instance. oracle.jdbc.OracleDriver
    Oracle’s Driver (Thin) for pooled instance connections; Versions: Any jdbc:oracle:thin:@hostname:port:SID Database is used as SID. Use this format to get a pooled data source, this is not a very commonly used format. oracle.jdbc.pool.OracleDataSource
  • MySQL (non-XA)

  • Third-party JDBC drivers (see Using JDBC Drivers with WebLogic Server ):

  • WebLogic-branded DataDirect drivers for the following database management systems (see Using WebLogic-branded DataDirect Drivers ):

    • DB2

    • Informix

    • Microsoft SQL Server

    • Sybase

All of these drivers are referenced by the weblogic.jar manifest file and do not need to be explicitly defined in a server's classpath.

When deciding which JDBC driver to use to connect to a database, you should try drivers from various vendors in your environment. In general, JDBC driver performance is dependent on many factors, especially the SQL code used in applications and the JDBC driver implementation.

For information about supported JDBC drivers, see Supported Configurations in What's New in Oracle WebLogic Server.

Note:

JDBC drivers listed in the WebLogic Server Administration Console when creating a data source are not necessarily certified for use with WebLogic Server. JDBC drivers are listed as a convenience to help you create connections to many of the database management systems available.

You must install JDBC drivers in order to use them to create database connections in a data source on each server on which the data source is deployed. Drivers are listed in the WebLogic Server Administration Console with known required configuration options to help you configure a data source. The JDBC drivers in the list are not necessarily installed. Driver installation can include setting system Path, Classpath, and other environment variables. See Adding Third-Party JDBC Drivers Not Installed with WebLogic Server .When a JDBC driver is updated, configuration requirements may change. The WebLogic Server Administration Console uses known configuration requirements at the time the WebLogic Server software was released. If configuration options for your JDBC driver have changed, you may need to manually override the configuration options when creating the data source or in the property pages for the data source after it is created.

Configure Transaction Options

When you configure a JDBC data source using the WebLogic Server Administration Console, WebLogic Server automatically selects specific transaction options based on the type of JDBC driver:

  • For XA drivers, the system automatically selects the Two-Phase Commit protocol for global transaction processing.

  • For non-XA drivers, local transactions are supported by definition, and WebLogic Server offers the following options

    Supports Global Transactions: (selected by default) Select this option if you want to use connections from the data source in global transactions, even though you have not selected an XA driver. See Enabling Support for Global Transactions with a Non-XA JDBC Driver.

    When you select Supports Global Transactions, you must also select the protocol for WebLogic Server to use for the transaction branch when processing a global transaction:

    • Logging Last Resource: With this option, the transaction branch in which the connection is used is processed as the last resource in the transaction and is processed as a local transaction. Commit records for two-phase commit (2PC) transactions are inserted in a table on the resource itself, and the result determines the success or failure of the prepare phase of the global transaction. This option offers some performance benefits and greater data safety than Emulate Two-Phase Commit, but it has some limitations. See Understanding the Logging Last Resource Transaction Option.

      Note:

      Logging Last Resource is not supported for data sources used by a multi data source except when used with Oracle RAC version 10g Release 2 (10gR2) and greater versions as described in Administrative Considerations and Limitations for LLR Data Sources.

    • Emulate Two-Phase Commit: With this option, the transaction branch in which the connection is used always returns success for the prepare phase of the transaction. It offers performance benefits, but also has risks to data in some failure conditions. Select this option only if your application can tolerate heuristic conditions. See Understanding the Emulate Two-Phase Commit Transaction Option.

    • One-Phase Commit: (selected by default) With this option, a connection from the data source can be the only participant in the global transaction and the transaction is completed using a one-phase commit optimization. If more than one resource participates in the transaction, an exception is thrown when the transaction manager calls XAResource.prepare on the 1PC resource.

For more information on configuring transaction support for a data source, see JDBC Data Source Transaction Options.

Configure Connection Properties

Connection Properties are used to configure the connection between the data source and the DBMS. Typical attributes are the database name, host name, port number, user name, and password.

Note:

You can use a Single Client Access Name (SCAN) address to represent the host name. When using Oracle RAC 11.2 and higher, consider the following:

  • If the Oracle RAC REMOTE_LISTENER your data source connects to is set to SCAN, the data source connection url can only use a SCAN address.

  • If the Oracle RAC REMOTE_LISTENER your data source connects to is set to List of Node VIPs, the data source connection url can only use a list of VIP addresses.

  • If the Oracle RAC REMOTE_LISTENER your data source connects to is set to Mix of SCAN and List of Node VIPs, the data source connection url can use both SCAN and VIP addresses.

For more information on using SCAN addresses, see "Introduction to Automatic Workload Management" in Real Application Clusters Administration and Deployment Guide 11g Release 2 (11.2).

Configuring Connection Properties for Oracle BI Server

If you selected Oracle BI Server as your DBMS, configure the additional connection properties on the Connection Properties page as described in Connection String in Oracle Business Intelligence Publisher Administrator's and Developer's Guide.

Test Connections

Test Database Connection allows you to test a database connection before the data source configuration is finalized using a table name or SQL statement. If necessary, you can test additional configuration information using the Properties and System Properties attributes.

Target the Data Source

You can select one or more targets to which to deploy your new JDBC data source. If you don't select a target, the data source will be created but not deployed. You will need to deploy the data source at a later time before getting connections.

Configuring Generic Connection Pool Features

Each JDBC data source has a pool of JDBC connections that are created when the data source is deployed or at server startup. Applications use a connection from the pool then return it when finished using the connection. Connection pooling enhances performance by eliminating the costly task of creating database connections for the application.

Note:

If a non-dynamic data source attribute is updated, the data source needs to be undeployed or redeployed for the attribute to take effect. To determine whether an attribute is dynamic or non-dynamic, see the MBean reference MBean Reference for Oracle WebLogic Server for the attribute. If the attribute definition contains the Redeploy or Restart required text, then it is a non-dynamic attribute.

The following sections include information about connection pool options for a JDBC data source. Some of these options are dynamically changeable and others are non-dynamic.

You can see more information and set these and other related options through the:

Note:

Certain Oracle JDBC extensions, and possibly other non-standard methods available from other drivers may durably alter a connection's behavior in a way that future users of the pooled connection will inherit. WebLogic Server attempts to protect connections against some types of these calls when possible.

Enabling JDBC Driver-Level Features

WebLogic JDBC data sources support the javax.sql.ConnectionPoolDataSource interface implemented by JDBC drivers. You can enable driver-level features by adding the property and its value to the Properties attribute in a JDBC data source. Driver-level properties in the Properties attribute are set on the driver's ConnectionPoolDataSource object.

Enabling Connection-based System Properties

WebLogic JDBC data sources support setting driver properties using the value of system properties. The value of each property is derived at runtime from the named system property. You can configure connection-based system properties using the WebLogic Server Administration Console by editing the System Properties attribute of your data source configuration.

If a system property value is set, it overrides an encrypted property value, which overrides a normal property value (you can only have one property value for each property name).

A system property value can contain one of the variables listed in Table 3-1. If one or more of these variables is included in the system property, it is substituted with the corresponding value. If a value is not found, no substitution is performed. If none of these variables are found in the system property, then the value is taken as a system property name.

Table 3-1 Variables Supported in System Property Values for JDBC Data Source

Variable Value Description

${pid}

First half (up to @) of ManagementFactory.getRuntimeMXBean().getName()

${machine}

Second half of ManagementFactory.getRuntimeMXBean().getName()

${user.name}

Java system property user.name

${os.name}

System property os.name

${datasourcename}

Data source name from the JDBC descriptor. It does not contain the partition name.

${partition}

Partition name or DOMAIN

${serverport}

WebLogic Server server listen port

${serversslport}

WebLogic Server server SSL listen port

${servername}

WebLogic Server server name

${domainname}

WebLogic Server domain name

A sample set of properties is shown in the following example:

<properties>
<property>
  <name>user</name>
  <sys-prop-value>user</sys-prop-value>
</property>
<property>
  <name>v$session.osuser</name>
  <sys-prop-value>${user.name}</sys-prop-value>
</property>
<property>
  <name>v$session.process</name>
  <sys-prop-value>${pid}</sys-prop-value>
</property>
<property>
  <name>v$session.machine</name>
  <sys-prop-value>${machine}</sys-prop-value>
</property>
<property>
  <name>v$session.terminal</name>
  <sys-prop-value>${datasourcename}</sys-prop-value>
</property>
<property>
  <name>v$session.program</name>
  <sys-prop-value>WebLogic ${servername} Partition ${partition}</sys-prop-value>
</property>
</properties>

In this example:

  • user is set to the value of -Duser=value

  • v$session values are set as described in Table 3-1

    For example, v$session.program running on myserver is set to WebLogic myserver Partition DOMAIN

Note that the values have the following length limitations:

  • osuser—30

  • process—24

  • machine—64

  • terminal—30

  • program—48

Enabling Connection-based Encrypted Properties

WebLogic JDBC data sources support setting driver properties using encrypted values. You can configure connection-based encrypted properties using the WebLogic Server Administration Console by editing the Encrypted Properties attribute of your data source configuration. See Using Encrypted Connection Properties.

Initializing Database Connections with SQL Code

When WebLogic Server creates database connections in a data source, the server can automatically run SQL code to initialize the database connection. To enable this feature, enter SQL followed by a space and the SQL code you want to run in the Init SQL attribute on the JDBC Data Source: Configuration: Connection Pool page in the WebLogic Server Administration Console. Alternatively, you can specify simply a table name without SQL and the statement SELECT COUNT(*) FROM tablename is used. If you leave this attribute blank (the default), WebLogic Server does not run any code to initialize database connections.

WebLogic Server runs this code whenever it creates a database connection for the data source, which includes at server startup, when expanding the connection pool, and when refreshing a connection.

You can use this feature to set DBMS-specific operational settings that are connection-specific or to ensure that a connection has memory or permissions to perform required actions.

Start the code with SQL followed by a space. An Oracle DBMS example:

SQL alter session set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'

or an Informix DBMS:

SQL SET LOCK MODE TO WAIT

The SQL statement is executed using JDBC Statement.execute(). Options that you can set using InitSQL vary by DBMS. See the documentation for your database vendor for supported statements. If you want to execute multiple statements, you may want to create a stored procedure and execute it. The syntax is vendor specific. For example, to execute an Oracle stored procedure:

SQL CALL MYPROCEDURE()

Advanced Connection Properties

You can set up advance connection properties like fatal error codes and use of Edition-Based Redefinition (EBR). You define fatal error codes which indicate the database server with which the data source communicates is no longer accessible on a connection. EBR provides the ability to upgrade the database component of an application while it is in use, thereby minimizing or eliminating down time.

The following sections highlight some important advanced connection properties.

Define Fatal Error Codes

You can define fatal error codes that indicate that the database server with which the data source communicates is no longer accessible on a connection. The connection is marked invalid and taken out of the pool but the data source is not suspended. These errors include deployment errors that cause a server to fail to boot and connection errors that prevent a connection from being put back in the connection pool.

When specified as the exception code within a SQLException (retrieved by sqlException.getErrorCode()), it indicates that a fatal error has occurred, the connection is no longer good, and it is removed from the connection pool. For Oracle databases the following fatal error codes are predefined within WLS and do not need to be placed in the configuration file:

Error Code Description

3113

end-of-file on communication channel

3114

not connected to ORACLE

1033

ORACLE initialization or shutdown in progress

1034

ORACLE not available

1089

immediate shutdown in progress - no operations are permitted

1090

shutdown in progress - connection is not permitted

17002

I/O exception

For DB2, the following fatal error codes are predefined: -4498, -4499, -1776, -30108, -30081, -30080, -6036, -1229, -1224, -1035, -1034, -1015, -924, -923, -906, -518, -514, 58004.

For Informix, the following fatal error codes are predefined: -79735, -79716, -43207, -27002, -25580, -4499, -908, -710, 43012.

To define fatal error codes in the WebLogic Server Administration Console, see Define Fatal Error Codes in Oracle WebLogic Server Administration Console Online Help.

Using Edition-Based Redefinition

Edition-based redefinition (EBR) provides the ability to upgrade the database component of an application while it is in use, thereby minimizing or eliminating down time. It allows a pre-upgrade and post-upgrade view of the data to exist at the same time, providing a hot upgrade capability. You can then specify which view you want for a particular session.

See:

Using EBR with JDBC Connections

There are two approaches to using EBR with JDBC connections:

  • If you use a database service to connect to the database and an initial session edition was specified for that service, then the initial session edition for the service is your initial session edition on the connection. This approach is recommended for minimal overhead on the connection.

    When you create or modify a database service, you can specify its initial session edition. To create or modify a database service, Oracle recommends using the srvctl add service or srvctl modify service command. To specify the default initial session edition of the service, use the -edition option.

    Alternatively, you can create or modify a database service with the DBMS_SERVICE.CREATE_SERVICE or DBMS_SERVICE.MODIFY_SERVICE procedure, and specify the default initial session edition of the service with the EDITION attribute.

  • Changing your session edition after connecting to the database using the SQL statement ALTER SESSION SET EDITION. You can change your session edition to any edition on which you have the USE privilege. Note that changing the edition can require re-generating a significant amount of state on session and database server. Oracle recommends using DBMS_SESSION.RESET_PACKAGE to clean-up some of this state when changing the edition on a session.

Using Edition-based redefinition does not require any new WebLogic Server functionality.

To make use of EBR, your environment needs to consist of an earlier version of the application with a data source that references the earlier EDITION and a later version of the application with a data source that references the later EDITION. When referring to multiple versions of a WebLogic Server application, you should be using WebLogic Server versioned applications in the production redeployment feature. See Developing Applications for Production Redeployment in Developing Applications for Oracle WebLogic Server. By combining Oracle database EBR and WebLogic Server versioned applications, the application can be upgraded with no downtime, making the combination of features more powerful than either feature independently.

You need to run with a versioned database and a versioned application initially so that you can switch versions. To version a WebLogic Server application, simply add the Weblogic-Application-Version property in the MANIFEST.MF file (you can also specify it at deployment time).

Configuring WebLogic Data Sources to Use Editions

The following list describe the different ways you can configure WebLogic data sources to use Oracle database editions.

  • Packaged Data Source Using a Single Edition—The recommended way to configure the data source is to use a packaged data source descriptor that is stored in the application EAR or WAR file so that everything is self-contained. By doing so, you can use the same name for each data source and you do not need to change the application to use a variable name based on the edition. The data source URL in the descriptor should reference the database service associated with the correct edition. If for some reason you are using a SID instead of a database service (no longer recommended), the alternative is to specify SQL ALTER SESSION SET EDITION = name in the Init SQL parameter in the data source descriptor. This SQL statement is executed for each newly created physical database connection in the data source pool. This approach assumes that a data source references only a single edition of the database and all connections use that edition.

    Note the following restrictions when using a packaged data source.

    • You cannot use a packaged data source with Logging Last Resource (LLR). You must use a system resource.

    • You cannot use an application-scoped packaged data source with EmulateTwoPhaseCommit for the global-transactions-protocol with a versioned application. You must use a global-scoped data source.

      Therefore, if you need to use LoggingLastResource or EmulateTwoPhaseCommit, you cannot use this approach. See JDBC Application Module Limitations.

  • System Resource Data Source Using a Single Edition—You can use a system resource as an alternative to a packaged data source. In this case, each data source must have a unique name and JNDI name. The application needs to be flexible enough to use that name at runtime. For example, you can pass in the data source JNDI name as a system property and the code that looks up the data source in JNDI will use that value.

    The disadvantage of using a single edition per data source, whether packaged or as a system resource, is that it requires more database connections. A single edition approach can work when the period during which the old and new editions are running is relatively short. For applications that are using a lot of data sources and/or connections, this is not a viable approach.

  • System Resource Data Source Using Multiple Editions—An alternative is to have a data source that references multiple editions. The recommended configuration would still use a database service associated with a single edition. However, the connections will be re-associated with different editions during the lifetime of the connection.

  • Multiple Editions by Setting the Edition for Every Reservation—It is possible for the application to set the database edition every time it gets a connection. There is some overhead associated with making this call each time (round trip to the database server and setting the session) and the application code needs to be modified everywhere that a connection is reserved. If you are using the replay driver, this initialization should be done in the ConnectionInitializationCallback. See Using a Connection Callback.

    It's important to optimize for the normal use case instead of optimizing for the (hopefully) short period during which the migration is done to a new edition. This approach doesn't optimize for the normal case where all connections are on the needed edition.

  • Multiple Editions using Connection Labeling—You can also associate an edition with the connection and try to reserve a connection with the correct edition. The recommended way to tag a connection with a property is to use connection labeling. The application then needs to implement the pieces associated with connection labeling.

    • When a connection is reserved, it needs to determine the edition needed in the context.

    • A matching method is needed to determine if the property, in this case just the edition, matches.

    • A labeling initialization method is needed to make the connection match if it doesn't already match by using SQL ALTER SESSION SET EDITION = name.

    There is overhead associated with connection labeling, particularly when exclusively scanning the list of existing connections to find a mach. On the other hand, the normal use case is that every connection matches the current edition so there is no need to look far to find a match. It is only during migration that there will be thrashing between editions and potentially longer searches to find a match (or to determine that there is no match).

Configuring Oracle Parameters

WebLogic Server provides several attributes that provide improved Data Source performance when using Oracle drivers.

For detailed information on how to configure Oracle parameters, see Advanced Configurations for Oracle Drivers and Databases

Configuring an ONS Client

Configuring an ONS client changes a generic data source to an AGL data source.

For more detailed configuration information and additional environment requirements, see Using Active GridLink Data Sources.

Tuning Generic Data Source Connection Pools

You can improve application and system performance by ensuring a proper configuration of the connection pool attributes in JDBC data sources in your WebLogic Server domain.

For detailed information on tuning generic data source connection, see Tuning Data Source Connection Pools.

Generic Data Source Handling for Oracle RAC Outages

It is possible to use a Generic data source with Oracle RAC with some limitations. These limitations complicate transaction processing, monitoring, and graceful handling of RAC outages.

Note:

Oracle recommends using a Multi Data Source or Active GridLink data source instead of a Generic data source using driver-level failover. See Using Active GridLink Data Sources or Using Multi Data Sources with Oracle RAC.

The following limitations are due to WebLogic Server instances not being aware of the RAC instances associated with the connections in the pool:

  • A generic data source does not have the ability to disable a single instance in the pool that a Multi Data Source or Active GridLink data source provides. If one of the RAC instances goes down (planned or unplanned), the data source tests all connections in the pool for the down instance, disabling them individually. In addition to more overhead and application delays, the pool sees multiple failures which cause the entire pool to be disabled. To prevent the pool from being disabled, set the value of Count Of Test Failures Till Flush to 0. See the JDBC Data Source: Configuration: Connection Pool page in the WebLogic Server Administration Console or see JDBCConnectionPoolParamsBean in the MBean Reference for Oracle WebLogic Server.

  • JTA or global transactions should not be used with this configuration. Because WebLogic Server is not aware of the RAC instances, it cannot guarantee transaction affinity. This is a problem if the transaction spans multiple servers or if a failure occurs such that another connection is used to complete the transaction. Since the additional connections required to complete the transaction may not be within the same RAC instance, transaction processing may fail.

  • It is not possible to monitor the connections based on the RAC instances.

Generic Data Source Handling of Driver-Level Failover

Several database drivers support a feature to define multiple database instances in the URL and failover from one database to the next. It possible to use a Generic data source with driver-level failover with some limitations. These limitations complicate transaction processing, monitoring, and graceful handling of database instance outages.

The following limitations are due to WebLogic Server instances not being aware of the database instances associated with the connections in the pool:

  • A generic data source does not have the ability to disable a single instance in the pool that a Multi Data Source provides. If one of the database instances goes down (planned or unplanned), the data source tests all connections in the pool for the down instance, disabling them individually. In addition to more overhead and application delays, the pool sees multiple failures which cause the entire pool to be disabled. To prevent the pool from being disabled, set the value of Count Of Test Failures Till Flush to 0. For more information, see:

  • JTA or global transactions should not be used with this configuration. Because WebLogic Server is not aware of the database instances, it cannot guarantee transaction affinity. This is a problem if the transaction spans multiple servers or if a failure occurs such that another connection is used to complete the transaction. Since the additional connections required to complete the transaction may not be within the same database instance, transaction processing may fail.

  • It is not possible to monitor the connections based on the database instances.