Package oracle.ucp.diagnostics

Interface Diagnosable

All Known Subinterfaces:

ConnectionFactoryAdapter, DiagnosticsCollector, PoolDataSource, PoolXADataSource, UniversalConnectionPool

All Known Implementing Classes:

PoolDataSourceImpl, PoolDataSourceImpl.ConnectionPublisher, PoolXADataSourceImpl, oracle.ucp.admin.UniversalConnectionPoolManagerBase, UniversalConnectionPoolManagerImpl

public interface Diagnosable

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	Description
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, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object... args)	For compatibility with older code that does not have a SecurityLabel...
default <T extends java.lang.Throwable> T	debug(java.util.logging.Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object... args)	If dynamic trace is enabled, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable.
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()	Only used by the default methods of this interface.
default boolean	isLoggingLevelFinest()	Is current logging level FINEST? This method allows to skip traces/debugs with expensive formatting, with 'if (isLoggingLevelFinest()) trace(...);'
default void	resumeLogging()	Resume trace 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 trace and debug logging.
default <T extends java.lang.Throwable> T	trace(java.util.logging.Level level, java.lang.String className, java.lang.String methodName, java.lang.String publicMessage, java.lang.String privateMessage, T thrown, java.lang.Object... args)	For compatibility with older code that does not have a SecurityLabel...
default <T extends java.lang.Throwable> T	trace(java.util.logging.Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, 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.

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 return 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,
                                                oracle.jdbc.diagnostics.SecurityLabel securityLabel,
                                                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 - security 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,
                                                oracle.jdbc.diagnostics.SecurityLabel securityLabel,
                                                java.lang.String className,
                                                java.lang.String methodName,
                                                java.lang.String publicMessage,
                                                java.lang.String privateMessage,
                                                T thrown,
                                                java.lang.Object... args)

If dynamic trace 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 dynamic trace 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 - security 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)

trace

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

For compatibility with older code that does not have a SecurityLabel...

debug

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

For compatibility with older code that does not have a SecurityLabel...

suspendLogging

default void suspendLogging()

Temporarily suspend trace 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 trace or debug. Each can be enabled and/or disabled repeatedly while logging is suspended and once logging is resumed trace and debug will be generated exactly as if logging were never suspended. While logging is suspended no trace or debug log records will be generated regardless of any calls to enable or disable trace 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. Sensitive values will appear in trace and debug logs if sensitive mode is enabled. Passwords cannot appear in logs ever, hence the need to suspend logging.

resumeLogging

default void resumeLogging()

Resume trace 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 trace or debug. Each can be enabled and/or disabled repeatedly while logging is suspended and once logging is resumed trace and debug will be generated exactly as if logging were never suspended. While logging is suspended no trace or debug log records will be generated regardless of any calls to enable or disable trace 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. Sensitive values will appear in trace and debug logs if sensitive mode is enabled. Passwords cannot appear in logs ever, hence the need to suspend logging.

beginCurrentSql

default void beginCurrentSql(java.lang.String sql)

Set the current SQL support logging a specific SQL.

Parameters:

sql - Must be origianl (user specified) SQL

endCurrentSql

default void endCurrentSql()

Restore the current SQL support logging a specific SQL.

isLoggingLevelFinest

default boolean isLoggingLevelFinest()

Is current logging level FINEST? This method allows to skip traces/debugs with expensive formatting, with 'if (isLoggingLevelFinest()) trace(...);'

Returns:

true, if current logging level is FINEST

getDiagnosable

default Diagnosable getDiagnosable()

Only used by the default methods of this interface. No other code should use it. Every class that implements this interface must either override this method to return a Diagnosable that actually implements the other methods or override the other methods to actually implement their defined behavior. It is not necessary or appropriate to do both.

Returns: