Advanced Configurations for Oracle Drivers and Databases

JDBC Replay Driver

JDBC Replay Driver (also referred to as Application Continuity Driver) is a general purpose, application-independent infrastructure for Active GridLink and Generic data sources that enables the recovery of work from an application perspective and masks many system, communication, and hardware failures.

In today's environment, application developers are required to deal explicitly with outages of the underlying software, hardware, communications, and storage layers. As a result, application development is complex and outages are exposed to the end users. For example, some applications warn users not to hit the submit button twice. When the warning is not heeded, users may unintentionally purchase items twice or submit multiple payments for the same invoice.

JDBC Replay Driver semantics assure that end-user transactions can be executed on time and at-most-once. The only time an end user should see an interruption in service is when the outage is such that there is no point in continuing.

The following topics provide information on how to configure and use JDBC Replay Driver:

Parent topic: Advanced Configurations for Oracle Drivers and Databases

How JDBC Replay Driver Works

Following any outage that is due to a loss of database service, planned or unplanned, JDBC Replay Driver rebuilds the database session. Once an outage is identified by Fast Application Notification or a recoverable ORACLE error, the Oracle driver:

Establishes a new database session to clear any residual state.
If a callback is registered, issues a callback allowing the application to re-establish initial state for that session.
Executes the saved history accumulated during the request.

The Oracle driver determines the timing of replay calls. Calls may be processed chronologically or using a lazy processing implementation depending on how the application changes the database state. The replay is controlled by the Oracle 12c Database Server. For a replay to be approved, each replayed call must return exactly the same client visible state that was seen and potentially used by the application during the original call execution.

Figure 6-1 JDBC Replay Driver

Description of "Figure 6-1 JDBC Replay Driver"

Parent topic: JDBC Replay Driver

Requirements and Considerations

The following section provides requirements and items to consider when using JDBC Replay Driver (also referred as Application Continuity) with WebLogic applications:

Requires an Oracle 12c JDBC driver and database. See Using an Oracle 12c Database.
JDBC Replay Driver supports read and read/write of non-XA transactions (local transactions) on XA connections. We discourage an Oracle driver for JDBC Replay Driver participating in a Global transaction.
Note:
- Application Continuity is silently disabled by the usage of XA transactions on a connection.
- Remember to call connection.setAutoCommit(false) in your application to prevent breaking the transaction semantics and disabling JDBC Replay Driver in your environment.
Deprecated oracle.sql.* concrete classes are not supported. Occurrences should be changed to use either the corresponding oracle.jdbc.* interfaces or java.sql.* interfaces. Oracle recommends using the standard java.sql.* interfaces. See Using API Extensions for Oracle JDBC Types in Developing JDBC Applications for Oracle WebLogic Server.
JDBC Replay Driver works by storing intermediate results in memory. An application may run slower and require significantly more memory than running without the feature.
If the WebLogic statement cache is configured with JDBC Replay Driver, the cache is cleared every time the connection is replayed.
There are additional limitations and exceptions to the JDBC Replay Driver feature which may affect whether your application can use Replay. For more information, see Application Continuity for Java in the Oracle Database JDBC Developer's Guide.
The database service that is specified in the URL for the data source must be configured with the failover type set to TRANSACTION and the -commit_outcome parameter to TRUE. For example:

srvctl modify service -d mydb -s myservice -e TRANSACTION -commit_outcome TRUE -rlbgoal SERVICE_TIME -clbgoal SHORT

Parent topic: JDBC Replay Driver

Configuring JDBC Replay Driver

The topic provides information on how to implement JDBC Replay Driver in your environment.

Parent topic: JDBC Replay Driver

Selecting the Driver for JDBC Replay Driver

Configure your data source to use the correct JDBC driver using one of the following methods:

If you are creating a new data source, when asked to select a Database driver from the drop-down menu in the configuration wizard, select the appropriate Oracle driver that supports JDBC Replay Driver for your environment. See Enable Application Continuity in Oracle WebLogic Server Administration Console Online Help.
If you are editing an existing data source in the Administrator Console, select the Connection Pool tab, change the Driver Class Name to oracle.jdbc.replay.OracleDataSourceImpl, and click Save.
When creating or editing a data source with a text editor or WLST, set the JDBC driver to oracle.jdbc.replay.OracleDataSourceImpl.

See Requirements and Considerations.

Parent topic: Configuring JDBC Replay Driver

Using a Connection Callback

Parent topic: Configuring JDBC Replay Driver

Create an Initialization Callback

To create a connection initialization callback, your application must implement the initialize(java.sql.Connection connection) method of the oracle.ucp.jdbc.ConnectionInitializationCallback interface. Only one callback can be created per connection pool.

The callback is ignored if a labeling callback is registered for the connection pool. Otherwise, the callback is executed at every connection check out from the pool and at each successful reconnect following a recoverable error at replay. Use the same callback at runtime and at replay to ensure that exactly the same initialization that was used when the original session was established is used during the replay. If the callback invocation fails, replay is disabled on that connection.

Note:

Connection Initialization Callback is not supported for clients (JDBC over RMI).

Connection callback once registered will be called even without Oracle driver.

The following example demonstrates a simple initialization callback implementation:

. . .
import oracle.ucp.jdbc.ConnectionInitializationCallback ;
. . .
class MyConnectionInitializationCallback implements ConnectionInitializationCallback { 
  public MyConnectionInitializationCallback()  { 
  }
  public void initialize(java.sql.Connection connection)  throws SQLException {
     // Re-set the state for the connection, if necessary
  }
}

Parent topic: Using a Connection Callback

Registering an Initialization Callback

The WLDataSource interface provides the registerConnectionInitializationCallback(ConnectionInitializationCallback callback) method for registering initialization callbacks. Only one callback may be registered on a connection pool. The following example demonstrates registering an initialization callback that is implemented in the MyConnectionInitializationCallback class:

. . .
import weblogic.jdbc.extensions.WLDataSource;
. . .
MyConnectionInitializationCallback callback = new MyConnectionInitializationCallback();
((WLDataSource)ds).registerConnectionInitializationCallback(callback);
. . .

The callback can also be registered by entering the callback class in the Connection Initialization Callback attribute on the Oracle tab for a data source in the WebLogic Server Administration Console. Oracle recommends configuring this callback attribute instead of setting the callback at runtime. See Enable Application Continuity in Oracle WebLogic Server Administration Console Online Help.

Parent topic: Using a Connection Callback

Unregister an Initialization Callback

The WLDataSource interface provides the unregisterConnectionInitializationCallback() method for unregistering a ConnectionInitializationCallback. The following example demonstrates removing an initialization callback:

. . .
import weblogic.jdbc.extensions.WLDataSource;
((WLDataSource)ds).unregisterConnectionInitializationCallback();
. . .

Parent topic: Using a Connection Callback

Setting the Replay Timeout

Use the ReplayInitiationTimeout attribute on the Oracle tab for a data source in the WebLogic Server Administration Console to set the amount of time a data source allows for JDBC Replay Driver processing before timing out and ending a replay session context for a connection.

For applications that use the WebLogic HTTP request timeout, make sure to set the ReplayInitiationTimeout appropriately:

You should set the ReplayInitiationTimeout value equal to the HTTP session timeout value to ensure the entire HTTP session is covered by a replay session. The default ReplayInitiationTimeout and the default HTTP session timeout are both 3600 seconds.

If the HTTP timeout value is longer than ReplayInitiationTimeout value, replay events will not be available for the entire HTTP session.
If the HTTP timeout value is shorter than the ReplayInitiationTimeout value, your application should close the connection to end the replay session.

Parent topic: Configuring JDBC Replay Driver

Disabling JDBC Replay Driver for a Connection

You can disable JDBC Replay Driver on a per-connection basis using the following:

. . .
if (connection instanceof oracle.jdbc.replay.ReplayableConnection) {
 ((oracle.jdbc.replay.ReplayableConnection)connection).disableReplay();
}
. . .

You can disable JDBC Replay Driver at the database service level by modifying the service to have a failover type of NONE. For example:

srvctl modify service -d mydb -s myservice -e NONE

You can also disable JDBC Replay Driver at the data source level by setting the ReplayINitializationTimeout to 0. When set to zero (0) seconds, replay processing (failover) is disabled (begin and endRequest are still called).

Parent topic: Configuring JDBC Replay Driver

Configuring Logging for JDBC Replay Driver

To enable logging of JDBC Replay Driver processing, use the following WebLogic property:

-Dweblogic.debug.DebugJDBCReplay=true

Use -Djava.util.logging.config.file=configfile, where configfile is the path and file name of the configuration file property used by standard JDK logging, to control the log output format and logging level. The following is an example of a configuration file that uses the SimplFormatter and sets the logging level to FINEST:

handlers = java.util.logging.ConsoleHandler 
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter 
#OR - use other formatters like the ones below 
#java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter 
#java.util.logging.ConsoleHandler.formatter = oracle.ucp.util.logging.UCPFormatter 

#OR - use FileHandler instead of ConsoleHandler 
#handlers = java.util.logging.FileHandler 
#java.util.logging.FileHandler.pattern = replay.log 
#java.util.logging.FileHandler.limit = 3000000000
#java.util.logging.FileHandler.count = 1 
#java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
oracle.jdbc.internal.replay.level = FINEST

See Adding WebLogic Logging Services to Applications Deployed on Oracle WebLogic Server.

Parent topic: Configuring JDBC Replay Driver

Enabling JDBC Driver Debugging

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

-Djava.util.logging.config.file=configfile
-Doracle.jdbc.Trace=true

In this command, configfile is the path and file name of the configuration property file property used by standard JDK logging to control the log output format and logging level.

The configfile must include one of the following lines:

oracle.jdbc.internal.replay.level=FINEST—Replay debugging
oracle.jdbc.level = FINEST—Standard JDBC debugging

For more information, see java.util.logging in Java Platform Standard Edition API Specification.

Parent topic: Configuring JDBC Replay Driver

Viewing Runtime Statistics for JDBC Replay Driver

JDBC Replay Driver statistics are available using the JDBCReplayStatisticsRuntimeMBean for Active GridLink and Generic data sources.

The JDBCReplayStatisticsRuntimeMBean:

Is available for Active GridLink and Generic data sources. It is not available (null is returned) for Universal Connection Pool and Multi Data Sources.
Is available only if running with the 12.1.0.2 or later Oracle thin driver. It is not available (null is returned) for earlier driver versions.
Is available only if the data source is configured to use the JDBC Replay Driver driver. It is not available (null is returned) for non-replay drivers.
Will not have any statistics set initially (they will be initialized to -1). You must call the refreshStatistics() operation on the MBean to update the statistics before getting them.

Note:

Refreshing the statistics is a heavy operation. It locks the entire pool and runs through all reserved and unreserved connections aggregating the statistics. Running this operation frequently will impact the performance of the data source. Performance can also be impacted when clearing the statistics.

Table 6-1 lists the statistics that you can access using the JDBCReplayStatisticsRuntimeMBean.

Table 6-1 Runtime Statistics for JDBCReplayStatisticsRuntimeMBean

Name	Description
`TotalRequests`	Total number of successfully submitted requests.
`TotalCompletedRequests`	Total number of completed requests.
`TotalCalls`	Total number of JDBC calls executed.
`TotalProtectedCalls`	Total number of JDBC calls executed that are protected by JDBC Replay Driver.
`TotalCallsAffectedByOutages`	Total number of JDBC calls affected by outages. This includes both local calls and calls that involve roundtrip(s) to the database server.
`TotalCallsTriggeringReplay`	Total number of JDBC calls that triggered replay. Replay can be disabled for some requests, therefore not all calls affected by an outage trigger replay.
`TotalCallsAffectedByOutagesDuringReplay`	Total number of JDBC calls affected by outages in the middle of replay. Outages may be cascaded and strike a call multiple times when replay is ongoing. JDBC Replay Driver automatically reattempts replay when this happens, unless it reaches the maximum retry limit.
`SuccessfulReplayCount`	Total number of replays that succeeded. Successful replays mask the outages from applications.
`FailedReplayCount`	Total number of replays that failed. When replay fails, it re-throws the original `SQLRecoverableException` to the application, along with the reason for the failure chained to the original exception. The application can call `getNextException` to retrieve the reason.
`ReplayDisablingCount`	Total number of times that replay is disabled. When replay is disabled in the middle of a request, the remaining calls in that request are no longer protected by JDBC Replay Driver. If an outage strikes one of the remaining calls, no replay is attempted, and the application gets an `SQLRecoverableException`.
`TotalReplayAttempts`	Total number of replay attempts. JDBC Replay Driver automatically reattempts when replay fails, so this number may exceed the number of JDBC calls that triggered replay.

For more information, see JDBCReplayStatisticsRuntimeMBean in MBean Reference for Oracle WebLogic Server and ReplayableConnection.StatisticsReportType in Oracle JDBC Java API Reference.

Example 6-1 WLST Sample

You can access the statistics on the runtime MBean using WLST. The following sample WLST script shows how to print the information on the JDBCReplayStatisticsRuntimeMBean:

import sys, socket, os 
hostname = socket.gethostname()
datasource='JDBC GridLink Data Source-0'
svr='myserver'
connect("weblogic","password","t3://"+hostname+":7001")
serverRuntime()
cd('/JDBCServiceRuntime/' + svr + '/JDBCDataSourceRuntimeMBeans/' +
   datasource + '/JDBCReplayStatisticsRuntimeMBean/' +
   datasource + '.ReplayStatistics') 
cmo.refreshStatistics()
ls()
total=cmo.getTotalRequests()
cmo.clearStatistics()

Example 6-2 Java Sample

The following Java example demonstrates how to expose the statistics using the JDBCReplayStatisticsRuntimeMBean:

import javax.naming.NamingException;
import javax.management.AttributeNotFoundException;
import javax.management.MBeanServer;
import javax.management.InstanceNotFoundException;
import javax.management.ReflectionException
 import javax.management.ObjectName;
import javax.management.MalformedObjectNameException;
import javax.management.MBeanAttributeInfo;
import javax.management.MBeanOperationInfo;
import javax.management.MBeanException;
import javax.management.MBeanParameterInfo;
import weblogic.management.runtime.JDBCReplayStatisticsRuntimeMBean;
  public void printReplayStats(String dsName) throws Exception {
     MBeanServer server = getMBeanServer();
     ObjectName[] dsRTs = getJdbcDataSourceRuntimeMBeans(server);
     for (ObjectName dsRT : dsRTs) {
       String name = (String) server.getAttribute(dsRT, "Name");
       if (name.equals(dsName)) {
         ObjectName mb = (ObjectName)server.getAttribute(dsRT,
           "JDBCReplayStatisticsRuntimeMBean");
         server.invoke(mb, "refreshStatistics", null, null);
        MBeanAttributeInfo[] attributes =
           server.getMBeanInfo(mb).getAttributes();
         for (int i = 0; i < attributes.length; i++) {
           if (attributes[i].getType().equals("java.lang.Long")) {
             System.out.println(attributes[i].getName()+"="+
               (Long) server.getAttribute(mb, attributes[i].getName()));
           }
         }
       }
     }
   }
  MBeanServer getMBeanServer() throws Exception {
     InitialContext ctx = new InitialContext();
     MBeanServer server = (MBeanServer) ctx.lookup("java:comp/env/jmx/runtime");
     return server;
   }
  ObjectName[] getJdbcDataSourceRuntimeMBeans(MBeanServer server)
       throws Exception {
     ObjectName service = new ObjectName(
       "com.bea:Name=RuntimeService,Type=weblogic.management.mbeanservers.runtime .RuntimeServiceMBean");
     ObjectName serverRT = (ObjectName) server.getAttribute(service,
       "ServerRuntime");
     ObjectName jdbcRT = (ObjectName) server.getAttribute(serverRT,
       "JDBCServiceRuntime");
     ObjectName[] dsRTs = (ObjectName[]) server.getAttribute(jdbcRT,
       "JDBCDataSourceRuntimeMBeans");
     return dsRTs;
   }

Parent topic: JDBC Replay Driver

JDBC Replay Driver Auditing

During a ConnectionInitializationCallback, between the first connection initialization and reinitialization during replay, the application may want to know when the connection work is being replayed. ThegetReplayAttemptCount() method on the WLConnection interface is available to get the number of times that replay is attempted on the connection.

When a connection is first being initialized, it will be set to 0. For subsequent initialization of the connection when it is being replayed, it will be set to a value greater than 0.

Note:

This counter only indicates attempted replays since it is possible for replay to fail for various reasons (after which the connection is no longer valid). For a non-replay driver, it will always return 0.

Example 6-3 WLST Sample

The following is a sample callback class for initializing the connection. It assumes that there is some mechanism for getting an application identifier associated with the current work or transaction.

import java.sql.SQLException;
import java.util.Date;
import java.text.SimpleDateFormat;
import java.util.Properties;
import weblogic.jdbc.extensions.WLConnection;
import oracle.ucp.jdbc.ConnectionInitializationCallback;
public class callback implements ConnectionInitializationCallback {
final String idLabel = "GUUID";
public callback() {
}
public void initialize(java.sql.Connection conn) throws SQLException {
if (((WLConnection)conn).getReplayAttemptCount() == 0) {
// first time - initialize the label value
((WLConnection)conn).applyConnectionLabel(idLabel, Application.getGuuid());
// Get the id from somewhere and store it in the connection label
} else {
Properties props = ((WLConnection)conn).getConnectionLabels();
String value = props.getProperty(idLabel);
System.out.println("Transaction '"+value+"' is getting replayed at " + new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS").format(new
Date()));
}
}
}

Parent topic: JDBC Replay Driver

Limitations with JDBC Replay Driver with Oracle 12c Database

The following section provides information on limitations when using Oracle Database Release 12c with JDBC Replay Driver:

Database Resident Connection Pooling is not supported. A web request is not replayed and the original java.sql.SQLRecoverableException is thrown if an outage occurs.
Cannot be used with PDB tenant switching using ALTER SESSION SET CONTAINER.

Parent topic: JDBC Replay Driver

Database Resident Connection Pooling

Database Resident Connection Pooling (DRCP) provides the ability for multiple web-tier and mid-tier data sources to pool database server processes and sessions that are resident in an Oracle database.

See Database Resident Connection Pooling in JDBC Developer's Guide.

Parent topic: Advanced Configurations for Oracle Drivers and Databases

Requirements and Considerations

The following section provides requirements and items to consider when using DRCP with WebLogic applications:

Requires an Oracle 12c JDBC Driver and Database. See Using an Oracle 12c Database.
If the WebLogic statement cache is configured along with DRCP, the cache is cleared every time the connection is returned to the pool with close().
WebLogic Server data sources do not support connection labeling on DRCP connections and a SQLException is thrown. For example, using getConnection with properties on WLDataSource or a method on LabelableConnection is called, generates an exception. Note, registerConnectionLabelingCallback and removeConnectionLabelingCallback on WLDataSource are permitted.
WebLogic Server does not support defining the oracle.jdbc.DRCPConnectionClass as a system property. It must be defined as a connection property in the data source descriptor.
For DRCP to be effective, applications must return connections to the connection pool as soon as work is completed. Holding on to connections and using harvesting defeats the use of DRCP.
When using DRCP, the JDBC program must attach to the server before performing operations on the connection and must detach from the server to allow other connections to use the pooled session. By default, when the JDBC program is attaching to the server, it does not actually reserve a session but returns and defers the reservation until the next database round-trip. As a result, the subsequent database operation may fail because it cannot reserve a session. To prevent this from happening, there is a network timeout value that forces a round-trip to the database after an attach to the server. Once this occurs, the network timer is unset. The default network timeout is 10,000 milliseconds. You can set it to another value by setting the system property weblogic.jdbc.attachNetworkTimeout.

This property is the timeout, in milliseconds to wait for the attach to be done and the database round trip to return. If set to 0, then the additional processing around the server attach is not done.

For more information on configuring DRCP, see Configuring Database Resident Connection Pooling in the Oracle® Database Administrator's Guide.

Parent topic: Database Resident Connection Pooling

Configuring DRCP

You must configure datasource and database for DRCP in your environment.

Parent topic: Database Resident Connection Pooling

Configuring a Data Source for DRCP

To configure your data source to support DRCP:

If you are creating a new data source, on the Connection Properties tab of the data source configuration wizard, under Additional Configuration Properties, enter the DRCP connection class in the oracle.jdbc.DRCPConnectionClass field. See Create JDBC Generic data sources and Create JDBC Active GridLink data sources in Oracle WebLogic Server Administration Console Online Help.

In the resulting data source:
- The suffix :POOLED is added to the constructed short-form of the URL. For example: jdbc:oracle:thin:@//host:port/service_name:POOLED
- For the service form of the URL, (SERVER=POOLED) is added after the (SERVICE_NAME=name) parameter in the CONNECT_DATA element.
- The value/name pair of the DRCP connection class appears as a connection property on the Connection Pool tab. For example: oracle.jdbc.DRCPConnectionClass=myDRCPclass.
If you are editing an existing data source in the Administrator Console, select the Connection Pool tab:
1. Change the URL to include a suffix of :POOLED or (SERVER=POOLED) for service URLs.
2. Update the connection properties to include the value/name pair of the DRCP connection class. For example: oracle.jdbc.DRCPConnectionClass=myDRCPclass.
3. Click Save.
When creating or editing a data source with a text editor or using WLST:
1. Change the URL element to include a suffix of :POOLED or (SERVER=POOLED) for service URLs. For example: <url>jdbc:oracle:thin:@host:port:service:POOLED</url>.
2. Update the connection properties to include the value/name pair of the DRCP connection class. For example:
```
<properties>
      <property>
        <name>aname</name>
        <value>avalue</value>
      </property>
      <property>
        <name>oracle.jdbc.DRCPConnectionClass</name>
        <value>myDRCPclass</value>
      </property>
</properties>
```
WebLogic Server throws a configuration error if the DataSource resource definition has a oracle.jdbc.DRCPConnectionClass connection property or a POOLED URL but not both. This validation is performed when testing the connection listener in the console, deploying a DataSource during system boot, or when targeting a DataSource.
Set TestConnectionsOnReserve=true to minimize problems with MAX_THINK_TIME. See Configuring a Database for DRCP.
Set TestFrequencySeconds to a value less than INACTIVITY_TIMEOUT. See Configuring a Database for DRCP.

Parent topic: Configuring DRCP

Configuring a Database for DRCP

To configure your Oracle database to support DRCP:

DRCP must be enabled on the database side using:

SQL> DBMS_CONNECTION_POOL.CONFIGURE_POOL('SYS_DEFAULT_CONNECTION_POOL')

SQL> EXECUTE DBMS_CONNECTION_POOL.START_POOL();
The following parameters of the server pool configuration must be set correctly:
- MAXSIZE: The maximum number of pooled servers in the pool. The default value is 40. The connection pool reserves 5% of the pooled servers for authentication and at least one pooled server is always reserved for authentication. When setting this parameter, ensure that there are enough pooled servers for both authentication and connections.
  
  It may be necessary to set MAXSIZE to the size of the largest WebLogic connection pool using the DRCP.
