com.unboundid.scim.sdk
Class Debug

java.lang.Object
  com.unboundid.scim.sdk.Debug

All Implemented Interfaces:

Serializable

public final class Debug
extends Object
implements Serializable

This class provides a means of enabling and configuring debugging in the SCIM 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 SCIM SDK debugging subsystem uses the Java logging framework available through the java.util.logging package with a logger name of "com.unboundid.scim.sdk". The getLogger() method may be used to access the logger instance used by the SCIM SDK.

Example

The following example demonstrates the process that may be used to enable debugging within the SCIM SDK and write information about all messages with a WARNING level or higher to a file named "/tmp/test.log":

   Debug.setEnabled(true);
   Logger logger = Debug.getLogger();

   FileHandler fileHandler = new FileHandler("/tmp/test.log");
   fileHandler.setLevel(Level.WARNING);
   logger.addHandler(fileHandler);
 

See Also:

Serialized Form

Field Summary

static 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 String	PROPERTY_DEBUG_ENABLED The name of the system property that will be used to enable debugging in the UnboundID SCIM SDK for Java.
static String	PROPERTY_DEBUG_LEVEL The name of the system property that will be used to set the initial level for the debug logger.
static 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 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.

Method Summary

static void	debug(Level l, DebugType t, String m) Writes a generic debug message, if appropriate.
static void	debug(Level l, DebugType t, String m, Throwable e) Writes a generic debug message, if appropriate.
static void	debugCodingError(Throwable t) Writes debug information about a coding error detected in the use of the SCIM SDK.
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(Level l, Throwable t) Writes debug information about the provided exception, if appropriate.
static void	debugException(Throwable t) Writes debug information about the provided exception, if appropriate.
static EnumSet<DebugType>	getDebugTypes() Retrieves the set of debug types that will be used if debugging is enabled.
static 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(Properties properties) Initializes this debugger with settings from the provided set of properties.
static void	setEnabled(boolean enabled) Specifies whether debugging should be enabled.
static void	setEnabled(boolean enabled, 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.

Methods inherited from class java.lang.Object

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

Field Detail

PROPERTY_DEBUG_ENABLED

public static final String PROPERTY_DEBUG_ENABLED

The name of the system property that will be used to enable debugging in the UnboundID SCIM SDK for Java. The fully-qualified name for this property is "com.unboundid.scim.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

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.scim.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

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.scim.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

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.scim.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

LOGGER_NAME

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:

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(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

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(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,
                              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.

getDebugTypes

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(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(Level l,
                                  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.

debugCodingError

public static void debugCodingError(Throwable t)

Writes debug information about a coding error detected in the use of the SCIM 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(Level l,
                         DebugType t,
                         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(Level l,
                         DebugType t,
                         String m,
                         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.