ec.util
Class Output

java.lang.Object
  |
  +--ec.util.Output

public class Output
extends java.lang.Object
implements java.io.Serializable

Outputs and logs system messages, errors, and other various items printed as a result of a run.

Output maintains zero or more logs, which contain Writers which write out stuff. Each log has an associated verbosity; if request is made to write text to a log, and the text's maximal verbosity is lower than the verbosity of the log, the log will not write it. Each Output instance also has an instance-level global verbosity; incoming requests to write text are additionally subject to this verbosity test. Lastly, the Output class itself has a global verbosity as well. This last verbostity is useful for shutting down writing to all logs in the entire system in a simple way.

When the system fails for some reason and must be started back up from a checkpoint, Output's log files may be overwritten. Output offers three approaches here. First, Output can clear the log file and overwrite it. Second, Output can append to the existing log file; because checkpoints are only done occasionally, this may result in duplicate outputs to a file, so keep this in mind. Third, Output can keep certain written text, typically announcements, in memory; this text gets written out into the checkpoint file, and so it is sound.

There are several kinds of announcements, in different levels of importance.

  1. SYSTEM MESSAGEs. Useful system-level facts printed out for the benefit of the user.
  2. FATAL ERRORs. These errors cause the system to exit(1) immediately.
  3. Simple ERRORs. These errors set the "errors" flag to true; at the end of a stream of simple errors, the system in general is expected to exit with a fatal error due to the flag being set. That's the protocol anyway. On restart from a checkpoint, if there were any simple errors, the system ends with a fatal error automatically.
  4. WARNINGs. These errors do not cause the system to exit under any circumstances.
  5. MESSAGEs. Useful facts printed out for the benefit of the user.

