Package oracle.jdbc.diagnostics

## Interface Diagnosable

All Superinterfaces:
  `java.util.EventListener`, `java.beans.PropertyChangeListener`

All Known Implementing Classes:
  `AbstractDiagnosable`, `ArrayDescriptor`, `CommonDiagnosable`, `ConverterArchive`, `OpaqueDescriptor`, `OracleConnectionPoolDataSource`, `OracleConnectionPoolDataSource`, `OracleConnectionPoolDataSourceImpl`, `OracleDataSource`, `OracleDataSource`, `OracleDataSourceImpl`, `OracleMultiPhaseArgs`, `OracleOCIConnectionPool`, `OraclePooledConnection`, `OracleXAConnection`, `OracleXAConnection`, `OracleXADataSource`, `OracleXADataSource`, `OracleXADataSourceImpl`, `OracleXAHeteroCloseCallback`, `OracleXAHeteroConnection`, `OracleXAHeteroResource`, `OracleXAResource`, `OracleXAResource`, `StructDescriptor`, `TypeDescriptor`

    public interface Diagnosable
    extends java.beans.PropertyChangeListener

Instances of this interface support collecting diagnostic information. Most JDBC and UCP objects should implement this interface by overriding getDiagnosable to return an object that implements the other methods. Classes that implement the other methods will do so by calling support code in other types in this package. My expectation is that only Connection and DataSource implementation classes will implement the other methods though that is not a requirement. All other classes that implement this interface will return a Connection or DataSource from getDiagnosable.

### Method Summary

All Methods Instance Methods Default Methods
`default void` `begin​(Metrics.ConnectionEvent event)` Begins collecting metrics for the given event.
`default void` `begin​(Metrics.ConnectionEvent event, int retryCount)` Begins collecting metrics for the given event.
`default void` `beginCurrentSql​(java.lang.String sql)` Set the current SQL support logging a specific SQL.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown)` Debug API with no args.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg)` Debug with one arg.

`default <T extends java.lang.Throwable>
T`

`debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object... args)`

If Diagnose First Failure is enabled, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable.

