4 JDBC Data Sources Types

Oracle WebLogic Server provides different types of JDBC data sources such as Generic data source, Multi Data Sources, and so on. You can configure database connectivity by configuring JDBC data sources and then targeting or deploying the JDBC resources to servers or clusters in your WebLogic domain.

• Using the Default Data Source
  Oracle provides a default data source required by a Java EE 7-compliant runtime. This pre-configured data source can be used by an application to access the Derby Database installed with WebLogic Server.
• Using Generic Data Sources
  Generic data sources provide database access and database connection management. Generic data sources and their connection pools provide connection management processes that help keep your system running efficiently.
• Using JDBC Multi Data Sources
  A Multi Data Source (MDS) is an abstraction around a group of Generic data sources that is bound to the JNDI tree or local application context just like Generic data sources are bound to the JNDI tree. You can configure a MDS to provide load balancing or failover processing at the time of connection requests, between the Generic data sources associated with the MDS.
• Using Active GridLink Data Sources
  An Active GridLink (AGL) data source provides connectivity between WebLogic Server and an Oracle database. Oracle database offers both on-premises and cloud database services with cluster capabilities of Oracle Grid Infrastructure and Oracle Clusterware.
• Using Universal Connection Pool Data Sources
  A Universal Connection Pool (UCP) data source is provided as an option for users who wish to use Oracle Universal Connection Pooling to connect to Oracle Databases. UCP provides an alternative connection pooling technology to Oracle WebLogic Server connection pooling.

Using the Default Data Source

Oracle provides a default data source required by a Java EE 7-compliant runtime. This pre-configured data source can be used by an application to access the Derby Database installed with WebLogic Server.

• What is Default Data Source
  Oracle provides a default data source required by a Java EE 7-compliant runtime.
• Defining a Custom Default Data Source
  You can implement a custom default data source by defining a custom data source descriptor that is bound to java:comp/DefaultDataSource or overidding the default data source to point to another JNDI name.
• Compatibility Limitations When Using a Default Data Source
  Learn about the limitations when using a default data source.

What is Default Data Source

Oracle provides a default data source required by a Java EE 7-compliant runtime.

It is accessible under the JNDI name:

java:comp/DefaultDataSource

which is equivalent to:

@Resource(lookup="java:comp/DefaultDataSource")
DataSource myDS;

You can explicitly bind a Data Source resource reference to the Default data source using the lookup element of the resource annotation or the lookup-name element of the resource-ref deployment descriptor element.

Note:

The Derby database is started by the startWebLogic command by default. For more information on starting and stopping a WebLogic Server instance, see Starting and Stopping Servers in Administering Server Startup and Shutdown for Oracle WebLogic Server.

Characteristics of a Default Data Source

A default data source has the following characteristics:

• Must be available for each component that is deployed.

• Only accessible for deployed components, not for data sources that are system resources or stand-alone deployments.

• Only visible in a console after it has been referenced.

• Appears as a deployment for each component, like other Java EE deployments.

• Not configurable.

• Has the lifecycle of the associated application.

Configuring a Default Data Source

The following table provides the configuration settings that define the WebLogic Server default data source definition:

Table 4-1 Default Data Source Configuration

Attribute	Value
Name	java:comp/DefaultDataSource
Initial capacity	0
Min capacity	0
Max capacity	15
Classname	org.apache.derby.jdbc.ClientDataSource
Port	1527
Host	localhost
Database name	DefaultDataSource
User	none
Password	none
Transactional	false
MaxStatements	0
MaxIdleTimeout	not set

Defining a Custom Default Data Source

You can implement a custom default data source by defining a custom data source descriptor that is bound to java:comp/DefaultDataSource or overidding the default data source to point to another JNDI name.

See:

• Creating a Custom Default Data Source Descriptor
• Overriding the Default Data Source

After the component is deployed, if java:comp/DefaultDataSource is not available for the component, the WebLogic Server preconfigured default data source is available to the component. However, if you disabled the Derby database by setting DERBY_FLAG=false) before running startWebLogic.sh script, the WebLogic Server preconfigured default data source is not available.

Creating a Custom Default Data Source Descriptor

You can configure a data source descriptor that is bound to java:comp/DefaultDataSource replacing the preconfigured default data source. For example, the following provides an example of Java EE 6 annotations in a EAR application:

@Stateless(mappedName="DSBean")
@DataSourceDefinition(name="java:comp/DefaultDataSource",
className="oracle.jdbc.OracleDriver",
portNumber=1521,
serverName="myServer",
databaseName="myDB",
user="a username",
password="a password",
transactional=false
)
public class DSBean implements DSInterface
. . . 

Overriding the Default Data Source

You can override the preconfigured default data source provided by WebLogic Server by updating the JNDI name in the default data source attribute in the configuration of a server or server template to point to another existing data source.

Compatibility Limitations When Using a Default Data Source

Learn about the limitations when using a default data source.

In releases prior to Weblogic Server 12.2.1, WebLogic Server tries to satisfy unresolved data source res-ref references automatically by attempting to lookup the data source in JNDI using the name of the res-ref. This behavior is undefined prior to Java EE 7. This WebLogic Server release uses the default data source as defined by Java EE 7.

Using Generic Data Sources

Generic data sources provide database access and database connection management. Generic data sources and their connection pools provide connection management processes that help keep your system running efficiently.

• What is Generic Data Source
  Generic data sources provide database access and database connection management.
• Configuring Generic Data Source
  This topic describes the steps required to create and configure Generic data sources.

What is Generic Data Source

Generic 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.

Configuring Generic Data Source

This topic describes the steps required to create and configure Generic data sources.

Configure JDBC Data Source Properties

Data Source Names: You can use JDBCA data source name 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 with a similar scope.

Data Source Scope: You can select the scope for the data source and 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 Using WebLogic JNDI in a Clustered Environment in Developing JNDI Applications for Oracle WebLogic Server.

Database Type: You can select the Database Management System (DBMS) of the database you want to connect. See Supported Configurations in What's New in Oracle WebLogic Server.

JDBC Driver: You must select a JDBC database driver that is preferred to create a database connection. 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. See Types of JDBC Drivers.

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. See Supported Configurations in What's New in Oracle WebLogic Server.

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. XA, non-XA, and Global transaction options are supported by WebLogic JDBC data sources. See JDBC Data Source Transaction Options.

Configure Testing Options

You can set database connection testing options in a data source to make sure that the database connections remain healthy, which helps keep your applications running properly.

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.

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. See Configure testing options for a JDBC data source in Oracle FMW Administration Console Online Help.

Configure Oracle Parameters

WebLogic Server provides several attributes that provide improved data source performance when using Oracle drivers. See Advanced Configurations for Oracle Drivers and Databases.

Target JDBC Data Sources

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. See Target JDBC data sources in Oracle WebLogic Server Administration Console Online Help and Using JDBC Drivers with WebLogic Server.

Using JDBC Multi Data Sources

A Multi Data Source (MDS) is an abstraction around a group of Generic data sources that is bound to the JNDI tree or local application context just like Generic data sources are bound to the JNDI tree. You can configure a MDS to provide load balancing or failover processing at the time of connection requests, between the Generic data sources associated with the MDS.

For information about Generic data sources, see Using Generic Data Sources.

Applications lookup a MDS on the JNDI tree or in the local application context (java:comp/env) just as they do for generic data sources, and then request a database connection. The MDS determines which generic data source to use to satisfy the request depending on the algorithm selected in the MDS configuration: load balancing or failover.

Note:

Active GridLink and Multi Data Source are designed to work with Oracle RAC clusters. Oracle does not recommend using Generic data sources with Oracle RAC clusters. See Generic Data Source Handling for Oracle RAC Outages.

• What is Multi Data Source
  Multi Data Source is used for failover or load balancing between nodes of a highly available database system such as Oracle Real Application Clusters (Oracle RAC). The Generic data source member list for a MDS source supports dynamic updates. This feature allows Oracle RAC environments to add and remove database nodes and corresponding Generic data sources without redeployment, grow and shrink RAC clusters in response to throughput, and shutdown Oracle RAC node for maintenance.
• Configuring Multi Data Sources
  Perform the steps mentioned in this topic to create and configure Multi Data Source.
• Multi Data Source Failover Enhancements
  Learn how to improve failover processing for Multi Data Sources.
• Planned Database Maintenance with a Multi Data Source
  Learn how to handle planned maintenance, without service interruption, on the database server used by a Multi Data Source.
• Shutting Down the Data Source
  Shutting down the data source involves first suspending the data source and then releasing the associated resources including the connections.

What is Multi Data Source

Multi Data Source is used for failover or load balancing between nodes of a highly available database system such as Oracle Real Application Clusters (Oracle RAC). The Generic data source member list for a MDS source supports dynamic updates. This feature allows Oracle RAC environments to add and remove database nodes and corresponding Generic data sources without redeployment, grow and shrink RAC clusters in response to throughput, and shutdown Oracle RAC node for maintenance.

Note:

Multi Data Sources do not provide any synchronization between databases. It is assumed that database synchronization is handled properly outside of WebLogic Server so that data integrity is maintained.

Adding and removing database nodes is a manual operation performed by the database administrator.

• Adding a Database Node
  You can add a database node and corresponding Generic data sources without redeployment. This capability provides you the ability to start a node after maintenance or grow a cluster.
• Removing a Database Node
  You can remove a database node and corresponding Generic data sources without redeployment. This capability provides you the ability to shutdown a node for maintenance or shrink a cluster.

Adding a Database Node

You can add a database node and corresponding Generic data sources without redeployment. This capability provides you the ability to start a node after maintenance or grow a cluster.

Use the following high-level steps to add a database node:

1. Restart the database node.
2. Restart the Generic data source. See Start JDBC data sources in Oracle WebLogic Server Administration Console Online Help.
3. Add the Generic data source back to the Multi Data Source. See Add or remove data sources in a JDBC Multi Data Sources in Oracle WebLogic Server Administration Console Online Help.

Removing a Database Node

You can remove a database node and corresponding Generic data sources without redeployment. This capability provides you the ability to shutdown a node for maintenance or shrink a cluster.

Use the following high-level steps to shutdown a database node:

Note:

Failure to follow these step may cause transaction roll-backs.

1. Remove the Generic data source from the Multi Data Source. See Add or remove data sources in a JDBC multi data sources in Oracle WebLogic Server Administration Console Online Help.
2. When all transactions have completed, suspend the Generic data source. See Suspend JDBC data sources in Oracle WebLogic Server Administration Console Online Help.
3. When all transactions have completed, shut down the Generic data source. See Shut down JDBC data sources in Oracle WebLogic Server Administration Console Online Help.
4. Shut down the database node.

Configuring Multi Data Sources

Perform the steps mentioned in this topic to create and configure Multi Data Source.

1. Create Generic data sources. See Using Generic Data Sources.

2. Create the Multi Data Source using either the WebLogic Server Administration Console or the WebLogic Scripting Tool. See, Configure JDBC Multi Data Sources in the Oracle WebLogic Server Administration Console Online Help.

3. Assign the Generic data sources to the Multi Data Source.

   For information about the configuration files created when configuring a Multi Data Source, see Understanding JDBC Resources in WebLogic Server and Creating a Multi Data Source Module.

Note:

In general, if a WebLogic Server data source setting of initial capacity is set to Zero, WebLogic Server makes no DBMS connections at startup. But to startup a Multi Data Source of LLR data sources, WebLogic Server makes a connection at startup to see if the DBMS is a RAC or not. For a generic LLR Multi Data Source, all the data sources need to be available, but if it is using RAC, only one node needs to be accessible for LLR processing.

• Choosing the Multi Data Source Algorithm
  Before you set up a Multi Data Source, you need to determine the primary purpose of the Multi Data Source—failover or load balancing. You can choose the algorithm that corresponds with your requirements.
• Multi Data Source Fail-Over Limitations and Requirements
  WebLogic Server provides a failover algorithm for Multi Data Sources so that if a Generic data source fails (for example, if the database management system crashes), your system can continue to operate. However, there are certain limitations and requirements you must consider when configuring the Multi Data Source.
• Controlling Multi Data Source Failover with a Callback
  You can register a callback handler with WebLogic Server that controls when a MDS with the Failover algorithm fails over connection requests from one JDBC Generic data source in the MDS to the next Generic data source in the list.
• Deploying JDBC Multi Data Sources on Servers and Clusters
  All Generic data sources used by a Multi Data Source to satisfy connection requests must be deployed on the same servers and clusters as the Multi Data Source. A Multi Data Source always uses a Generic data source deployed on the same server to satisfy connection requests. Multi Data Sources do not route connection requests to other servers in a cluster or in a domain.

Choosing the Multi Data Source Algorithm

Before you set up a Multi Data Source, you need to determine the primary purpose of the Multi Data Source—failover or load balancing. You can choose the algorithm that corresponds with your requirements.

• Failover
  
