Trace (neohabitat 0.1.0-SNAPSHOT API)

java.lang.Object
- org.elkoserver.util.trace.Trace

```
public class Trace
extends Object
```
This class provides output to the server log on behalf of a particular server subsystem. A number of frequently used trace subsystem objects are available as static variables on this class. Users can also create additional trace objects as needed for their own purposes.
A collection of trace priority thresholds, represented by a group of boolean variables, control which trace messages are actually output. These variables can be tested by a user of the trace code to quickly decide whether to call a trace method (thus helping avoid the costs of procedure call and string manipulation in cases where no output would be generated anyway).

Field Summary

Fields
Modifier and Type	Field and Description
`static Trace`	`comm` Trace object for the 'comm' (communications) subsystem.
`boolean`	`debug` Flag to control tracing of debug messages.
`static int`	`DEBUG` "Debug" level trace threshold
`boolean`	`error` Flag to control tracing of error messages.
`static int`	`ERROR` "Error" level trace threshold
`boolean`	`event` Flag to control tracing of event messages.
`static int`	`EVENT` "Event" level trace threshold
`static int`	`MESSAGE` "Message" level trace threshold.
`static int`	`METRICS` "Metrics" level (not thresholded)
`static Trace`	`none` Trace object for the 'none' subsystem.
`static int`	`NOTICE` "Notice" level (not thresholded)
`static boolean`	`ON` This variable statically controls whether tracing is enabled at all.
`static Trace`	`runq` Trace object for the 'runq' (run queue) subsystem.
`static Trace`	`startup` Trace object for the 'startup' subsystem.
`static Trace`	`timers` Trace object for the 'timers' subsystem.
`static Trace`	`trace` Trace object for the 'trace' subsystem itself.
`boolean`	`usage` Flag to control tracing of usage messages.
`static int`	`USAGE` "Usage" level trace threshold
`boolean`	`verbose` Flag to control tracing of verbose messages.
`static int`	`VERBOSE` "Verbose" level trace threshold
`boolean`	`warning` Flag to control tracing of warning messages.
`static int`	`WARNING` "Warning" level trace threshold
`boolean`	`world` Flag to control tracing of world messages.
`static int`	`WORLD` "World" level trace threshold

Method Summary

Methods
Modifier and Type	Method and Description
`static String`	`byteArrayToASCII(byte[] buf, int offset, int length)` Convert an array of bytes into a string suitable for output to a log.
`void`	`debugi(String message)` Output an informational log message at `DEBUG` level.
`void`	`debugm(String message)` Output a log message at `DEBUG` level.
`void`	`debugm(String message, Object obj)` Output a log message at `DEBUG` level, with attached object.
`void`	`debugReportException(Throwable th, String message)` Log an exception event at `DEBUG` level.
`void`	`errori(String message)` Output an informational log message at `ERROR` level.
`void`	`errorm(String message)` Output a log message at `ERROR` level.
`void`	`errorm(String message, Object obj)` Output a log message at `ERROR` level, with attached object.
`void`	`errorReportException(Throwable th, String message)` Log an exception event at `ERROR` level.
`void`	`eventi(String message)` Output an informational log message at `EVENT` level.
`void`	`eventm(String message)` Output a log message at `EVENT` level.
`void`	`eventm(String message, Object obj)` Output a log message at `EVENT` level, with attached object.
`void`	`eventReportException(Throwable th, String message)` Log an exception event at `EVENT` level.
`void`	`fatalError(String message)` Exit reporting a fatal error.
`void`	`fatalError(String message, Object obj)` Exit reporting a fatal error, with attached object (usually but not necessarily a `Throwable` of some kind).
`void`	`metrics(String type, int id)` Output an unvalued metrics message.
`void`	`metrics(String type, int id, boolean value)` Output a boolean-valued metrics message.
`void`	`metrics(String type, int id, double value)` Output a floating point-valued metrics message.
`void`	`metrics(String type, int id, int value)` Output an integer-valued metrics message.
`void`	`metrics(String type, int id, JSONLiteral value)` Output a JSON object-valued metrics message.
`void`	`metrics(String type, int id, JSONObject value)` Output a JSON object-valued metrics message.
`void`	`metrics(String type, int id, long value)` Output a long-valued metrics message.
`void`	`metrics(String type, int id, String value)` Output a string-valued metrics message.
`void`	`msgi(Object conn, boolean inbound, Object msg)` Output a log message describing a comm message.
`void`	`noticei(String message)` Output an informational log message at `NOTICE` level (which is unblockable).
`void`	`setThreshold(int threshold)` Set the logging threshold.
`void`	`shred(Throwable ex, String reason)` Record a `Throwable` along with a trace message.
`Trace`	`subTrace(String subSubsystem)` Obtain a Trace object based on another Trace object.
`static Trace`	`trace(String subsystem)` Obtain the Trace object for a given subsystem.
`void`	`usagei(String message)` Output an informational log message at `USAGE` level.
`void`	`usagem(String message)` Output a log message at `USAGE` level.
`void`	`usagem(String message, Object obj)` Output a log message at `USAGE` level, with attached object.
`void`	`usageReportException(Throwable th, String message)` Log an exception event at `USAGE` level.
`void`	`verbosei(String message)` Output an informational log message at `VERBOSE` level.
`void`	`verbosem(String message)` Output a log message at `VERBOSE` level.
`void`	`verbosem(String message, Object obj)` Output a log message at `VERBOSE` level, with attached object.
`void`	`verboseReportException(Throwable th, String message)` Log an exception event at `VERBOSE` level.
`void`	`warningi(String message)` Output an informational log message at `WARNING` level.
`void`	`warningm(String message)` Output a log message at `WARNING` level.
`void`	`warningm(String message, Object obj)` Output a log message at `WARNING` level, with attached object.
`void`	`warningReportException(Throwable th, String message)` Log an exception event at `WARNING` level.
`void`	`worldi(String message)` Output an informational log message at `WORLD` level.
`void`	`worldm(String message)` Output a log message at `WORLD` level.
`void`	`worldm(String message, Object obj)` Output a log message at `WORLD` level, with attached object.
`void`	`worldReportException(Throwable th, String message)` Log an exception event at `WORLD` level.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NOTICE
```
public static final int NOTICE
```
    "Notice" level (not thresholded)
    
    See Also:
    Constant Field Values
  - METRICS
