Class Debug

  • All Implemented Interfaces:
    java.io.Serializable

    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class Debug
    extends java.lang.Object
    implements java.io.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:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String LOGGER_NAME
      The name that will be used for the Java logger that will actually handle the debug messages if debugging is enabled.
      static java.lang.String PROPERTY_DEBUG_ENABLED
      The name of the system property that will be used to enable debugging in the UnboundID LDAP SDK for Java.
      static java.lang.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.
      static java.lang.String PROPERTY_DEBUG_LEVEL
      The name of the system property that will be used to set the initial level for the debug logger.
      static java.lang.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.
      static java.lang.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.
      static java.lang.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.
      static java.lang.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.
      static java.lang.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.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static void debug​(java.util.logging.Level l, DebugType t, java.lang.String m)
      Writes a generic debug message, if appropriate.
      static void debug​(java.util.logging.Level l, DebugType t, java.lang.String m, java.lang.Throwable e)
      Writes a generic debug message, if appropriate.
      static void debugASN1Read​(ASN1Element e)
      Writes debug information about the provided ASN.1 element that was read, if appropriate.
      static void debugASN1Read​(java.util.logging.Level l, ASN1Element e)
      Writes debug information about the provided ASN.1 element that was read, if appropriate.
      static void debugASN1Read​(java.util.logging.Level l, java.lang.String dataType, int berType, int length, java.lang.Object value)
      Writes debug information about the provided ASN.1 element that was read, if appropriate.
      static void debugASN1Write​(ASN1Buffer b)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      static void debugASN1Write​(ASN1Element e)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      static void debugASN1Write​(java.util.logging.Level l, ASN1Buffer b)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      static void debugASN1Write​(java.util.logging.Level l, ASN1Element e)
      Writes debug information about the provided ASN.1 element to be written, if appropriate.
      static void debugCodingError​(java.lang.Throwable t)
      Writes debug information about a coding error detected in the use of the LDAP SDK.
      static void debugConnect​(java.lang.String h, int p)
      Writes debug information to indicate that a connection has been established, if appropriate.
      static void debugConnect​(java.lang.String h, int p, LDAPConnection c)
      Writes debug information to indicate that a connection has been established, if appropriate.
      static void debugConnect​(java.util.logging.Level l, java.lang.String h, int p)
      Writes debug information to indicate that a connection has been established, if appropriate.
      static void debugConnect​(java.util.logging.Level l, java.lang.String h, int p, LDAPConnection c)
      Writes debug information to indicate that a connection has been established, if appropriate.
      static void debugConnectionPool​(java.util.logging.Level l, AbstractConnectionPool p, LDAPConnection c, java.lang.String m, java.lang.Throwable e)
      Writes debug information about interaction with a connection pool.
      static void debugDisconnect​(java.lang.String h, int p, DisconnectType t, java.lang.String m, java.lang.Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      static void debugDisconnect​(java.lang.String h, int p, LDAPConnection c, DisconnectType t, java.lang.String m, java.lang.Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      static void debugDisconnect​(java.util.logging.Level l, java.lang.String h, int p, DisconnectType t, java.lang.String m, java.lang.Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      static void debugDisconnect​(java.util.logging.Level l, java.lang.String h, int p, LDAPConnection c, DisconnectType t, java.lang.String m, java.lang.Throwable e)
      Writes debug information to indicate that a connection has been terminated, if appropriate.
      static boolean debugEnabled()
      Indicates whether any form of debugging is enabled.
      static boolean debugEnabled​(DebugType debugType)
      Indicates whether debugging is enabled for messages of the specified debug type.
      static void debugException​(java.lang.Throwable t)
      Writes debug information about the provided exception, if appropriate.
      static void debugException​(java.util.logging.Level l, java.lang.Throwable t)
      Writes debug information about the provided exception, if appropriate.
      static void debugLDAPRequest​(LDAPRequest r)
      Writes debug information about the provided request, if appropriate.
      static void debugLDAPRequest​(LDAPRequest r, int i, LDAPConnection c)
      Writes debug information about the provided request, if appropriate.
      static void debugLDAPRequest​(java.util.logging.Level l, LDAPRequest r)
      Writes debug information about the provided request, if appropriate.
      static void debugLDAPRequest​(java.util.logging.Level l, LDAPRequest r, int i, LDAPConnection c)
      Writes debug information about the provided request, if appropriate.
      static void debugLDAPRequest​(java.util.logging.Level l, java.lang.String s, int i, LDAPConnection c)
      Writes debug information about the provided request, if appropriate.
      static void debugLDAPResult​(LDAPResponse r)
      Writes debug information about the provided result, if appropriate.
      static void debugLDAPResult​(LDAPResponse r, LDAPConnection c)
      Writes debug information about the provided result, if appropriate.
      static void debugLDAPResult​(java.util.logging.Level l, LDAPResponse r)
      Writes debug information about the provided result, if appropriate.
      static void debugLDAPResult​(java.util.logging.Level l, LDAPResponse r, LDAPConnection c)
      Writes debug information about the provided result, if appropriate.
      static void debugLDIFRead​(LDIFRecord r)
      Writes debug information about the provided record read from LDIF, if appropriate.
      static void debugLDIFRead​(java.util.logging.Level l, LDIFRecord r)
      Writes debug information about the provided record read from LDIF, if appropriate.
      static void debugLDIFWrite​(LDIFRecord r)
      Writes debug information about the provided LDIF record to be written, if if appropriate.
      static void debugLDIFWrite​(java.util.logging.Level l, LDIFRecord r)
      Writes debug information about the provided LDIF record to be written, if appropriate.
      static void debugMonitor​(Entry e, java.lang.String m)
      Writes debug information about monitor entry parsing.
      static void debugMonitor​(java.util.logging.Level l, Entry e, java.lang.String m)
      Writes debug information about monitor entry parsing, if appropriate.
      static void debugToFile​(java.io.File file, boolean includeTimestamp, boolean includeStackTrace, java.lang.String message)
      Appends the provided debug message to the specified file.
      static void debugToFile​(java.io.File file, java.lang.String message)
      Appends the provided debug message to the specified file.
      static void debugToFile​(java.lang.String path, java.lang.String message)
      Appends the provided debug message to the specified file.
      static java.util.EnumSet<DebugType> getDebugTypes()
      Retrieves the set of debug types that will be used if debugging is enabled.
      static java.util.logging.Logger getLogger()
      Retrieves the logger that will be used to write the debug messages.
      static boolean includeStackTrace()
      Indicates whether log messages should include a stack trace of the thread that invoked the debug method.
      static void initialize()
      Initializes this debugger with the default settings.
      static void initialize​(java.util.Properties properties)
      Initializes this debugger with settings from the provided set of properties.
      static java.util.logging.Level parseDebugLogLevel​(java.lang.String levelString)
      Attempts to parse the provided string as a debug log level.
      static void setEnabled​(boolean enabled)
      Specifies whether debugging should be enabled.
      static void setEnabled​(boolean enabled, java.util.Set<DebugType> types)
      Specifies whether debugging should be enabled.
      static void setIncludeStackTrace​(boolean includeStackTrace)
      Specifies whether log messages should include a stack trace of the thread that invoked the debug method.
      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.
      static boolean useMultiLineDebugMessages()
      Indicates whether debug messages (which will be formatted as JSON objects) should use a multi-line or single-line string representation.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • PROPERTY_DEBUG_ENABLED

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • PROPERTY_INCLUDE_STACK_TRACE

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • PROPERTY_DEBUG_LEVEL

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • PROPERTY_DEBUG_TYPE

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • PROPERTY_USE_MULTI_LINE_DEBUG_MESSAGES

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • PROPERTY_DEBUG_FILE

        @NotNull
        public static final java.lang.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:
        Constant Field Values
      • LOGGER_NAME

        @NotNull
        public static final java.lang.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:
        Constant Field Values
    • Method Detail

      • 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
                                      java.util.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 java.util.logging.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
                                      java.util.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 java.util.EnumSet<DebugTypegetDebugTypes()
        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
                                          java.lang.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
                                          java.util.logging.Level l,
                                          @NotNull
                                          java.lang.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
                                        java.lang.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
                                        java.util.logging.Level l,
                                        @NotNull
                                        java.lang.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
                                        java.lang.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
                                        java.util.logging.Level l,
                                        @NotNull
                                        java.lang.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
                                           java.lang.String h,
                                           int p,
                                           @NotNull
                                           DisconnectType t,
                                           @Nullable
                                           java.lang.String m,
                                           @Nullable
                                           java.lang.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
                                           java.util.logging.Level l,
                                           @NotNull
                                           java.lang.String h,
                                           int p,
                                           @NotNull
                                           DisconnectType t,
                                           @Nullable
                                           java.lang.String m,
                                           @Nullable
                                           java.lang.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
                                           java.lang.String h,
                                           int p,
                                           @Nullable
                                           LDAPConnection c,
                                           @NotNull
                                           DisconnectType t,
                                           @Nullable
                                           java.lang.String m,
                                           @Nullable
                                           java.lang.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
                                           java.util.logging.Level l,
                                           @NotNull
                                           java.lang.String h,
                                           int p,
                                           @Nullable
                                           LDAPConnection c,
                                           @NotNull
                                           DisconnectType t,
                                           @Nullable
                                           java.lang.String m,
                                           @Nullable
                                           java.lang.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
                                            java.util.logging.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
                                            java.util.logging.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
                                            java.util.logging.Level l,
                                            @NotNull
                                            java.lang.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
                                           java.util.logging.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
                                           java.util.logging.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
                                          java.util.logging.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
                                          java.util.logging.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
                                         java.util.logging.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
                                         java.util.logging.Level l,
                                         @NotNull
                                         java.lang.String dataType,
                                         int berType,
                                         int length,
                                         @Nullable
                                         java.lang.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
                                               java.util.logging.Level l,
                                               @NotNull
                                               AbstractConnectionPool p,
                                               @Nullable
                                               LDAPConnection c,
                                               @Nullable
                                               java.lang.String m,
                                               @Nullable
                                               java.lang.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
                                          java.util.logging.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
                                         java.util.logging.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
                                        java.lang.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
                                        java.util.logging.Level l,
                                        @Nullable
                                        Entry e,
                                        @Nullable
                                        java.lang.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
                                            java.lang.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
                                 java.util.logging.Level l,
                                 @NotNull
                                 DebugType t,
                                 @Nullable
                                 java.lang.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
                                 java.util.logging.Level l,
                                 @NotNull
                                 DebugType t,
                                 @Nullable
                                 java.lang.String m,
                                 @Nullable
                                 java.lang.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
                                       java.lang.String path,
                                       @NotNull
                                       java.lang.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
                                       java.io.File file,
                                       @NotNull
                                       java.lang.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
                                       java.io.File file,
                                       boolean includeTimestamp,
                                       boolean includeStackTrace,
                                       @NotNull
                                       java.lang.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 java.util.logging.Level parseDebugLogLevel​(@NotNull
                                                                 java.lang.String levelString)
                                                          throws java.lang.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:
        java.lang.IllegalArgumentException - If the provided string cannot be parsed as a valid debug log level.