• Load Balancing
  

Failover

The Failover algorithm provides an ordered list of Generic data sources to use to satisfy connection requests. Normally, every connection request to this kind of Multi Data Source is served by the first Generic data source in the list. If a database connection test fails and the connection cannot be replaced, or if the Generic data source is suspended, a connection is sought sequentially from the next Generic data source on the list.

Note:

This algorithm requires that Test Reserved Connections (TestConnectionsOnReserve) on the Generic data source is enabled. If enabled, a connection in the first Generic data source is tested to verify if the Generic data source is healthy. If the connection fails the test, the Multi Data Source uses a connection from the next Generic data source listed in the Multi Data Source. See Connection Testing Options for a Data Source for information about configuring TestConnectionsOnReserve.

JDBC is a highly stateful client-DBMS protocol, in which the DBMS connection and transactional state are tied directly to the socket between the DBMS process and the client (driver). For this reason, failover of a connection while it is in use is not supported.

Load Balancing

Connection requests to a load-balancing Multi Data Source are served from any Generic data source in the list. The MDS selects Generic data sources to use to satisfy connection requests using a round-robin scheme. When the MDS provides a connection, it selects a connection from the Generic data source listed just after the last Generic data source that was used to provide a connection. Multi Data Sources that use the Load Balancing algorithm also fail over to the next Generic data source in the list if a database connection test fails and the connection cannot be replaced, or if the Generic data source is suspended.

Multi Data Source Fail-Over Limitations and Requirements

WebLogic Server provides a failover algorithm for Multi Data Sources so that if a Generic data source fails (for example, if the database management system crashes), your system can continue to operate. However, there are certain limitations and requirements you must consider when configuring the Multi Data Source.

• Test Connections on Reserve to Enable Fail-Over
  
• No Fail-Over for In-Use Connections
  

Test Connections on Reserve to Enable Fail-Over

Generic data sources rely on the Test Reserved Connections (TestConnectionsOnReserve) feature on the Generic data source to know when database connectivity is lost. Testing reserved connections must be enabled for the Generic data sources within the Multi Data Source. WebLogic Server will test each connection before giving it to an application. With the Failover algorithm, the Multi Data Source uses the results from connection test to determine when to fail over to the next Generic data source in the Multi Data Source. After a test failure, the Generic data source attempts to recreate the connection. If that attempt fails, the Multi Data Source fails over to the next Generic data source.

No Fail-Over for In-Use Connections

It is possible for a connection to fail after being reserved, in which case your application must handle the failure. WebLogic Server cannot provide fail-over for connections that fail while being used by an application. Any failure while using a connection requires that the application code close the failed connection, and the transaction must be restarted from the beginning with a new connection.

Controlling Multi Data Source Failover with a Callback

You can register a callback handler with WebLogic Server that controls when a MDS with the Failover algorithm fails over connection requests from one JDBC Generic data source in the MDS to the next Generic data source in the list.

You can use callback handlers to control if or when the failover occurs so that you can make any other system preparations before the failover, such as priming a database or communicating with a high-availability framework.

Callback handlers are registered using the Failover Callback Handler attribute of the MDS and are registered per MDS. You must register the callback handler for each MDS to which you want the callback handler to apply. And you can register different callback handlers for each MDS in your domain.

• Callback Handler Requirements
  
• Callback Handler Configuration
  
• How It Works—Failover
  

Callback Handler Requirements

A callback handler used to control the failover and failback within a Multi Data Source must include an implementation of the weblogic.jdbc.extensions.ConnectionPoolFailoverCallback interface. When the Multi Data Source needs to failover to the next Generic data source in the list or when a previously disabled Generic data source becomes available, WebLogic Server calls the allowPoolFailover() method in the ConnectionPoolFailoverCallback interface, and passes a value for the three parameters, currPool, nextPool, and opcode, as defined below. WebLogic Server then waits for the return from the callback handler before completing the task.

Your application must return OK, RETRY_CURRENT, or DONOT_FAILOVER as defined below. The application should handle failover and failback cases.

See the weblogic.jdbc.extensions.ConnectionPoolFailoverCallback interface.

Note:

Failover callback handlers are optional. If no callback handler is specified in the Multi Data Source configuration, WebLogic Server proceeds with the operation (failing over or re-enabling the disabled Generic data source).

Callback Handler Configuration

There are two Multi Data Source configuration attributes associated with the failover and failback functionality:

• Failover Callback Handler (ConnectionPoolFailoverCallbackHandler)—To register a failover callback handler for a Multi Data Source, you add a value for this attribute to the Multi Data Source configuration. The value must be an absolute name, such as com.bea.samples.wls.jdbc.MultiDataSourceFailoverCallbackApplication. You can set the Failover Callback Handler using the WebLogic Server Administration Console (see Register a failover callback handler in the Oracle WebLogic Server Administration Console Online Help) or on the JDBCDataSourceParamsBean for the Multi Data Source using WLST.

• Test Frequency (TestFrequencySeconds)—To control how often the Multi Data Source checks disabled (dead) Generic data sources to see if they are now available. See Automatic Re-enablement on Recovery of a Failed Generic Data Source within a Multi Data Source for more details.

How It Works—Failover

WebLogic Server attempts to failover connection requests to the next Generic data source in the list when the current Generic data source fails a connection test or, if you enabled FailoverRequestIfBusy, when all connections in the current Generic data source are busy.

To enable the callback feature, you register the callback handler with Weblogic Server using Failover Callback Handler in the Multi Data Source configuration.

With the Failover algorithm, connection requests are served from the first Generic data source in the list. If a connection from that Generic data source fails a connection test, WebLogic Server marks the Generic data source as dead and disables it. If a callback handler is registered, WebLogic Server calls the callback handler, passing the following information, and waits for a return:

• currPool—For failover, this is the name of Generic data source currently being used to supply database connections. This is the "failover from" Generic data source.

• nextPool—The name of next available Generic data source listed in the Multi Data Source. For failover, this is the "failover to" Generic data source.

• opcode—A code that indicates the reason for the call:

  • OPCODE_CURR_POOL_DEAD—WebLogic Server determined that the current Generic data source is dead and has disabled it.

  • OPCODE_CURR_POOL_BUSY—All database connections in the Generic data source are in use. (Requires FailoverIfBusy=true in the Multi Data Source configuration. See Enabling Failover for Busy Generic Data Sources in a Multi Data Source.)

Failover is synchronous with the connection request: Failover occurs only when WebLogic Server is attempting to satisfy a connection request.

The return from the callback handler can indicate one of three options:

• OK—proceed with the operation. In this case, that means to failover to the next Generic data source in the list.

• RETRY_CURRENT—Retry the connection request with the current Generic data source.

• DONOT_FAILOVER—Do not retry the current connection request and do not failover. WebLogic Server will throw a weblogic.jdbc.extensions.PoolUnavailableSQLException.

WebLogic Server acts according to the value returned by the callback handler.

If the secondary Generic data sources fails, WebLogic Server calls the callback handler again, as in the previous failover, in an attempt to failover to the next available Generic data source in the Multi Data Source, if there is one.

Note:

WebLogic Server does not call the callback handler when you manually disable a Generic data source.

For Multi Data Sources with the Load-Balancing algorithm, WebLogic Server does not call the callback handler when a Generic data source is disabled. However, it does call the callback handler when attempting to re-enable a disabled Generic data source. See the following section for more details.

Deploying JDBC Multi Data Sources on Servers and Clusters

All Generic data sources used by a Multi Data Source to satisfy connection requests must be deployed on the same servers and clusters as the Multi Data Source. A Multi Data Source always uses a Generic data source deployed on the same server to satisfy connection requests. Multi Data Sources do not route connection requests to other servers in a cluster or in a domain.

To deploy a Multi Data Source to a cluster or server, you select the server or cluster as a deployment target. When a Multi Data Source is deployed on a server, WebLogic Server creates an instance of the Multi Data Source on the server. When you deploy a Multi Data Source to a cluster, WebLogic Server creates an instance of the Multi Data Source on each server in the cluster.

For instructions, see Target and deploy JDBC Multi Data Sources in the Oracle WebLogic Server Administration Console Online Help.

Multi Data Source Failover Enhancements

Learn how to improve failover processing for Multi Data Sources.

• Connection Request Routing Enhancements When a Generic Data Source Fails
  
• Automatic Re-enablement on Recovery of a Failed Generic Data Source within a Multi Data Source
  
• Enabling Failover for Busy Generic Data Sources in a Multi Data Source
  
• Controlling Multi Data Source Failback with a Callback
  

Connection Request Routing Enhancements When a Generic Data Source Fails

To improve performance when a Generic data source within a Multi Data Source fails, WebLogic Server automatically disables the Generic data source when a pooled connection fails a connection test. After a Generic data source is disabled, WebLogic Server does not route connection requests from applications to the Generic data source. Instead, it routes connection requests to the next available Generic data source listed in the Multi Data Source.

This feature requires that Generic data source testing options are configured for allGeneric data sources in a Multi Data Source, specifically Test Table Name and Test Reserved Connections. See Connection Testing Options for a Data Source.

If a callback handler is registered for the Multi Data Source, WebLogic Server calls the callback handler before failing over to the next Generic data source in the list. See Controlling Multi Data Source Failover with a Callback for more details.

Automatic Re-enablement on Recovery of a Failed Generic Data Source within a Multi Data Source

After a Generic data source is automatically disabled because a connection failed a connection test, the Multi Data Source periodically tests a connection from the disabled Generic data source to determine when the Generic data source (or underlying database) is available again. When the Generic data source becomes available, the Multi Data Source automatically re-enables the Generic data source and resumes routing connection requests to the Generic data source, depending on the Multi Data Source algorithm and the position of the Generic data source in the list of included Generic data sources. Frequency of these tests is controlled by the Test Frequency Seconds attribute of the Multi Data Source. The default value for Test Frequency is 120 seconds, so if you do not specifically set a value for the option, the Multi Data Source will test disabled Generic data sources every 120 seconds. See JDBC Multi Data Source: Configuration: General in the Oracle WebLogic Server Administration Console Online Help.

WebLogic Server does not test and automatically re-enable Generic data sources that you manually disable. It only tests Generic data sources that are automatically disabled.

If a callback handler is registered for the Multi Data Source, WebLogic Server calls the callback handler before re-enabling the Generic data source. See Controlling Multi Data Source Failback with a Callback for more details.

Enabling Failover for Busy Generic Data Sources in a Multi Data Source

By default, for Multi Data Sources with the Failover algorithm, when the number of requests for a database connection exceeds the number of available connections in the current Generic data source in the Multi Data Source, subsequent connection requests fail.

To enable the Multi Data Source to failover when all connections in the current Generic data source are in use, you can enable the Failover Request if Busy option on the JDBC Multi Data Source: Configuration: General page in the WebLogic Server Administration Console. (Also available as the FailoverRequestIfBusy attribute in the JDBCDataSourceParamsBean). If enabled (set to true), when all connections in the current Generic data source are in use, application requests for connections will be routed to the next available Generic data source within the Multi Data Source. When disabled (set to false, the default), connection requests do not failover.

If a ConnectionPoolFailoverCallbackHandler is included in the Multi Data Source configuration, WebLogic Server calls the callback handler before failing over. See Controlling Multi Data Source Failover with a Callback for more details.

Controlling Multi Data Source Failback with a Callback

If you register a failover callback handler for a Multi Data Source, WebLogic Server calls the same callback handler when re-enabling a Generic data source that was automatically disabled. You can use the callback to control if or when the disabled Generic data source is re-enabled so that you can make any other system preparations before the Generic data source is re-enabled, such as priming a database or communicating with a high-availability framework.

See the following sections for more details about the callback handler:

• How It Works—Failback
  

How It Works—Failback

WebLogic Server periodically checks the status of Generic data sources in a Multi Data Source that were automatically disabled. (See Automatic Re-enablement on Recovery of a Failed Generic Data Source within a Multi Data Source.) If a disabled Generic data source becomes available and if a failover callback handler is registered, WebLogic Server calls the callback handler with the following information and waits for a return:

• currPool—For failback, this is the name of the Generic data source that was previously disabled and is now available to be re-enabled.

• nextPool—For failback, this is null.

• opcode—A code that indicates the reason for the call. For failback, the code is always OPCODE_REENABLE_CURR_POOL, which indicates that the Generic data source named in currPool is now available.

Failback, or automatically re-enabling a disabled Generic data source, differs from failover in that failover is synchronous with the connection request, but failback is asynchronous with the connection request.

The callback handler can return one of the following values:

• OK—proceed with the operation. In this case, that means to re-enable the indicated Generic data source. WebLogic Server resumes routing connection requests to the Generic data source, depending on the Multi Data Source algorithm and the position of the Generic data source in the list of included Generic data sources.

• DONOT_FAILOVER—Do not re-enable the currPool Generic data source. Continue to serve connection requests from the Generic data sources in use.

