27 Application Continuity for Java

Configuring Oracle JDBC for Application Continuity for Java

You must use either the oracle.jdbc.replay.OracleDataSourceImpl or oracle.jdbc.replay.OracleConnectionPoolDataSourceImpl data source to obtain JDBC connections. They are new Oracle JDBC data sources, and work similarly to the existing non-XA data sources, such as oracle.jdbc.pool.OracleDataSource. You can use both in a standalone manner, or configure them as connection factories for a connection pool, such as Universal Connection Pool (UCP), or Oracle WebLogic Server connection pool.

The following code snippet illustrates their usage in a standalone JDBC application:

import java.sql.Connection;
import javax.sql.PooledConnection;
import oracle.jdbc.OracleConnection;
import oracle.jdbc.replay.OracleDataSourceFactory;
import oracle.jdbc.replay.OracleDataSource;
import oracle.jdbc.replay.OracleConnectionPoolDataSource;
 
...
{
......
OracleDataSource rds = OracleDataSourceFactory.getOracleDataSource();
rds.setUser(user);
rds.setPassword(passwd);
rds.setURL(url);
......  // Other data source configuration like callback, timeouts, etc.
 
Connection conn = rds.getConnection();
((OracleConnection) conn).beginRequest();  // Explicit request begin
......  // JDBC calls protected by Application Continuity
((OracleConnection) conn).endRequest();  // Explicit request end
conn.close();
 
OracleConnectionPoolDataSource rcpds = OracleDataSourceFactory.getOracleConnectionPoolDataSource();
rcpds.setUser(user);
rcpds.setPassword(passwd);
rcpds.setURL(url);
......  // other data source configuration like callback, timeouts, and so on
 
PooledConnection pc = rcpds.getPooledConnection();
Connection conn2 = pc.getConnection();  // Implicit request begin
......  // JDBC calls protected by Application Continuity
conn2.close();  // Implicit request end
......

You must remember the following points while using the connection URL:

• Always use the thin driver in the connection URL.

• Always connect to a service. Never use instance_name or SID because these do not direct to known good instances and SID is deprecated.

• If the addresses in the ADDRESS_LIST at the client does not match the REMOTE_LISTENER setting for the database, then it does not connect showing services cannot be found. So, the addresses in the ADDRESS_LIST at the client must match the REMOTE_LISTENER setting for the database:

  • If REMOTE_LISTENER is set to the SCAN_VIP, then the ADDRESS_LIST uses SCAN_VIP

  • If REMOTE_LISTENER is set to the host VIPs, then the ADDRESS_LIST uses the same host VIPs

  • If REMOTE_LISTENER is set to both SCAN_VIP and host VIPs, then the ADDRESS_LIST uses SCAN_VIP and the same host VIPs

    Note:

    For Oracle clients prior to release 11.2, the ADDRESS_LIST must be upgraded to use SCAN, which means expanding the ADDRESS_LIST to three ADDRESS entries corresponding to the three SCAN IP addresses.

    If such clients connect to a database that is upgraded from an earlier release through Database Upgrade Assistant, then you must retain the ADDRESS_LIST of these clients set to the HOST VIPs. However, if REMOTE_LISTENER is changed to ONLY SCAN, or the clients are moved to a newly installed Oracle Database 12c Release 1, where REMOTE_LISTENER is ONLY SCAN, then they do not get a complete service map, and may not always be able to connect.

• Set RETRY_COUNT, CONNECT_TIMEOUT, and TRANSPORT_CONNECT_TIMEOUT parameters in the connection string. This is a general recommendation for configuring the JDBC thin driver connections, starting from Oracle Database Release 11.2.0.2. These settings improve acquiring new connections at runtime, at replay, and during work drains for planned outages.

  The CONNECT_TIMEOUT parameter is equivalent to the SQLNET.OUTBOUND_CONNECT_TIMEOUT parameter in the sqlnet.ora file and applies to the full connection. The TRANSPORT_CONNECT_TIMEOUT parameter applies as per the ADDRESS parameter. If the service is not registered for a failover or restart, then retrying is important when you use SCAN. For example, for using remote listeners pointing to SCAN addresses, you should use the following settings:

  jdbc:oracle:thin:@(DESCRIPTION = 
   (TRANSPORT_CONNECT_TIMEOUT=3)
   (RETRY_COUNT=20)(FAILOVER=ON)
   (ADDRESS_LIST =(ADDRESS=(PROTOCOL=tcp)
    (HOST=CLOUD-SCANVIP.example.com)(PORT=5221)) 
   (CONNECT_DATA=(SERVICE_NAME=orcl))) 
   
  REMOTE_LISTENERS=CLOUD-SCANVIP.example.com:5221 
  

  Similarly, for using remote listeners pointing to VIPs at the database, you should use the following settings:

  jdbc:oracle:thin:@(DESCRIPTION = 
  (TRANSPORT_CONNECT_TIMEOUT=3)
  (CONNECT_TIMEOUT=60)(RETRY_COUNT=20)(FAILOVER=ON)
   (ADDRESS_LIST=
   (ADDRESS=(PROTOCOL=tcp)(HOST=CLOUD-VIP1.example.com)(PORT=5221) )
  (ADDRESS=(PROTOCOL=tcp)(HOST=CLOUD-VIP2.example.com)(PORT=5221) )
   (ADDRESS=(PROTOCOL=tcp)(HOST=CLOUD-VIP3.example.com)(PORT=5221) )) 
  (CONNECT_DATA=(SERVICE_NAME=orcl)))
  
  REMOTE_LISTENERS=CLOUD-VIP1.example.com:5221 
  

  See Also:

  • Oracle Database Net Services Reference for more information about local naming parameters

  • Oracle Real Application Clusters Administration and Deployment Guide

Configuring Oracle Database for Application Continuity for Java

You must have the following configuration for Oracle Database to use Application Continuity for Java:

• Use Oracle Database 12c Release 1 (12.1)

• If you are using Oracle Real Application Clusters (Oracle RAC) or Oracle Data Guard, then ensure that FAN is configured with Oracle Notification System (ONS) to communicate with Oracle WebLogic Server or the Universal Connection Pool (UCP)

• Use an application service for all database work. To create the service you must:

  • Run the SRVCTL command if you are using Oracle RAC

  • Use the DBMS_SERVICE package if you are not using Oracle RAC

• Set the required properties on the service for replay and load balancing. For example, set:

  • FAILOVER_TYPE = TRANSACTION for using Application Continuity

  • COMMIT_OUTCOME = TRUE for enabling Transaction Guard

  • REPLAY_INITIATION_TIMEOUT = 900 for setting the duration in seconds for which replay will occur

  • FAILOVER_RETRIES = 30 for specifying the number of connection retries for each replay

  • FAILOVER_DELAY = 10 for specifying the delay in seconds between connection retries

  • GOAL = SERVICE_TIME, if you are using Oracle RAC, then this is a recommended setting

  • CLB_GOAL = LONG, if you are using Oracle RAC, then this is a recommended setting

• Do not use the database service, that is, the default service corresponding to the DB_NAME or DB_UNIQUE_NAME. This service is reserved for Oracle Enterprise Manager and for DBAs. Oracle does not recommend the use of the database service for high availability because this service cannot be:

  • Enabled and disabled

  • Relocated on Oracle RAC

  • Switched over to Oracle Data Guard

Identifying Request Boundaries in Application Continuity for Java

A Request is a unit of work on a physical connection to Oracle Database that is protected by Application Continuity. Request demarcation varies with specific use-case scenarios. A request begins when a connection is borrowed from the Universal Connection Pool (UCP) or WebLogic Server connection pool, and ends when this connection is returned to the connection pool.

The JDBC driver provides explicit request boundary declaration APIs beginRequest and endRequest in the oracle.jdbc.OracleConnection interface. These APIs enable applications, frameworks, and connection pools to indicate to the JDBC Replay Driver about demarcation points, where it is safe to release the call history, and to enable replay if it had been disabled by a prior request. At the end of the request, the JDBC Replay Driver purges the recorded history on the connection, where the API is called. This helps to further conserve memory consumption for applications that use the same connections for an extended period of time without returning them to the pool.

You do not need to make any changes to your application for identifying request boundaries, if the application uses connections from these Oracle connection pools, or from the oracle.jdbc.replay.OracleConnectionPoolDataSourceImpl data source. However, for the connection pool to work, the application must get connections when needed, and release connections when not in use. This scales better and provides request boundaries transparently.

Applications that do not borrow and return connections from the Oracle connection pools should explicitly mark request boundaries. For example, if your application is using custom JDBC pools, then the beginRequest method should be called at check-out and the endRequest method should be called at check-in. These methods can also be used for standalone JDBC applications without a connection pool.

The APIs have no impact on the applications other than improving resource consumption, recovery, and load balancing performance. These APIs do not involve altering a connection state by calling any JDBC method, SQL, or PL/SQL. An error is returned if an attempt is made to begin or end a request while a local transaction is open.

Registering a Connection Initialization Callback in Application Continuity for Java (optional)

Non-transactional session state (NTSS) is state of a database session that exists outside database transactions and is not protected by recovery. For applications that use stateful requests, the non-transactional state is re-established as the rebuilt session.

For applications that set state only at the beginning of a request, or for stateful applications that gain performance benefits from using connections with a preset state, one among the following callback options are provided:

• No Callback

• Connection Labeling

• Connection Initialization Callback

import oracle.jdbc.replay.ConnectionInitializationCallback;
class MyConnectionInitializationCallback implements ConnectionInitializationCallback
{
    public MyConnectionInitializationCallback()  
    {
        ...
    }
    public void initialize(java.sql.Connection connection) throws SQLException
    {
        // Reset the state for the connection, if necessary (like ALTER SESSION)
        ...
    }
 }

Delaying the Reconnection in Application Continuity for Java

By default, when JDBC Replay Driver initiates a failover, the driver attempts to recover the in-flight work at an instance where the service is available. For doing this, the driver must first reestablish a good connection to a working instance. This reconnection can take some time if the database or the instance needs to be restarted before the service is relocated and published. So, the failover should be delayed until the service is available from another instance or database.

You need to use the FAILOVER_RETRIES and FAILOVER_DELAY parameters to manage reconnecting. These parameters can work well in conjunction with a planned outage, for example, an outage that may make a service unavailable for several minutes. While setting the FAILOVER_DELAY and FAILOVER_RETRIES parameters, check the value of the REPLAY_INITIAITION_TIMEOUT parameter first. The default value for this parameter is 900 seconds. A high value for the FAILOVER_DELAY parameter can cause replay to be canceled.

srvctl add service -d codedb -s GOLD -g Srvpool -j SHORT -B SERVICE_TIME –z 30 –w 10 -commit_outcome
 TRUE -e TRANSACTION -replay_init_time 1800 -retention 86400 -notification TRUE

srvctl add service -d codedb -s GOLD -r serv1 -a serv2  -j SHORT -B SERVICE_TIME –z 30 –w 10 -commit_outcome
 TRUE -e TRANSACTION -replay_init_time 1800 -retention 86400 -notification TRUE

declare
params dbms_service.svc_parameter_array;
begin
params('FAILOVER_TYPE'):='TRANSACTION';
params('REPLAY_INITIATION_TIMEOUT'):=1800;
params('RETENTION_TIMEOUT'):=604800;
params('FAILOVER_DELAY'):=10;
params('FAILOVER_RETRIES'):=30;
params('commit_outcome'):='true';
params('aq_ha_notifications'):='true';
dbms_service.modify_service('[your service]',params);
end;
/

Retaining Mutable Values in Application Continuity for Java

A mutable object is a variable, function return value, or other structure that returns a different value each time that it is called. For example, Sequence.NextVal, SYSDATE, SYSTIMESTAMP, and SYS_GUID. To retain the function results for named functions at replay, the DBA must grant KEEP privileges to the user who invokes the function. This security restriction is imposed to ensure that it is valid for replay to save and restore function results for code that is not owned by that user.

GRANT [KEEP DATE_TIME | KEEP SYS_GUID].. [to  USER]
REVOKE [KEEP DATE_TIME | KEEP SYS_GUID] … [from USER]

Grant KEEP DATE_TIME,  KEEP SYS_GUID  to [custom user];
Grant KEEP DATE_TIME,  KEEP SYS_GUID  to [apps user];

ALTER SEQUENCE [sequence object] [KEEP|NOKEEP];

GRANT KEEP SEQUENCES.. [to  USER]  on [sequence object];
REVOKE  KEEP SEQUENCES … [from USER]  on [sequence object];

Grant KEEP SEQUENCES  to [apps user] on [sequence object]; 
Grant KEEP SEQUENCES  to [custom user] on [sequence object];

Disabling Replay in Application Continuity for Java

This section describes the following concepts:

• How to Disable Replay

• When to Disable Replay

• Diagnostics and Tracing

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

select 
    sys_context('USERENV','DB_NAME') 
    ,sys_context('USERENV','HOST') 
    ,sys_context('USERENV','INSTANCE') 
    ,sys_context('USERENV','IP_ADDRESS') 
    ,sys_context('USERENV','ISDBA')  
    ,sys_context('USERENV','SESSIONID') 
    ,sys_context('USERENV','TERMINAL') 
    ,sys_context('USERENV',ID') 
from dual

oracle.jdbc.internal.replay.level = FINER|FINEST

oracle.jdbc.internal.replay.level = FINER
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = ALL
java.util.logging.ConsoleHandler.formatter = java.util.logging.XMLFormatter

oracle.jdbc.internal.replay.level = FINEST

# Output File Format (size, number and style)
# count: Number of output files to cycle through, by appending an integer to the base file name:
# limit: Limiting size of output file in bytes
handlers = java.util.logging.FileHandler
java.util.logging.FileHandler.pattern = [file location]/replay_%U.trc
java.util.logging.FileHandler.limit = 500000000
java.util.logging.FileHandler.count = 1000
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter