edu.stanford.nlp.util.logging
Class Redwood

java.lang.Object
  extended by edu.stanford.nlp.util.logging.Redwood

public class Redwood
extends Object

A hierarchical channel based logger. Log messages are arranged hierarchically by depth (e.g. main->tagging->sentence 2) using the startTrack() and endTrack() methods. Furthermore, messages can be flagged with a number of channels, which allow filtering by channel. Log levels are implemented as channels (ERROR, WARNING, etc). Details on the handlers used are documented in their respective classes, which all implement LogRecordHandler. New handlers should implement this class. Details on configuring Redwood can be found in the RedwoodConfiguration class. New configuration methods should be implemented in this class, following the standard builder paradigm. There is a tutorial on Redwood on the NLP website.

Author:
Gabor Angeli (angeli at cs.stanford), David McClosky

Nested Class Summary
static class Redwood.ConsoleHandler
          Default output handler which actually prints things to the real System.out
static class Redwood.FileHandler
          Handler which prints to a specified file
protected static class Redwood.Flag
          Standard channels; enum for the sake of efficiency
static class Redwood.Record
          A log record, which encapsulates the information needed to eventually display the enclosed message.
protected static class Redwood.RecordHandlerTree
          A tree structure of record handlers
static class Redwood.RedwoodChannels
          Represents a collection of channels.
static class Redwood.Util
          A utility class for Redwood intended for static import (import static edu.stanford.nlp.util.logging.Redwood.Util.*;), providing a wrapper for Redwood functions and adding utility shortcuts
 
Field Summary
static Redwood.Flag DBG
           
static Redwood.Flag ERR
           
static Redwood.Flag FORCE
           
static Redwood.Flag STDERR
           
static Redwood.Flag STDOUT
           
static Redwood.Flag WARN
           
 
Constructor Summary
Redwood()
           
 
Method Summary
protected static void addLoggingClass(String className)
          Add a class to the list of known logging classes.
protected static void appendHandler(Class<? extends LogRecordHandler> parent, LogRecordHandler child)
          Append a Handler to every parent of the given class
protected static void appendHandler(LogRecordHandler child)
          Append a Handler to the end of the root of the Handler tree.
protected static void appendHandler(LogRecordHandler parent, LogRecordHandler child)
          Append a Handler to a portion of the handler tree
protected static void captureSystemStreams(boolean captureOut, boolean captureErr)
          Captures System.out and System.err and redirects them to Redwood logging.
static Redwood.RedwoodChannels channels(Object... channelNames)
          Create an object representing a group of channels.
protected static void clearHandlers()
          Remove all log handlers from Redwood, presumably in order to construct a custom pipeline afterwards
protected static void clearLoggingClasses()
          Removes all classes from the list of known logging classes
static void endThreads(String check)
          Signal that all threads have run to completion, and the multithreaded environment is over.
static void endTrack()
          A utility method for closing calls to the anonymous startTrack() call.
static void endTrack(String title)
          End a "track;" that is, return to logging at one level shallower.
protected static List<StackTraceElement> filterStackTrace(StackTraceElement[] stack)
          Removes logging classes from a stack trace.
static void finishThread()
          Signal that this thread will not log any more messages in the multithreaded environment
static void forceTrack()
          Helper method to start an anonymous track on the FORCE channel.
static void forceTrack(Object arg)
          Helper method to start a track on the FORCE channel.
protected static void formatTimeDifference(long diff, StringBuilder b)
          Utility method for formatting a time difference (maybe this should go to a util class?)
static void hideAllChannels()
          Hide all channels.
static void hideChannels(Object... channels)
          Hide multiple channels.
static void hideOnlyChannels(Object... channels)
          Hide multiple channels.
static void log(Object... args)
          Log a message.
static void logf(String format, Object... args)
           
static void main(String[] args)
          Various informal tests of Redwood functionality
protected static
<E extends LogRecordHandler>
boolean
removeHandler(Class<E> toRemove)
          Remove a handler from the list
protected static void restoreSystemStreams()
          Restores System.out and System.err to their original values
static void showAllChannels()
          Show all channels.
static void showChannels(Object... channels)
          Show multiple channels.
static void showOnlyChannels(Object... channels)
          Show only the given channel.
protected static void spliceHandler(Class<? extends LogRecordHandler> parent, LogRecordHandler toAdd, Class<? extends LogRecordHandler> grandchild)
           
protected static void spliceHandler(LogRecordHandler parent, LogRecordHandler toAdd, Class<? extends LogRecordHandler> grandchild)
           
protected static void spliceHandler(LogRecordHandler parent, LogRecordHandler toAdd, LogRecordHandler grandchild)
           
static void startThreads(String title)
          Start a multithreaded logging environment.
static void startTrack(Object... args)
          Begin a "track;" that is, begin logging at one level deeper.
static void stop()
          Stop Redwood, closing all tracks and prohibiting future log messages.
protected static boolean supportsAnsi()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ERR

public static final Redwood.Flag ERR

WARN

public static final Redwood.Flag WARN

DBG

public static final Redwood.Flag DBG

FORCE

public static final Redwood.Flag FORCE

STDOUT

public static final Redwood.Flag STDOUT

STDERR

public static final Redwood.Flag STDERR
Constructor Detail

Redwood

public Redwood()
Method Detail

removeHandler

