Package com.unboundid.util

Class Debug

java.lang.Object
com.unboundid.util.Debug
All Implemented Interfaces:
Serializable
@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class Debug extends Object implements Serializable
This class provides a means of enabling and configuring debugging in the LDAP SDK.

Access to debug information can be enabled through applications that use the SDK by calling the setEnabled(boolean) methods, or it can also be enabled without any code changes through the use of system properties. In particular, the PROPERTY_DEBUG_ENABLED, PROPERTY_DEBUG_LEVEL, and PROPERTY_DEBUG_TYPE properties may be used to control debugging without the need to alter any code within the application that uses the SDK.

The LDAP SDK debugging subsystem uses the Java logging framework available through the java.util.logging package with a logger name of "com.unboundid.ldap.sdk". The getLogger() method may be used to access the logger instance used by the LDAP SDK.

Example

The following example demonstrates the process that may be used to enable debugging within the LDAP SDK and write information about all messages with a WARNING level or higher to a specified file: 
 Debug.setEnabled(true);
 Logger logger = Debug.getLogger();

 FileHandler fileHandler = new FileHandler(logFilePath);
 fileHandler.setLevel(Level.WARNING);
 logger.addHandler(fileHandler);
See Also:

  • Field Details

    • PROPERTY_DEBUG_ENABLED

      @NotNull public static final String PROPERTY_DEBUG_ENABLED
      The name of the system property that will be used to enable debugging in the UnboundID LDAP SDK for Java. The fully-qualified name for this property is "com.unboundid.ldap.sdk.debug.enabled". If it is set, then it should have a value of either "true" or "false".
      See Also:

    • PROPERTY_INCLUDE_STACK_TRACE

      @NotNull public static final String PROPERTY_INCLUDE_STACK_TRACE
      The name of the system property that may be used to indicate whether stack trace information for the thread calling the debug method should be included in debug log messages. The fully-qualified name for this property is "com.unboundid.ldap.sdk.debug.includeStackTrace". If it is set, then it should have a value of either "true" or "false".
      See Also:

    • PROPERTY_DEBUG_LEVEL

      @NotNull public static final String PROPERTY_DEBUG_LEVEL
      The name of the system property that will be used to set the initial level for the debug logger. The fully-qualified name for this property is "com.unboundid.ldap.sdk.debug.level". If it is set, then it should be one of the strings "SEVERE", "WARNING", "INFO", "CONFIG", "FINE", "FINER", or "FINEST".
      See Also:

    • PROPERTY_DEBUG_TYPE

      @NotNull public static final String PROPERTY_DEBUG_TYPE
      The name of the system property that will be used to indicate that debugging should be enabled for specific types of messages. The fully-qualified name for this property is "com.unboundid.ldap.sdk.debug.type". If it is set, then it should be a comma-delimited list of the names of the desired debug types. See the DebugType enum for the available debug types.
      See Also:

    • PROPERTY_INCLUDE_CAUSE_IN_EXCEPTION_MESSAGES

      @NotNull public static final String PROPERTY_INCLUDE_CAUSE_IN_EXCEPTION_MESSAGES
      The name of the system property that will be used to indicate whether the LDAP SDK should default to including information about the exception's cause in an exception message obtained from the StaticUtils.getExceptionMessage(Throwable) method. By default, the cause will not be included in most messages.
      See Also:

    • PROPERTY_INCLUDE_STACK_TRACE_IN_EXCEPTION_MESSAGES

      @NotNull public static final String PROPERTY_INCLUDE_STACK_TRACE_IN_EXCEPTION_MESSAGES
      The name of the system property that will be used to indicate whether the LDAP SDK should default to including a full stack trace (albeit in condensed form) in an exception message obtained from the StaticUtils.getExceptionMessage(Throwable) method. By default, stack traces will not be included in most messages.
      See Also:

    • PROPERTY_USE_MULTI_LINE_DEBUG_MESSAGES

      @NotNull public static final String PROPERTY_USE_MULTI_LINE_DEBUG_MESSAGES
      The name of the system property that will be used ot indicate whether debug messages (which will be formatted as JSON objects) should be generated using a multi-line string representation. By default, debug message will use a single-line string representation.
      See Also:

    • PROPERTY_DEBUG_FILE

      @NotNull public static final String PROPERTY_DEBUG_FILE
      The name of the system property that will be used to indicate that debug log messages should be written to the specified file. The fully-qualified name for this property is "com.unboundid.ldap.sdk.debug.file". If it is set, then its value should be a pattern that describes the path to the log file to create as described in the Javadoc documentation for the java.util.logging.FileHandler class.
      See Also:

    • LOGGER_NAME

      @NotNull public static final String LOGGER_NAME
      The name that will be used for the Java logger that will actually handle the debug messages if debugging is enabled.
      See Also:

  • Method Details

    • initialize

      public static void initialize()
      Initializes this debugger with the default settings. Debugging will be disabled, the set of debug types will include all types, and the debug level will be "ALL".

    • initialize

      public static void initialize(@Nullable Properties properties)
      Initializes this debugger with settings from the provided set of properties. Any debug setting that isn't configured in the provided properties will be initialized with its default value.
      Parameters:
      properties - The set of properties to use to initialize this debugger.

    • getLogger

      @NotNull public static Logger getLogger()
      Retrieves the logger that will be used to write the debug messages.
      Returns:
      The logger that will be used to write the debug messages.

    • debugEnabled

      public static boolean debugEnabled()
      Indicates whether any form of debugging is enabled.
      Returns:
      true if debugging is enabled, or false if not.

    • debugEnabled

      public static boolean debugEnabled(@NotNull DebugType debugType)
      Indicates whether debugging is enabled for messages of the specified debug type.
      Parameters:
      debugType - The debug type for which to make the determination.
      Returns:
      true if debugging is enabled for messages of the specified debug type, or false if not.

    • setEnabled

      public static void setEnabled(boolean enabled)
      Specifies whether debugging should be enabled. If it should be, then it will be enabled for all debug types.
      Parameters:
      enabled - Specifies whether debugging should be enabled.

    • setEnabled

      public static void setEnabled(boolean enabled, @Nullable Set<DebugType> types)
      Specifies whether debugging should be enabled. If it should be, then it will be enabled for all debug types in the provided set.
      Parameters:
      enabled - Specifies whether debugging should be enabled.
      types - The set of debug types that should be enabled. It may be null or empty to indicate that it should be for all debug types.

    • includeStackTrace

      public static boolean includeStackTrace()
      Indicates whether log messages should include a stack trace of the thread that invoked the debug method.
      Returns:
      true if log messages should include a stack trace of the thread that invoked the debug method, or false if not.

    • setIncludeStackTrace

      public static void setIncludeStackTrace(boolean includeStackTrace)
      Specifies whether log messages should include a stack trace of the thread that invoked the debug method.
      Parameters:
      includeStackTrace - Indicates whether log messages should include a stack trace of the thread that invoked the debug method.

    • useMultiLineDebugMessages

      public static boolean useMultiLineDebugMessages()
      Indicates whether debug messages (which will be formatted as JSON objects) should use a multi-line or single-line string representation.
      Returns:
      true if debug messages should be formatted as multi-line strings, or false if debug messages should be formatted as single-line strings.

    • setUseMultiLineDebugMessages

      public static void setUseMultiLineDebugMessages(boolean useMultiLineDebugMessages)
      Specifies whether debug messages (which will be formatted as JSON objects) should use a multi-line or single-line string representation.
      Parameters:
      useMultiLineDebugMessages - Indicates whether debug messages should be formatted as multi-line strings (if true) or single-line strings (if false).

    • getDebugTypes

      @NotNull public static EnumSet<DebugType> getDebugTypes()
      Retrieves the set of debug types that will be used if debugging is enabled.
      Returns:
      The set of debug types that will be used if debugging is enabled.

    • debugException

      public static void debugException(@NotNull Throwable t)
      Writes debug information about the provided exception, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the WARNING level.
      Parameters:
      t - The exception for which debug information should be written.

    • debugException

      public static void debugException(@NotNull Level l, @NotNull Throwable t)
      Writes debug information about the provided exception, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      t - The exception for which debug information should be written.

    • debugConnect

      public static void debugConnect(@NotNull String h, int p)
      Writes debug information to indicate that a connection has been established, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.

    • debugConnect

      public static void debugConnect(@NotNull Level l, @NotNull String h, int p)
      Writes debug information to indicate that a connection has been established, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.

    • debugConnect

      public static void debugConnect(@NotNull String h, int p, @Nullable LDAPConnection c)
      Writes debug information to indicate that a connection has been established, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      c - The connection object for the connection that has been established. It may be null for historic reasons, but should be non-null in new uses.

    • debugConnect

      public static void debugConnect(@NotNull Level l, @NotNull String h, int p, @Nullable LDAPConnection c)
      Writes debug information to indicate that a connection has been established, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      c - The connection object for the connection that has been established. It may be null for historic reasons, but should be non-null in new uses.

    • debugDisconnect

      public static void debugDisconnect(@NotNull String h, int p, @NotNull DisconnectType t, @Nullable String m, @Nullable Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      t - The disconnect type.
      m - The disconnect message, if available.
      e - The disconnect cause, if available.

    • debugDisconnect

      public static void debugDisconnect(@NotNull Level l, @NotNull String h, int p, @NotNull DisconnectType t, @Nullable String m, @Nullable Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      t - The disconnect type.
      m - The disconnect message, if available.
      e - The disconnect cause, if available.

    • debugDisconnect

      public static void debugDisconnect(@NotNull String h, int p, @Nullable LDAPConnection c, @NotNull DisconnectType t, @Nullable String m, @Nullable Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      c - The connection object for the connection that has been closed. It may be null for historic reasons, but should be non-null in new uses.
      t - The disconnect type.
      m - The disconnect message, if available.
      e - The disconnect cause, if available.

    • debugDisconnect

      public static void debugDisconnect(@NotNull Level l, @NotNull String h, int p, @Nullable LDAPConnection c, @NotNull DisconnectType t, @Nullable String m, @Nullable Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      h - The address of the server to which the connection was established.
      p - The port of the server to which the connection was established.
      c - The connection object for the connection that has been closed. It may be null for historic reasons, but should be non-null in new uses.
      t - The disconnect type.
      m - The disconnect message, if available.
      e - The disconnect cause, if available.

    • debugLDAPRequest

      public static void debugLDAPRequest(@NotNull LDAPRequest r)
      Writes debug information about the provided request, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The LDAP request for which debug information should be written.

    • debugLDAPRequest

      public static void debugLDAPRequest(@NotNull Level l, @NotNull LDAPRequest r)
      Writes debug information about the provided request, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The LDAP request for which debug information should be written.

    • debugLDAPRequest

      public static void debugLDAPRequest(@NotNull LDAPRequest r, int i, @Nullable LDAPConnection c)
      Writes debug information about the provided request, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The LDAP request for which debug information should be written.
      i - The message ID for the request that will be sent. It may be negative if no message ID is available.
      c - The connection on which the request will be sent. It may be null for historic reasons, but should be non-null in new uses.

    • debugLDAPRequest

      public static void debugLDAPRequest(@NotNull Level l, @NotNull LDAPRequest r, int i, @Nullable LDAPConnection c)
      Writes debug information about the provided request, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The LDAP request for which debug information should be written.
      i - The message ID for the request that will be sent. It may be negative if no message ID is available.
      c - The connection on which the request will be sent. It may be null for historic reasons, but should be non-null in new uses.

    • debugLDAPRequest

      public static void debugLDAPRequest(@NotNull Level l, @NotNull String s, int i, @Nullable LDAPConnection c)
      Writes debug information about the provided request, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      s - A string representation of the LDAP request for which debug information should be written.
      i - The message ID for the request that will be sent. It may be negative if no message ID is available.
      c - The connection on which the request will be sent. It may be null for historic reasons, but should be non-null in new uses.

    • debugLDAPResult

      public static void debugLDAPResult(@NotNull LDAPResponse r)
      Writes debug information about the provided result, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The result for which debug information should be written.

    • debugLDAPResult

      public static void debugLDAPResult(@NotNull Level l, @NotNull LDAPResponse r)
      Writes debug information about the provided result, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The result for which debug information should be written.

    • debugLDAPResult

      public static void debugLDAPResult(@NotNull LDAPResponse r, @Nullable LDAPConnection c)
      Writes debug information about the provided result, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The result for which debug information should be written.
      c - The connection on which the response was received. It may be null for historic reasons, but should be non-null in new uses.

    • debugLDAPResult

      public static void debugLDAPResult(@NotNull Level l, @NotNull LDAPResponse r, @Nullable LDAPConnection c)
      Writes debug information about the provided result, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The result for which debug information should be written.
      c - The connection on which the response was received. It may be null for historic reasons, but should be non-null in new uses.

    • debugASN1Write

      public static void debugASN1Write(@NotNull ASN1Element e)
      Writes debug information about the provided ASN.1 element to be written, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      e - The ASN.1 element for which debug information should be written.

    • debugASN1Write

      public static void debugASN1Write(@NotNull Level l, @NotNull ASN1Element e)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      e - The ASN.1 element for which debug information should be written.

    • debugASN1Write

      public static void debugASN1Write(@NotNull ASN1Buffer b)
      Writes debug information about the provided ASN.1 element to be written, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      b - The ASN.1 buffer with the information to be written.

    • debugASN1Write

      public static void debugASN1Write(@NotNull Level l, @NotNull ASN1Buffer b)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      b - The ASN1Buffer with the information to be written.

    • debugASN1Read

      public static void debugASN1Read(@NotNull ASN1Element e)
      Writes debug information about the provided ASN.1 element that was read, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      e - The ASN.1 element for which debug information should be written.

    • debugASN1Read

      public static void debugASN1Read(@NotNull Level l, @NotNull ASN1Element e)
      Writes debug information about the provided ASN.1 element that was read, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      e - The ASN.1 element for which debug information should be written.

    • debugASN1Read

      public static void debugASN1Read(@NotNull Level l, @NotNull String dataType, int berType, int length, @Nullable Object value)
      Writes debug information about the provided ASN.1 element that was read, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      dataType - A string representation of the data type for the data that was read.
      berType - The BER type for the element that was read.
      length - The number of bytes in the value of the element that was read.
      value - A representation of the value that was read. The debug message will include the string representation of this value, unless the value is a byte array in which it will be a hex representation of the bytes that it contains. It may be null for an ASN.1 null element.

    • debugConnectionPool

      public static void debugConnectionPool(@NotNull Level l, @NotNull AbstractConnectionPool p, @Nullable LDAPConnection c, @Nullable String m, @Nullable Throwable e)
      Writes debug information about interaction with a connection pool.
      Parameters:
      l - The log level that should be used for the debug information.
      p - The associated connection pool.
      c - The associated LDAP connection, if appropriate.
      m - A message with information about the pool interaction.
      e - An exception to include with the log message, if appropriate.

    • debugLDIFWrite

      public static void debugLDIFWrite(@NotNull LDIFRecord r)
      Writes debug information about the provided LDIF record to be written, if if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The LDIF record for which debug information should be written.

    • debugLDIFWrite

      public static void debugLDIFWrite(@NotNull Level l, @NotNull LDIFRecord r)
      Writes debug information about the provided LDIF record to be written, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The LDIF record for which debug information should be written.

    • debugLDIFRead

      public static void debugLDIFRead(@NotNull LDIFRecord r)
      Writes debug information about the provided record read from LDIF, if appropriate. If it is to be logged, then it will be sent to the underlying logger using the INFO level.
      Parameters:
      r - The LDIF record for which debug information should be written.

    • debugLDIFRead

      public static void debugLDIFRead(@NotNull Level l, @NotNull LDIFRecord r)
      Writes debug information about the provided record read from LDIF, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      r - The LDIF record for which debug information should be written.

    • debugMonitor

      public static void debugMonitor(@Nullable Entry e, @Nullable String m)
      Writes debug information about monitor entry parsing. If it is to be logged, then it will be sent to the underlying logger using the FINE level.
      Parameters:
      e - The entry containing the monitor information being parsed.
      m - The message to be written to the debug logger.

    • debugMonitor

      public static void debugMonitor(@NotNull Level l, @Nullable Entry e, @Nullable String m)
      Writes debug information about monitor entry parsing, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      e - The entry containing the monitor information being parsed.
      m - The message to be written to the debug logger.

    • debugCodingError

      public static void debugCodingError(@NotNull Throwable t)
      Writes debug information about a coding error detected in the use of the LDAP SDK. If it is to be logged, then it will be sent to the underlying logger using the SEVERE level.
      Parameters:
      t - The Throwable object that was created and will be thrown as a result of the coding error.

    • debug

      public static void debug(@NotNull Level l, @NotNull DebugType t, @Nullable String m)
      Writes a generic debug message, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      t - The debug type to use to determine whether to write the message.
      m - The message to be written.

    • debug

      public static void debug(@NotNull Level l, @NotNull DebugType t, @Nullable String m, @Nullable Throwable e)
      Writes a generic debug message, if appropriate.
      Parameters:
      l - The log level that should be used for the debug information.
      t - The debug type to use to determine whether to write the message.
      m - The message to be written.
      e - An exception to include with the log message.

    • debugToFile

      public static void debugToFile(@NotNull String path, @NotNull String message)
      Appends the provided debug message to the specified file. This method should be safe to call concurrently, even across multiple processes.
      Parameters:
      path - The path to the file to which the message should be appended. It must not be null.
      message - The debug message to be appended to the file. It must not be null.

    • debugToFile

      public static void debugToFile(@NotNull File file, @NotNull String message)
      Appends the provided debug message to the specified file. This method should be safe to call concurrently, even across multiple processes.
      Parameters:
      file - The file to which the message should be appended. It must not be null.
      message - The debug message to be appended to the file. It must not be null.

    • debugToFile

      public static void debugToFile(@NotNull File file, boolean includeTimestamp, boolean includeStackTrace, @NotNull String message)
      Appends the provided debug message to the specified file. This method should be safe to call concurrently, even across multiple processes.
      Parameters:
      file - The file to which the message should be appended. It must not be null.
      includeTimestamp - Indicates whether to include a timestamp along with the debug message.
      includeStackTrace - Indicates whether to include a stack trace along with the debug message.
      message - The debug message to be appended to the file. It must not be null.

    • parseDebugLogLevel

      @NotNull public static Level parseDebugLogLevel(@NotNull String levelString) throws IllegalArgumentException
      Attempts to parse the provided string as a debug log level.
      Parameters:
      levelString - The string representation of the level to use. It must not be null or empty.
      Returns:
      The log level that was parsed.
      Throws:
      IllegalArgumentException - If the provided string cannot be parsed as a valid debug log level.