# OpenORB 1.3.1: Class Trace

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