Package oracle.jdbc.diagnostics

Class AbstractDiagnosable

  • All Implemented Interfaces:
    java.beans.PropertyChangeListener, java.util.EventListener, Diagnosable
    Direct Known Subclasses:
    CommonDiagnosable
    public abstract class AbstractDiagnosable
extends java.lang.Object
implements Diagnosable
    The abstract implementation of Diagnosable interface. This is a base class of concrete implementations oracle.jdbc.driver.ConnectionDiagnosable and oracle.jdbc.diagnostics.CommonDiagnosable.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      protected void abstractPropertyChange​(java.beans.PropertyChangeEvent event)
      The common event handler implementation of PropertyChangeEvent propertyChange(PropertyChangeEvent).
      void begin​(Metrics.ConnectionEvent event)
      Begins collecting metrics for the given event.
      void begin​(Metrics.ConnectionEvent event, int retryCount)
      Begins collecting metrics for the given event.
      <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.
      <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.
      <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 active, creates an OracleLogRecord and passes it to the java.util.logging.Logger configured for this Diagnosable.
      <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.
      <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.
      <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.
      <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.
      <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.
      <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.
      <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.
      <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.
      void enableDiagnoseFirstFailureDump​(boolean enableDump)
      Enables or disables the automatic dump of Diagnose First Failure data on error.
      static void enableGlobalDebug​(boolean enabled)
      Set or reset the global debug flag.
      static void enableMetrics​(boolean isEnabled)  
      static void enableWriteLogsToDiagnoseFirstFailure​(boolean enabled)
      Set or reset the flag that enables writing debug logs to Diagnose First Failure.
      void end​(Metrics.ConnectionEvent event)
      Ends collecting metrics for the given event.
      void end​(Metrics.ConnectionEvent event, int retryCount)
      Ends collecting metrics for the given event.
      protected abstract java.lang.String getDiagnosticLoggerName()  
      protected static java.lang.String getSystemProperty​(java.lang.String key, java.lang.String defaultValue, java.util.function.Predicate isValid)
      Reads the given system property.
      protected abstract TraceAttributes getTraceAttributes()  
      static boolean isGlobalDebugEnabled()
      Returns true if global debug logging flag is enabled.
      boolean isLoggable​(java.util.logging.Level level)
      Check if a message of the given level would actually be logged by this logger.
      static boolean isMetricsEnabled()  
      boolean isSensitiveEnabled()
      Returns true if sensitive logging is enabled, Otherwise returns false
      protected abstract boolean isSensitivePermitted()  
      static boolean isWriteLogsToDiagnoseFirstFailureEnabled()  
      void onClose()
      Action to be performed on close of this diagnosable.
      protected static void onConfigFileChange​(java.lang.String loggingConfigFileName)
      Reinitialize the logging properties and reread the logging configuration from the given stream, which should be in java.util.Properties format.
      void resumeLogging()
      Resume Diagnose First Failure and debug logging after it is temporarily suspended by calling suspendLogging.
      java.lang.Object secure​(java.lang.Object value)
      Return a secure representation for the value.
      protected abstract void setDebugEnabled​(boolean isEnabled)  
      protected abstract void setDiagnoseFirstFailureEnabled​(boolean isEnabled)  
      protected void setSensitiveEnabled​(boolean enabled)
      Before enabling sensitive logging, this method checks if sensitive logging is permitted.
      void suspendLogging()
      Temporarily suspend Diagnose First Failure and debug logging.
      <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.
      <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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • diagnostic

        protected Diagnostic diagnostic
        The reference of Diagnostic class used for recording Diagnose First Failure and debug logs.

      • IS_VALID_BUFFER_SIZE

        public static final java.util.function.Predicate<java.lang.String> IS_VALID_BUFFER_SIZE

      • IS_VALID_BOOLEAN_STRING

        protected static final java.util.function.Predicate<java.lang.String> IS_VALID_BOOLEAN_STRING

      • IS_VALID_LOGGER_NAME

        protected static final java.util.function.Predicate<java.lang.String> IS_VALID_LOGGER_NAME

    • Constructor Detail

      • AbstractDiagnosable

        public AbstractDiagnosable()

    • Method Detail

      • setDebugEnabled

        protected abstract void setDebugEnabled​(boolean isEnabled)

      • setDiagnoseFirstFailureEnabled

        protected abstract void setDiagnoseFirstFailureEnabled​(boolean isEnabled)

      • isSensitivePermitted

        protected abstract boolean isSensitivePermitted()

      • getDiagnosticLoggerName

        protected abstract java.lang.String getDiagnosticLoggerName()

      • getTraceAttributes

        protected abstract TraceAttributes getTraceAttributes()

      • setSensitiveEnabled

        protected void setSensitiveEnabled​(boolean enabled)
        Before enabling sensitive logging, this method checks if sensitive logging is permitted. Throws IllegalStateException if sensitive logging is not permitted.
        Parameters:
        enabled -

      • enableDiagnoseFirstFailureDump

        public void enableDiagnoseFirstFailureDump​(boolean enableDump)
        Enables or disables the automatic dump of Diagnose First Failure data on error.
        Parameters:
        enableDump - enable or disable automatic dump of Diagnose First Failure data

      • getSystemProperty

        protected static java.lang.String getSystemProperty​(java.lang.String key,
                                                    java.lang.String defaultValue,
                                                    java.util.function.Predicate isValid)
        Reads the given system property.
        Parameters:
        str - the system property name
        defaultValue - the default value to be returned if property is not set.
        isValid - predicate
        Returns:
        the property value.

      • abstractPropertyChange

        protected void abstractPropertyChange​(java.beans.PropertyChangeEvent event)
        The common event handler implementation of PropertyChangeEvent propertyChange(PropertyChangeEvent). The concrete classes oracle.jdbc.driver.ConnectionDiagnosable and oracle.jdbc.diagnostics.CommonDiagnosable override propertyChange(PropertyChangeEvent) and call this method for common event handling.
        Parameters:
        event - A PropertyChangeEvent object describing the event source and the property that has changed.

      • isSensitiveEnabled

        public boolean isSensitiveEnabled()
        Description copied from interface: Diagnosable
        Returns true if sensitive logging is enabled, Otherwise returns false
        Specified by:
        isSensitiveEnabled in interface Diagnosable
        Returns:
        isSensitiveEnabled

      • onConfigFileChange

        protected static void onConfigFileChange​(java.lang.String loggingConfigFileName)
        Reinitialize the logging properties and reread the logging configuration from the given stream, which should be in java.util.Properties format.
        Parameters:
        loggingConfigFileName - the name of logging properties file to read.

      • enableGlobalDebug

        public static void enableGlobalDebug​(boolean enabled)
        Set or reset the global debug flag. The global debug flag enables debug logging across Diagnosables.
        Parameters:
        enabled -

      • isGlobalDebugEnabled

        public static boolean isGlobalDebugEnabled()
        Returns true if global debug logging flag is enabled.

      • enableWriteLogsToDiagnoseFirstFailure

        public static void enableWriteLogsToDiagnoseFirstFailure​(boolean enabled)
        Set or reset the flag that enables writing debug logs to Diagnose First Failure.
        Parameters:
        enabled -

      • isWriteLogsToDiagnoseFirstFailureEnabled

        public static boolean isWriteLogsToDiagnoseFirstFailureEnabled()

      • enableMetrics

        public static void enableMetrics​(boolean isEnabled)

      • isMetricsEnabled

        public static boolean isMetricsEnabled()

      • trace

        public final <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).
        Specified by:
        trace in interface Diagnosable
        Type Parameters:
        T -
        Parameters:
        level - log level
        label - 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:

      • debug

        public final <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 active, 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).
        Specified by:
        debug in interface Diagnosable
        Type Parameters:
        T -
        Parameters:
        level - log level
        label - 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:

      • debug

        public final <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)
        Description copied from interface: Diagnosable
        Debug API with eight args.
        Specified by:
        debug in interface Diagnosable
        See Also:
        Diagnosable.debug(Level, SecurityLabel, String, String, String, String, Throwable, Object...)

      • tracep

        public final <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)
        Description copied from interface: Diagnosable
        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.
        Specified by:
        tracep in interface Diagnosable
        Parameters:
        level - log level
        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

        public final <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)
        Description copied from interface: Diagnosable
        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.
        Specified by:
        debugp in interface Diagnosable
        Parameters:
        level - log level
        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)

      • secure

        public 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.
        Specified by:
        secure in interface Diagnosable
        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

      • suspendLogging

        public 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.
        Specified by:
        suspendLogging in interface Diagnosable

      • resumeLogging

        public 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.
        Specified by:
        resumeLogging in interface Diagnosable

      • isLoggable

        public boolean isLoggable​(java.util.logging.Level level)
        Description copied from interface: Diagnosable
        Check if a message of the given level would actually be logged by this logger.
        Specified by:
        isLoggable in interface Diagnosable

      • onClose

        public void onClose()
        Action to be performed on close of this diagnosable.
        Specified by:
        onClose in interface Diagnosable

      • begin

        public void begin​(Metrics.ConnectionEvent event,
                  int retryCount)
        Begins collecting metrics for the given event.
        Specified by:
        begin in interface Diagnosable
        Parameters:
        event - the event name
        retryCount - the retry count. Non-zero if this event is being retried.

      • end

        public void end​(Metrics.ConnectionEvent event,
                int retryCount)
        Ends collecting metrics for the given event.
        Specified by:
        end in interface Diagnosable
        Parameters:
        event - the event name
        retryCount - the retry count. Non-zero if this event is being retried.