//============================================================================== // LoggerI.java //------------------------------------------------------------------------------ package tribble.io; // System imports import java.io.IOException; import java.io.PrintWriter; import java.io.Writer; import java.lang.String; // Local imports // (None) /******************************************************************************* * Message logger (logging output stream). * *

* Classes that implement this interface are encouraged (but not required) to * have the following constructors: * 

*    class MyLoggerClass
*        implements tribble.io.LoggerI
*    {
*        public MyLoggerClass() {...}
*        public MyLoggerClass(java.io.PrintWriter out) {...}
*    }
* *

* It is also recommended that implementations synchronize their write operations * to their underlying output streams. (See java.io.Writer.lock for * further details.) * * @version $Revision: 1.3 $ $Date: 2003/03/08 17:16:44 $ * @since 2003-01-06 * @author * David R. Tribble, * david@tribble.com. *
* Copyright * ©2003 by David R. Tribble, all rights reserved. *
* Permission is granted to freely use and distribute this source code * provided that the original copyright and authorship notices remain * intact. * * @see Logger */ public interface LoggerI { // Identification /** Revision information. */ static final String REV = "@(#)tribble/io/LoggerI.java $Revision: 1.3 $ $Date: 2003/03/08 17:16:44 $\n"; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Public constants //---------------------------------- // Message severity levels /** Severity level: Debug. */ public static final short SEV_DEBUG = 1; /** Severity level: Informational. */ public static final short SEV_INFO = 2; /** Severity level: Warning. */ public static final short SEV_WARNING = 3; /** Severity level: Error. */ public static final short SEV_ERROR = 4; /** Severity level: Fatal (unrecoverable) error. */ public static final short SEV_FATAL = 5; /** Severity level: Internal (unrecoverable) fatal error. */ public static final short SEV_INTERNAL = 6; //---------------------------------- // Message prefix option bitflags /** Prefixing flag: None. */ public static final int PFX_NONE = 0x0000; /** Prefixing flag: Show the current date. */ public static final int PFX_DATE = 0x0001; /** Prefixing flag: Show the current time. */ public static final int PFX_TIME = 0x0002; /** Prefixing flag: Show the location name/title. */ public static final int PFX_LOC = 0x0004; /** Prefixing flag: Default setting. */ public static final int PFX__DFL = PFX_LOC | PFX_DATE | PFX_TIME; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Public methods /*************************************************************************** * Establish the underlying output stream for this message logger. * * @param out * A logging output stream. * * @since 1.3, 2003-03-08 */ public void setOutput(Writer out); /*************************************************************************** * Retrieve the underlying output stream for this message logger. * * @return * The underlying output stream for this logging output stream. * * @since 1.1, 2003-01-06 */ public PrintWriter getOutput(); /*************************************************************************** * Close this message logger. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @since 1.1, 2003-01-06 */ public void close(); /*************************************************************************** * Establish the prefixes to be prepended to messages written to this message * logger. * * @param pfx * Zero or more of the PFX_XXX * prefixing bitflag constants or-ed together. * * @return * The previous prefix setting. * * @since 1.1, 2003-01-08 */ public int setPrefix(int pfx); /*************************************************************************** * Establish the verbosity filtering level for this message logger. * * @param sev * The severity of the messages to be filtered. * This should be one of the SEV_XXX * constants, or zero to specify all message severities. * * @param max * The maximum verbosity filtering level for messages written to * this message logger. * Log messages with a verbosity level not greater than this value will be * written to the logging output stream; those with a verbosity level greater * than this value will be ignored. * * @return * The previous verbosity level setting. * * @since 1.2, 2003-02-16 */ public int setVerbosity(int sev, int max); /*************************************************************************** * Write a formatted message to this message logger. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param sev * The severity of the message, which should be one of the * SEV_XXX constants. * * @param verb * The verbosity level of the message. * The higher the level, the more verbose the message (i.e., the more * frequently the message is logged) and thus the more likely it will be * filtered and not written to the output stream; messages with a level of * zero will always be written to the output stream. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void log(int sev, int verb, String loc, String msg); /*************************************************************************** * Write a formatted debugging message to this message logger. * Debugging messages have an implied severity of {@link SEV_DEBUG}. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param verb * The verbosity level of the message. * The higher the level, the more verbose the message (i.e., the more * frequently the message is logged) and thus the more likely it will be * filtered and not written to the output stream; messages with a level of * zero will always be written to the output stream. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void debug(int verb, String loc, String msg); /*************************************************************************** * Write a formatted informational message to this message logger. * Informational messages have an implied severity of {@link SEV_INFO}. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param verb * The verbosity level of the message. * The higher the level, the more verbose the message (i.e., the more * frequently the message is logged) and thus the more likely it will be * filtered and not written to the output stream; messages with a level of * zero will always be written to the output stream. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void info(int verb, String loc, String msg); /*************************************************************************** * Write a formatted warning message to this message logger. * Warning messages have an implied severity of {@link SEV_WARNING}. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param verb * The verbosity level of the message. * The higher the level, the more verbose the message (i.e., the more * frequently the message is logged) and thus the more likely it will be * filtered and not written to the output stream; messages with a level of * zero will always be written to the output stream. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void warning(int verb, String loc, String msg); /*************************************************************************** * Write a formatted error message to this message logger. * Error messages have an implied severity of {@link SEV_ERROR}. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void error(String loc, String msg); /*************************************************************************** * Write a formatted fatal error message to this message logger. * Fatal error messages have an implied severity of {@link SEV_FATAL}. * *

* Note that this method does not throw any checked exceptions, specifically * java.io.IOException. * * @param loc * The name of the location (typically a thread or class name) from where the * log message originates. This serves as a label to prefix the message with * in the logging output stream. This can be empty ("") or null, in * which case no location is written. * * @param msg * A text message to log. * * @since 1.2, 2003-01-16 */ public void fatal(String loc, String msg); } // End LoggerI.java