To create a JDBC connection initialization callback, an application implements the oracle.jdbc.replay.ConnectionInitializationCallback interface. One callback is allowed for every instance of the oracle.jdbc.replay.OracleDataSource interface.

Example

The following code snippet demonstrates a simple initialization callback implementation:

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

For applications using an XA data source, the connection initialization callback is registered on the XA replay data source. The callback is executed every time when both of the following happen:

• A connection is borrowed from the connection pool.

• The replay XA data source gets a new physical connection at failover.

If a callback invocation fails, replay is disabled on that connection. For example, an application embeds the set up phase for a connection in this callback.

Use the following method that the JDBC Replay Driver provides in the oracle.jdbc.replay.OracleDataSource interface for registering a connection initialization callback:

registerConnectionInitializationCallback(ConnectionInitializationCallback cbk)

One callback is allowed for every instance of the OracleDataSource interface.

For using an XA Data Source, use the registerConnectionInitializationCallback(ConnectionInitializationCallback cbk) method in the oracle.jdbc.replay.OracleXADataSource interface.

Use the following method that the JDBC Replay Driver provides in the oracle.jdbc.replay.OracleDataSource interface for unregistering a connection initialization callback:

unregisterConnectionInitializationCallback(ConnectionInitializationCallback cbk)

For using an XA Data Source, use the unregisterConnectionInitializationCallback(ConnectionInitializationCallback cbk) method in the oracle.jdbc.replay.OracleXADataSource interface.

If you are using Oracle RAC or Oracle RAC One, then use the SRVCTL command to create and modify services in the following way:

• For Policy-Managed Environments

• For Administrator-Managed Environments

For Policy-Managed Environments

srvctl add service -db codedb -service gold -serverpool Srvpool -clbgoal SHORT -rlbgoal SERVICE_TIME -failoverdelay 30 -failoverretry 10 -commit_outcome TRUE -failovertype TRANSACTION -replay_init_time 1800 -retention 86400 -notification TRUE

For Administrator-Managed Environments

srvctl add service -db codedb -service gold -preferred serv1 -available serv2 -clbgoal SHORT -rlbgoal SERVICE_TIME -failoverdelay 30 -failoverretry 10 -commit_outcome TRUE -failovertype TRANSACTION -replay_init_time 1800 -retention 86400 -notification TRUE

If you are using a single-instance database, then use the DBMS_SERVICE package to modify services in the following way:

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;
/

The DATE_TIME and SYS_GUID syntax is as follows:

GRANT [KEEP DATE TIME|SYSGUID]..[to USER}
REVOKE [KEEP DATE_TIME | KEEP SYS_GUID] … [from USER]

For example, for EBS standard usage with original dates

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

The Sequence syntax can be of the following types:

• Owned Sequence Syntax

• Others Sequence Syntax

Owned Sequence Syntax

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

This command retains the original values of sequence.nextval for replaying, so that the keys match after replay. Most applications need to retain the sequence values at replay. The ALTER SYNTAX is only for owned sequences.

Others Sequence Syntax

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

For example, use the following command for EBS standard usage with original sequence values:

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

The GRANT ALL statement grants KEEP privilege on all the objects of a user. However, it excludes mutable values, that is, mutable values require explicit grants.

Follow these rules while granting privileges on mutable objects:

• If a user has KEEP privilege granted on mutables values, then the objects inherit mutable access when the SYS_GUID, SYSDATE, and SYSTIMESTAMP functions are called.

• If the KEEP privilege on mutable values on a sequence object is revoked, then SQL or PL/SQL blocks using that object will not allow mutable collection or application for that sequence.

• If granted privileges are revoked between runtime and failover, then the mutable values that are collected are not applied for replay.

• If new privileges are granted between runtime and failover, mutable values are not collected and these values are not applied for replay.

During replay, autonomous transactions and external PL/SQL calls can have side effects that are separate from the main transaction. These side effects are replayed unless you specify otherwise and leave persistent results behind. These side effects include writing to an external table, sending email, forking sessions out of PL/SQL or Java, transferring files, accessing external URLs, and so on. For example, in case of PL/SQL messaging, suppose, you walk away in-between some work without committing and the session times out. Now, if you issue a Ctrl+C command, then the foreground of a component fails. When you resubmit the work, then this side effect can also be repeated.

You must make a conscious decision about whether to enable replay for external actions or not. For example, you can consider the following situations where this decision is important:

• Using the UTL_HTTP package to issue a SOA call

• Using the UTL_SMTP package to send a message

• Using the UTL_URL package to access a web site

Use the disableReplay API if you do not want such external actions to be replayed.

You can configure an application for replay if the application synchronizes independent sessions using volatile entities that are held until commit, rollback, or session loss. In this case, the application synchronizes multiple sessions connected to several data sources that are otherwise inter-dependent using resources such as a database lock. This synchronization may be fine if the application is only serializing these sessions and understands that any session may fail. However, if the application assumes that a lock or any other volatile resource held by one data source implies exclusive access to data on the same or a separate data source from other connections, then this assumption may be invalidated when replaying.

During replay, the driver is not aware that the sessions are dependent on one session holding a lock or other volatile resource. You can also use pipes, buffered queues, stored procedures taking a resource (such as a semaphore, device, or socket) to implement the synchronization that are lost by failures.

In this case, the application uses the wall clock at the middle-tier as part of the execution logic. The JDBC replay driver does not repeat the middle-tier time logic, but uses the database calls that execute as part of this logic. For example, an application using middle-tier time may assume that a statement executed at Time T1 is not reexecuted at Time T2, unless the application explicitly does so.

If an application caches ROWIDs, then access to these ROWIDs may be invalidated due to database changes. Although a ROWID uniquely identifies a row in a table, a ROWID may change its value in the following situations:

• The underlying table is reorganized

• An index is created on the table

• The underlying table is partitioned

• The underlying table is migrated

• The underlying table is exported and imported using EXP/IMP/DUL

• The underlying table is rebuilt using Golden Gate or Logical Standby or other replication technology

• The database of the underlying table is flashed back or restored

It is bad practice for an application to store ROWIDs for later use as the corresponding row may either not exist or contain completely different data.

In this case, the following are replayed during a replay:

• Autonomous transactions

• Opening of back channels separate to the main transaction side effects

Examples of back channels separate to the main transaction include writing to an external table, sending email, forking sessions out of PL/SQL or Java, writing to output files, transferring files, and writing exception files. Any of these actions leave persistent side effects in the absence of replay. Back channels can leave persistent results behind. For example, if a user leaves a transaction midway without committing and the session times out, then the user presses Ctrl+C, the foreground or any component fails. If the user resubmits work, then the side effects can be repeated.

SYSCONTEXT options comprise a location-independent set such as National Language Support (NLS) settings, ISDBA, CLIENT_IDENTIFIER, MODULE, and ACTION, and a location-dependent set that uses physical locators. Typically, an application does not use the physical identifier, except in testing environments. If physical locators are used in mainline code, then the replay finds the mismatch and rejects it. However, it is fine to use physical locators in callbacks.

Example

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

Following is the example of a configuration file for logging configuration.

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

Following is the example of a properties file for logging configuration.

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