10 Advanced Configurations for Oracle Drivers and Databases

This chapter provides advanced configuration options that can provide management of connection reservation in the data source.

This chapter includes the following sections:

Application Continuity

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.

Application Continuity (also referred to as Replay) is a general purpose, application-independent infrastructure for GridLink and Generic data sources that enables the recovery of work from an application perspective and masks many system, communication, and hardware failures. The 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 sections provide information on how to configure and use Application Continuity:

How Application Continuity Works

Following any outage that is due to a loss of database service, planned or unplanned, Application Continuity 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 10-1 Application Continuity

Description of Figure 10-1 follows
Description of "Figure 10-1 Application Continuity"

Requirements and Considerations

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

  • Requires an Oracle 12c JDBC Driver and Database. See Using an Oracle 12c Database.

  • Application Continuity supports read and read/write transactions. XA transactions are not supported. To support transactions using non-XA drivers such as an Oracle driver for Application Continuity, see "Enabling Support for Global Transactions with a Non-XA JDBC Driver" in Administering JDBC Data Sources for Oracle WebLogic Server for information.

    Note:

    Remember to set autocommit=FALSE to prevent breaking the transaction semantics and disabling Application Continuity 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.

  • Application Continuity 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 Application Continuity, the cache is cleared every time the connection is replayed.
  • There are additional limitations and exceptions to the Application Continuity 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

Configuring Application Continuity

The following sections provide information on how to implement Application Continuity in your environment:

Selecting the Driver for Application Continuity

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 Application Continuity 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.

Using a Connection Callback

The following sections provide information on how to use a Connection Callback:

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

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();
. . .

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 Application Continuity replay 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.

Disabling Application Continuity for a Connection

You can disable Application Continuity on a per-connection basis using the following:

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

You can disable application continuity 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 application continuity 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).

Configuring Logging for Application Continuity

To enable logging of Application Continuity 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.

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 7 API Specification.

Viewing Runtime Statistics for Application Continuity

This topic describes Runtime statics for application continuity.

Application Continuity (or Replay) statistics are available using the JDBCReplayStatisticsRuntimeMBean for Generic and Active GridLink data sources.

The JDBCReplayStatisticsRuntimeMBean:

  • Is available for Generic and Active GridLink data sources. It is not available (null is returned) for Multi Data Source (MDS), PROXY, and UCP 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 replay driver. It is not available (null is returned) for non-replay drivers (such as the Oracle driver and XA 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 10-1 lists the statistics that you can access using the JDBCReplayStatisticsRuntimeMBean.

Table 10-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 Application Continuity.

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. Application Continuity 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 rethrows 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 Application Continuity. 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. Application Continuity automatically reattempts when replay fails, so this number may exceed the number of JDBC calls that triggered replay.

For more information, see:

Example 10-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 10-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;
   }

Application Continuity 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. The getReplayAttemptCount() 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 10-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()));
}
}
}

Limitations with Application Continuity with Oracle 12c Database

The following section provides information on limitations when using Oracle Database Release 12c with Application Continuity:

  • DRCP is not supported. That is, a web request will not be 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.

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 (DRCP) at http://www.oracle.com/technetwork/articles/oracledrcp11g-1-133381.pdf.

The following sections provide more information on using and configuring DRCP in WebLogic Server:

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.

Configuring DRCP

The following sections provide information on how to configure DRCP in your environment:

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:

    • Change the URL to include a suffix of :POOLED or (SERVER=POOLED) for service URLs.

    • Update the connection properties to include the value/name pair of the DRCP connection class. For example: oracle.jdbc.DRCPConnectionClass=myDRCPclass.

    • Click Save.

  • When creating or editing a data source with a text editor or using WLST:

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

    • 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 a datasource 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.

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 datasource 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 datasource 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 datasource 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 datasource connections may be terminated and your applications may receive an error, such as a socket exception, when accessing a WebLogic datasource connection.

Global Database 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.

The following sections provide information on requirements and configuration for GDS in WebLogic Server:

Requirements and Considerations

The following section provides requirements and considerations when using Global Database 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 manger (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 datasource configuration, one datasource must be defined for the update service and another datasource defined for the read-only service.

  • Your application must be written so that update operations are process by the update datasource and read-only operations are processed by the read-only datasource.

Creating a GridLink DataSource for GDS Connectivity

Use the WebLogic Server Administration Console to create a GridLink datasource that uses a modified URL to provide 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 Managers

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

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 Oracle Pluggable Databases" in the Oracle Database Administrator's Guide.

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 Application Continuity, 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;
/

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

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;

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:

  • Application Continuity (Replay)

  • DRCP

  • client identifier

  • proxy user

  • The connection harvesting callback.

Limitations with Tenant Switching

When you switch from one tenant to another tenant using ALTER SESSION SET CONTAINER, there is currently no mechanism to indicate to which user service you want to switch in that PDB. Instead the PDB service on the new tenant is used. The PDB service is an administrative service that is created for every PDB (so every PDB has at least one service for administration). As an administrative service, user-level service features are not supported. These restrictions will be removed in a future database release by allowing user services.

The following additional WebLogic Server limitations exist when using tenant switching with the 12.1 database release:

  • XA and global transactions are not supported.

  • FAN is not supported. Even though FAN is not supported, Active GridLink still provides the benefit of a single datasource view of multiple RAC instances and the ability to reserve connections on new instances as they are available without reconfiguration using connection load balancing. This connection load balancing is based strictly on session counts as there is no metrics support. If you want to use tenant switching with an Active GridLink data source, FAN enabled must be set to false. Runtime Load Balancing is not available to optimally reserve existing connections (either local or with Global Data Services). Instead, round robin is used to assign connections. This also implies that connection gravitation is not supported since the runtime load balancing information is not available. Session affinity is not supported. ONS (including auto-ONS) is not supported; this also affects features like Global Data Services and Active Data Guard. Instead of receiving down events, WebLogic uses connection testing to see if an instance is down. See Using Active GridLink Data Sources without FAN Notification for details of what this implies for AGL. Transaction Affinity is not affected because it is not based on FAN. This restriction does not apply to Generic data sources (they don't use FAN).

  • DRCP is not supported. If a connection is chosen from the database-resident connection pool that doesn't match the requested tenant, an error occurs (service switching is not supported by DRCP). Since WebLogic Server is not matching on the tenant when selecting a connection, WebLogic Server cannot guarantee that a valid connection will be selected.

  • Application Continuity is not supported. The attributes needed (FAILOVER_TYPE=TRANSACTION and COMMIT_OUTCOME=true) can not be set on the PDB service.

  • Proxy authentication is not supported. A java.sql.SQLException "ORA-01017: invalid username/password" is thrown.

  • A number of database features based on services are not available including: management operations based on services, service-based metrics, top consumers in Enterprise Manager, database service-based alerts, restriction of parallel query to a user service.