WebLogic Server acts according to the value returned by the callback handler.

If the callback handler returns DONOT_FAILOVER, WebLogic Server will attempt to re-enable the Generic data source during the next testing cycle as determined by the TestFrequencySeconds attribute in the Multi Data Source configuration, and will call the callback handler as part of that process.

The order in which Generic data sources are listed in a Multi Data Source is very important. A Multi Data Source with the Failover algorithm will always attempt to serve connection requests from the first available Generic data source in the list of Generic data sources in the Multi Data Source. Consider the following scenario:

1. MultiDataSource_1 uses the Failover algorithm, has a registered ConnectionPoolFailoverCallbackHandler, and includes three Generic data sources: DS1, DS2, and DS3, listed in that order.

2. DS1 becomes disabled, so MultiDataSource_1 fails over connection requests to DS2.

3. DS2 then becomes disabled, so MultiDataSource_1 fails over connection requests to DS3.

4. After some time, DS1 becomes available again and the callback handler allows WebLogic Server to re-enable the Generic data source. Future connection requests will be served by DS1 because DS1 is the first Generic data source listed in the Multi Data Source.

5. If DS2 subsequently becomes available and the callback handler allows WebLogic Server to re-enable the Generic data source, connection requests will continue to be served by DS1 because DS1 is listed before DS2 in the list of Generic data sources.

Planned Database Maintenance with a Multi Data Source

Learn how to handle planned maintenance, without service interruption, on the database server used by a Multi Data Source.

To avoid service interruption, multiple database instances must be available so that the database can be updated in a rolling fashion. Oracle RAC cluster and Oracle GoldenGate, or a combination of these products, can be used to help accomplish this goal. (Note that Oracle DataGuard cannot be used for planned maintenance without service interruption). Each database instance is configured as a Generic data source member of the Multi Data Source. This approach assumes that the application is returning connections to the pool on a regular basis.

Process Overview

The following steps provide a high-level overview of the planned maintenance process:

1. On mid-tier systems—Shutdown all member data sources associated with the Oracle RAC instance that will be shut down for maintenance. It is important that you do not shut down all data sources in each Multi Data Source list so that connections can be reserved for the other member(s). Wait for data source shutdown to complete. See:

   • Shutting Down the Data Source

   • JDBCDataSourceRuntimeMBean shutdown operation in MBean Reference for Oracle WebLogic Server

2. If required, you may want to reduce the remaining connections on the database side that are not associated with the WebLogic data source. For the Oracle database server, this might include stopping (or relocating) the application services at the instances that will be shut down for maintenance, stopping the listener, and/or issuing a transactional disconnect for the services on the database instance.
3. Shut down the database instance using your preferred tools.
4. Perform the planned maintenance
5. Restart the database instance using your preferred tools.
6. Startup the services when the database instances are ready for application use.
7. On mid-tier systems—Start the member data sources. See JDBCDataSourceRuntimeMBean start operation in MBean Reference for Oracle WebLogic Server.

Shutting Down the Data Source

Shutting down the data source involves first suspending the data source and then releasing the associated resources including the connections.

When a member data source in a Multi Data Source is marked as suspended, the Multi Data Source will not try to get connections from the suspended pool. Instead, to reserve connections, it will go to the next member data source. It is important that you do not shut down all member data sources in a Multi Data Source list at the same time. If all members are shut down or fail, then access to the Multi Data Source fails and the application will see failures.

When you gracefully suspend a data source, which is the first step of the shut down process, the following occurs:

• The data source is immediately marked as suspended at the beginning of the operation and no further connections are created on the data source.

• Idle (not reserved) connections are marked closed

• After a timeout period for the suspend operation, all remaining connections in the pool are marked as suspended and the following exception is thrown for any operations on the connection, indicating that the data source is suspended:

  java.sql.SQLRecoverableException: Connection has been administratively disabled. Try later.

• All the remaining connections are then closed. We won't know until the data source is resumed if they are good or not. In this case, we know that the database will be shut down and the connections in the pool will not be good if the data source is resumed. Instead, we are doing a data source shutdown which will close all of the disabled connections.

  The shutdown operation can be done synchronously or asynchronously. If you do a synchronous shutdown, the default timeout period is 60 seconds. You can change the value of this timeout period by configuring or dynamically setting Inactive Connection Timeout Seconds to a non-zero value. There is no upper limit on the inactive timeout period. Note that the processing actually checks for in-use (reserved) resources every tenth of a second so if the timeout value is set to 2 hours and all reserved resources are released a second later, the shut down will complete a second later. If you do an asynchronous operation, the timeout period is specified on the method itself. If set to 0, the default is used. The default is to use Inactive Connection Timeout Seconds if set or 60 seconds. If you want a minimal timeout, set the value to 1. If you want no timeout, set it to a large value (not recommended).

This shutdown operation runs synchronously; there is no asynchronous version of the MBean operation available.

You can also use this for Multi Data Sources configured with either Load-Balancing or Failover.

Example 4-1 WLST Example

The following WLST example script demonstrates how to edit the configuration to increase the suspend timeout period and then use the runtime MBean to shutdown a data source. This script must be integrated into the existing framework for all WebLogic Server servers and data sources.

import sys, socket, os
hostname = 'hostname'
datasource='ds'
svr='myserver'
connect("weblogic","password","t3://"+hostname+":7001")
# Shutdown the data source serverRuntime()
serverRuntime()
cd('/JDBCServiceRuntime/' + svr + '/JDBCDataSourceRuntimeMBeans/' +datasource )
task = cmo.shutdown(10000)
while (task.isRunning ()): 
      print 'SHUTTING DOWN' 
      java.lang.Thread.sleep(2000) 
      print 'Datasource task is in status' + task.getStatus()
exit()
$ java weblogic.WLST myscript2.py
Intializing Weblogic Scripting Tool (WLST)...
Welcome to WebLogic Server Administration Scripting Shell
....
Location changed to serverRuntime tree.
This is a read-only tree with ServerRuntimeMBean as the root. For more help, use help('serverRuntime').
SHUTTING DOWN
Datasource task is in status
SUCCESS
Datasource task is in status
SUCCESS
Exiting WebLogic Scripting Tool.

Important Considerations

The following list describes issues you should be aware of when performing planned maintenance:

• If the Multi Data Source is using a database service, you cannot stop or relocate the database service before suspending or shutting down the Multi Data Source. If you do, the Multi Data Source may attempt to create a connection to the now missing service and it will react as though the database is down and kill all connections, preventing a graceful shutdown. Because suspending a Multi Data Source ensures that no new connections are created at the associated instance, it is not necessary to stop the service. (Note that the Multi Data Source only creates connections on this instance. It will never create connections on another instance even if it is relocated). Also, suspending a Multi Data Source ceases operations on all connections, therefore no further progress occurs on any sessions (the transactions will not complete) that remain in the Multi Data Source pool.

• You may encounter an issue related to XA affinity that is enforced by the Multi Data Source algorithms. When an XA branch is created on an Oracle RAC instance, all additional branches are created on the same instance. While Oracle RAC supports XA across instances, there are some significant limitations that applications run into before the prepare phase, and the Multi Data Source enforces that all operations are on the same instance. As soon as the graceful suspend operation starts, the member data source is marked as suspended and no further connections are allocated there. If an application using global transactions tries to start another branch on the suspending data source, it will fail to get a connection and the transaction fails. In the case of an XA transaction spanning multiple WebLogic servers, the suspend is not graceful. This issue does not apply to Emulate Two-Phase Commit or one-phase commit, which use a single connection for all work, and Logging Last Resource (LLR).

• If for some reason you must separate suspending the data source, at which point all connections are disabled, from releasing the resources, you can perform a suspend followed by forceShutdown. You must use a forced shutdown to avoid going through the waiting period a second time. Oracle does not recommend using this process.

• To get a graceful shutdown of the data source when shutting down the database, the data source must be involved. This process of shutting down the data source followed by shutdown of the database requires coordination between the mid-tier and the database server processing. Processing is simplified by using Active GridLink instead of Multi Data Source. See Using Active GridLink Data Sources.

• When using the Oracle database, Oracle recommends that an application service be configured for each database so that it can be configured for high availability. By using an application service, you can start up the database on its own without the data source starting to use it. Once the application service is explicitly started, the administrator can make the database available to the data source.

Using Active GridLink Data Sources

An Active GridLink (AGL) data source provides connectivity between WebLogic Server and an Oracle database. Oracle database offers both on-premises and cloud database services with cluster capabilities of Oracle Grid Infrastructure and Oracle Clusterware.

For more information, see Supported Oracle On-Premises and Cloud Database Services and Understanding the ActiveGridlink Attribute.

Using an AGL data source involves creating the AGL data source, configuring the connection pool and Oracle database parameters, tuning, monitoring, and so on. The following sections explain in detail these concepts:

• What is Active GridLink Data Source
  An Active GridLink Data Source (AGL) data source provides connectivity between WebLogic Server and an Oracle database service, which may include one or more Oracle RAC clusters. An Oracle database service represents a workload with common attributes that enables system administrators to manage the workload as a single entity.
• Configuring Active GridLink Data Source
  Use the WebLogic Server Administration Console or WLST to configure Active GridLink Data Source in a WebLogic domain.
• Configuring Runtime Load Balancing using SDP
  To configure load balancing across SDP connections, you must edit the TNSNAMES.ORA file on all nodes and add an SDP end-point to the LISTENER_IBLOCAL entry.
• Configuring Active GridLink Connection Pool Features
  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. Connection pools have options that allow you to control JDBC driver features and system properties associated with connection pools as well as use SQL for database connection initialization.
• Tuning Active GridLink Data Source Connection Pools
  By properly configuring the connection pool attributes in JDBC data sources in your WebLogic Server domain, you can improve application and system performance.
• Monitoring Active GridLink JDBC Resources
  Learn about monitoring and debugging Active GridLink data sources.
• Using Active GridLink Data Sources without FAN Notification
  You can configure and use an Active GridLink data source without enabling Fast Application Notification (FAN). In this configuration, disabling a connection to a RAC node occurs after two successive connection test failures. Connectivity is reestablished after a successful connection test.
• Best Practices for Active GridLink Data Sources
  Learn about the best practices for using Active GridLink data sources by understanding the catch and handle exceptions and how connections are created when using an Active GridLink data source.
• Comparing Active GridLink and Multi Data Sources
  There are several benefits to using Active GridLink data sources over Multi Data Sources when using Oracle RAC clusters.
• Migrating from Multi Data Source to Active GridLink
  You can migrate to Multi Data Source from Active GridLink data sources using simple manual process.
• Managing Database Downtime with Active GridLink Data Sources
  Learn several ways to handle database downtime with Active GridLink data sources in an Oracle RAC database environment.
• Gradual Draining
  During planned database maintenance, gradually close the database connections instead of closing all of the connections immediately. This strategy prevents uneven performance by the application.

What is Active GridLink Data Source

An Active GridLink Data Source (AGL) data source provides connectivity between WebLogic Server and an Oracle database service, which may include one or more Oracle RAC clusters. An Oracle database service represents a workload with common attributes that enables system administrators to manage the workload as a single entity.

You scale the number of AGL data sources as the number of services increases in the data base, independent of the number of nodes in the Oracle RAC cluster(s). Examples of High Availability support for multiple clusters include Data Guard, GoldenGate, and Global Database Service.

Note:

Active GridLink and Multi Data Source are designed to work with Oracle RAC clusters. Oracle does not recommend using Generic data sources with Oracle RAC clusters. See Comparing AGL and Multi Data Sources.

Figure 4-1 Active GridLink Data Source Connectivity

Description of "Figure 4-1 Active GridLink Data Source Connectivity"

An Active GridLink data source includes the features of Generic data sources plus the following support for Oracle RAC:

• Fast Connection Failover
  
• Runtime Connection Load Balancing
  
• GridLink Affinity
  
• SCAN Addresses
  
• Secure Communication using Oracle Wallet with ONS Listener
  
• Support for Active Data Guard
  
• Supported Oracle On-Premises and Cloud Database Services
  
• Using Socket Direct Protocol
  

Fast Connection Failover

Fast Connection Failover feature provides an application-independent method to implement Oracle RAC event notifications such as detection and cleanup of invalid connections, load balancing of available connections, and work redistribution on active Oracle RAC instances.

WebLogic Server supports Fast Connection Failover. See About Fast Connection Failover in Universal Connection Pool for JDBC Developer's Guide.

An AGL data source uses Fast Connection Failover and responds to Oracle RAC events using Oracle Notification Service (ONS). This ensures that the connection pool in the AGL data source contains valid connections (including reserved connections) without the need to poll and test connections. It also ensures that connections are created on new nodes as they become available.

Figure 4-2 Fast Connection Failover

Description of "Figure 4-2 Fast Connection Failover"

An AGL data source uses Fast Connection Failover to:

• Provide rapid failure detection.

