edu.stanford.nlp.util.logging

Class Redwood

java.lang.Object

edu.stanford.nlp.util.logging.Redwood

public class Redwood
extends java.lang.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

Nested Classes

Modifier and Type	Class and Description
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 TODO: make constructors for other ways of describing files (File, for example!)
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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
Redwood()

Method Summary

Methods

Modifier and Type	Method and Description
protected static void	addLoggingClass(java.lang.String className) Add a class to the list of known logging classes.
protected static void	appendHandler(java.lang.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(java.lang.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(java.lang.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(java.lang.String title) End a "track;" that is, return to logging at one level shallower.
protected static java.util.List<java.lang.StackTraceElement>	filterStackTrace(java.lang.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(java.lang.Object arg) Helper method to start a track on the FORCE channel.
protected static void	formatTimeDifference(long diff, java.lang.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(java.lang.Object... channels) Hide multiple channels.
static void	hideOnlyChannels(java.lang.Object... channels) Hide multiple channels.
static void	log(java.lang.Object... args) Log a message.
static void	logf(java.lang.String format, java.lang.Object... args) The Redwood equivalent to printf().
static void	main(java.lang.String[] args) Various informal tests of Redwood functionality
protected static <E extends LogRecordHandler> boolean	removeHandler(java.lang.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(java.lang.Object... channels) Show multiple channels.
static void	showOnlyChannels(java.lang.Object... channels) Show only the given channel.
protected static void	spliceHandler(java.lang.Class<? extends LogRecordHandler> parent, LogRecordHandler toAdd, java.lang.Class<? extends LogRecordHandler> grandchild)
protected static void	spliceHandler(LogRecordHandler parent, LogRecordHandler toAdd, java.lang.Class<? extends LogRecordHandler> grandchild)
protected static void	spliceHandler(LogRecordHandler parent, LogRecordHandler toAdd, LogRecordHandler grandchild)
static void	startThreads(java.lang.String title) Start a multithreaded logging environment.
static void	startTrack(java.lang.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(java.lang.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,
                 java.lang.Class<? extends LogRecordHandler> grandchild)

spliceHandler

protected static void spliceHandler(java.lang.Class<? extends LogRecordHandler> parent,
                 LogRecordHandler toAdd,
                 java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String format,
        java.lang.Object... args)

The Redwood equivalent to printf().

Parameters:

format - The format string, as per java's Formatter.format() object.

args - The arguments to format.

startTrack

public static void startTrack(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.Object... channels)

Show only the given channel.

Parameters:

channels - The channels to show

hideOnlyChannels

public static void hideOnlyChannels(java.lang.Object... channels)

Hide multiple channels. All other channels will be shown.

Parameters:

channels - The channels to hide

showChannels

public static void showChannels(java.lang.Object... channels)

Show multiple channels. All other channels will be unaffected.

Parameters:

channels - The channels to show

hideChannels

public static void hideChannels(java.lang.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,
                        java.lang.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 java.util.List<java.lang.StackTraceElement> filterStackTrace(java.lang.StackTraceElement[] stack)

Removes logging classes from a stack trace.

supportsAnsi

protected static boolean supportsAnsi()

main

public static void main(java.lang.String[] args)

Various informal tests of Redwood functionality

Parameters:

args - Unused