```
public static final int METRICS
```
    "Metrics" level (not thresholded)
    
    See Also:
    Constant Field Values
  - ERROR
```
public static final int ERROR
```
    "Error" level trace threshold
    
    See Also:
    Constant Field Values
  - WARNING
```
public static final int WARNING
```
    "Warning" level trace threshold
    
    See Also:
    Constant Field Values
  - WORLD
```
public static final int WORLD
```
    "World" level trace threshold
    
    See Also:
    Constant Field Values
  - USAGE
```
public static final int USAGE
```
    "Usage" level trace threshold
    
    See Also:
    Constant Field Values
  - EVENT
```
public static final int EVENT
```
    "Event" level trace threshold
    
    See Also:
    Constant Field Values
  - MESSAGE
```
public static final int MESSAGE
```
    "Message" level trace threshold. Essentially the save as "Event", but flagged differently in log entries.
    
    See Also:
    Constant Field Values
  - DEBUG
```
public static final int DEBUG
```
    "Debug" level trace threshold
    
    See Also:
    Constant Field Values
  - VERBOSE
```
public static final int VERBOSE
```
    "Verbose" level trace threshold
    
    See Also:
    Constant Field Values
  - ON
```
public static final boolean ON
```
    This variable statically controls whether tracing is enabled at all. By compiling against a version of this class that has this variable set to false and testing this prior to invoking trace operations, one can arrange to have the trace calls removed by the compiler.
    
    See Also:
    Constant Field Values
  - error
```
public boolean error
```
    Flag to control tracing of error messages. Error messages report on some internal error. They don't necessarily lead to the system stopping, but they might. Error messages are always logged.
  - warning
```
public boolean warning
```
    Flag to control tracing of warning messages. Warning messages are not as serious as errors, but they're signs of something odd.
  - world
```
public boolean world
```
    Flag to control tracing of world messages. World messages track the state of the world as a whole. They are the sort of things server operators ask for specifically, such as "can you tell me when someone connects." They should appear only occasionally.
  - usage
```
public boolean usage
```
    Flag to control tracing of usage messages. Usage messages are used to answer the question "who did what up to the point the bug appeared?" They are also used to collect higher-level usability information.
  - event
```
public boolean event
```
    Flag to control tracing of event messages. Event messages describe the major actions the system takes in response to user actions. The distinction between this category and debug is fuzzy, especially since debug is already used for many messages of this type. However, it can be used to log specific user actions for usability testing, and to log information for testers.
  - debug
```
public boolean debug
```
    Flag to control tracing of debug messages. Debug messages provide more detail for people who want to delve into what's going on, probably to figure out a bug.
  - verbose
```
public boolean verbose
```
    Flag to control tracing of verbose messages. Verbose messages provide even more detail than debug. They're probably mainly used when first getting code to work.
  - comm