• Abort and remove invalid connections from the connection pool.

• Perform graceful shutdown for planned and unplanned Oracle RAC node outages. See Planned Outage Procedures and Unplanned Outages.

• Adapt to changes in topology, such as adding or removing a node.

• Distribute runtime work requests to all active Oracle RAC instances, including those rejoining a cluster.

Note:

AGL data sources do not support the deprecated FastConnectionFailoverEnabled connection property. An attempt to create an XA connection with this property enabled results in a java.sql.SQLException: Can not use getXAConnection() when connection caching is enabled exception because the driver implementation of Fast Connection Failover for this property does not support XA connections.

• JDBC Driver Configuration for use with Oracle Fast Connection Failover
  To enable Fast Connection Failover on a data source, you need to set specific values for the Driver Class Name and ONS configuration string properties.

JDBC Driver Configuration for use with Oracle Fast Connection Failover

To enable Fast Connection Failover on a data source, you need to set specific values for the Driver Class Name and ONS configuration string properties.

Set the following connection pool properties:

• In Driver Class Name—set the class name to oracle.jdbc.pool.OracleDataSource.

• In Properties—set the ONS configuration string to remotely subscribe the Oracle RAC nodes to Oracle FAN/ONS events. For example: ONSConfiguration=nodes=hostname1:port1,hostname2:port2

  Note:

  Oracle's OracleDataSource class is not XA-capable, so the resulting data source does not implement a XA connection pool.

Runtime Connection Load Balancing

AGL data sources provide load balancing. AGL data sources use runtime connection load balancing (RCLB) to distribute connections to Oracle RAC instances based on Oracle FAN events issued by the database. This simplifies data source configuration and improves performance as the database drives load balancing of connections through the AGL data source, independent of the database topology.

Runtime Connection Load Balancing allows WebLogic Server to:

• Adjust the distribution of work based on back end node capacities such as CPU, availability, and response time.

• React to changes in Oracle RAC topology.

• Manage pooled connections for high performance and scalability.

Figure 4-3 Runtime Connection Load Balancing

Description of "Figure 4-3 Runtime Connection Load Balancing"

If FAN is not enabled, AGL data sources use a round-robin load balancing algorithm to allocate connections to Oracle RAC nodes.

Note:

Connections may be shut down periodically on AGL data sources. If the connections allocated to various RAC instances do not correspond to the Runtime Load Balancing percentages in the FAN load-balancing advisories, connections to overweight instances are destroyed and new connections opened. This process occurs every 30 seconds by default.

You can tune this behavior using the weblogic.jdbc.gravitationShrinkFrequencySeconds system property which specifies the amount of time, in seconds, the system waits before rebalancing connections. A value of 0 disables the rebalancing process.

GridLink Affinity

WebLogic Server GridLink affinity policies are designed to improve application performance by maximizing RAC cluster utilization.

• Session Affinity Policy
  
• XA Affinity Policy
  

Session Affinity Policy

Web applications have better performance when repeated operations against the same set of records are processed by the same RAC instance. Business applications such as online shopping and online banking are typical examples of this pattern.

An AGL data source uses the Session Affinity policy to ensure all the data base operations for a web session, including transactions, are directed to the same Oracle RAC instance of a RAC cluster.

Note:

The context is stored in the HTTP session. It is up to the application how windows (within a browser or across browsers) are mapped to HTTP sessions.

If an AGL data source with a session affinity policy is accessed outside the context of a web session, the affinity policy changes to the XA affinity policy. See XA Affinity Policy.

Figure 4-4 Session Affinity

Description of "Figure 4-4 Session Affinity"

An AGL data source monitors RAC load balancing advisories (LBAs) using the AffEnabled attribute to determine if RAC affinity is enabled for a RAC cluster. The first connection request is load balanced using Runtime Connection Load-Balancing (RCLB) and is assigned an Affinity context. All subsequent connection requests are routed to the same Oracle RAC instance using the Affinity context of the first connection until the session ends or the transaction completes. Affinity is based on the database name, service name, and instance name. Although the Session Affinity policy for an AGL data source is always enabled by default, a Web session is active for Session Affinity if:

• Oracle RAC is enabled, active, and the service has enabled RCLB. RCLB is enabled for a service if the service GOAL (NOT CLB_GOAL) is set to either SERVICE_TIME or THROUGHPUT.

• The database determines there is sufficient performance improvement in the cluster wait time and the Affinity flag in the payload in the information from ONS is set to TRUE.

If the database determines it is not advantageous to implement session affinity, such as a high database availability condition, the database load balancing algorithm reverts to its default work allocation policy and the Affinity flag in the payload is set to FALSE.

XA Affinity Policy

XA Affinity for global transactions ensures all the data base operations for a global transaction performed on an Oracle RAC cluster are directed to the same Oracle RAC instance. There are limitations to consider:

• XA transaction can't span instances.

• Strict affinity is enforced for connections within an XA transaction. If a connection cannot be created on the correct instance, an exception is thrown.

Figure 4-5 XA Affinity

Description of "Figure 4-5 XA Affinity"

SCAN Addresses

There are two options to load balance connections across nodes:

• Use a single Oracle Single Client Access Name (SCAN) address

  jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=scanname)(PORT=scanport))(CONNECT_DATA=(SERVICE_NAME=myservice)))

• Use multiple non-SCAN addresses with LOAD_BALANCE=on

  jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(LOAD_BALANCE=ON)(ADDRESS=(PROTOCOL=TCP)(HOST=host1)(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=host2)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=myservice)))

Using a SCAN address is recommended over using multiple non-SCAN addresses. However, a SCAN address can only be used if your database is configured to use it. Contact your network administrator for appropriately configured SCAN URLs for your environment.

Note:

When using Oracle RAC 11.2 and higher, consider the following:

• If the Oracle RAC listener is set to SCAN, the AGL data source configuration can only use a SCAN address.

• If the Oracle RAC listener is set to List of Node VIPs, the AGL data source configuration can only use a list of VIP addresses.

• If the Oracle RAC listener is set to Mix of SCAN and List of Node VIPs, the AGL data source configuration can use both SCAN and VIP addresses.

See:

• Overview of Automatic Workload Management with Dynamic Database Services in Real Application Clusters Administration and Deployment Guide.

• Oracle Single Client Access Name (SCAN) White Paper at http://www.oracle.com/technetwork/database/clustering/overview/scan-129069.pdf

Secure Communication using Oracle Wallet with ONS Listener

This feature allows you to configure secure communication with the ONS listener using Oracle Wallet. See Secure ONS Client Communication.

Support for Active Data Guard

Active GridLink data source also works with Oracle Active Data Guard. Oracle Clusterware must be installed and active on the primary and standby sites for both single instance (using Oracle Restart) and Oracle RAC databases. Oracle Data Guard broker coordinates with Oracle Clusterware to properly fail over role-based services to a new primary database after a Data Guard failover has occurred. Cluster Ready Services (CRS) posts FAN events when the role change occurs.

Supported Oracle On-Premises and Cloud Database Services

Oracle database offers both on-premises and cloud database services that use the Fast Application Notification (FAN) feature provided with the cluster capabilities of Oracle Grid Infrastructure and Oracle Clusterware.

Oracle database on-premises services that use the FAN feature include the following products and features:

• Oracle Real Application Clusters (RAC). See, Using WebLogic Server with Oracle RAC.

• Oracle Real Application Clusters (RAC) One Node. See Overview of Oracle Real Application Clusters One Node and Administering Oracle RAC One Node in Real Application Clusters Administration and Deployment Guide.

• Oracle Data Guard (with Broker). See Oracle Data Guard Broker Concepts in Oracle® Data Guard Broker Guide.

• Oracle Standard Edition High Availability. See About Standard Edition High Availability and Installing Standard Edition High Availability in Database Installation Guide.

• Oracle Database Global Data Services. See Global Data Services.

Oracle Database related cloud services that use the FAN feature includes the following products:

• Oracle Autonomous Transaction Processing Dedicated (ATP-D). See About Dedicated Autonomous Database and Access Dedicated Autonomous Database in the Oracle Cloud Infrastructure Console in Oracle Autonomous Database on Dedicated Exadata Infrastructure Guide.

• Oracle Autonomous Database Dedicated (ADB-D). See About Dedicated Autonomous Database in Oracle Autonomous Database on Dedicated Exadata Infrastructure Guide.

• Oracle Exadata Cloud@Customer. See About Oracle Exadata Cloud at Customer in Exadata Database Service on Cloud@Customer Administrator's Guide.

• Oracle Exadata Cloud Service. See About Exadata Cloud Service Instances in Administering Oracle Database Exadata Cloud Service Guide.

• Oracle Database Cloud Service. See About Oracle Database Cloud Services in Administering Oracle Database Classic Cloud Service Guide.

Using Socket Direct Protocol

To use the Socket Direct Protocol (SDP), your database network must be configured to use Infiniband. SDP does not support SCAN addresses.

See Configuring SDP Support for InfiniBand Connections in the Oracle Database Net Services Administrator's Guide.

Configuring Active GridLink Data Source

Use the WebLogic Server Administration Console or WLST to configure Active GridLink Data Source in a WebLogic domain.

See:

• Create JDBC GridLink data sources in the Oracle WebLogic Server Administration Console Online Help.

• 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. This example creates a Generic data source. See WLST Online Sample Scripts in Understanding the WebLogic Scripting Tool.

You must perform the following basic steps to create a data source using the WebLogic Server Administration Console:

• Configure JDBC Data Source Properties
  
• Configure Transaction Options
  
• Configure Connection Properties
  
• Test Connections
  
• Configure ONS Client
  
• Target the Data Source
  
• Configuring Oracle Parameters
  
• Configuring an ONS Client Using WLST
  

Configure 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, including data sources. 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 scoped to an application, data source names must be unique among JDBC data sources that are similarly scoped.
• Data Source Scope: You can select the scope for the data source and 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. You can use a multi-JNDI-named data source in place of legacy configurations that included multiple data sources that pointed to a single JDBC connection pool. See Developing JNDI Applications for Oracle WebLogic Server.
• Driver: Select the replay driver for JDBC Replay Driver, or the XA or non-XA Thin driver.

  Note:

  The JDBC Replay Driver does not currently support XA transactions.

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. WebLogic JDBC data sources supports XA, non-XA, and Global transaction options.

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 service name, database name, host name, port number, user name, and password.

Note:

Using service names:

• When a Database Domain is used, service names must be suffixed with the domain name. For example, if the database name is db.country.myCorp.com, the service name myservice would need to be entered as myservice.db.country.myCorp.com.

The console allows you to enter connection properties in one of the following ways:

• Enter Connection Properties
  
• Enter a Complete URL
  
• Supported Active GridLink Data Source URL Formats
  

Enter Connection Properties

On the GridLink data source connection Properties Options page, select Enter individual listener information and click Next. Enter the connection properties. For example:

• Enter myService in Service Name.

• Enter left:1234, center:1234, right:1234 in the Host and Port:. Separate the host and port of each listener with colon.

• Enter myDataBase in Database User Name.

• Enter myPassword1 in Password.

• If required, set Protocol to SDP.

The console automatically generates the complete JDBC URL. For example:

jdbc:oracle:thin:@( DESCRIPTION = (ADDRESS_LIST = (LOAD_BALANCE=on) (FAILOVER=ON) (ADDRESS=(PROTOCOL=TCP)(HOST=left)(PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=center)(PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=right)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=myService)))

Enter a Complete URL

On the GridLink data source connection Properties Options page, select Enter complete JDBC URL and click Next. Enter the connection properties. For example:

• In Complete JDBC URL, enter the JDBC URL. For example:

  jdbc:oracle:thin:@( DESCRIPTION = (ADDRESS_LIST = (LOAD_BALANCE=on) (FAILOVER=ON) (ADDRESS=(PROTOCOL=TCP)(HOST=left)(PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=center)(PORT=1521)) (ADDRESS=(PROTOCOL=TCP)(HOST=right)(PORT=1521))) (CONNECT_DATA=(SERVICE_NAME=myService)))

  You can also use a SCAN address. For example: jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=MyScanAddr-scn.myCompany.com)(PORT=1234)))(CONNECT_DATA=(SERVICE_NAME=myService)))

• Enter myDataBase in Database User Name.

• Enter myPassword1 in Password.

• If required, set Protocol to SDP.

Supported Active GridLink Data Source URL Formats

AGL data sources only support long format JDBC URLs. The supported long format pattern is:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=[SCAN_VIP])(PORT=[SCAN_PORT])))(CONNECT_DATA=(SERVICE_NAME=[SERVICE_NAME])))

Easy Connect (short) format URLs are not supported for AGL data sources. The following is an example of a Easy Connect URL pattern that is not supported for use with AGL data sources:

jdbc:oracle:thin:[SCAN_VIP]:[SCAN_PORT]/[SERVICE_NAME]

Recommendations for AGL Data Source URLs

