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:
  - Serialized Form

- ## 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:
      - Constant Field Values

  - ### V_NO_MESSAGES

    public static final int V_NO_MESSAGES
    Don't print messages
    See Also:
      - Constant Field Values

  - ### V_NO_WARNINGS

    public static final int V_NO_WARNINGS
    Don't print warnings or messages
    See Also:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### V_NO_ERRORS

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

  - ### V_TOTALLY_SILENT

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

  - ### ALL_MESSAGE_LOGS

    public static final int ALL_MESSAGE_LOGS
    See Also:
      - Constant Field Values

  - ### NO_LOGS

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

- ## 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.