The default verbosity values for different kinds of announcements are given below:
0V_VERBOSE(totally verbose)
1000V_NO_MESSAGES(don't print messages)
2000V_NO_WARNINGS(don't print warnings or messages)
3000V_NO_GENERAL(don't print warnings, messages, or other "general info" stuff that might come along (like statistics maybe))
4000V_NO_ERRORS(don't even print errors)
5000V_TOTALLY_SILENT(be totally silent)

See Also:
Serialized Form

Field Summary
static int ALL_LOGS
           
static int V_NO_ERRORS
          Don't print warnings, messages, or simple errors
static int V_NO_GENERAL
          The standard verbosity to use if you don't want common reporting (like statistics)
static int V_NO_MESSAGES
          Don't print messages
static int V_NO_WARNINGS
          Don't print warnings or messages
static int V_TOTALLY_SILENT
          No verbosity at all, not even system messages or fatal errors
static int V_VERBOSE
          Total verbosity
 
Constructor Summary
Output(boolean storeAnnouncementsInMemory, int verbosity)
          Creates a new, verbose, empty Output object.
 
Method Summary
 int addLog(java.io.File filename, int verbosity, boolean postAnnouncements, boolean appendOnRestart)
          Creates a new log of minimal verbosity verbosity and adds it to Output.
 int addLog(int descriptor, int verbosity, boolean postAnnouncements)
          Creates a new log of minimal verbosity verbosity and adds it to Output.
 int addLog(Log l)
          Adds the given log to Output.
 int addLog(java.io.Writer writer, LogRestarter restarter, int verbosity, boolean postAnnouncements, boolean repostAnnouncements)
          Creates a new log of minimal verbosity verbosity and adds it to Output.
 void clearAnnouncements()
          Clears out announcements.
 void clearErrors()
          Clears the error flag.
 void error(java.lang.String s)
          Posts a simple error.
 void error(java.lang.String s, Parameter p1)
          Posts a simple error.
 void error(java.lang.String s, Parameter p1, Parameter p2)
          Posts a simple error.
 void exitIfErrors()
          Exits with a fatal error if the error flag has been raised.
 void fatal(java.lang.String s)
          Posts a fatal error.
 void fatal(java.lang.String s, Parameter p1)
          Posts a fatal error.
 void fatal(java.lang.String s, Parameter p1, Parameter p2)
          Posts a fatal error.
protected  void finalize()
           
 void flush()
          Flushes the logs
 int getGlobalVerbosity()
          Returns the global (static) verbosity of Output objects
 int getVerbosity()
          Returns the Output object's general verbosity
static void initialError(java.lang.String s)
          Prints an initial error to System.err.
static void initialError(java.lang.String s, Parameter p1)
          Prints an initial error to System.err.
static void initialError(java.lang.String s, Parameter p1, Parameter p2)
          Prints an initial error to System.err.
 Log log(int x)
          Returns the given log.
 void message(java.lang.String s)
          Posts a message.
 int numLogs()
          Returns the number of logs currently posted.
 void print(java.lang.String s, int _verbosity, int log)
          Prints a non-announcement message to a given log, with a certain verbosity.
 void print(java.lang.String s, int _verbosity, int[] _logs)
          Prints a non-announcement message to the given logs, with a certain verbosity.
protected  void print(java.lang.String s, int _verbosity, Log log)
          Prints a non-announcement message to a given log, with a certain verbosity.
 void println(java.lang.String s, int _verbosity, int log)
          Prints a non-announcement message to the given logs, with a certain verbosity.
 void println(java.lang.String s, int _verbosity, int[] _logs)
          Prints a non-announcement message to the given logs, with a certain verbosity.
 void println(java.lang.String s, int _verbosity, int log, boolean _announcement)
          Prints a message to a given log, with a certain verbosity.
protected  void println(java.lang.String s, int _verbosity, Log log, boolean _announcement, boolean _reposting)
          Prints a message to a given log, with a certain verbosity.
 Log removeLog(int x)
          Removes the given log.
 void reopen(int _log)
          Forces a file-based log to reopen, erasing its previous contents.
 void reopen(int[] _logs)
          Forces one or more file-based logs to reopen, erasing their previous contents.
 void restart()
           
 boolean setFlush(boolean v)
          Sets whether the Output flushes its announcements.
 int setGlobalVerbosity(int v)
          Sets the global (static) verbosity of Output objects to v.
 int setVerbosity(int v)
          Sets the Output object's general verbosity to v.
 void systemMessage(java.lang.String s)
          Posts a system message.
 void warning(java.lang.String s)
          Posts a warning.
 void warning(java.lang.String s, Parameter p1)
          Posts a warning.
 void warning(java.lang.String s, Parameter p1, Parameter p2)
          Posts a warning.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ALL_LOGS

public static final int ALL_LOGS

V_VERBOSE

public static final int V_VERBOSE
Total verbosity

V_NO_MESSAGES

public static final int V_NO_MESSAGES
Don't print messages

V_NO_WARNINGS

public static final int V_NO_WARNINGS
Don't print warnings or messages

V_NO_GENERAL

public static final int V_NO_GENERAL
The standard verbosity to use if you don't want common reporting (like statistics)

V_NO_ERRORS

public static final int V_NO_ERRORS
Don't print warnings, messages, or simple errors

V_TOTALLY_SILENT

public static final int V_TOTALLY_SILENT
No verbosity at all, not even system messages or fatal errors
Constructor Detail

Output

public Output(boolean storeAnnouncementsInMemory,
              int verbosity)
Creates a new, verbose, empty Output object.
Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable
Overrides:
finalize in class java.lang.Object

flush

public void flush()
Flushes the logs

setFlush

public boolean setFlush(boolean v)
Sets whether the Output flushes its announcements.

setVerbosity

public int setVerbosity(int v)
Sets the Output object's general verbosity to v.

getVerbosity

public int getVerbosity()
Returns the Output object's general verbosity

setGlobalVerbosity

public int setGlobalVerbosity(int v)
Sets the global (static) verbosity of Output objects to v.

getGlobalVerbosity

public int getGlobalVerbosity()
Returns the global (static) verbosity of Output objects

addLog

public int addLog(java.io.File filename,
                  int verbosity,
                  boolean postAnnouncements,
                  boolean appendOnRestart)
           throws java.io.IOException
Creates a new log of minimal verbosity verbosity and adds it to Output. This log will write to the file filename, and may or may not post announcements to the log. If the log must be reset upon restarting from a checkpoint, it will append to the file or erase the file and start over depending on appendOnRestart. If appendOnRestart is false and postAnnouncements is true, then this log will repost all the announcements on restarting from a checkpoint. Returns the position of the log in Output's collection of logs -- you should use this to access the log always; never store the log itself, which may go away upon a system restart.

addLog

public int addLog(int descriptor,
                  int verbosity,
                  boolean postAnnouncements)
Creates a new log of minimal verbosity verbosity and adds it to Output. This log will write to stdout (descriptor == Log.D_STDOUT) or stderr (descriptor == Log.D_STDERR), and may or may not post announcements to the log. Returns the position of the log in Output's collection of logs -- you should use this to access the log always; never store the log itself, which may go away upon a system restart.

addLog

public int addLog(java.io.Writer writer,
                  LogRestarter restarter,
                  int verbosity,
                  boolean postAnnouncements,
                  boolean repostAnnouncements)
Creates a new log of minimal verbosity verbosity and adds it to Output. This log may or may not post announcements to the log, and if it does, it additionally may or may not repost all of its announcements to the log upon a restart. The log writes to writer, which is reset upon system restart by restarter. Returns the position of the log in Output's collection of logs -- you should use this to access the log always; never store the log itself, which may go away upon a system restart.

addLog

public int addLog(Log l)
Adds the given log to Output. In general you shouldn't use this method unless you really really need something custom. Returns the position of the log in Output's collection of logs -- you should use this to access the log always; never store the log itself, which may go away upon a system restart.

numLogs

public int numLogs()
Returns the number of logs currently posted.

log

public Log log(int x)
Returns the given log.

removeLog

public Log removeLog(int x)
Removes the given log.

initialError

public static void initialError(java.lang.String s)
Prints an initial error to System.err. This is only to be used by ec.Evolve in starting up the system.

initialError

public static void initialError(java.lang.String s,
                                Parameter p1)
Prints an initial error to System.err. This is only to be used by ec.Evolve in starting up the system.

initialError

public static void initialError(java.lang.String s,
                                Parameter p1,
                                Parameter p2)
Prints an initial error to System.err. This is only to be used by ec.Evolve in starting up the system.

systemMessage

public void systemMessage(java.lang.String s)
Posts a system message.

fatal

public void fatal(java.lang.String s)
Posts a fatal error. This causes the system to exit.

fatal

public void fatal(java.lang.String s,
                  Parameter p1)
Posts a fatal error. This causes the system to exit.

fatal

public void fatal(java.lang.String s,
                  Parameter p1,
                  Parameter p2)
Posts a fatal error. This causes the system to exit.

error

public void error(java.lang.String s)
Posts a simple error. This causes the error flag to be raised as well.

error

public void error(java.lang.String s,
                  Parameter p1)
Posts a simple error. This causes the error flag to be raised as well.

error

public void error(java.lang.String s,
                  Parameter p1,
                  Parameter p2)
Posts a simple error. This causes the error flag to be raised as well.

warning

public void warning(java.lang.String s,
                    Parameter p1,
                    Parameter p2)
Posts a warning.

warning

public void warning(java.lang.String s,
                    Parameter p1)
Posts a warning.

warning

public void warning(java.lang.String s)
Posts a warning.

message

public void message(java.lang.String s)
Posts a message.

reopen

public void reopen(int _log)
            throws java.io.IOException
Forces a file-based log to reopen, erasing its previous contents. non-file logs ignore this.

reopen

public void reopen(int[] _logs)
            throws java.io.IOException
Forces one or more file-based logs to reopen, erasing their previous contents. non-file logs ignore this.

println

protected void println(java.lang.String s,
                       int _verbosity,
                       Log log,
                       boolean _announcement,
                       boolean _reposting)
                throws OutputException
Prints a message to a given log, with a certain verbosity. _announcement indicates that the message is an announcement.

println

public void println(java.lang.String s,
                    int _verbosity,
                    int log,
                    boolean _announcement)
             throws OutputException
Prints a message to a given log, with a certain verbosity. If log==ALL_LOGS, posted to all logs.

println

public void println(java.lang.String s,
                    int _verbosity,
                    int[] _logs)
             throws OutputException
Prints a non-announcement message to the given logs, with a certain verbosity.

println

public void println(java.lang.String s,
                    int _verbosity,
                    int log)
             throws OutputException
Prints a non-announcement message to the given logs, with a certain verbosity.

print

protected void print(java.lang.String s,
                     int _verbosity,
                     Log log)
              throws OutputException
Prints a non-announcement message to a given log, with a certain verbosity. No '\n' is printed.

print

public void print(java.lang.String s,
                  int _verbosity,
                  int log)
           throws OutputException
Prints a non-announcement message to a given log, with a certain verbosity. If log==ALL_LOGS, posted to all logs. No '\n' is printed.

print

public void print(java.lang.String s,
                  int _verbosity,
                  int[] _logs)
           throws OutputException
Prints a non-announcement message to the given logs, with a certain verbosity. No '\n' is printed.

exitIfErrors

public void exitIfErrors()
Exits with a fatal error if the error flag has been raised.

clearErrors

public void clearErrors()
Clears the error flag.

clearAnnouncements

public void clearAnnouncements()
Clears out announcements. Note that this will cause these announcements to be unavailable for reposting after a restart!

restart

public void restart()
             throws java.io.IOException