Home / Middleware / Oracle WebLogic Server

5 Using Active GridLink Data Sources

This chapter provides information on how to configure and tune Active GridLink (AGL) data sources.

• What is an Active GridLink Data Source

• Creating an Active GridLink Data Source

• Using Socket Direct Protocol

• Configuring Connection Pool Features

• Configuring Oracle Parameters

• Configuring an ONS Client

• Tuning Active GridLink Data Source Connection Pools

• Monitoring GridLink JDBC Resources

• Using Active GridLink Data Sources without FAN Notification

• Best Practices for Active GridLink Data Sources

• Comparing AGL and Multi Data Sources

• Migrating from Multi Data Source to Active GridLink.

What is an Active GridLink Data Source

A single 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 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 5-1 Active GridLink Data Source Connectivity

An AGL data source includes the features of generic data sources plus the following support for Oracle RAC:

• Fast Connection Failover

• Runtime Connection Load Balancing

• Graceful Handling for Oracle RAC Outages

• GridLink Affinity

• SCAN Addresses

• Secure Communication using Oracle Wallet with ONS Listener.

Fast Connection Failover

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 5-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 Graceful Handling for Oracle RAC 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.

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

Graceful Handling for Oracle RAC Outages

An AGL data source provides graceful handling for the planned and unplanned shutdown of an Oracle RAC service:

• For planned shutdowns, the data source allows in-progress transactions to complete before closing connections. New Requests are load balanced to active Oracle RAC instances.

• For unplanned shutdowns, the data source rolls back in-progress transactions and closes the connections. New Requests are load balanced to active Oracle RAC instances.

Handling for Oracle RAC Outages Prior to Oracle RAC 11.2

In Releases prior to Oracle RAC 11.2, manually shutting down an Oracle RAC instance without first shutting down the corresponding services results in an unplanned shutdown.

GridLink Affinity

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

• 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 5-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 5-5 XA Affinity

SCAN Addresses

There are two options to load balance connections across nodes:

• 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)))

• 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)))

SCAN addresses can be used to specify the host for both the TNS listener and the ONS listener in the WebLogic console. An AGL data source containing SCAN addresses does not need to change if you add or remove Oracle RAC nodes and 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.

For more information on using SCAN addresses, see "Introduction to Automatic Workload Management" in Real Application Clusters Administration and Deployment Guide 11g Release 2 (11.2) and 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.

Creating an Active GridLink Data Source

To create an AGL data source in your WebLogic domain, you can use the Administration Console or the WebLogic Scripting Tool (WLST).

See the following for more information:

• "Create an Active GridLink data source" 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.

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

• JDBC Data Source Properties

• Configure Transaction Options

• Configure Connection Properties

• Test Connections

• Configure an ONS Client Configuration

• Test ONS Client Configuration

• Target the Data Source

JDBC Data Source Properties

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

Data Source Names

JDBC data source names are used to identify the data source within the WebLogic domain. For system resource data sources, names must be unique among all other JDBC system resources, 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.

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. For more information, see Developing JNDI Applications for Oracle WebLogic Server.

Select a Driver

Select the replay driver for application continuity, or the XA or non-XA Thin driver.

Note:

The replay driver does not currently support XA transactions.

Configure Transaction Options

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

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

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

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

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

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

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

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

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

Configure Connection Properties

Connection Properties are used to configure the connection between the data source and the DBMS. Typical attributes are the 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

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 AGL 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 an ONS Client Configuration

ONS client configuration allows the data source to subscribe to and process Oracle FAN events. To configure an ONS client:

• Select Fan Enabled.

• In ONS host and port, enter a comma-separate list of ONS daemon listen addresses and ports for receiving ONS-based FAN events. You can use a Single Client Access Name (SCAN) address to access FAN notifications.

  Note:

  If you are using an Oracle 12c database with WebLogic Server release12.1.2 and higher, you are no longer required to provide the ONS Listener list. The ONS list is automatically provided from the database to the driver and you can see this information in the associated runtime Mbean. However, if you want to use an associated Oracle wallet for ONS with SSL, the ONS listener list must be specified.

• Optionally, configure secure ONS client communication using SSL. See Secure ONS Client Communication.

Secure ONS Client Communication

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

• Update your AGL 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 Database Advanced Security Administrator's Guide.

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

Using Socket Direct Protocol

To use 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 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 Connection Pool Features

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

Note:

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.

The following sections include information about connection pool options for a JDBC data source.

• Enabling JDBC Driver-Level Features

• Enabling Connection-based System Properties.

• Initializing Database Connections with SQL Code

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