The following section provides general recommendations when creating AGL data source URLs.

• Use a single DESCRIPTION. Avoid a DESCRIPTION_LIST to avoid connection delays.

• Use one ADDRESS_LIST for each RAC cluster or DataGuard database

• Enter RETRY_COUNT, RETRY_DELAY, CONNECT_TIMEOUT at the DESCRIPTION level so that all ADDRESS_LIST entries use the same value.

• RETRY_DELAY specifies the delay, in seconds, between the connection retries. This attribute is new in the Oracle 12.1.0.2 release.

• RETRY_COUNT is used to specify the number of times an ADDRESS list is traversed before the connection attempt is terminated. The default value is 0. When using SCAN listeners with FAILOVER=on, setting RETRY_COUNT to a value of 2 means that if you had 3 SCAN IP addresses, each would be traversed three times each, resulting in a total of nine connect attempts (3 * 3)

• Specify LOAD_BALANCE=on for each address list to balance the SCAN addresses.

• The service name should be a configured application service, not a PDB or administration service.

• CONNECT_TIMEOUT is used to specify the overall time used to complete the Oracle Net connect. Set CONNECT_TIMEOUT=90 or higher to prevent logon storms. For JDBC driver 12.1.0.2 and earlier, CONNECT_TIMEOUT is also used for the TCP/IP connection timeout for each address in the URL. When considering TCP/IP connections, a shorter CONNECT_TIMEOUT is preferred though secondary to overall timeout requirements.

• Do not set the oracle.net.CONNECT_TIMEOUT driver property on the data source because it is overridden by the URL property.

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.

Configure ONS Client

ONS client configuration allows the data source to subscribe to and process Oracle FAN events. When configuring the ONS node list, Oracle recommends not specifying a value and allowing auto-ONS to perform the ONS configuration. In some cases, however, it is necessary to explicitly configure the ONS configuration, for example if you need to specify an Oracle Wallet and password, or if you want to explicitly specify the ONS topology.

You can also configure an ONS client using WLST. For an example, see Configuring an ONS Client Using WLST.

To configure an ONS client from the Summary of Data Sources page in the Administration Console, see Configure ONS client parameters in Oracle WebLogic Server Administration Console Online Help.

Other Considerations

In general, if a WebLogic Server data source setting of initial capacity is set to 0,  WebLogic Server makes no DBMS connections at startup. For Active GridLink data sources with Auto-ONS, WebLogic Server needs to connect to the DBMS once at startup to get the ONS information.

• Enabling FAN Events
  
• Configure ONS Host and Port
  
• Secure ONS Client Communication
  
• Test ONS Client Configuration
  

Enabling FAN Events

To ensure that the data source is configured to subscribe to and process Oracle Fast Application Notification (FAN) events, select Fan Enabled.

Configure ONS Host and Port

There are two methods that you can use to configure the OnsNodeList value: a single node list or a property node list. You can use one or the other, but not both. If the WebLogic Server OnsNodeList contains an equals sign (=), it is assumed to be a property node list.

For both types of node lists you can use a Single Client Access Name (SCAN) address instead of a host name, and to access FAN notifications. For more information about SCAN addresses, see Scan Addresses.

To configure the OnsNodeList value using a:

• Single node list—Specify a comma separated list of ONS daemon listen addresses and ports for receiving ONS-based FAN events. For example, rac1:6200,rac2:6200. You can enter a single node list in the ONS host and port field in the Administration Console when creating an AGL Data Source.

• Property node list—Specify a string composed of multiple records, with each record consisting of a key=value pair and terminated by a new line ('\n') character. For example, nodes.1=rac1:6200,rac2:6200. You cannot enter a property node list in the ONS host and port field when creating a data source. Instead, you should leave this field blank. After you finish creating the data source, you can enter the property node list on the Configuration: ONS tab on the settings page for the data source.

You can specify the following keys in a property node list:

• nodes.id—A list of nodes representing a unique topology of remote ONS servers. id specifies a unique identifier for the node list. Duplicate entries are ignored. The list of nodes configured in any list must not include any nodes configured in any other list for the same client or duplicate notifications will be sent and delivered. The list format is a comma separated list of ONS daemon listen addresses and ports pairs separated by colon.

• maxconnections.id—Specifies the maximum number of concurrent connections maintained with the ONS servers. id specifies the node list to which this parameter applies. The default is 3

• active.id If true, the list is active and connections are automatically established to the configured number of ONS servers. If false, the list is inactive and is only be used as a fail over list in the event that no connections for an active list can be established. An inactive list can only serve as a fail over for one active list at a time, and once a single connection is re-established on the active list, the fail-over list reverts to being inactive. Note that only notifications published by the client after a list has failed over are sent to the fail over list. id specifies the node list to which this parameter applies. The default is true

• remotetimeout —The timeout period, in milliseconds, for a connection to each remote server. If the remote server has not responded within this timeout period, the connection is closed. The default is 30 seconds

Note:

Although walletfile and walletpassword are supported in the string, WebLogic Server has separate configuration elements for these values, OnsWalletFile and OnsWalletPasswordEncrypted.

Secure ONS Client Communication

To use an Oracle Wallet file with WebLogic Server, you must:

• Update your Active GridLink data source configuration to include the directory of the Oracle wallet file in which the SSL certificates are stored and optionally, the ONS Wallet password. See Secure ONS Listener using Oracle Wallet in Oracle WebLogic Server Administration Console Online Help.

• For more information on Oracle Wallet, see the Creating and Managing Oracle Wallet.

Test ONS Client Configuration

Test ONS client configuration allows you to test a connection to the ONS listener before the data source configuration is finalized.

Target the Data Source

You can select one or more targets to which to deploy your new Active GridLink 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.

Configuring Oracle Parameters

WebLogic Server provides several attributes that provide improved data source performance when using Oracle drivers. See Advanced Configurations for Oracle Drivers and Databases.

Configuring an ONS Client Using WLST

Use WLST to configure an ONS client.

The following fragment provides an example for setting the Oracle parameters of an Active GridLink data source.

cd('/JDBCSystemResources/' + dsName + '/JDBCResource/' + dsName + '/JDBCOracleParams/' + dsName)
cmo.setFanEnabled(true)
cmo.setOnsNodeList('nodes.1=rac1:6200,rac2:6200\nmaxconnections.1=3\n')

For more information about configuring an ONS client, see ONS Client Communication.

Configuring Runtime Load Balancing using SDP

To configure load balancing across SDP connections, you must edit the TNSNAMES.ORA file on all nodes and add an SDP end-point to the LISTENER_IBLOCAL entry.

Note:

The TNSNAMES.ORA file is only read at instance startup or when using an ALTER SYSTEM SET LISTENER_NETWORKS="listener address" command. After updating the TNSNAMES.ORA file, restart all instances or run the ALTER SYSTEM SET LISTENER_NETWORKS command on all networks.

For example:

LISTENER_IBLOCAL =  
  (DESCRIPTION =  
    (ADDRESS_LIST =  
      (ADDRESS = (PROTOCOL = TCP)(HOST =
 
   sclcgdb02ibvip.country.myCorp.com)(PORT=1522))  
       (ADDRESS = (PROTOCOL = SDP)(HOST =  
    sclcgdb02-bvip.country.myCorp.com)(PORT=1522))  
    )  
  ) 

You should then distribute connections on the LISTERNER_IB network using the following URL:

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=SDP)  (HOST=sclcgdb01-bvip.country.myCorp.com)(PORT=1522))(ADDRESS=(PROTOCOL=SDP)  (HOST=sclcgdb02-ibvip.country.myCorp.com)(PORT=1522)))(CONNECT_DATA=(SERVICE_NAME=elservice)))

Configuring Active GridLink Connection Pool Features

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. Connection pools have options that allow you to control JDBC driver features and system properties associated with connection pools as well as use SQL for database connection initialization.

Note:

Certain Oracle JDBC extensions 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.

For more information, see JDBC Data Source: Configuration: Connection Pool in Oracle WebLogic Server Administration Console Online Help and JDBCConnectionPoolParamsBean in MBean Reference for Oracle WebLogic Server.

The following connection pool options are available for a JDBC data source:

• Enabling JDBC Driver-Level Features
  
• Enabling Connection-based System Properties
  
• Initializing Database Connections with SQL Code
  

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.

Note:

Do not use FastConnectionFailoverEnabled, ConnectionCachingEnabled, or ConnectionCacheName as Driver-level properties in the Properties attribute in a JDBC data source.

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.

Note:

Do not specify oracle.jdbc.FastConnectionFailover as a Java system property when starting the WebLogic Server.

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 from 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()

Tuning Active GridLink Data Source Connection Pools

By properly configuring the connection pool attributes in JDBC data sources in your WebLogic Server domain, you can improve application and system performance.

See Tuning Data Source Connection Pools.

Monitoring Active GridLink JDBC Resources

Learn about monitoring and debugging Active GridLink data sources.

For more information, see Monitoring WebLogic JDBC Resources.

• Viewing Run-Time Statistics
  
• Debug Active GridLink Data Sources
  

Viewing Run-Time Statistics

You can view run-time statistics for an Active GridLink data source via the WebLogic Server Administration Console or through the associated runtime MBeans.

• JDBCOracleDataSourceRuntimeMBean
  
• JDBCOracleDataSourceInstanceRuntimeMBean
  
• ONSDaemonRuntimeMBean
  

JDBCOracleDataSourceRuntimeMBean

The JDBCOracleDataSourceRuntimeMBean provides methods for getting the current state of the data source instance and for getting statistics about the data source, such as the average number of active connections, the current number of active connections, and the highest number of active connections. This MBean also has a child JDBCOracleDataSourceInstanceRuntimeMBean for each node that is active in the Active GridLink data source. See JDBCOracleDataSourceRuntimeMBean in the MBean Reference for Oracle WebLogic Server.

JDBCOracleDataSourceInstanceRuntimeMBean

The JDBCOracleDataSourceInstanceRuntimeMBean provides methods for getting the current state of the data source instance. There an instance for each ONS listener that is active. In a configuration that uses auto-ONS where the administrator doesn't configure the ONS string, this is the only way to discover which ONS listeners are available. See JDBCOracleDataSourceInstanceRuntimeMBean in the MBean Reference for Oracle WebLogic Server.

ONSDaemonRuntimeMBean

The ONSDaemonRuntimeMBean provides methods for monitoring the ONS client configuration that is associated with an Active GridLink data source.

The following is a WLST script for testing an ONS connection. In this example, the Active GridLink data source is named glds and it is targeted to myserver:

connect(<wluser>, <wlpassword>, 't3://localhost:7001')
serverRuntime()
cd('JDBCServiceRuntime')
cd('myserver')
cd('JDBCDataSourceRuntimeMBeans')
cd('glds')
cd('ONSClientRuntime')
cd('glds')
cd('ONSDaemonRuntimes')
cd('glds_0')
cmo.ping()

See ONSDaemonRuntimeMBean in the MBean Reference for Oracle WebLogic Server.

Debug Active GridLink Data Sources

You can activate WebLogic Server's debugging features to track down the specific problem within the application.

• JDBC Debugging Scopes
  
• UCP JDK Logging
  
• Enable Debugging Using the Command Line
  

JDBC Debugging Scopes

The following are registered debugging scopes for JDBC:

• DebugJDBCRAC—prints information about Active GridLink data source lifecycle, Universal Connection Pool callback, and connection information.

• DebugJDBCONS—traces ONS client information, including the LBA event body. One trace is available for each ONS listener that is active. In a configuration that uses auto-ONS where the administrator doesn't configure the ONS string, this is the only way to see what ONS listeners are available.

• DebugJDBCReplay—traces JDBC Replay Driver replay information.

• DebugJDBCUCP—traces low level RAC information from the UCP driver.

UCP JDK Logging

For enabling UCP JDK logging, see Overview of Logging in UCP in Universal Connection Pool for JDBC Developer's Guide.

Enable Debugging Using the Command Line

Set the appropriate AGL data source debugging properties on the command line. For example,

-Dweblogic.debug.DebugJDBCRAC=true 
-Dweblogic.debug.DebugJDBCONS=true
-Dweblogic.debug.DebugJDBCUCP=true
-Dweblogic.debug.DebugJDBCREPLAY=true

Setting these values is static and can only be used at server startup.

To enable ONS debugging, you must configure Java Util Logging. To do so, set the following properties on the command line as follows:

-Doracle.ons.debug=true

See java.util.logging in Java Platform Standard Edition API Specification.

Using Active GridLink Data Sources without FAN Notification

You can configure and use an Active GridLink data source without enabling Fast Application Notification (FAN). In this configuration, disabling a connection to a RAC node occurs after two successive connection test failures. Connectivity is reestablished after a successful connection test.

Note:

This is not a standard recommendation from Oracle.

Oracle recommends that you enable TestConnectionsOnReserve. You might need to turn off FAN if a configured firewall doesn't allow this protocol to flow.

