package uk.co.wingpath.util;

import java.util.*;

/**
* This interface is used to provide notification of errors and other
* information.
* The implementations of the methods in this interface would normally display
* the supplied message (e.g. in a status bar) or write it to a log file.
* <p>The message paramater to each of these methods may contain '\n' characters,
* and implementations must deal correctly with such multi-line messages.
*/

public interface Reporter
{
    /**
    * This enum represents the different logging levels used by Reporters.
    */
    enum Level
    {
        NONE, FATAL, ERROR, WARN, INFO, TRACE, DEBUG
    }

    /**
    * This method is called to inform the user of an irrecoverable error.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    * @return true if the error was reported somewhere other than the GUI.
    */
    boolean fatal (String fmt, Object... args);

    /**
    * This method is called to inform the user of an irrecoverable error.
    * The stack trace of the supplied exception is included in the report.
    * @param t exception to report, including its stack trace.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    * @return true if the error was reported somewhere other than the GUI.
    */
    boolean fatal (Throwable t, String fmt, Object... args);

    /**
    * This method is called to inform the user of a recoverable error.
    * @param helpId help identifier for the message.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    */
    void error (String helpId, String fmt, Object... args);

    /**
    * This method is called to warn the user of an unusual condition.
    * @param helpId help identifier for the message.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    */
    void warn (String helpId, String fmt, Object... args);

    /**
    * This method is called to provide other information to the user.
    * @param helpId help identifier for the message.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    */
    void info (String helpId, String fmt, Object... args);

    /**
    * This method is called to provide trace information to the user.
    * @param helpId help identifier for the message.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    */
    void trace (String helpId, String fmt, Object... args);

    /**
    * This method is called to provide debug information to the developer.
    * @param fmt a format string as described in {@link Formatter}.
    * @param args arguments referenced by the format specifiers in the
    * format string.
    * @return true, so that the construction "assert reporter.debug (...);"
    * can be used to enable stripping of the debug code by the compiler.
    */
    boolean debug (String fmt, Object... args);

    /**
    * This method is called to indicate that the previous message is no
    * longer relevant. It is used to clear a message display area (e.g.
    * status bar), but would normally be ignored for logging output.
    */
    void clear ();
}