4 Using GridLink Data Sources

This chapter provides information on how to configure and tune GridLink data sources.

What is a GridLink Data Source

A single GridLink data source provides connectivity between WebLogic Server and an Oracle Database service, which may include multiple Oracle RAC clusters.Foot 1  It uses the Oracle Notification Service (ONS) to adaptively respond to state changes in an Oracle RAC instance. 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 GridLink data sources as the number of services increases in the data base, independent of the number of nodes in the cluster.

Figure 4-1 GridLink Data Source Connectivity

Surrounding text describes Figure 4-1 .

A GridLink data source includes the features of generic data sources plus the following support for Oracle RAC:

Fast Connection Failover

A GridLink data source uses Fast Connection Failover and responds to Oracle RAC events using ONS. This ensures that the connection pool in the GridLink data source contains valid connections (including reserved connections) without the need to poll and test connections.

Figure 4-2 Fast Connection Failover

Surrounding text describes Figure 4-2 .

A GridLink 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:

GridLink 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

GridLink data sources provide load balancing in XA and non-XA environments. GridLink 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 GridLink 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

Surrounding text describes Figure 4-3 .

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

Note:

Connections may be shut down periodically on GridLink 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 -1 disables the rebalancing process.

Graceful Handling for Oracle RAC Outages

A GridLink 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. A GridLink 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. See:

Session Affinity Policy

Web applications where a user session has back-to-back online transaction processing (OLTP) 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.

A GridLink 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 a GridLink 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

Surrounding text describes Figure 4-4 .

Although the Session Affinity policy for a GridLink 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 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.

Figure 4-5 XA Affinity

Surrounding text describes Figure 4-5 .

SCAN Addresses

Oracle Single Client Access Name (SCAN) addresses can be used to specify the host and port for both the TNS listener and the ONS listener in the WebLogic console. A GridLink data source containing SCAN addresses does not need to change if you add or remove Oracle RAC nodes. 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 GridLink data source configuration can only use a SCAN address.

  • If the Oracle RAC listener is set to List of Node VIPs, the GridLink 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 GridLink 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

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

Creating a GridLink Data Source

To create a GridLink 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 a JDBC GridLink Data Source" in the Oracle WebLogic Server Administration Console Help.

  • The sample WLST script SAMPLES_HOME\server\examples\src\examples\wlst\online\jdbc_data_source_creation.py, where SAMPLES_HOME refers to the main examples directory of your WebLogic Server installation. This example creates a generic data source. See "WLST Online Sample Scripts" in Oracle 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

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 and multi 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 and multi 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 Programming JNDI for Oracle WebLogic Server.

Select an XA or Non-XA Driver

Specify how your data source handles global 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 XA drivers, the system automatically selects the Two-Phase Commit protocol for global transaction processing.

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

    Supports Global Transactions: (selected by default) Select this option if you want to use connections from the data source in global transactions, even though you have not selected an XA driver. See Enabling Support for Global Transactions with a Non-XA JDBC Driver 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.us.oracle.com, the service name myservice would need to be entered as myservice.us.oracle.com.

  • Service names must not include upper case letters.

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

Enter Connection Properties

On the One 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=(ADDRESS=(PROTOCOL=TCP)(HOST=left)(PORT=1234))(ADDRESS=(PROTOCOL=TCP)(HOST=right)(PORT=1234))(ADDRESS=(PROTOCOL=TCP)(HOST=center)(PORT=1234)))(CONNECT_DATA=(SERVICE_NAME=myService)))

Enter a Complete URL

On the One 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=(ADDRESS=(PROTOCOL=TCP)(HOST=left)(PORT=1234))(ADDRESS=(PROTOCOL=TCP)(HOST=right)(PORT=1234))(ADDRESS=(PROTOCOL=TCP)(HOST=center)(PORT=1234)))(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.

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 Single Client Access Name (SCAN) addresses to access FAN notifications.

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

  • Add the following files to the WebLogic Server classpath:

    • $MW_HOME/modules/com.oracle.osdt_cert_1.0.0.0.jar

    • $MW_HOME/modules/com.oracle.osdt_core_1.0.0.0.jar

    • $MW_HOME/modules/com.oracle.oraclepki_1.0.0.0.jar

Test ONS Client Configuration

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

Target the Data Source

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

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

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.us.oracle.com)(PORT=1522))  
       (ADDRESS = (PROTOCOL = SDP)(HOST =  
    sclcgdb02-bvip.us.oracle.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.us.oracle.com)(PORT=1522))(ADDRESS=(PROTOCOL=SDP)  (HOST=sclcgdb02-ibvip.us.oracle.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, and possibly other non-standard methods available from other drivers may durably alter a connection's behavior in a way that future users of the pooled connection will inherit. WebLogic Server attempts to protect connections against some types of these calls when possible.

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

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

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.

Note:

Init SQL is not a dynamic attribute. When you change the value for Init SQL, you must either undeploy and redeploy the data source or restart the server.

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

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 Single Client Access Name (SCAN) addresses to access FAN notifications.

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

Configuring Generic Data Source Connection Testing

Normally, when FAN events are enabled, it's not necessary to enable test on reserve. However, if the ONS server is down or in unhealthy state, you can disable FAN Enabled and enable test on reserve. For more information, see Connection Testing Options for a Data Source.

Using a Wallet File

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

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.

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

Setting Database Security Credentials

The following sections provide information on how to pass security credentials to a DBMS:

Note:

GridLink Data Sources do not support identity-based connection pooling.

Using a User Name/Password

The simplest type of credential is to provide the connection pool a user account name and password for the DBMS. All the connections in the pool then use the same credentials to access a DBMS. See "Create JDBC data sources" in Oracle WebLogic Server Administration Console Help.

Note:

You can enter the password as a name-value pair in the Properties field (not permitted for production environments) or you can enter it in the Password field. The value in the Password field overrides any password value defined in the Properties passed to the JDBC Driver when creating physical database connections. Oracle recommends that you use the Password attribute in place of the password property in the properties string because the Password value is encrypted in the configuration file (stored as the password-encrypted attribute in the jdbc-driver-params tag in the module file) and is hidden in the administration console.

Set Client ID On Connection

If the Set Client ID On Connection attribute is enabled on the data source, when an application requests a database connection from the data source, the WebLogic Server instance determines the current WebLogic user ID and then sets the mapped database ID as a light-weight client ID. All the connections in the pool have the same credentials to access a DBMS. Basic configuration steps are:

  1. Select Set Client ID On Connection, see "Enable Set Client ID On Connection for a JDBC data source" in Oracle WebLogic Server Administration Console Help.

    Note:

    Credential mapping to map the WebLogic user ID and the database ID is only supported on the Oracle database with the Oracle Thin driver. This feature is not supported with the Oracle DMS driver.
  2. Map the WebLogic user ID and the database ID. See "Configure credential mapping for a JDBC data source" in the Oracle WebLogic Server Administration Console Help.

This feature relies on features in the JDBC driver and DBMS. It is only supported for use with Oracle and DB2 databases using a vendor extension method:

  • oracle.jdbc.OracleConnection.setClientIdentifier(String id)

  • com.ibm.db2.jcc.DB2Connection.setDB2ClientUser(String user)

    Note:

    Set Client ID On Connection and Enable Identity Based Connection Pooling are mutually exclusive. If you think you need both mechanisms to pass security credentials in your application environment, create separate data sources—one for with Set Client ID On Connection and one with Enable Identity Based Connection Pooling.

Monitoring GridLink JDBC Resources

The following sections include details about monitoring GridLink JDBC objects:

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

Viewing Run-Time Statistics

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

JDBCOracleDataSourceInstanceRuntimeMBean

The JDBCOracleDataSourceInstanceRuntimeMBean provides methods for getting the current state of the data source instance. For more information, see "JDBCOracleDataSourceInstanceRuntimeMBean" in the Oracle WebLogic Server MBean Reference.

JDBCDataSourceRuntimeMBean

The JDBCDataSourceRuntimeMBean provides methods for getting the current state of the data source instance. The JDBCDataSourceRuntimeMBean 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. For more information, see "JDBCDataSourceRuntimeMBean" in the Oracle WebLogic Server MBean Reference.

ONSDaemonRuntimeMBean

The ONSDaemonRuntimeMBean provides methods for monitoring the ONS client configuration that is associated with a GridLink data source For more information, see "ONSDaemonRuntimeMBean" in the Oracle WebLogic Server MBean Reference.

Debug 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 (scope weblogic.jdbc.racl) - prints information about GridLink data source lifecycle, UCP callback, and connection information.

  • DebugJDBCONS (scope weblogic.jdbc.connection) - traces ONS client information, including the LBA event body.

UCP JDK Logging

You can enable UPC JDK logging by following the instructions at http://download.oracle.com/docs/cd/B28359_01/java.111/e10788/get_started.htm#sthref67.

Enable Debugging Using the Command Line

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

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

This method is static and can only be used at server startup.

Best Practices for GridLink Data Sources

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

Catch and Handle Exceptions

Applications need to catch and handle all exceptions. Applications using 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 pool. For unplanned down events, a connection pool aborts all borrowed connections that are affected by the outage.



Footnote Legend

Footnote 1: For example, Oracle Data Guard.