The following table indicates the availability of Active GridLink data source features when FAN Enabled set to false.

Table 4-2 Active GridLink Features when FAN Enabled is False

Active GridLink Feature	Available when FAN Enabled is False?
Single data source configuration for access to RAC cluster	Yes
Runtime MBeans for individual RAC cluster instances	Yes
Connection load balancing using Runtime Load Balancing (RLB)	No
Fast Application Notification (FAN)	No
Fast Connection Failover (FCF)	No
Graceful shutdown	No
Gravitation (rebalancing connections)	No
ONS Client Support, including password and encrypted wallet configurations	Yes
Transaction affinity	Yes
Session affinity	No

Understanding the ActiveGridlink Attribute

In WebLogic Server 12.1.2 and higher, the ActiveGridlink attribute is used to explicitly declare a data source configuration as an Active GridLink data source. It is automatically enabled by the WebLogic Server Administration Console when creating a Active GridLink data source. If you create data source configurations using WLST, you must remember to set ActiveGridlink=true.

Note:

To maintain backward compatibility with releases prior to WebLogic Server 12.1.2, a data source configuration is always an Active GridLink data source configuration if FanEnabled=true or the OnsNodeList is non-null. In this case, the ActiveGridlink value is ignored.

Legacy data source configurations are not updated during the upgrade process. If you need to update a legacy Active GridLink data source to access RAC clusters without enabling Fast Application Notification (FAN), edit or use WLST to set ActiveGridlink=true in the configuration.

Best Practices for Active GridLink Data Sources

Learn about the best practices for using Active GridLink data sources by understanding the catch and handle exceptions and how connections are created when using an Active GridLink data source.

• Catch and Handle Exceptions
  
• Connection Creation with Active GridLink Data Sources
  

Catch and Handle Exceptions

Applications need to catch and handle all exceptions. Applications using Active GridLink data sources should expect exceptions, such as an IO socket read error, when performing JDBC operations on borrowed connections. Best practice is to check the connection validity and reconnect if necessary. Connection exceptions can occur if the driver detects an outage earlier than FAN event arrival or as a result of the cleanup of a connection. For unplanned down events, a connection pool aborts all borrowed connections that are affected by the outage.

Connection Creation with Active GridLink Data Sources

This section summarizes the change in connections in Active GridLink data source, assuming FAN and ONS are enabled:

• Connections are added to the pool initially based on the configured initial capacity. That uses connect time load balancing based on the listener. For that to work correctly, you must either specify LOAD_BALANCE=ON for multiple non-scan addresses or use SCAN.

• Connections are added to the pool on demand based on runtime load balancing. However, this is overridden by XA affinity or Web session affinity, in which case connections are added on the instance providing affinity to the last request in the transaction or Web session.

• When a planned down event occurs, unused connections for that instance are released immediately and connections in use are released when returned to the pool.

• When an unplanned down event occurs, all connections for that instance are destroyed immediately.

• When an up event occurs, connections are proactively created on the new instance.

• When gravitation shrinking occurs, one unused connection is destroyed on a heavily loaded instance (per period).

• When normal shrinking occurs, half of the unused connections down to minimum capacity are destroyed without respect to load (per period).

Comparing Active GridLink and Multi Data Sources

There are several benefits to using Active GridLink data sources over Multi Data Sources when using Oracle RAC clusters.

The benefits include:

• Requires one data source with a single URL. Multi Data Sources require a configuration with n Generic data sources and a Multi Data Source.

• Eliminates a polling mechanism that can fail if one of the Generic data sources is performing slowly.

• Eliminates the need to manually add or delete a node to/from the cluster.

• Provides a fast internal notification (out-of-band) when nodes are available so that connections are load-balanced to the new nodes using Oracle Notification Service (ONS).

• Provides a fast internal notification when a node goes down so that connections are steered away from the node using ONS.

• Provides load balancing advisories (LBA) so that new connections are created on the node with the least load, and the LBA information is also used for gravitation to move idle connections around based on load.

• Provides affinity based on your XA transaction or your web session which may significantly improve performance.

• Leverages all the advantages of HA configurations like DataGuard. For more information, see Oracle WebLogic Server and Highly Available Oracle Databases: Oracle Integrated Maximum Availability Solutions on the Oracle Technology network at http://www.oracle.com/technetwork/middleware/weblogic/learnmore/index.html.

  .

Migrating from Multi Data Source to Active GridLink

You can migrate to Multi Data Source from Active GridLink data sources using simple manual process.

• Application Changes to Migrate a Multi Data Source
  
• Configuration Changes to Migrate a Multi Data Source
  
• Basic Migration Steps
  

Application Changes to Migrate a Multi Data Source

No changes should be required to your applications. A standard application looks up the Multi Data Source in JNDI and uses it to get connections. By giving the Active GridLink data source the same JNDI name as the Multi Data Source, the process is exactly the same in the application to use a data source name from JNDI.

Configuration Changes to Migrate a Multi Data Source

The only changes necessary should be to your configuration. An Active GridLink data source (AGL) is composed of information from the Multi Data Source (MDS) and the member generic data sources combined into a single AGL descriptor. The only additional information that is needed is the configuration of Oracle Notification Service (ONS) on the RAC cluster. In many cases, the ONS information consists of the same host names as used in the MDS and the only additional information is the port number, and which can be simplified by the use of a SCAN address.

A MDS descriptor does not contain much information. The key components are:

• The JNDI name. It must become the name of your new AGL data source to keep things transparent to the application. If you want to run the MDS in parallel with the AGL data source, then you must give the AGL data source a new JNDI name but you must also update the application to use that new JNDI name.

• A list of the member Generic data sources which provide any remaining information that you need to configure the AGL data source.

  Each of the member Generic data sources has its own URL. As described in Using Multi Data Sources with Oracle RAC, it has the following pattern:

  jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=
       (PROTOCOL=TCP)(HOST=host1-vip)(PORT=1521)) 
       (CONNECT_DATA=(SERVICE_NAME=dbservice)(INSTANCE_NAME=inst1)))
  

  Each member should have its own host and port pair. The members probably have the same service and often have the same port on different hosts. The URL for the AGL data source is a combination of the host and port pairs. For example:

  jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=
      (ADDRESS=(PROTOCOL=TCP)(HOST=host1-vip)(PORT=1521))
      (ADDRESS=(PROTOCOL=TCP)(HOST=host2-vip)(PORT=1521)))
      (CONNECT_DATA=(SERVICE_NAME=dbservice))
  

  It is preferable to use an Oracle Single Client Access Name (SCAN) address instead of multiple host or Virtual IP (VIP) addresses. SCAN addresses are simpler and makes changes to the nodes in the cluster transparent. For more information on SCAN addresses, see the Oracle Real Application Clusters Administration and Deployment Guide. For example:

  jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=scanaddress)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=dbservice))
  

• Ignore the Algorithm Type.

Basic Migration Steps

The following section provides the basic steps needed to migrate a Multi Data Source to an Active GridLink data source:

• Delete the Multi Data Source and the Generic data sources from the configuration using the WebLogic Server Administration Console.

• Add a single Active GridLink data source using the WebLogic Server Administration Console.

  • Give it the same JNDI name as the Multi Data Source.

  • Select an XA or non-XA driver based on your what Generic data sources used.

  • Enter the complete URL as described in Configuration Changes to Migrate a Multi Data Source.

  • Set the user and password, it should be the same as what you had on the Multi Data Source members.

  • On the Test GridLink Datasource Connection page, click Test All Listeners and verify the new URL.

  • Enter the information for the ONS connections. Specify one or more host:port pairs. For example, host1-vip:6200 or scanaddress:6200. If possible, use a single SCAN address and port. Make sure that FAN Enabled is checked.

  • Test the ONS connections.

• Deploy the data source.

• Edit the Active GridLink data source and configure additional parameters.

  There are many data source parameters that can't be configured while creating a new data source. In most cases, you should be able to use the parameter setting used in the Multi Data Source. If there are conflicts, you will need to resolve them and select the appropriate settings for your environment.

For more information on creating Active GridLink data sources using the WebLogic Server Administration Console, see Configure JDBC GridLink data sources in Oracle WebLogic Server Administration Console Online Help.

Managing Database Downtime with Active GridLink Data Sources

Learn several ways to handle database downtime with Active GridLink data sources in an Oracle RAC database environment.

• Active GridLink Configuration for Database Outages
  
• Planned Outage Procedures
  
• Unplanned Outages
  

Active GridLink Configuration for Database Outages

Ensure that the Active GridLink data source is configured as follows:

• Fast Application Notification (FAN) is enabled. FAN provides rapid notification about state changes for database services, instances, the databases themselves, and the nodes that form the cluster. It allows for draining of work during planned maintenance with no errors returned to applications.

• Is using auto-ONS, or an explicitly defined ONS configuration. See ONS Client Configuration.

• Is using a dynamic database service. Do not connect using the administrative service or PDB service. They are for intended for administration purposes only and are not supported for FAN.

• Test connections is enabled. Depending on the outage, applications may receive stale connections when connections are borrowed before a down event is processed. This can occur, for example, on a clean instance down when sockets are closed coincident with incoming connection requests. To prevent the application from receiving any errors, connection checks should be enabled at the connection pool. This requires setting test-connections-on-reserve to true and setting the test-table (the recommended value for Oracle is SQL ISVALID).

• SCAN usage is optimized. For database drivers 12.1.0.2 and later, set the URL setting LOAD_BALANCE=TRUE for the ADDRESSLIST as an optimization to force re-ordering of the SCAN IP addresses that are returned from DNS for a SCAN address.

For database drivers before 12.1.0.2, use the connection property oracle.jdbc.thinForceDNSLoadBalancing=true. See SCAN Addresses.

Planned Outage Procedures

For planned downtime, the primary goal is to manage scheduled maintenance with no application interruption while maintenance is underway at the database server. Achieving this goal requires the following:

• Transparent scheduled maintenance—Ensures that the scheduled maintenance process at the database servers is transparent to applications.

• Session Draining—When an instance is brought down for maintenance at the database server, session draining ensures that all work using instances at that node completes and that idle sessions are removed. Sessions are drained without impacting in-flight work.

For maintenance purposes (such as software and hardware upgrades, repairs, changes, migrations within and across systems), the services used are shutdown gracefully one or several at a time without disrupting the operations and availability of the WebLogic Server applications. Upon a FAN DOWN event, Active GridLink drains sessions away from the instance(s) targeted for maintenance. It is necessary to stop non-singleton services running on the target database instance (assuming that they are still available on the remaining running instances) or relocate singleton services from the target instance to another instance. Once the services have drained, the instance is stopped with no application errors

The following steps provide a high level overview of the planned maintenance process:

1. Detect DOWN event triggered by DBA on instances targeted for maintenance.
2. Drain sessions away from the targeted instance(s).
3. Perform scheduled maintenance on the database servers.
4. Resume operations on the upgraded node(s).

Unlike Multi Data Source where operations need to be coordinated on both the database server and the mid tier, Active GridLink co-operates with the database so that all of these operations are managed from the database server, simplifying the process. Table 4-3 lists the steps that are executed on the database server and the corresponding reactions at the mid tier.

Table 4-3 Steps Performed on Database Server for Active GridLink Planned Maintenance

Step #	Database Server Steps	Command	Mid-Tier Reaction
1.	Stop the non-singleton service without -force or relocate the singleton service. Omitting the –server option operates on all services on the instance.	$ srvctl stop service –db db_name -service service_name -instance instance_name or $ srvctl relocate service –db db_name -service service_name -oldinst oldins -newinst newinst	The FAN Planned Down (reason=USER) event for the service informs the connection pool that a service is no longer available for use and connections should be drained. Idle connections on the stopped service are released immediately. In-use connections are released when returned (logically closed) by the application. New connections are reserved on other instance(s) and databases offering the services. This FAN action invokes draining the sessions from the instance without disrupting the application.
2.	Disable the stopped service to ensure it is not automatically started again. Disabling the service is optional. This step is recommended for maintenance actions where the service must not restart automatically until the action has completed.	$ srvctl disable service –db db_name -service service_name -instance instance_name	No new connections are associated with the stopped/disabled service at the mid-tier.
3.	Allow sessions to drain.	Not applicable	The amount of time depends on the application. There may be long-running queries. Batch programs may not be written to periodically return connections and get new ones. It is recommended that batch be drained in advance of the maintenance.
4.	Check for long-running sessions. Terminate these sessions using a transactional disconnect. Wait for the sessions to drain. You can run the query again to check if any sessions remain.	SQL> select count(*) from (select 1 from v$sessionwhere service_name in upper('service_name') union all select 1 from v$transaction where status = 'ACTIVE' ) SQL> exec dbms_service.disconnect_session( 'service_name', DBMS_SERVICE.POST_TRANSACTION)	The connection on the mid-tier will get an error. If using JDBC Replay Driver, it is possible to hide the error from the application by automatically replaying the operations on a new connection on another instance. Otherwise, the application gets a SQLException.
5.	Repeat steps 1 through 4.	Repeat for all services targeted for planned maintenance	Not Applicable
6.	Stop the database instance using the immediate option.	$ srvctl stop instance –db db_name -instance instance_name -stopoption immediate	No impact on the mid-tier until the database and service are re-started.
7.	Optionally, disable the instance so that it will not automatically start again during maintenance. This step is for maintenance operations where the services cannot resume during the maintenance.	$ srvctl disable instance –db db_name -instance instance_name	Not Applicable
8.	Perform the scheduled maintenance work (patches, repairs, and changes).	Not Applicable	Not Applicable
9.	Enable and start the instance.	$ srvctl enable instance –db db_name -instance instance_name $ srvctl start instance –db db_name -instance instance_name	Not Applicable
10.	Enable and start the service back. Check that the service is up and running.	$ srvctl enable service –db db_name -service service_name -instance instance_name $ srvctl start service –db db_name -service service_name -instance instance_name	The FAN UP event for the service informs the connection pool that a new instance is available for use, allowing sessions to be created on this instance at the next request submission. Automatic rebalancing of sessions starts.