- INACTIVITY_TIMEOUT: The maximum time, in seconds, the pooled server can stay idle in the pool. After this time, the server is terminated. The default value is 300. This parameter does not apply if the server pool has a size of MINSIZE.
  
  If a connection is reserved from the WebLogic data source and then not used, the inactivity timeout may occur and the DRCP connection will be released. Set INACTIVITY_TIMEOUT appropriately or return connections to the WebLogic data source if they will not be used. You can also use TestFrequencySeconds to ensure that unused connections don't time out.
- MAX_THINK_TIME: The maximum time of inactivity, in seconds, for a client after it obtains a pooled server from the pool. After obtaining a pooled server from the pool, if the client application does not issue a database call for the time specified by MAX_THINK_TIME, the pooled server is freed and the client connection is terminated. The default value is 120.
  
  If a connection is reserved from the WebLogic data source and no activity is done within the MAX_THINK_TIME, the connection is released. You can set Test Connections On Reserve (see Testing Reserved Connections) or set MAX_THINK_TIME appropriately. You can minimize the overhead of testing connections by setting SecondstoTrustanIdlePoolConnection to a reasonable value less than MAX_THINK_TIME. See Tuning Data Source Connection Pools.
If the server pool configuration parameters are not set correctly for your environment, your data source connections may be terminated and your applications may receive an error, such as a socket exception, when accessing a WebLogic data source connection.

Parent topic: Configuring DRCP

Global Data Services

Global Data Services (GDS) enables you to use a global service to provide seamless central management in a distributed database environment. A global server provides automated load balancing, fault tolerance and resource utilization across multiple RAC and single-instance Oracle databases interconnected by replication technologies such as Data Guard or GoldenGate.

Parent topic: Advanced Configurations for Oracle Drivers and Databases

Requirements and Considerations

Ensure to complete the following requirements and considerations when using Global Data Services in WebLogic Server:

Requires an Oracle 12c JDBC driver and database. See Using an Oracle 12c Database.
It is not possible to use a single SCAN address to replace multiple Global Service Manager (GSM) addresses.
For update operations to be handled correctly, you must define a service for updates that is only enabled on the primary database.
Define a separate service for read-only operations that is located on the primary and secondary databases.
Since only a single service can be defined for a URL and a single URL for a data source configuration, one data source must be defined for the update service and another data source defined for the read-only service.
Your application must be written so that update operations are process by the update data source and read-only operations are processed by the read-only data source.

Parent topic: Global Data Services

Creating a Active GridLink Data Source for GDS Connectivity

Use the WebLogic Server Administration Console to create a Active GridLink data source that uses a modified URL to provide Global Data Services (GDS) connectivity. See Create JDBC Active GridLink data sources in the Oracle WebLogic Server Administration Console Online Help.

The connection information for a GDS URL is similar to a RAC Cluster, containing the following basic information:

Service name (Global Service Name)
Address/port pairs for Global Service Manager
GDS Region in the CONNECT_DATA parameter

The following is a sample URL:

jdbc:oracle:thin:@(DESCRIPTION= 
    (ADDRESS_LIST=(LOAD_BALANCE=ON)(FAILOVER=ON) 
         (ADDRESS=(HOST=myHost1.com)(PORT=1111)(PROTOCOL=tcp)) 
         (ADDRESS=(HOST=myHost2.com)(PORT=2222)(PROTOCOL=tcp))) 
    (CONNECT_DATA=(SERVICE_NAME=my.gds.cloud)(REGION=west)))

Parent topic: Global Data Services

Container Database with Pluggable Databases

Container Database (CDB) is an Oracle Database feature that minimizes the overhead of having many of databases by consolidating them into a single database with multiple Pluggable Databases (PDB) in a single CDB.

See Managing Pluggable Databases in Enterprise Manager Lifecycle Management Administrator's Guide.

Parent topic: Advanced Configurations for Oracle Drivers and Databases

Creating Service for PDB Access

