Fusion Middleware Documentation
Advanced Search


Administering JDBC Data Sources for Oracle WebLogic Server
Close Window

Table of Contents

Show All | Collapse

6 Advanced Configurations for Oracle Drivers and Databases

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

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 6-1 Application Continuity

Surrounding text describes Figure 6-1 .

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 Appendix A, "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 datasource 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 run time 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).

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

Configuring Logging for Application Continuity

To enable logging of Application Continuity processing, use the following WebLogic property:

-Dweblogic.debug.DebugJDBCReplay=true

Note:

To get driver-level debugging, you must use the ojdbc6_g.jar or ojdbc7_g.jar.

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.

Limitations with Application Continuity with Database Release 12.1.0.1

The following section provides information on limitations when using Oracle Database release 12.1.0.1 with Application Continuity:

  • Proxy authentication is not supported. That is, a transaction request will not be replayed and the original java.sql.SQLRecoverableException is thrown if an outage occurs.

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

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

Configuring a Database for DRCP

To configure your Oracle database to support DRCP:

  • DRCP must be enabled on the Database side using:

    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.

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

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