The following figure shows the distribution of connections for a service across two Oracle RAC instances before and after Planned Downtime. Notice that the connection workload moves from fifty-fifty across both instances to hundred-zero. In other words, RAC_INST_1 can be taken down for maintenance without any impact on the business operation.

Figure 4-6 Distribution of Connections Across Two Oracle RAC Instances

Description of "Figure 4-6 Distribution of Connections Across Two Oracle RAC Instances"

Unplanned Outages

There are several differences when an unplanned outage occurs:

• A component at the database server may fail making all services unavailable on the instances running at that node. There is no stop or disable on the services because they have failed.

• The FAN unplanned DOWN event (reason=FAILURE) is delivered to the mid-tier.

• All sessions are closed immediately, preventing the application from hanging on TCP/IP timeouts. Existing connections on other instances remain usable, and new connections are opened to these instances as needed.

• There is no graceful draining of connections. For those applications using services that are configured to use JDBC Replay Driver, active sessions are restored on a surviving instance and recovered by replaying the operations, masking the outage from applications. If not protected by JDBC Replay Driver, any sessions in active communication with the instance receive a SQLException.

Gradual Draining

During planned database maintenance, gradually close the database connections instead of closing all of the connections immediately. This strategy prevents uneven performance by the application.

When planned database maintenance occurs, a planned down service event is processed by the WebLogic Server JDBC data source. By default, all unreserved connections in the pool are closed immediately and borrowed connections are closed when they are returned to the pool. This shutdown process can cause uneven application performance because:

• New connections need to be created on the alternative instances.

• A logon storm can occur on the other instances.

This feature is supported for an Active GridLink data source running with Oracle RAC.

Setting the Drain Timeout Period

The connection property weblogic.jdbc.drainTimeout is recognized to define the draining period in seconds. The value must be a non-negative integer. For example, the following is a sample from a WLST script that creates a data source.

jdbcSR = create(dsname, 'JDBCSystemResource')
jdbcResource = jdbcSR.getJDBCResource()
driverParams = jdbcResource.getJDBCDriverParams()
driverProperties = driverParams.getProperties()
drainprop = driverProperties.createProperty('weblogic.jdbc.drainTimeout')
drainprop.setValue('60')

When running with the Oracle database 12.2 driver and the Oracle database 12.2 server, the drain timeout can be configured on the database server side by setting -drain_timeout on the database service. For example, a repayable service can be created by using:

srvctl add service -db ORCL -service otrade -clbgoal SHORT  -preferred orcl1,orcl2 -rlbgoal SERVICE_TIME -failoverretry 30 -failoverdelay 10  -failovertype TRANSACTION -commit_outcome TRUE -replay_init_time 1800 -retention 86400 -notification TRUE -drain_timeout 60

If both the connection property and the server-side drain timeout are set on an Oracle database 12.2 configuration, the server-side value takes precedence.  This value is only used during a planned down event to stop some but not all of the instances on which a service is running. For example,

srvctl stop service -db ORCL -instance orcl2 -service otrade.example.com

If the drain period is not set or set to 0, then by default, there is no drain period and connections are closed immediately.

A small value accelerates the migration, but might cause applications to experience higher response times, as requests on the target node hit a cold buffer cache. A larger value migrates work more gently and gives the buffer cache on the target node more time to warm-up, which in consequence leads to reduced impact on the application, but a longer overall migration duration.

Gradual Draining Processing

Processing starts when a database service that is configured for an Active GridLink data source is stopped using srvctl stop service -db dbname -instance instancename -service servicename.

Note:

Draining is not done if all services are shutdown (for example, when no instance name is specified).

• If the drain timeout is not set or set to 0, there is no drain period. Unreserved connections are immediately closed and borrowed connections are closed when returned to the pool.

• If the drain timeout is specified, it takes effect only if the service is available at another RAC instance. For active/active services draining is gradual. For active/passive services, version 12.2 of RAC relocates the service first, so gradual draining is also supported.  This feature does not work with Oracle DataGuard, which has only one primary active service at a time.

• If an alternative instance is available, the drain timeout period is started. The granularity and reducing the connections is done on a five-second interval. The total connection count is the count of the unreserved and the count of the reserved connections. The total count is divided by the value “(drain period/5)” to compute the number of connections to be released per interval (note that if the number is less than 1, then some intervals may not have any connections drained).  After each five-second interval, harvestable connections are harvested and interval count connections are closed if they are unreserved or marked for closure on return to the pool. After the last interval, the instance is marked as down (with respect to monitor status).

• If a data source is suspended or shut down, draining is stopped on any instance that is currently draining. Unreserved connections are immediately closed and borrowed connections are closed when returned to the pool.

• If a service is started again on an instance that is draining for that service, draining is stopped.

• If a service is stopped on all instances by not specifying a instance name or the last instance is stopped, draining is stopped on all instances. For all instances, unreserved connections are immediately closed and borrowed connections are closed when returned to the pool.

• When draining is happening on an instance, connection gravitation on the data source (rebalancing connections based on the runtime load balancing information) is stopped until the draining completes.

• When the service is stopped, the Load Balance Advisories (LBA) indicates that the percentage for the stopped service should be 0. This causes the preference for allocating existing connections to other instances first. If a connection does not exists on the other instances and a connection exists on the stopped service, it will pick that one instead of creating a connection.  This applies to connections created using LBA or Session Affinity. XA affinity will try to create a new connection for the instance in the affinity context, and only use a different instance or branch if a new connection can't be created.

Example

The following figure shows the effect of gradual draining when a service on an instance is stopped. In this case, the service is stopped on instance beadev2 just after 25:00. Note that it takes a while for the Load Balancing Advisories (LBA) to respond to the shut down at around 25:25 and the percentage goes to 0 for instance beadev2.   WebLogic Server receives the shutdown event almost instantly and starts to take action.  If gradual draining were not configured, the graph of Current Capacity would show the capacity dropping to 0 (or the count of active connections) immediately when the event is received.  Instead, you can see that the capacity gradually goes down every five- seconds for the sixty-second drain period and there is a corresponding increase in capacity on beadev1. Note that the total capacity stays constant through the entire period. 

Note:

These graphs were generated from an artificial work-load of requests that are getting a connection, doing a little work, and releasing the connection. In the real world, the results may not be so perfect.

Figure 4-7 Gradual Draining

Description of "Figure 4-7 Gradual Draining"

Using Universal Connection Pool Data Sources

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

• What is Universal Connection Pool Data Source
  A Universal Connection Pool data source is provided as an option for users who wish to use UCP for connecting to Oracle Databases. UCP provides an alternative connection pooling technology to Oracle WebLogic Server connection pooling.
• Creating a Universal Connection Pool Data Source
  To create a Universal Connection Pool data source in your WebLogic domain, you can use the WebLogic Server Administration Console, the WebLogic Scripting Tool (WLST), or Fusion Middleware Control.
• Universal Connection Pool Multi Tenant Shared Pool support
  To use this feature, the URI for the Universal Connection Pool (UCP) MT Shared Pool support XML configuration file must be specified using the oracle.ucp.jdbc.xmlConfigFile system property before any UCP data source is loaded in the JVM.
• Monitoring Universal Connection Pool JDBC Resources
  Learn about monitoring Universal Connection Pool JDBC Resources using the WebLogic Sever Administration Console or the JDBCUCPDataSourceRuntimeMBean, JDBCDataSourceRuntimeMBean .
• Oracle Sharding Support
  Sharding is a data tier architecture in which data is horizontally partitioned across independent databases.

What is Universal Connection Pool Data Source

A Universal Connection Pool data source is provided as an option for users who wish to use UCP for connecting to Oracle Databases. UCP provides an alternative connection pooling technology to Oracle WebLogic Server connection pooling.

Note:

Oracle generally recommends the use of Generic data source, Multi Data Source, or Active GridLink data source with Oracle WebLogic Server to establish connectivity with Oracle databases.

WebLogic Server provides the following support when using a UCP data source:

• Configuration as an alternative data source to Generic data source, Multi Data Source, or Active GridLink data source.

• Deploy and undeploy data source.

• Basic monitoring and statistics:

  • ConnectionsTotalCount

  • CurrCapacity

  • FailedReserveRequestCount

  • ActiveConnectionsHighCount

  • ActiveConnectionsCurrentCount

• Certification with Oracle simple driver, XA driver, and JDBC Replay Driver driver.

A UCP data source does not support:

• WebLogic Server Transaction Manager (one-phase, LLR, JTS, JDBC TLog, determiner resource, and so on).

• Additional life cycle operations (suspend, resume, shutdown, forceshutdown, start, and so on).

• Generic support for any connection pool.

• Oracle WebLogic Server Security options.

• JDBC drivers other than those listed above.

• Oracle WebLogic Server data operations such as JMS, Leasing, EJB, and so on.

• RMI access to a UCP data source.

The implementations of UCP data sources are loosely coupled, allowing the swapping of the ucp.jar to support the use of new UCP features by the applications. UCP data sources are not supported in an application-scoped/packaged or stand-alone module environment.

For details about the Oracle Universal Connection Pool, see Oracle Universal Connection Pool for JDBC Developer's Guide.

Creating a Universal Connection Pool Data Source

To create a Universal Connection Pool data source in your WebLogic domain, you can use the WebLogic Server Administration Console, the WebLogic Scripting Tool (WLST), or Fusion Middleware Control.

Procedures for creating a Universal Connection Pool data source using Fusion Middleware Control are described in Create JDBC Universal Connection Pool data sources in Administering Oracle WebLogic Server with Fusion Middleware Control.

The WebLogic Server Administration Console and WLST methods are described in the following sections:

• Configuring a UCP in the WebLogic Server Administration Console
  
• Configuring a UCP Using WLST
  

Configuring a UCP in the WebLogic Server Administration Console

The procedure for creating a Universal Connection Pool (UCP) data source in the WebLogic Server Administration Console is provided in Create Universal Connection Pool data sources in the Oracle WebLogic Server Administration Console Online Help. This procedure includes instructions for accessing the data source configuration wizard.

The following sections provide an overview of the basics steps used in the data source configuration wizard to create a data source using the WebLogic Server Administration Console:

Set JDBC Data Source Properties

The JDBC Data Source Properties section includes options that determine the identity of the data source and the way the data is handled on a database connection. Guidelines for configuring these properties are described as follows:

• Data Source Names—Enter a name for the UCP data source in the Name field. 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, including data sources. 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.

• 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—Enter a JNDI name for the UCP data source in the JNDI Name field. You can configure a data source so that it binds to the JNDI tree with a single name or multiple names. You can use a multi-JNDI-named data source in place of legacy configurations that included multiple data sources that pointed to a single JDBC connection pool. For more information, see Developing JNDI Applications for Oracle WebLogic Server.

• Database Type and Driver—The UCP data source is certified with three Oracle drivers: thin XA and non-XA, and an JDBC Replay Driver driver. Select the required driver from the menu.

The supported combinations of driver and JDBC connection factory are shown in Table 4-4

Table 4-4 Supported Driver and Connection Factory Combinations for UCP Data Source

Driver	Factory (ConnectionFactoryClassName)
oracle.ucp.jdbc.PoolDataSourceImpl (default)	oracle.ucp.jdbc.PoolDataSourceImpl
oracle.ucp.jdbc.PoolXADataSourceImpl	oracle.jdbc.xa.client.OracleXADataSource
oracle.ucp.jdbc.PoolDataSourceImpl	oracle.jdbc.replay.OracleDataSourceImpl

Note:

The JDBC Replay Driver does not currently support XA transactions.

If a non-XA driver from the list in Table 4-4 is specified with an XA factory from the table, an error is generated. If you specify values that are not in the table they are not validated.

If the driver-name is not specified in the jdbc-driver-params, it defaults to oracle.ucp.jdbc.PoolDataSourceImpl.

If you specify a supported driver name but do not specify the ConnectionFactoryClassName connection property, the corresponding entry from Table 4-4 is used. If you do not specify a supported driver name, an error is generated.

Set Connection Properties

Connection properties are used to configure the connection between the data source and the DBMS. There are two ways that you can enter the connection properties for a UCP data source in the Administration Console.

On the Connection Properties page of the wizard, all of the available connection properties for a UCP driver are displayed so that you can enter the appropriate values. As an alternative, you can configure properties by entering the properties directly into the Properties text box on the Test Database Connection page using the format propertyName=value. Any values that you entered on the Connection Properties page are already listed Properties text box.

Table 4-5 describes the connection properties that you can configure for a UCP data source. For more information about UCP properties, see Class PoolDataSourceImpl. In Oracle Universal Connection Pool for JDBC Java API Reference. Attributes are determined by setters on the PoolDataSourceImpl class. Use the attribute name without the "set" prefix. The names are case insensitive.

Table 4-5 Universal Connection Pool Properties

Property	Type	Description
AbandonedConnectionTimeout	int	Sets the abandoned connection timeout. The range of valid values is 0 to Integer.MAX_VALUE. The default is 0.
ConnectionFactoryClassName	String	Sets the Connection Factory class name.
ConnectionFactoryProperties	name=value	Sets the connection factory properties on the connection factory.
ConnectionFactoryProperty	name=value	Sets a connection factory property on the connection factory.
ConnectionHarvestMaxCount	int	Sets the maximum number of connections that can be harvested when the connection harvesting occurs.
ConnectionHarvestTriggerCount	int	Sets the number of available connections at which the connection pool's connection harvesting will occur.
ConnectionLabelingHighCost	int	Sets the cost value that identifies a connection as "high-cost" for connection labeling.
ConnectionPoolName	String	Sets the connection pool name.
ConnectionProperties	name=value	Sets the connection properties on the connection factory.
ConnectionProperty	name=value	Sets a connection property on the connection factory.
ConnectionWaitTimeout	int	Sets the amount of time to wait (in seconds) for a used connection to be released by a client. The range of valid values is 0 to Integer.MAX_VALUE. The default is 3.
DatabaseName	String	Sets the database name.
DataSourceName	String	Sets the data source name.
Description	String	Sets the data source description.
FastConnectionFailoverEnabled	Boolean	Enables Fast Connection Failover (FCF) for the connection pool accessed using this pool-enabled data source. Valid values are true and false.
HighCostConnectionReuseThreshold	int	Sets the high-cost connection reuse threshold for connection labeling.
InactiveConnectionTimeout	int	Sets the inactive connection timeout. he range of valid values is 0 to Integer.MAX_VALUE. The default is 0.
InitialPoolSize	int	Sets the initial pool size. The range of valid values is 0 to Integer.MAX_VALUE. It is illegal to set this to a value greater than the maximum pool size. The default is 0.
LoginTimeout	int	Sets the login timeout.
MaxConnectionReuseCount	int	Sets the connection reuse count property.
MaxConnectionReuseTime	long	Sets the connection reuse time property.
MaxIdleTime	int	Sets Idle timeout for available connections in the pool.
MaxPoolSize	int	Sets the maximum number of connections. The range of valid values is 1 to Integer.MAX_VALUE. The default is Integer.MAX_VALUE.
MaxStatements	int	Sets the maximum number of statements that may be pooled or cached on a connection.
MinPoolSize	int	Sets the minimum number of connections. The range of valid values is 0 to Integer.MAX_VALUE. It is illegal to set this to a value greater than the maximum pool size. The default is 0.
NetworkProtocol	String	Sets the data source network protocol.
ONSConfiguration	String	Sets the configuration string used for remote ONS subscription.
Password	String	Sets the password with which connections have to be obtained.
PortNumber	int	Sets the database port number.
PropertyCycle	int	Sets the Property cycle in seconds.
RoleName	String	Sets the data source role name.
ServerName	String	Sets the database server name.
SQLForValidateConnection	String	Sets the value (SQL) for SQLForValidateConnection property.
TimeoutCheckInterval	int	Sets the timeoutCheckInterval, in seconds.
TimeToLiveConnectionTimeout	int	Sets the maximum time, in seconds, that a connection may remain in-use.
URL	String	Sets the URL that the data source uses to obtain connections to the database.
User	String	Sets the user name with which connections have to be obtained.
ValidateConnectionOnBorrow	Boolean	Sets whether or not a connection being borrowed should first be validated. Valid values are true and false.

Note:

System properties and encrypted properties are supported in addition to normal string literals. See the following topics in Oracle WebLogic Server Administration Console Online Help:

• Set System Properties

• Encrypt connection properties

If the jdbc-driver-params URL is set, any URL property is ignored. If the encrypted-password is set, any password property is ignored.

The attributes ConnectionFactoryProperty, ConnectionFactoryProperties, ConnectionProperty, and ConnectionFactoryProperties accept values of the form "name1=value1,name2=value2...".

Test Database Connections

The Test Database Connection page allows you to enter free-form values for properties and 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.

Select Targets

You can select one or more targets to which to deploy your new UCP 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.

Configuring a UCP Using WLST

You can create a UCP data source using WebLogic Scripting Tool (WLST) in the same way that you create other data source types. However, UCP data sources have less attributes.

The configuration elements for a UCP data source are as follows.

• name

• datasource-type=UCP

• jdbc-driver-params url

• jdbc-driver-params property - user

• jdbc-driver-params password-encrypted

• jdbc-data-source-params jndi-name

• jdbc-driver-params other properties

No other elements from the WebLogic Server data source descriptor are recognized. If other elements are specified, they are ignored.

A sample WLST script for creating a UCP data source is provided in Example 4-2

Example 4-2 Sample WLST Script to Create a UCP Data Source

import sys, socket
import os
hostname = socket.gethostname()
connect("username","password","t3://"+hostname+":7001")
edit()
startEdit()
serverName="AdminServer"
serverBean = getMBean('/Servers/'+serverName)
host='%s.us.example.com' %hostname
print 'Creating UCP datasource'
domain = getMBean("/")
startEdit()
resourceName='ucpDS'
print "Creating datasource ds in domain"
systemResource=domain.createJDBCSystemResource(resourceName)
systemResource.setName(resourceName)
jdbcResource=systemResource.getJDBCResource()
jdbcResource.setName(resourceName)
jdbcResource.setDatasourceType('UCP')
driverParams=jdbcResource.getJDBCDriverParams()
driverParams.setDriverName('oracle.ucp.jdbc.PoolDataSourceImpl')
driverParams.setUrl('jdbc:oracle:thin:@dbhost:1521/otrade')
properties = driverParams.getProperties()
properties.createProperty('user', 'dbuser')
properties.createProperty('ConnectionFactoryClassName', 'oracle.jdbc.pool.OracleDataSource')
driverParams.setPassword('PASSWD')
jdbcDataSourceParams=jdbcResource.getJDBCDataSourceParams()
jdbcDataSourceParams.addJNDIName(resourceName)
jdbcDataSourceParams.setGlobalTransactionsProtocol('None')
cd('/SystemResources/' + resourceName )
set('Targets',jarray.array([ObjectName('com.bea:Name=' + serverName + ',Type=Server')], ObjectName))
save()
activate()

Note:

You can also use the sample WLST script for creating a Generic data source that is provided with WebLogic Server as the basis for your UCP data source:

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.

Universal Connection Pool Multi Tenant Shared Pool support

To use this feature, the URI for the Universal Connection Pool (UCP) MT Shared Pool support XML configuration file must be specified using the oracle.ucp.jdbc.xmlConfigFile system property before any UCP data source is loaded in the JVM.

This can be set on the command line when starting Weblogic Server. Since this is sometimes inconvenient, it is also possible to set the XmlConfigFile connection property. If you use the connection property approach, it must be set on all UCP data sources configured in WebLogic Server, even if they do not use the XML file. The format is generally something like file:///path/file.xml.

See Overview of UCP Shared Pool for Database Sharding in Universal Connection Pool Developer's Guide .

When using the shared pool feature, all attributes for the data source are ignored except for the following:

• Name – the data source name

• Data source Type – UCP

• Driver class name – oracle.ucp.jdbc.PoolDataSourceImpl or oracle.ucp.jdbc.PoolXADataSourceImpl

• Property DataSourceFromConfiguration – data source name in the XML file

• Property XmlConfigFile – optionally set the URI of the XML file if not set as a system property

• JNDI Name – the JNDI name where the data source object is mapped

  Example:

  import sys, socket
  import os
  hostname = socket.gethostname()
  connect("weblogic","server_password","t3://"+hostname+":7001")
  edit()
  startEdit()
  serverName="myserver"
  print 'Creating UCP datasource'
  domain = getMBean("/")
  startEdit()
  resourceName='ds5'
  print "Creating datasource ds in domain"
  systemResource=domain.createJDBCSystemResource(resourceName)
  systemResource.setName(resourceName)
  jdbcResource=systemResource.getJDBCResource()
  jdbcResource.setName(resourceName)
  jdbcResource.setDatasourceType('UCP')
  driverParams=jdbcResource.getJDBCDriverParams()
  driverParams.setDriverName('oracle.ucp.jdbc.PoolDataSourceImpl')
  properties = driverParams.getProperties()
  properties.createProperty('DataSourceFromConfiguration', 'pds1')
  properties.createProperty('XmlConfigFile', 'file:///SharedPoolDemo.xml')
  jdbcDataSourceParams=jdbcResource.getJDBCDataSourceParams()
  jdbcDataSourceParams.addJNDIName(resourceName)
  cd('/SystemResources/' + resourceName )
  set('Targets',jarray.array([ObjectName('com.bea:Name=' + serverName + ',Type=Server')], ObjectName))
  save()
  activate()

  The UCP XML file might look like the following.

  <?xml version="1.0" encoding="UTF-8"?> 
  <ucp-properties> 
  <connection-pool  
  connection-pool-name="pool1"  
  connection-factory-class-name="oracle.jdbc.pool.OracleDataSource" 
  url="jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)
  (HOST=dbhost)(PORT=5521))(CONNECT_DATA=
  (SERVICE_NAME=dbhostservice)))"  
  user="system"  
  password="manager"  
  initial-pool-size="4" 
  min-pool-size="2" 
   max-pool-size="10"  
  shared="true"
    >  
  <data-source data-source-name="pds1" 
   user="system" 
   password="manager" 
   service="pdb1_service" 
   description="pdb1 data source"
    />  
  <data-source data-source-name="pds2"   
  user="system"  
   password="manager"   
  service="pdb2_service"  
   description="pdb2 data source"  
  /> 
  </connection-pool> 
  </ucp-properties>

Monitoring Universal Connection Pool JDBC Resources

Learn about monitoring Universal Connection Pool JDBC Resources using the WebLogic Sever Administration Console or the JDBCUCPDataSourceRuntimeMBean, JDBCDataSourceRuntimeMBean .

The JDBCUCPDataSourceRuntimeMBean provides methods for getting the current state of the data source and for getting statistics about the data source, such as the average number of active connections, the current number of active connections, and the highest number of active connections. This MBean extends the JDBCDataSourceRuntimeMBean so that it can be returned with the list of other JDBC MBeans from the JDBC service. See JDBCUCPDataSourceRuntimeMBean in the MBean Reference for Oracle WebLogic Server.

In addition to runtime statistics, the testPool() operation returns null if the test is success or an error string otherwise (similar to other data source types). Testing the pool is done only if SQLForValidateConnection is set to a SQL string to be executed for validation (for example SELECT 1 from DUAL). The rest of the operations will take no action.

To understand more about JDBC monitoring, see Monitoring WebLogic JDBC Resources.

Oracle Sharding Support

Sharding is a data tier architecture in which data is horizontally partitioned across independent databases.

Oracle sharding is available in 12.2 UCP and surfaced from WebLogic Server by using the native UCP data source feature. See Overview of Oracle Sharding in Using Oracle Sharding.

After the UCP data source is accessed using a JNDI lookup, the sharding APIs can be used, as seen in the following Java code:

import javax.naming.Context;
import javax.naming.InitialContext;
import java.sql.Connection;
import oracle.ucp.jdbc.PoolDataSource;

Context cts = new InitialContext();

/// Look up the data source using JNDI
PoolDatasource pds = (PoolDataSource) ctx.lookup("shardDataSource");

 // Create a key corresponding to sharding key columns, to access the correct shard
OracleShardingKey key = pds.createShardingKeyBuilder().subkey(100, JDBCType.NUMERIC).build();

 // Fetch a connection to the shard corresponding to the key
Connection conn = pds.createconnectionBuilder().shardingKey(key).build();

 // Use the above connection for performing shard specific operations