org.openorb.util
Class Trace

java.lang.Object
  |
  +--org.openorb.util.Trace

public class Trace

extends java.lang.Object

This class provides methods to display trace messages. The trace levels are defined by the Avalon LogKit Priority class. In order to control the verbostity of the DEBUG priority there are three levels available:

 OpenORB Debug Verbostity    Description
 ---------------------------------------------------------------------
 - level 0 / LOW   : low verbosity
 - level 1 / MEDIUM: medium verbosity
 - level 2 / HIGH  : high verbosity
 

Author:

Jerome Daniel, Stephen McConnell, Michael Rumpf, Richard G Clark

Inner Class Summary

static class	Trace.IllegalConditionError A specialization of Error for signalling the occurrence of an illegal condition.
static class	Trace.StackSnapshot This class is intended to expose a stack trace for debug logging.

Field Summary

static int	HIGH Debug verbosity HIGH (Only applies when priority DEBUG).
static int	LOW Debug verbosity LOW (Only applies when priority DEBUG).
static int	MEDIUM Debug verbosity MEDIUM (Only applies when priority DEBUG).
static int	OFF Debug verbosity OFF (Only applies when priority DEBUG).

Constructor Summary

Trace()

Method Summary

static java.lang.String	bufferToString(java.lang.String msg, byte[] buffer) Convert a byte buffer into its hexadecimal string representation.
static java.lang.String	bufferToString(java.lang.String msg, StorageBuffer buf) Convert a byte buffer into its hexadecimal string representation.
static int	getDebugLevel() Get the debug verbosity level.
static int	getDebugLevelFromName(java.lang.String level) Convert the stringified representation into the debug level.
static org.apache.avalon.framework.logger.Logger	getLogger() Returns the default logger.
static org.apache.avalon.framework.logger.Logger	getLogger(java.util.Properties props) Returns the default logger.
static java.lang.String	getNameOfDebugLevel(int level) Get the stringified representation of the debug verbosity level.
static org.apache.avalon.framework.logger.Logger	getNewLogger(org.apache.log.Priority priority) Creates a new instance of the logger.
static org.apache.log.Priority	getPriorityFromName(java.lang.String priority) Convert the stringified representation into the trace priority.
static boolean	isEnabled(int value) Returns true if the trace level is at equal to or greater than the supplied value.
static boolean	isHigh() Returns true is the debugging verbosity level is set below or equal to HIGH.
static boolean	isLow() Returns true if the debugging verbosity level is set below or equal to LOW.
static boolean	isMedium() Returns true if the debugging verbosity level is set below or equal to MEDIUM.
static void	setDebugLevel(int newLevel) Set the debug verbosity level.
static void	setLogger(org.apache.avalon.framework.logger.Logger logger) Sets the default logger.
static java.lang.Error	signalIllegalCondition(org.apache.avalon.framework.logger.Logger optionalLogger, java.lang.String message) This method is invoked to indicate that an illegal condition has occurred, typically an assertion error.

Methods inherited from class java.lang.Object

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

Field Detail

OFF

public static final int OFF

Debug verbosity OFF (Only applies when priority DEBUG).

LOW

public static final int LOW

Debug verbosity LOW (Only applies when priority DEBUG).

MEDIUM

public static final int MEDIUM

Debug verbosity MEDIUM (Only applies when priority DEBUG).

HIGH

public static final int HIGH

Debug verbosity HIGH (Only applies when priority DEBUG).

Constructor Detail

Trace

public Trace()

Method Detail

getLogger

public static org.apache.avalon.framework.logger.Logger getLogger()

Returns the default logger.

Returns:

a logger

getLogger

public static org.apache.avalon.framework.logger.Logger getLogger(java.util.Properties props)

Returns the default logger.

Parameters:

props - Properties that may contain a "openorb.debug.trace=FATAL|ERROR|WARN|INFO|DEBUG or 0|1|2|3|4" property which uses the value to create a priority.

Returns:

A logger instance.

getNewLogger