• JDBC Data Source: Configuration: Connection Pool page in the Administration Console. See "JDBC Data Source: Configuration: Connection Pool" in the Oracle WebLogic Server Administration Console Online Help

• JDBCConnectionPoolParamsBean, which is a child MBean of the JDBCDataSourceBean

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 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 Administration Console. 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. For example:

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

or

SQL SET LOCK MODE TO WAIT

Options that you can set using InitSQL vary by DBMS.

Configuring Oracle Parameters

WebLogic Server provides several attributes that provide improved Data Source performance when using Oracle drivers, for more information, see Advanced Configurations for Oracle Drivers and Databases.

Configuring an ONS Client

The following section provides information on how to configure an ONS client.

• Enabling FAN Events

• Using a Wallet File

Enabling FAN Events

Enabling a data source to subscribe to and process Oracle Fast Application Notification (FAN) events.

1. Select Fan Enabled

2. Provide a comma-separate list of ONS daemon listen addresses and ports for receiving ONS-based FAN events. You can use a Single Client Access Name (SCAN) address to access FAN notifications.

   Note:

   If you are using an Oracle 12c database with WebLogic Server release12.1.2 and higher, you are no longer required to provide the ONS Listener list as part of an AGL data source configuration. The ONS list is automatically provided from the database to the driver and you can see this information in the associated runtime Mbean. However, if you want to use an associated Oracle wallet for ONS with SSL, the ONS listener list must be specified.

See Configure ONS client parameters in Oracle WebLogic Server Administration Console Online Help.

Using a Wallet File

To communicate with ONS daemons using SSL, you must use a wallet file. See Secure ONS Client Communication..

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. For more information, see Tuning Data Source Connection Pools.

Monitoring GridLink JDBC Resources

The following sections include details about monitoring GridLink JDBC objects:

• Viewing Run-Time Statistics

• Debug Active GridLink Data Sources.

For more information on JDBC monitoring, see Monitoring WebLogic JDBC Resources.

Viewing Run-Time Statistics

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

JDBCOracleDataSourceRuntimeMBean

The JDBCOracleDataSourceRuntimeMBean provides methods for getting the current state of the data source instance. The JDBCOracleDataSourceRuntimeMBean 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 also has a child JDBCOracleDataSourceInstanceRuntimeMBean for each node that is active in the AGL datasource.For more information, 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.For more information, 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 AGL data source. For more information, 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

The following are registered debugging scopes for JDBC:

• DebugJDBCRAC—prints information about AGL data source lifecycle, UCP 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 application continuity replay information.

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

UCP JDK Logging

You can enable UPC JDK logging by following the instructions at "Setting Up Logging in UCP" in the Oracle 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.

Using Active GridLink Data Sources without FAN Notification

Although not recommended, you can configure and use an AGL 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. 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 AGL data source features when FAN Enabled set to false.

Table 5-1 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	No
Transaction affinity	Yes
Session affinity	No

Understanding the ActiveGridlink Attribute

In WebLogic Server 12.1.2, a new configuration attribute, ActiveGridlink, is used to explicitly declare a data source configuration as an AGL datasource. It is automatically enabled by the Administration Console when creating a 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 AGL 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 AGL 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

The following sections provide best practices for using AGL data sources:

• 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 AGL 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 AGL, 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 AGL and Multi Data Sources

AGL is a superior implementation to Multi Data Source (MDS) for supporting RAC clusters. The following section provides additional information on the benefits of AGL data sources. AGL:

• 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."

Migrating from Multi Data Source to Active GridLink

Multi data source (MDS) for RAC connectivity has been supported in WebLogic Server since 2005. As the popularity of Oracle RAC has grown, so has the use of MDS. With the introduction of Active GridLink (AGL) in early 2011, many MDS users are migrating to AGL. Although there is no automated upgrade path, it is a simple manual process to implement AGL in your environment. See Comparing AGL and Multi Data Sources.

Application Changes to Migrate a Multi Data Source

No changes should be required to your applications. A standard application looks up the MDS in JNDI and uses it to get connections. By giving the AGL the same JNDI name as the MDS, 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 AGL data source is composed of information from the 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 Steps to Migrate a Multi Data Source to a Active GridLink Data Source

The following section provides the basic steps needed to migrate a MDS to a AGL data source:

• Delete the MDS and the generic data sources from the configuration using the administration console.

• Add a single AGL data source using the administration console.

  • Give it the same JNDI name as the MDS.

  • 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 MDS 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 AGL 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 MDS. If there are conflicts, you will need to resolve them and select the appropriate settings for your environment.

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