Package ec.util

Class Output

java.lang.Object
ec.util.Output
All Implemented Interfaces:
Serializable
public class Output extends Object implements 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 verbosity 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. FATAL ERRORs. These errors cause the system to exit(1) immediately.
  2. 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.
  3. WARNINGs. These errors do not cause the system to exit under any circumstances.
  4. MESSAGEs. Useful facts printed out for the benefit of the user.
  5. SYSTEM MESSAGEs. Useful system-level facts printed out for the benefit of the user.

Output will also store all announcements in memory by default so as to reproduce them if it's restarted from a checkpoint. You can change this behavior also by

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Output.OutputExitException
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    ALL_MESSAGE_LOGS
     
    static final int
    NO_LOGS
    When passed to print functions, doesn't do any printing
    static final int
    V_NO_ERRORS
    Don't print warnings, messages, or simple errors
    static final int
    V_NO_GENERAL
    The standard verbosity to use if you don't want common reporting (like statistics)
    static final int
    V_NO_MESSAGES
    Don't print messages
    static final int
    V_NO_WARNINGS
    Don't print warnings or messages
    static final int
    V_TOTALLY_SILENT
    No verbosity at all, not even system messages or fatal errors
    static final int
    V_VERBOSE
    Total verbosity

  • Constructor Summary

    Constructors
    Constructor
    Description
    Output(boolean storeAnnouncementsInMemory)
    Creates a new, verbose, empty Output object.
    Output(boolean storeAnnouncementsInMemory, int _verbosity)
    Creates a new, verbose, empty Output object.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    addLog(int descriptor, boolean postAnnouncements)
    Creates a new log 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(File file, boolean appendOnRestart)
    Creates a new log and adds it to Output.
    int
    addLog(File file, boolean appendOnRestart, boolean gzip)
    Creates a new log and adds it to Output.
    int
    addLog(File file, boolean postAnnouncements, boolean appendOnRestart, boolean gzip)
    Creates a new log and adds it to Output.
    int
    addLog(File file, int _verbosity, boolean postAnnouncements, boolean appendOnRestart)
    Creates a new log of minimal verbosity verbosity and adds it to Output.
    int
    addLog(File file, int _verbosity, boolean postAnnouncements, boolean appendOnRestart, boolean gzip)
    Creates a new log of minimal verbosity verbosity and adds it to Output.
    int
    addLog(Writer writer, LogRestarter restarter, boolean postAnnouncements, boolean repostAnnouncements)
    Creates a new log and adds it to Output.
    int
    addLog(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
    close()
    Closes the logs -- ONLY call this if you are preparing to quit
    void
    error(String s)
    Posts a simple error.
    void
    error(String s, Parameter p1)
    Posts a simple error.
    void
    error(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(String s)
    Posts a fatal error.
    void
    fatal(String s, Parameter p1)
    Posts a fatal error.
    void
    fatal(String s, Parameter p1, Parameter p2)
    Posts a fatal error.
    void
    flush()
    Flushes the logs
    boolean
    getFlush()
     
    Log
    getLog(int x)
    Returns the given log.
    boolean
    getStore()
     
    boolean
    getThrowsErrors()
     
    int
    getVerbosity()
    Returns the Output object's general verbosity
    static void
    initialError(String s, boolean throwsErrors)
    Prints an initial error to System.err.
    static void
    initialError(String s, Parameter p1, boolean throwsErrors)
    Prints an initial error to System.err.
    static void
    initialError(String s, Parameter p1, Parameter p2, boolean throwsErrors)
    Prints an initial error to System.err.
    static void
    initialMessage(String s)
    Prints an initial message to System.err.
    static void
    initialWarning(String s)
    Prints an initial warning to System.err.
    static void
    initialWarning(String s, Parameter p1)
    Prints an initial warning to System.err.
    static void
    initialWarning(String s, Parameter p1, Parameter p2)
    Prints an initial warning to System.err.
    static InputStream
    makeCompressingInputStream(InputStream in)
    Returns a compressing input stream using JZLib (http://www.jcraft.com/jzlib/).
    static OutputStream
    makeCompressingOutputStream(OutputStream out)
    Returns a compressing output stream using JZLib (http://www.jcraft.com/jzlib/).
    void
    message(String s)
    Posts a message.
    int
    numLogs()
    Returns the number of logs currently posted.
    void
    print(String s, int log)
    Prints a non-announcement message to a given log.
    void
    print(String s, int[] _logs)
    Prints a non-announcement message to the given logs, with a certain verbosity.
    void
    print(String s, int _verbosity, int log)
    Prints a non-announcement message to a given log, with a certain verbosity.
    void
    print(String s, int _verbosity, int[] _logs)
    Prints a non-announcement message to the given logs, with a certain verbosity.
    protected void
    print(String s, int _verbosity, Log log)
    Prints a non-announcement message to a given log, with a certain verbosity.
    void
    println(String s, int log)
    Prints a non-announcement message to the given logs, with a verbosity of V_NO_GENERAL.
    void
    println(String s, int log, boolean _announcement)
    Prints a message to a given log.
    void
    println(String s, int _verbosity, int log)
    Prints a non-announcement message to the given logs, with a certain verbosity.
    void
    println(String s, int _verbosity, int[] _logs)
    Prints a non-announcement message to the given logs, 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()
     
    void
    setFilePrefix(String filePrefix)
     
    void
    setFlush(boolean v)
    Sets whether the Output flushes its announcements.
    void
    setStore(boolean v)
    Sets whether the Output stores its announcements.
    void
    setThrowsErrors(boolean val)
     
    void
    setVerbosity(int v)
    Sets the Output object's general verbosity to v.
    void
    systemMessage(String s)
    Posts a system message.
    void
    warning(String s)
    Posts a warning.
    void
    warning(String s, Parameter p1)
    Posts a warning.
    void
    warning(String s, Parameter p1, Parameter p2)
    Posts a warning.
    void
    warnOnce(String s)
    Posts a warning one time only.
    void
    warnOnce(String s, Parameter p1)
     
    void
    warnOnce(String s, Parameter p1, Parameter p2)
     

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • V_VERBOSE

      public static final int V_VERBOSE
      Total verbosity
      See Also:

    • V_NO_MESSAGES

      public static final int V_NO_MESSAGES
      Don't print messages
      See Also:

    • V_NO_WARNINGS

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

    • V_NO_GENERAL

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

    • V_NO_ERRORS

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

    • V_TOTALLY_SILENT

      public static final int V_TOTALLY_SILENT
      No verbosity at all, not even system messages or fatal errors
      See Also:

    • ALL_MESSAGE_LOGS

      public static final int ALL_MESSAGE_LOGS
      See Also:

    • NO_LOGS

      public static final int NO_LOGS
      When passed to print functions, doesn't do any printing
      See Also:

  • Constructor Details

    • Output

      public Output(boolean storeAnnouncementsInMemory, int _verbosity)
      Creates a new, verbose, empty Output object.

    • Output

      public Output(boolean storeAnnouncementsInMemory)
      Creates a new, verbose, empty Output object.

  • Method Details

    • setFilePrefix

      public void setFilePrefix(String filePrefix)

    • setThrowsErrors

      public void setThrowsErrors(boolean val)

    • getThrowsErrors

      public boolean getThrowsErrors()

    • close

      public void close()
      Closes the logs -- ONLY call this if you are preparing to quit

    • flush

      public void flush()
      Flushes the logs

    • setFlush

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

    • getFlush

      public boolean getFlush()

    • setStore

      public void setStore(boolean v)
      Sets whether the Output stores its announcements.

    • getStore

      public boolean getStore()

    • setVerbosity

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

    • getVerbosity

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

    • addLog

      public int addLog(File file, int _verbosity, boolean postAnnouncements, boolean appendOnRestart, boolean gzip) throws IOException
      Creates a new log of minimal verbosity verbosity and adds it to Output. This log will write to the file file, 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. The log can be compressed with gzip, but you cannot appendOnRestart and compress at the same time.
      Throws:
      IOException

    • addLog

      public int addLog(File file, int _verbosity, boolean postAnnouncements, boolean appendOnRestart) throws IOException
      Creates a new log of minimal verbosity verbosity and adds it to Output. This log will write to the file file, 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.
      Throws:
      IOException

    • addLog

      public int addLog(File file, boolean postAnnouncements, boolean appendOnRestart, boolean gzip) throws IOException
      Creates a new log and adds it to Output. This log will write to the file file, 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. The log can be compressed with gzip, but you cannot appendOnRestart and compress at the same time.
      Throws:
      IOException

    • addLog

      public int addLog(File file, boolean appendOnRestart, boolean gzip) throws IOException
      Creates a new log and adds it to Output. This log will write to the file file, and you 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. 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. The log can be compressed with gzip, but you cannot appendOnRestart and compress at the same time.
      Throws:
      IOException

    • addLog

      public int addLog(File file, boolean appendOnRestart) throws IOException
      Creates a new log and adds it to Output. This log will write to the file file, and you 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. 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.
      Throws:
      IOException

    • 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(int descriptor, boolean postAnnouncements)
      Creates a new log 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(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(Writer writer, LogRestarter restarter, boolean postAnnouncements, boolean repostAnnouncements)
      Creates a new log 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.

    • getLog

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

    • removeLog

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

    • initialWarning

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

    • initialWarning

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

    • initialWarning

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

    • initialError

      public static void initialError(String s, boolean throwsErrors)
      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(String s, Parameter p1, boolean throwsErrors)
      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(String s, Parameter p1, Parameter p2, boolean throwsErrors)
      Prints an initial error to System.err. This is only to be used by ec.Evolve in starting up the system.

    • initialMessage

      public static void initialMessage(String s)
      Prints an initial message to System.err. This is only to be used by ec.Evolve in starting up the system. These messages are not logged.

    • systemMessage

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

    • fatal

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

    • fatal

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

    • fatal

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

    • error

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

    • error

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

    • error

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

    • warning

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

    • warning

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

    • warning

      public void warning(String s)
      Posts a warning.

    • warnOnce

      public void warnOnce(String s)
      Posts a warning one time only.

    • warnOnce

      public void warnOnce(String s, Parameter p1)

    • warnOnce

      public void warnOnce(String s, Parameter p1, Parameter p2)

    • message

      public void message(String s)
      Posts a message.

    • reopen

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

    • reopen

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

    • println

      public void println(String s, int log, boolean _announcement) throws OutputException
      Prints a message to a given log. If log==ALL_MESSAGE_LOGS, posted to all logs which accept announcements. If the log is NO_LOGS, nothing is printed.
      Throws:
      OutputException

    • println

      public void println(String s, int _verbosity, int[] _logs) throws OutputException
      Prints a non-announcement message to the given logs, with a certain verbosity. If a log is NO_LOGS, nothing is printed to that log.
      Throws:
      OutputException

    • println

      public void println(String s, int _verbosity, int log) throws OutputException
      Prints a non-announcement message to the given logs, with a certain verbosity. If the log is NO_LOGS, nothing is printed.
      Throws:
      OutputException

    • println

      public void println(String s, int log) throws OutputException
      Prints a non-announcement message to the given logs, with a verbosity of V_NO_GENERAL. If the log is NO_LOGS, nothing is printed.
      Throws:
      OutputException

    • print

      protected void print(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. If the log is null, nothing is printed.
      Throws:
      OutputException

    • print

      public void print(String s, int _verbosity, int log) throws OutputException
      Prints a non-announcement message to a given log, with a certain verbosity. If log==ALL_MESSAGE_LOGS, posted to all logs which accept announcements. No '\n' is printed. If the log is NO_LOGS, nothing is printed.
      Throws:
      OutputException

    • print

      public void print(String s, int log) throws OutputException
      Prints a non-announcement message to a given log. If log==ALL_MESSAGE_LOGS, posted to all logs which accept announcements. No '\n' is printed. If the log is NO_LOGS, nothing is printed.
      Throws:
      OutputException

    • print

      public void print(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. If a log is NO_LOGS, nothing is printed to that log.
      Throws:
      OutputException

    • print

      public void print(String s, int[] _logs) throws OutputException
      Prints a non-announcement message to the given logs, with a certain verbosity. No '\n' is printed. If a log is NO_LOGS, nothing is printed to that log.
      Throws:
      OutputException

    • 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 IOException
      Throws:
      IOException

    • makeCompressingInputStream

      public static InputStream makeCompressingInputStream(InputStream in)
      Returns a compressing input stream using JZLib (http://www.jcraft.com/jzlib/). If JZLib is not available on your system, this method will return null.

    • makeCompressingOutputStream

      public static OutputStream makeCompressingOutputStream(OutputStream out)
      Returns a compressing output stream using JZLib (http://www.jcraft.com/jzlib/). If JZLib is not available on your system, this method will return null.