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(String sql)
    Set the current SQL support logging a specific SQL.
    default <T extends Throwable>
    T
    debug(Level level, String className, String methodName, String publicMessage, String privateMessage, T thrown, Object... args)
    For compatibility with older code that does not have a SecurityLabel...
    default <T extends Throwable>
    T
    debug(Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, String className, String methodName, String publicMessage, String privateMessage, T thrown, 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 Object
    format(oracle.jdbc.clio.annotations.Format.Style f, 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 Object
    secure(Object value)
    Return a secure representation for the value.
    default void
    suspendLogging()
    Temporarily suspend trace and debug logging.
    default <T extends Throwable>
    T
    trace(Level level, String className, String methodName, String publicMessage, String privateMessage, T thrown, Object... args)
    For compatibility with older code that does not have a SecurityLabel...
    default <T extends Throwable>
    T
    trace(Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, String className, String methodName, String publicMessage, String privateMessage, T thrown, Object... args)
    If diagnose first failure is enabled store an OracleLogRecord in the appropriate ring buffer.

  • Method Details

    • secure

      default Object secure(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 Object format(oracle.jdbc.clio.annotations.Format.Style f, Object value, long... args)
      Return an Object that will format the value as specified.
      Parameters:
      f -
      value -
      args -
      Returns:

    • trace

      default <T extends Throwable> T trace(Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, String className, String methodName, String publicMessage, String privateMessage, T thrown, 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 Throwable> T debug(Level level, oracle.jdbc.diagnostics.SecurityLabel securityLabel, String className, String methodName, String publicMessage, String privateMessage, T thrown, 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 Throwable> T trace(Level level, String className, String methodName, String publicMessage, String privateMessage, T thrown, Object... args)
      For compatibility with older code that does not have a SecurityLabel...

    • debug

      default <T extends Throwable> T debug(Level level, String className, String methodName, String publicMessage, String privateMessage, T thrown, 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(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: