com.aliasi.io
Class Reporter

java.lang.Object
  extended by com.aliasi.io.Reporter

public abstract class Reporter
extends Object

A Reporter is the abstract base class on which reporters are defined that provide incremental feedback from long-running tasks at various levels of granularity. See the utility class Reporters for factory methods to create reporters with various output sources ranging from files to writers to standard output.

A reporter has a defined severity level, which is an instance of LogLevel. A reporter will report (by whichever means at its disposal) all reports at or above its specified severity level. Whether a reporter will report a message reported at level may be determined by calling isEnabled(LogLevel), which returns true if a message at the specified level will be reported.

Messages are reported as simple strings at a specified log level using report(LogLevel,String). It is up to specific implementations to embellish these with time stamps, thread identifiers, etc.

The severity level may be inspected using getLevel() and changed using setLevel(LogLevel).

Reporting versus Logging

aAlthough this class behaves like other loggers, such as those found in Apache's Log4J or Java's util.logging package, it is not intended to replace them in server-side applications. Unlike these other loggers, reporters as defined in this abstract class are not configurable through reflection -- they are purely controlled through the API. Their intended use is in command-line programs that call long-running training or run methods.

Creating Reporters The static utility class Reporters contains static factory methods for creating a variety of different kinds of reporters.

Thread Safety

The getLevel() and setLevel(LogLevel) methods are synchronized with each other, and thus thread safe. If reporters accept concurrent reports from multiple threads, the report method should be synchronized. As long as the reporter uses the getLevel() method to access the current log level, it does not need to be synchronized with the get and set methods.

Since:
Lingpipe3.8
Version:
3.8
Author:
Bob Carpenter

Constructor Summary
Reporter()
          Construct an instance of a reporter with log level LogLevel.NONE.
Reporter(LogLevel level)
          Construct an instance of a reporter with the specified log level.
 
Method Summary
abstract  void close()
          Close this reporter and free all resources associated with it.
 void debug(String msg)
          Utility method for debug-level reports.
 void error(String msg)
          Utility method for error-level reports.
 void fatal(String msg)
          Utility method for fatal-level reports.
 LogLevel getLevel()
          Return the log level for this reporter.
 void info(String msg)
          Utility method for info-level reports.
 boolean isDebugEnabled()
          Returns true if this reporter is enabled at the debug level.
 boolean isEnabled(LogLevel level)
          Returns true if the specified level is at least as severe as the level specified by this reporter.
 boolean isErrorEnabled()
          Returns true if this reporter is enabled at the error level.
 boolean isFatalEnabled()
          Returns true if this reporter is enabled at the fatal level.
 boolean isInfoEnabled()
          Returns true if this reporter is enabled at the info level.
 boolean isTraceEnabled()
          Returns true if this reporter is enabled at the trace level.
 boolean isWarnEnabled()
          Returns true if this reporter is enabled at the warn level.
abstract  void report(LogLevel level, String msg)
          Reports the specified message if the specified level's severity is at or above the level of this reporter.
 Reporter setLevel(LogLevel level)
          Sets the log level for this reporter to the specified level and returns the reporter.
 void trace(String msg)
          Utility method for trace-level reports.
 void warn(String msg)
          Utility method for warn-level reports.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Reporter

public Reporter()
Construct an instance of a reporter with log level LogLevel.NONE.


Reporter

public Reporter(LogLevel level)
Construct an instance of a reporter with the specified log level.

Parameters:
level - Initial log level for this reporter.
Method Detail

report

public abstract void report(LogLevel level,
                            String msg)
Reports the specified message if the specified level's severity is at or above the level of this reporter.

The objects should be converted to strings and concatenated.

The default implementation in this class does nothing.

If this reporter supports concurrent reports from multiple threads, this method should in some way be synchronized.

Parameters:
level - Log level for this report instance.
msg - Message to report.

trace

public void trace(String msg)
Utility method for trace-level reports.

This is a convenience method calling report(LogLevel.TRACE,msg).

Parameters:
msg - Message to report.

debug

public void debug(String msg)
Utility method for debug-level reports.

This is a convenience method calling report(LogLevel.DEBUG,msg).

Parameters:
msg - Message to report.

info

public void info(String msg)
Utility method for info-level reports.

This is a convenience method calling report(LogLevel.INFO,msg).

Parameters:
msg - Message to report.

warn

public void warn(String msg)
Utility method for warn-level reports.

This is a convenience method calling report(LogLevel.WARN,msg).

Parameters:
msg - Message to report.

error

public void error(String msg)
Utility method for error-level reports.

This is a convenience method calling report(LogLevel.ERROR,msg).

Parameters:
msg - Message to report.

fatal

public void fatal(String msg)
Utility method for fatal-level reports.

This is a convenience method calling report(LogLevel.FATAL,msg).

Parameters:
msg - Message to report.

getLevel

public final LogLevel getLevel()
Return the log level for this reporter.

The default implementation in this base class returns LogLevel.NONE.

Returns:
The log level for this reporter.

isEnabled

public boolean isEnabled(LogLevel level)
Returns true if the specified level is at least as severe as the level specified by this reporter.

This is a utility method that is equivalent to LogLevel.COMPARATOR.compare(leve,getLevel()).

Parameters:
level - Level to test.
Returns:
true if the specified level will be reported.

isTraceEnabled

public boolean isTraceEnabled()
Returns true if this reporter is enabled at the trace level.

This is just a convenience method calling isEnabled(LogLevel.TRACE).

Returns:
true if trace reporting is enabled.

isDebugEnabled

public boolean isDebugEnabled()
Returns true if this reporter is enabled at the debug level.

This is just a convenience method calling isEnabled(LogLevel.DEBUG).

Returns:
true if debug reporting is enabled.

isInfoEnabled

public boolean isInfoEnabled()
Returns true if this reporter is enabled at the info level.

This is just a convenience method calling isEnabled(LogLevel.INFO).

Returns:
true if info reporting is enabled.

isWarnEnabled

public boolean isWarnEnabled()
Returns true if this reporter is enabled at the warn level.

This is just a convenience method calling isEnabled(LogLevel.WARN).

Returns:
true if warn reporting is enabled.

isErrorEnabled

public boolean isErrorEnabled()
Returns true if this reporter is enabled at the error level.

This is just a convenience method calling isEnabled(LogLevel.ERROR).

Returns:
true if error reporting is enabled.

isFatalEnabled

public boolean isFatalEnabled()
Returns true if this reporter is enabled at the fatal level.

This is just a convenience method calling isEnabled(LogLevel.FATAL).

Returns:
true if fatal reporting is enabled.

setLevel

public final Reporter setLevel(LogLevel level)
Sets the log level for this reporter to the specified level and returns the reporter. The reporter is returned to allow argument chaining, as in:
 Reporter r = Reporters.stdOut().setLevel(LogLevel.DEBUG);

The default implementation in this class sets the logging level to the specified level and returns this reporter.

This method must return this reporter in order to be plug-and-play compatible with the built-in reporters.

Parameters:
level - New log level.
Returns:
This reporter.

close

public abstract void close()
Close this reporter and free all resources associated with it. This method will likely to cause the reporter to become inoperable after closed.

The default implementation in this class does nothing.