/* Copyright (c) 2001, 2002 Oracle Corporation. All Rights Reserved */
package oracle.portal.log;

import java.util.Map;


/**
 * A <code>Logger</code> object logs messages. These messages could detail
 * reasons why <code>Exceptions</code> are thrown, or detail debugging
 * information.
 */
abstract public class Logger
{

    /**
     * Performs per-thread initialization of a Logger.
     *
     * @param msgContext the {@link MessageContext} object to be used to format 
     *                   log messages
     */
    public void initCurrentThread(MessageContext msgContext)
    {
        // this method not abstract for backwards compatibility
    }


    /**
     * Performs per-thread clean-up
     */
    public void resetCurrentThread()
    {
        // this method not abstract for backwards compatibility
    }


    /**
     * frees any resources the Logger might be using so the web application
     * can shut down and re-started cleanly.
     *
     * this method should release any resources and release any objects it
     * might be holding references to - especially those relating to the 
     * Servlet engine such as the ServletContext
     *
     * This method should NEVER throw ANY exceptions
     */
    abstract public void destroy();

    
    /**
     * Logs the specified message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message message to log.
     */
    abstract public void log(String message);


    /**
     * Logs the specified message and Throwable.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message explanatory message.
     * @param throwable a <code>Throwable</code> exception.
     */
    abstract public void log(String message, Throwable throwable);

    
    /**
     * Logs the specified error message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message error message to be logged.
     */
    abstract public void config(String message);


    /**
     * Logs the specified error message and Throwable.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message error message.
     * @param throwable a <code>Throwable</code> exception.
     */
    abstract public void config(String message, Throwable throwable);

    
    /**
     * Logs the specified error message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message error message to be logged.
     */
    abstract public void severe(String message);


    /**
     * Logs the specified error message and Throwable.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message error message.
     * @param throwable a <code>Throwable</code> exception.
     */
    abstract public void severe(String message, Throwable throwable);

    
    /**
     * Logs the given warning message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message warning message to log.
     */
    abstract public void warning(String message);


    /**
     * Logs the specified warning message and Throwable.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message explanatory message.
     * @param throwable a <code>Throwable</code> exception.
     */
    abstract public void warning(String message, Throwable throwable);

    
    /**
     * Logs the specified warning message and Throwable.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message explanatory message.
     * @param throwable a <code>Throwable</code> exception.
     */
    abstract public void throwing(String message, Throwable throwable);

    
    /**
     * Logs the given informational message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message informational message to log.
     */
    abstract public void info(String message);

    
    /**
     * Logs the given performance related message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message performance related message to log.
     */
    abstract public void perf(String message);

    
    /**
     * Logs the specified debug message.
     *
     * This method should be coded with a try/catch block surrounding the 
     * logging code. The try/catch block should catch and swallow ANY and ALL
     * Throwables.
     *
     * @param message debug message to log.
     */
    abstract public void debug(String message);


    /**
     * Returns true if Configuration level logging is enabled. Otherwise false.
     *
     * @return true if configuration level logging is enabled. Otherwise false.
     */
    public boolean isConfigEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if Severe error level logging is enabled. Otherwise false.
     *
     * @return true if severe error level logging is enabled. Otherwise false.
     */
    public boolean isSevereEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if Warning level logging is enabled. Otherwise false.
     *
     * @return true if warning level logging is enabled. Otherwise false.
     */
    public boolean isWarningEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if exception level logging is enabled. Otherwise false.
     *
     * @return true if exception level logging is enabled. Otherwise false.
     */
    public boolean isThrowingEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if information level logging is enabled. Otherwise false.
     *
     * @return true if information level logging is enabled. Otherwise false.
     */
    public boolean isInfoEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if Performance level logging is enabled. Otherwise false.
     *
     * @return true if performance level logging is enabled. Otherwise false.
     */
    public boolean isPerfEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }

    
    /**
     * Returns true if debug level logging is enabled. Otherwise false.
     *
     * @return true if debug level logging is enabled. Otherwise false.
     */
    public boolean isDebugEnabled()
    {
        // default implementation provided for backwards compatibility. We
        // have to assume logging is turned on otherwise any code written to
        // use the extended interface, but an older implementation would never
        // log anything. 
        return true;
    }
}
