oracle.jdbc.diagnostics

Interface Diagnosable

All Superinterfaces:

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

Modifier and Type	Method and Description
default void	begin(Metrics.ConnectionEvent event) 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... 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 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 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	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(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(PropertyChangeEvent event)

This method gets called when a MBean operation is invoked.

Specified by:

propertyChange in interface 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

end

default void end(Metrics.ConnectionEvent event)

Ends collecting metrics for the given event.

Parameters:

event - the event name

onClose

default void onClose()

Action to be performed on close of this diagnosable.