```
public static Trace comm
```
    Trace object for the 'comm' (communications) subsystem. In particular, message traffic is logged when the trace level of this object is set to EVENT or above.
  - none
```
public static Trace none
```
    Trace object for the 'none' subsystem. This is a trace object that will never log under any circumstances. It can be passed in method parameters that require a trace object but you don't want any tracing to result.
  - runq
```
public static Trace runq
```
    Trace object for the 'runq' (run queue) subsystem. This is used for log messages from the event queue manager.
  - startup
```
public static Trace startup
```
    Trace object for the 'startup' subsystem. This is used for log messages that need to be generated as a part of server boot.
  - timers
```
public static Trace timers
```
    Trace object for the 'timers' subsystem. This is used for log messages from the clock/timer API.
  - trace
```
public static Trace trace
```
    Trace object for the 'trace' subsystem itself.
- Method Detail
  - trace
```
public static Trace trace(String subsystem)
```
    Obtain the Trace object for a given subsystem. The Trace object will be manufactured if it does not already exist.
    
    Parameters:
    subsystem - The name of the subsystem of interest.
    
    Returns:
    a Trace object for the given subsystem.
  - subTrace
```
public Trace subTrace(String subSubsystem)
```
    Obtain a Trace object based on another Trace object. The new trace object will acquire its initial threshold settings based on its parent.
    
    Parameters:
    subSubsystem - A name tag that will be appended to this trace object's subsystem name.
    
    Returns:
    a a Trace object derived from this trace object.
  - setThreshold
```
public void setThreshold(int threshold)
```
    Set the logging threshold.
    
    Parameters:
    threshold - The new threshold value.
  - byteArrayToASCII
```
public static String byteArrayToASCII(byte[] buf,
                      int offset,
                      int length)
```
    Convert an array of bytes into a string suitable for output to a log. Such data is usually UTF-8, or ASCII (which is a subset of UTF-8), but sometimes it is just random binary data. If we simply use Java's built-in charset conversion, it can produce illegible binary crud in the server log. Instead we convert it ourselves, rendering printable ASCII bytes as the chars they represent and non-printable bytes as hexadecimal character literal escape sequences. This will have the downside of sometimes rendering valid Unicode chars funny, but nearly everything we actually care about seeing when debugging is printable ASCII.
    
    Parameters:
    buf - Byte array containing data to be converted.
    offset - Index of start position to convert.
    length - Number of bytes to convert.
    
    Returns:
    a String rendering the indicated bytes in a legible form suitable for loggging.
  - fatalError
```
public void fatalError(String message)
```
    Exit reporting a fatal error.
    
    Parameters:
    message - The error message to die with.
  - fatalError
```
public void fatalError(String message,
              Object obj)
```
    Exit reporting a fatal error, with attached object (usually but not necessarily a Throwable of some kind).
    
    Parameters:
    message - The error message to die with.
    obj - Object to report with message.
  - shred
```
public void shred(Throwable ex,
         String reason)
```
    Record a Throwable along with a trace message.
    To ensure that exceptional conditions are only being ignored for good reason, we adopt the discipline that a caught exception should:
    1) be rethrown
    2) cause another exception to be thrown instead
    3) be ignored, in a traceable way, for some stated reason
    Only by making #3 explicit can we distinguish it from accidentally ignoring the exception. An exception should, therefore, only be ignored by asking a Trace object to shred it. This request carries a string that justifies allowing the program to continue normally following this event. As shredded exceptions may be symptoms of bugs, this will enable them to be traced.
    The reason for the shredding is logged at verbose level.
    
    Parameters:
    ex - The exception to shred.
    reason - A string justifying this.
  - metrics
```
public void metrics(String type,
           int id,
           String value)
```
    Output a string-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id,
           int value)
```
    Output an integer-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id,
           long value)
```
    Output a long-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id,
           double value)
```
    Output a floating point-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id)
```
    Output an unvalued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
  - metrics
```
public void metrics(String type,
           int id,
           boolean value)
```
    Output a boolean-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id,
           JSONLiteral value)
```
    Output a JSON object-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - metrics
```
public void metrics(String type,
           int id,
           JSONObject value)
```
    Output a JSON object-valued metrics message.
    
    Parameters:
    type - Type tag
    id - Session id number to associate with the message.
    value - The value to record.
  - noticei
```
public void noticei(String message)
```
    Output an informational log message at NOTICE level (which is unblockable).
    
    Parameters:
    message - The message string
  - msgi
```
public void msgi(Object conn,
        boolean inbound,
        Object msg)