`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2)` Debug API with two args.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3)` Debug API with three args.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4)` Debug API with four args.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5)` Debug API with five args.
`default <T extends java.lang.Throwable> T` `debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5, java.lang.Object arg6)` Debug API with six args.

`default <T extends java.lang.Throwable>
T`

`debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5, java.lang.Object arg6, java.lang.Object arg7)`

Debug API with seven args.

`default <T extends java.lang.Throwable>
T`

`debug​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object arg1, java.lang.Object arg2, java.lang.Object arg3, java.lang.Object arg4, java.lang.Object arg5, java.lang.Object arg6, java.lang.Object arg7, java.lang.Object arg8)`

Debug API with eight args.

`default <T extends java.lang.Throwable>
T`

`debugp​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.util.function.Supplier<java.lang.Object[]> argsSupplier)`

If Diagnose First Failure is enabled, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable.

`default void` `end​(Metrics.ConnectionEvent event)` Ends collecting metrics for the given event.
`default void` `end​(Metrics.ConnectionEvent event, int retryCount)` Ends collecting metrics for the given event.
`default void` `endCurrentSql()` Restore the current SQL support logging a specific SQL.
`default java.lang.Object` `format​(oracle.jdbc.clio.annotations.Format.Style f, java.lang.Object value, long... args)` Return an Object that will format the value as specified.
`default Diagnosable` `getDiagnosable()`
`default boolean` `isDebugEnabled()` Returns true if debug is enabled.
`default boolean` `isDiagnoseFirstFailureEnabled()` Returns true if Diagnose First Failure is enabled.
`default boolean` `isLoggable​(java.util.logging.Level level)` Check if a message of the given level would actually be logged by this logger.
`default boolean` `isSensitiveEnabled()` Returns `true` if sensitive logging is enabled, Otherwise returns `false`
`default void` `onClose()` Action to be performed on close of this diagnosable.
`default void` `propertyChange​(java.beans.PropertyChangeEvent event)` This method gets called when a MBean operation is invoked.
`default void` `resumeLogging()` Resume Diagnose First Failure and debug logging after it is temporarily suspended by calling suspendLogging.
`default java.lang.Object` `secure​(java.lang.Object value)` Return a secure representation for the value.
`default void` `suspendLogging()` Temporarily suspend Diagnose First Failure and debug logging.
`default <T extends java.lang.Throwable> T` `trace​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object... args)` If diagnose first failure is enabled store an OracleLogRecord in the appropriate ring buffer.
`default <T extends java.lang.Throwable> T` `tracep​(java.util.logging.Level level, SecurityLabel label, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.util.function.Supplier<java.lang.Object[]> argsSupplier)` If diagnose first failure is enabled store an OracleLogRecord in the appropriate ring buffer.

### Method Detail

#### secure

    default java.lang.Object secure​(java.lang.Object value)

Return a secure representation for the value. If sensitive mode is not enabled that representation will display as "". If sensitive mode is enabled when this method is called the representation will display the value.

Parameters:
  `value` - the value to return if sensitive mode is enabled
Returns:
  a representation that displays the value only if sensitive mode is enabled when this method is called

#### format

    default java.lang.Object format​(oracle.jdbc.clio.annotations.Format.Style f,
                                    java.lang.Object value,
                                    long... args)

Return an Object that will format the value as specified.

Parameters:
  `f` -
  `value` -
  `args` -
Returns:

#### trace

    default <T extends java.lang.Throwable> T trace​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object... args)

If diagnose first failure is enabled store an OracleLogRecord in the appropriate ring buffer. If sensitive mode is enabled when this method is called the stored OracleLogRecord holds the privateMessage. If sensitive mode is not enabled when this method is called the stored OracleLogRecord holds the publicMessage. If diagnose first failure is not enabled this is a no op. Usage Note: The messages should be String literals or concatenations of String literals to minimize the cost of execution. The arguments should be simple values, not expressions or method calls. If complex formatting is needed use a Parameter. Sensitive arguments must be wrapped in a call to secure(Object).

Parameters:
  `level` - log level
  `SecurityLabel` - label
  `className` - the name of a class from which trace() is called
  `methodName` - the name of a method from which trace() is called
  `publicMessage` - some public message
  `privateMessage` - some private message (null in the 1st version)
  `thrown` - exception thrown (null for entering and returning calls, non-null for throwing calls)
  `args` - caller method's args, if is called in "entering" context
Returns:
  exception (must be non-null in throwing context, null in entering and returning context)

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object... args)

If Diagnose First Failure is enabled, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable. If sensitive mode is enabled when this method is called the logged OracleLogRecord holds the privateMessage. If sensitive mode is not enabled when this method is called the logged OracleLogRecord holds the publicMessage. If Diagnose First Failure is not enabled this is a no op. Usage Note: The messages should be String literals or concatenations of String literals to minimize the cost of execution. The arguments should be simple values, not expressions or method calls. If complex formatting is needed use a Parameter. Sensitive arguments must be wrapped in a call to secure(Object).

Parameters:
  `level` - log level
  `SecurityLabel` - label
  `className` - the name of a class from which trace() is called
  `methodName` - the name of a method from which trace() is called
  `publicMessage` - some public message
  `privateMessage` - some private message (null in the 1st version)
  `thrown` - exception thrown (null for entering and returning calls, non-null for throwing calls)
  `args` - caller method's args, if is called in "entering" context
Returns:
  exception (must be non-null in throwing context, null in entering and returning context)

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown)

Debug API with no args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg)

Debug with one arg.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2)

Debug API with two args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3)

Debug API with three args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3,
                                                    java.lang.Object arg4)

Debug API with four args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3,
                                                    java.lang.Object arg4,
                                                    java.lang.Object arg5)

Debug API with five args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3,
                                                    java.lang.Object arg4,
                                                    java.lang.Object arg5,
                                                    java.lang.Object arg6)

Debug API with six args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3,
                                                    java.lang.Object arg4,
                                                    java.lang.Object arg5,
                                                    java.lang.Object arg6,
                                                    java.lang.Object arg7)

Debug API with seven args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### debug

    default <T extends java.lang.Throwable> T debug​(java.util.logging.Level level,
                                                    SecurityLabel label,
                                                    java.lang.String className,
                                                    java.lang.String methodName,
                                                    java.lang.String publicMessage,
                                                    java.lang.String privateMessage,
                                                    T thrown,
                                                    java.lang.Object arg1,
                                                    java.lang.Object arg2,
                                                    java.lang.Object arg3,
                                                    java.lang.Object arg4,
                                                    java.lang.Object arg5,
                                                    java.lang.Object arg6,
                                                    java.lang.Object arg7,
                                                    java.lang.Object arg8)

Debug API with eight args.

See Also:
  `debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)`

#### tracep

    default <T extends java.lang.Throwable> T tracep​(java.util.logging.Level level,
                                                     SecurityLabel label,
                                                     java.lang.String className,
                                                     java.lang.String methodName,
                                                     java.lang.String publicMessage,
                                                     java.lang.String privateMessage,
                                                     T thrown,
                                                     java.util.function.Supplier<java.lang.Object[]> argsSupplier)

If diagnose first failure is enabled store an OracleLogRecord in the appropriate ring buffer. If sensitive mode is enabled when this method is called the stored OracleLogRecord holds the privateMessage. If sensitive mode is not enabled when this method is called the stored OracleLogRecord holds the publicMessage. If diagnose first failure is not enabled this is a no op.

Parameters:
  `level` - log level
  `SecurityLabel` - label
  `className` - the name of a class from which trace() is called
  `methodName` - the name of a method from which trace() is called
  `publicMessage` - some public message
  `privateMessage` - some private message
  `thrown` - exception thrown (null for entering and returning calls, non-null for throwing calls)
  `argsSupplier` - caller method's args supplier, if is called in "entering" context
Returns:
  exception (must be non-null in throwing context, null in entering and returning context)

#### debugp

    default <T extends java.lang.Throwable> T debugp​(java.util.logging.Level level,
                                                     SecurityLabel label,
                                                     java.lang.String className,
                                                     java.lang.String methodName,
                                                     java.lang.String publicMessage,
                                                     java.lang.String privateMessage,
                                                     T thrown,
                                                     java.util.function.Supplier<java.lang.Object[]> argsSupplier)

If Diagnose First Failure is enabled, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable. If sensitive mode is enabled when this method is called the logged OracleLogRecord holds the privateMessage. If sensitive mode is not enabled when this method is called the logged OracleLogRecord holds the publicMessage. If Diagnose First Failure is not enabled this is a no op.

Parameters:
  `level` - log level
  `SecurityLabel` - label
  `className` - the name of a class from which trace() is called
  `methodName` - the name of a method from which trace() is called
  `publicMessage` - some public message
  `privateMessage` - some private message
  `thrown` - exception thrown (null for entering and returning calls, non-null for throwing calls)
  `argsSupplier` - caller method's args supplier, if is called in "entering" context
Returns:
  exception (must be non-null in throwing context, null in entering and returning context)

#### suspendLogging

    default void suspendLogging()

Temporarily suspend Diagnose First Failure and debug logging. Logging is resumed, if enabled, by calling resumeLogging. Calls should always be paired and calls to resumeLogging should be in a finally block. Calls can be nested. Suspending logging is orthogonal to enabling Diagnose First Failure or debug. Each can be enabled and/or disabled repeatedly while logging is suspended and once logging is resumed Diagnose First Failure and debug will be generated exactly as if logging were never suspended. While logging is suspended no Diagnose First Failure or debug log records will be generated regardless of any calls to enable or disable Diagnose First Failure and debug. Logging should be suspended only when password values and other data of equivalent sensitivity are in motion. Note that @Sensitive is not sufficient to protect such values.

#### resumeLogging

    default void resumeLogging()

Resume Diagnose First Failure and debug logging after it is temporarily suspended by calling suspendLogging. Calls should always be paired and calls to resumeLogging should be in a finally block. Calls can be nested. Suspending logging is orthogonal to enabling Diagnose First Failure or debug. Each can be enabled and/or disabled repeatedly while logging is suspended and once logging is resumed Diagnose First Failure and debug will be generated exactly as if logging were never suspended. While logging is suspended no Diagnose First Failure or debug log records will be generated regardless of any calls to enable or disable Diagnose First Failure and debug. Logging should be suspended only when password values and other data of equivalent sensitivity are in motion. Note that @Sensitive is not sufficient to protect such values.

#### beginCurrentSql

    default void beginCurrentSql​(java.lang.String sql)

Set the current SQL support logging a specific SQL.

Parameters:
  `the` - new SQL. Must be origianl (user specified) SQL

#### endCurrentSql

    default void endCurrentSql()

Restore the current SQL support logging a specific SQL.

#### getDiagnosable

    default Diagnosable getDiagnosable()

Returns:

#### isLoggable

    default boolean isLoggable​(java.util.logging.Level level)

Check if a message of the given level would actually be logged by this logger.

#### isDebugEnabled

    default boolean isDebugEnabled()

Returns true if debug is enabled.

Returns:
  true if debug is enabled.

#### isSensitiveEnabled

    default boolean isSensitiveEnabled()

Returns `true` if sensitive logging is enabled, Otherwise returns `false`

Returns:
  isSensitiveEnabled

#### isDiagnoseFirstFailureEnabled

    default boolean isDiagnoseFirstFailureEnabled()

Returns true if Diagnose First Failure is enabled.

Returns:
  true if Diagnose First Failure is enabled.

#### propertyChange

    default void propertyChange​(java.beans.PropertyChangeEvent event)

This method gets called when a MBean operation is invoked.

Specified by:
  `propertyChange` in interface `java.beans.PropertyChangeListener`
Parameters:
  `event` - A PropertyChangeEvent object describing the event source and the property that has changed.

#### begin

    default void begin​(Metrics.ConnectionEvent event)

Begins collecting metrics for the given event.

Parameters:
  `event` - the event name

#### begin

    default void begin​(Metrics.ConnectionEvent event,
                       int retryCount)

Begins collecting metrics for the given event.

Parameters:
  `event` - the event name
  `retryCount` - the retry count. Non-zero if this event is being retried.

#### end

    default void end​(Metrics.ConnectionEvent event)

Ends collecting metrics for the given event.

Parameters:
  `event` - the event name

#### end

    default void end​(Metrics.ConnectionEvent event,
                     int retryCount)

Ends collecting metrics for the given event.

Parameters:
  `event` - the event name
  `retryCount` - the retry count. Non-zero if this event is being retried.

#### onClose

    default void onClose()

Action to be performed on close of this diagnosable.