public static org.apache.avalon.framework.logger.Logger getNewLogger(org.apache.log.Priority priority)

Creates a new instance of the logger. this is necessary in case of a priority change !

Parameters:

priority - the priority of the logger to create

setLogger

public static void setLogger(org.apache.avalon.framework.logger.Logger logger)

Sets the default logger.

Parameters:

logger - A logger instance or null.

getPriorityFromName

public static org.apache.log.Priority getPriorityFromName(java.lang.String priority)

Convert the stringified representation into the trace priority. This method always returns a valid priority. If there is no match found or the parameter is null the lowest priority FATAL_ERROR is assumed.

Parameters:

priority - The priority name.

Returns:

The priority instance corresponding to the name or FATAL_ERROR when the name can't be mapped.

getDebugLevelFromName

public static int getDebugLevelFromName(java.lang.String level)

Convert the stringified representation into the debug level. This method always returns a valid debug level. If there is no match found or the parameter is null the lowest debug level OFF is assumed.

Parameters:

level - The name of the debug level.

Returns:

The corresponding integer value or OFF if the level name is not valid.

setDebugLevel

public static void setDebugLevel(int newLevel)

Set the debug verbosity level. This applies to DEBUG Priority only. This method is called by the OpenORBLoader following ORB parameterization.

Parameters:

newLevel - The new debug verbosity level for this process.

getDebugLevel

public static int getDebugLevel()

Get the debug verbosity level.

Returns:

The debug verbosity level.

getNameOfDebugLevel

public static java.lang.String getNameOfDebugLevel(int level)

Get the stringified representation of the debug verbosity level.

Parameters:

level - The debug verbosity's integer value.

Returns:

The stringified debug verbosity level.

isEnabled

public static boolean isEnabled(int value)

Returns true if the trace level is at equal to or greater than the supplied value.

Parameters:

value - the debug verbosity level to test.

Returns:

boolean TRUE if the current verbosity level is set equal or higher than the supplied level.

isLow

public static boolean isLow()

Returns true if the debugging verbosity level is set below or equal to LOW.

Returns:

boolean True if the verbosity level is at or above LOW.

isMedium

public static boolean isMedium()

Returns true if the debugging verbosity level is set below or equal to MEDIUM.

Returns:

boolean True if the verbosity level is at or above MEDIUM.

isHigh

public static boolean isHigh()

Returns true is the debugging verbosity level is set below or equal to HIGH.

Returns:

boolean True if the verbosity level is at or above HIGH.

bufferToString

public static java.lang.String bufferToString(java.lang.String msg,
                                              byte[] buffer)

Convert a byte buffer into its hexadecimal string representation. This new version has the great advantage that there are not two arrays allocated. The given buffer is not modified at all. It maybe takes some more time to convert, but that is the price for having the hex dump of an arbitrary buffer.

Parameters:

msg - A text describing the buffer to be shown.

buffer - The buffer to show the hex dump of.

Returns:

The hex dump of the buffer.

bufferToString

public static java.lang.String bufferToString(java.lang.String msg,
                                              StorageBuffer buf)

Convert a byte buffer into its hexadecimal string representation.

Parameters:

msg - A text describing the buffer to be shown.

buf - The StorageBuffer to show the hex dump of. ATTENTION: This is an expensive operation, because internally buf.linearize() is called which creates a copy of the buffer. For large buffers this can be a problem concerning memory consumption.

Returns:

The hex dump of the buffer.

signalIllegalCondition

public static java.lang.Error signalIllegalCondition(org.apache.avalon.framework.logger.Logger optionalLogger,
                                                     java.lang.String message)

This method is invoked to indicate that an illegal condition has occurred, typically an assertion error. The method will always throw an IllegalConditionError with the passed message.

The client can optionally pass their preferred logger to be used instead the default. The client also passes a message to log and throw. The method will handle a null message gracefully so that an IllegalConditionError will always be thrown.

Parameters:

optionalLogger - a logger to use instead of the default, permitted to be null

message - the message to log and throw, permitted to be null

Returns:

never returns