Access to a PDB is completely transparent to a WebLogic Server data source. It is accessed like any other database using a URL with a service. The service must be associated with the PDB. It can be created in SQLPlus by associating a session with the PDB, creating the service and starting it.

alter session set container = cdb1_pdb1; -- configure service for each PDB
execute dbms_service.create_service('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com','replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com');
execute DBMS_SERVICE.START_SERVICE('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com');

If you want to set up the service for use with JDBC Replay Driver, it needs to be appropriately configured. For example, SQLPlus:

declare
params dbms_service.svc_parameter_array ;
begin
params('goal') := 'service_time' ;
params('commit_outcome') := 'true' ;
params('aq_ha_notifications') := 'true' ;
params('failover_method') := 'BASIC' ;
params('failover_type') := 'TRANSACTION' ;
params('failover_retries') := 60 ;
params('failover_delay') := 2 ;
dbms_service.modify_service('replaytest_cdb1_pdb1.regress.rdbms.dev.us.myCompany.com', params);
end;
/

Parent topic: Container Database with Pluggable Databases

DRCP and CDB/PDB

DRCP cannot be used in a PDB. It must be associated with a CDB only. To configure, set a session to point to the CDB and start the DRCP pool. For example:

alter session set container = cdb$root;
execute dbms_connection_pool.configure_pool('SYS_DEFAULT_CONNECTION_POOL');
execute dbms_connection_pool.start_pool();

Parent topic: Container Database with Pluggable Databases

Setting the PDB using JDBC

Initially when a connection is created for the pool, it is created using the URL with the service associated with a specific PDB in a CDB. It is possible to dynamically change the PDB within the same CDB. Changing PDB's is done by executing the SQL statement:

ALTER SESSION SET CONTAINER = name SET SERVICE servicename;

Specifying SET SERVICE servicename allows for an explicit service to be configured by the application and named. This allows for support of Load Balancing Advisories, Session Affinity, Fast Application Notification, JDBC Replay Driver, and Proxy Authentication. These features are not available without the SET SERVICE servicename clause.

After the container is changed, the following do not change:

The RAC instance
The connection object
The WebLogic connection lifecycle (enabled/disabled/destroyed)
The WebLogic connection attributes.

Any remaining state on the connection is cleared to avoid leaking information between PDB's.

If configured, the following are reset:

JDBC Replay Driver
DRCP
client identifier
proxy user
The connection harvesting callback

Note:

DRCP is not supported with PDB switching

Parent topic: Container Database with Pluggable Databases

Service Switching

Learn about the limitations of service switching.

The limitations of using service switching with WebLogic Server are as follows:

Service switching has no impact on where the service is offered.
Service switching is only allowed only when the service is published at that instance.
Service switching is only allowed at request boundaries. This is necessary for JDBC Replay Driver to work correctly.
Service switching is only allowed at a top level call (no user call is active).
Service switching is not supported with Database Resident Connection Pooling.
Service switching returns an error if there is an open transaction, local, or XA.
Service attributes set at switch are never carried over from earlier usage. The application must set up the session appropriately.
Service switching is supported in non-CDB environments as wells as CDB environments. In the non-CDB environment, the container cannot change.
As with the earlier version, the service name may change during the switch but the instance name may not change.
XA affinity is based on a service_name, database_name, instance_name triple. When the service changes, there is no XA affinity enforced.

Note:

There is a limitation for Generic, Active GridLink, and Universal Connection Pool data sources. Fast Application Notification and Fast Connection Failover (FCF) are service based. When the data source is created, a subscription is set up for the configured service name. The data source will receive events for instance and service up and down. When the application switches the service, service up and down events will not be received for the new service name. Since gradual draining and scheduled maintenance are based on stopping the service allowing connections to drain before the instance is stopped, scheduled maintenance (planned down) does not work with application service switching. When the instance is stopped, a down event will be processed and the connections closed. WebLogic Server shared pooling manages multiple subscriptions and the resulting Fast Application Notification service events properly.

Parent topic: Advanced Configurations for Oracle Drivers and Databases