oracle.jdbc

Interface TraceEventListener

public interface TraceEventListener

A listener that receives application and system tracing events from the Oracle Database JDBC drivers.

If an instance is registered with an OracleConnection, that instance's roundTrip method will be called before and after each round trip to the database executed by that connection. The roundTrip method has limited access to the Connection but can get some information about the round trip and set a trace id.

The instance's onExecutionEventReceived method will be called for each execution event if the isDesiredEvent returns true for that event type.

If the driver understands the type of the trace id, the driver will use that trace id in trace records generated by the driver during the round trip. If the driver does not understand the type of the trace id it will use the result of calling toString on the trace id. What trace ids the driver understands may change from release to release.

Implementations of TraceEventListener may be registered programmatically with OracleConnectionBuilder.traceEventListener(TraceEventListener). Implementations may also be provided by an OracleResourceProvider identified with OracleConnection.CONNECTION_PROPERTY_PROVIDER_TRACE_EVENT_LISTENER.

Since:

23

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TraceEventListener.JdbcExecutionEvent
static class	TraceEventListener.Sequence Indicates if a call to roundTrip(Sequence, TraceContext, Object) is before or after the round trip to the database.
static interface	TraceEventListener.TraceContext Information about the round trip.

Method Summary

Modifier and Type	Method and Description
default boolean	isDesiredEvent(TraceEventListener.JdbcExecutionEvent event) Indicates whether the TraceEventListener desires to receive a given event.
default java.lang.Object	onExecutionEventReceived(TraceEventListener.JdbcExecutionEvent event, java.lang.Object userContext, java.lang.Object... params) Called each time an event occurs if observability is enabled and the event is present in the list of desired events.
java.lang.Object	roundTrip(TraceEventListener.Sequence seq, TraceEventListener.TraceContext traceContext, java.lang.Object userContext) Called before and after each round trip on the Connection if observability is enabled.

Method Detail

roundTrip

java.lang.Object roundTrip(TraceEventListener.Sequence seq,
                           TraceEventListener.TraceContext traceContext,
                           java.lang.Object userContext)

Called before and after each round trip on the Connection if observability is enabled. The before and after calls are always made in pairs even if observability is enabled/disabled during a round trip.

Parameters:

seq - BEFORE if before the round trip, AFTER if after the round trip

traceContext - Information about the round trip. Valid only during the call

userContext - Result of previous call on this Connection or null if no previous call or if observability was disabled since the previous call.

Returns:

a user context object that is passed to the next call on this Connection. May be null.

onExecutionEventReceived

default java.lang.Object onExecutionEventReceived(TraceEventListener.JdbcExecutionEvent event,
                                                  java.lang.Object userContext,
                                                  java.lang.Object... params)

Called each time an event occurs if observability is enabled and the event is present in the list of desired events.

The following parameters are available depending on the event type:

• VIP_RETRY
• The error message of the error that caused the retry
• The protocol
• The host
• The port
• The service name
• The SID
• The connection data
• The VIP address
• AC_REPLAY_STARTED
• The error message of the error that caused the replay
• The SQLException object of that error
• The current replay retry count
• AC_REPLAY_SUCCESSFUL
• The error message of the error that caused the replay
• The SQLException object of that error
• The current replay retry count

Note: This callback runs in the same thread as the connection.

Parameters:

event - the event.

userContext - the result of the previous call or null if no previous. call has been made.

params - event specific parameters.

Returns:

a user context object that is passed to the next call for the same type of event. May be null.

isDesiredEvent

default boolean isDesiredEvent(TraceEventListener.JdbcExecutionEvent event)

Indicates whether the TraceEventListener desires to receive a given event.

Parameters:

event - the event.

Returns:

true if the TraceEventListner whishes to receive the event otherwise false.