```
    Output a log message describing a comm message.
    
    Parameters:
    conn - The connection over which the message was sent or received.
    inbound - True if the message was received, false if it was sent
    msg - The message itself that is to be logged
  - debugi
```
public void debugi(String message)
```
    Output an informational log message at DEBUG level.
    
    Parameters:
    message - The message to write to the log.
  - debugm
```
public void debugm(String message)
```
    Output a log message at DEBUG level.
    
    Parameters:
    message - The message to write to the log.
  - debugm
```
public void debugm(String message,
          Object obj)
```
    Output a log message at DEBUG level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - debugReportException
```
public void debugReportException(Throwable th,
                        String message)
```
    Log an exception event at DEBUG level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - errori
```
public void errori(String message)
```
    Output an informational log message at ERROR level.
    
    Parameters:
    message - The message to write to the log.
  - errorm
```
public void errorm(String message)
```
    Output a log message at ERROR level.
    
    Parameters:
    message - The message to write to the log.
  - errorm
```
public void errorm(String message,
          Object obj)
```
    Output a log message at ERROR level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - errorReportException
```
public void errorReportException(Throwable th,
                        String message)
```
    Log an exception event at ERROR level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - eventi
```
public void eventi(String message)
```
    Output an informational log message at EVENT level.
    
    Parameters:
    message - The message to write to the log.
  - eventm
```
public void eventm(String message)
```
    Output a log message at EVENT level.
    
    Parameters:
    message - The message to write to the log.
  - eventm
```
public void eventm(String message,
          Object obj)
```
    Output a log message at EVENT level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - eventReportException
```
public void eventReportException(Throwable th,
                        String message)
```
    Log an exception event at EVENT level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - usagei
```
public void usagei(String message)
```
    Output an informational log message at USAGE level.
    
    Parameters:
    message - The message to write to the log.
  - usagem
```
public void usagem(String message)
```
    Output a log message at USAGE level.
    
    Parameters:
    message - The message to write to the log.
  - usagem
```
public void usagem(String message,
          Object obj)
```
    Output a log message at USAGE level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - usageReportException
```
public void usageReportException(Throwable th,
                        String message)
```
    Log an exception event at USAGE level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - verbosei
```
public void verbosei(String message)
```
    Output an informational log message at VERBOSE level.
    
    Parameters:
    message - The message to write to the log.
  - verbosem
```
public void verbosem(String message)
```
    Output a log message at VERBOSE level.
    
    Parameters:
    message - The message to write to the log.
  - verbosem
```
public void verbosem(String message,
            Object obj)
```
    Output a log message at VERBOSE level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - verboseReportException
```
public void verboseReportException(Throwable th,
                          String message)
```
    Log an exception event at VERBOSE level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - warningi
```
public void warningi(String message)
```
    Output an informational log message at WARNING level.
    
    Parameters:
    message - The message to write to the log.
  - warningm
```
public void warningm(String message)
```
    Output a log message at WARNING level.
    
    Parameters:
    message - The message to write to the log.
  - warningm
```
public void warningm(String message,
            Object obj)
```
    Output a log message at WARNING level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - warningReportException
```
public void warningReportException(Throwable th,
                          String message)
```
    Log an exception event at WARNING level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.
  - worldi
```
public void worldi(String message)
```
    Output an informational log message at WORLD level.
    
    Parameters:
    message - The message to write to the log.
  - worldm
```
public void worldm(String message)
```
    Output a log message at WORLD level.
    
    Parameters:
    message - The message to write to the log.
  - worldm
```
public void worldm(String message,
          Object obj)
```
    Output a log message at WORLD level, with attached object.
    
    Parameters:
    message - The message to write to the log.
    obj - Object to report with message.
  - worldReportException
```
public void worldReportException(Throwable th,
                        String message)
```
    Log an exception event at WORLD level.
    
    Parameters:
    th - The exception to log
    message - An explanatory message to accompany the log entry.

Class Trace

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NOTICE

METRICS

ERROR

WARNING

WORLD

USAGE

EVENT

MESSAGE

DEBUG

VERBOSE

ON

error

warning

world

usage

event

debug

verbose

comm

none

runq

startup

timers

trace

Method Detail

trace

subTrace

setThreshold

byteArrayToASCII

fatalError

fatalError

shred

metrics

metrics

metrics

metrics

metrics

metrics

metrics

metrics

noticei

msgi

debugi

debugm

debugm

debugReportException

errori

errorm

errorm

errorReportException

eventi

eventm

eventm

eventReportException

usagei

usagem

usagem

usageReportException

verbosei

verbosem

verbosem

verboseReportException

warningi

warningm

warningm

warningReportException

worldi

worldm

worldm

worldReportException