protected static <E extends LogRecordHandler> boolean removeHandler(Class<E> toRemove)
Remove a handler from the list

Parameters:
toRemove - The handler to remove. Any handler object that matches this class will be removed.
Returns:
true if this handler was in the list.

spliceHandler

protected static void spliceHandler(LogRecordHandler parent,
                                    LogRecordHandler toAdd,
                                    LogRecordHandler grandchild)

spliceHandler

protected static void spliceHandler(LogRecordHandler parent,
                                    LogRecordHandler toAdd,
                                    Class<? extends LogRecordHandler> grandchild)

spliceHandler

protected static void spliceHandler(Class<? extends LogRecordHandler> parent,
                                    LogRecordHandler toAdd,
                                    Class<? extends LogRecordHandler> grandchild)

appendHandler

protected static void appendHandler(LogRecordHandler parent,
                                    LogRecordHandler child)
Append a Handler to a portion of the handler tree

Parameters:
parent - The parent to add the child to
child - The Handler to add.

appendHandler

protected static void appendHandler(Class<? extends LogRecordHandler> parent,
                                    LogRecordHandler child)
Append a Handler to every parent of the given class

Parameters:
parent - The class of the parents to add the child to
child - The Handler to add.

appendHandler

protected static void appendHandler(LogRecordHandler child)
Append a Handler to the end of the root of the Handler tree.

Parameters:
child - The Handler to add.

clearHandlers

protected static void clearHandlers()
Remove all log handlers from Redwood, presumably in order to construct a custom pipeline afterwards


captureSystemStreams

protected static void captureSystemStreams(boolean captureOut,
                                           boolean captureErr)
Captures System.out and System.err and redirects them to Redwood logging.

Parameters:
captureOut - True is System.out should be captured
captureErr - True if System.err should be captured

restoreSystemStreams

protected static void restoreSystemStreams()
Restores System.out and System.err to their original values


addLoggingClass

protected static void addLoggingClass(String className)
Add a class to the list of known logging classes. Any stack trace element that starts with these class names is skipped.

Parameters:
className - The class to report as a logging class

clearLoggingClasses

protected static void clearLoggingClasses()
Removes all classes from the list of known logging classes


log

public static void log(Object... args)
Log a message. The last argument to this object is the message to log (usually a String); the first arguments are the channels to log to. For example: log(Redwood.ERR,"tag","this message is tagged with ERROR and tag")

Parameters:
args - The last argument is the message; the first arguments are the channels.

logf

public static void logf(String format,
                        Object... args)

startTrack

public static void startTrack(Object... args)
Begin a "track;" that is, begin logging at one level deeper. Channels other than the FORCE channel are ignored.

Parameters:
args - The title of the track to begin, with an optional FORCE flag.

forceTrack

public static void forceTrack(Object arg)
Helper method to start a track on the FORCE channel.

Parameters:
arg -

forceTrack

public static void forceTrack()
Helper method to start an anonymous track on the FORCE channel.


endTrack

public static void endTrack(String title)
End a "track;" that is, return to logging at one level shallower.

Parameters:
title - A title that should match the beginning of this track.

endTrack

public static void endTrack()
A utility method for closing calls to the anonymous startTrack() call.


startThreads

public static void startThreads(String title)
Start a multithreaded logging environment. Log messages will be real time from one of the threads; as each thread finishes, another thread begins logging, first by making up the backlog, and then by printing any new log messages. A thread signals that it has finished logging with the finishThread() function; the multithreaded environment is ended with the endThreads() function

Parameters:
title - The name of the thread group being started

finishThread

public static void finishThread()
Signal that this thread will not log any more messages in the multithreaded environment


endThreads

public static void endThreads(String check)
Signal that all threads have run to completion, and the multithreaded environment is over.

Parameters:
check - The name of the thread group passed to startThreads()

channels

public static Redwood.RedwoodChannels channels(Object... channelNames)
Create an object representing a group of channels. Redwood.RedwoodChannels contains a more complete description.

See Also:
Redwood.RedwoodChannels

showOnlyChannels

public static void showOnlyChannels(Object... channels)
Show only the given channel.

Parameters:
channels - The channels to show

hideOnlyChannels

public static void hideOnlyChannels(Object... channels)
Hide multiple channels. All other channels will be shown.

Parameters:
channels - The channels to hide

showChannels

public static void showChannels(Object... channels)
Show multiple channels. All other channels will be unaffected.

Parameters:
channels - The channels to show

hideChannels

public static void hideChannels(Object... channels)
Hide multiple channels. All other channels will be unaffected.

Parameters:
channels - The channels to hide

showAllChannels

public static void showAllChannels()
Show all channels.


hideAllChannels

public static void hideAllChannels()
Hide all channels.


stop

public static void stop()
Stop Redwood, closing all tracks and prohibiting future log messages.


formatTimeDifference

protected static void formatTimeDifference(long diff,
                                           StringBuilder b)
Utility method for formatting a time difference (maybe this should go to a util class?)

Parameters:
diff - Time difference in milliseconds
b - The string builder to append to

filterStackTrace

protected static List<StackTraceElement> filterStackTrace(StackTraceElement[] stack)
Removes logging classes from a stack trace.


supportsAnsi

protected static boolean supportsAnsi()

main

public static void main(String[] args)
Various informal tests of Redwood functionality

Parameters:
args - Unused


Stanford NLP Group