/*
* Copyright (c) 2009, 2012 IBM Corp.
*
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Dave Locke - initial API and implementation and/or initial documentation
*/
package org.eclipse.paho.client.mqttv3.internal.logging;
/**
* A Logger object is used to send log and trace messages to the platform
* specific logging implementation. Loggers are named, using a hierarchical
* dot-separated name-space.
* Logger names can be arbitrary strings, but they should normally be based on
* the component or the package name of the logged component
*
* Logger objects may be obtained by calls on one of the getLogger factory
* methods. These will either create a new Logger or return a suitable existing
* Logger.
*
* <p>
* The int levels define a set of standard logging levels that can be used to
* control logging output. The logging levels are ordered and are specified by
* ordered integers. Enabling logging at a given level also enables logging at
* all higher levels.
* <p>
* Clients should use the the convenience methods such as severe() and fine() or
* one of the predefined level constants such as Logger.SEVERE and Logger.FINE
* with the appropriate log(int level...) or trace(int level...) methods.
* <p>
* The levels in descending order are:
* <ul>
* <li>SEVERE (log - highest value)</li>
* <li>WARNING (log)</li>
* <li>INFO (log)</li>
* <li>CONFIG (log)</li>
* <li>FINE (trace)</li>
* <li>FINER (trace)</li>
* <li>FINEST (trace - lowest value)</li>
* </ul>
* <p>
*/
public interface Logger {
/**
* SEVERE is a message level indicating a serious failure.
* <p>
* In general SEVERE messages should describe events that are of
* considerable importance and which will prevent normal program execution.
* They should be reasonably intelligible to end users and to system
* administrators.
*/
public static final int SEVERE = 1;
/**
* WARNING is a message level indicating a potential problem.
* <p>
* In general WARNING messages should describe events that will be of
* interest to end users or system managers, or which indicate potential
* problems.
*/
public static final int WARNING = 2;
/**
* INFO is a message level for informational messages.
* <p>
* Typically INFO messages will be written to the console or its equivalent.
* So the INFO level should only be used for reasonably significant messages
* that will make sense to end users and system admins.
*/
public static final int INFO = 3;
/**
* CONFIG is a message level for static configuration messages.
* <p>
* CONFIG messages are intended to provide a variety of static configuration
* information, to assist in debugging problems that may be associated with
* particular configurations. For example, CONFIG message might include the
* CPU type, the graphics depth, the GUI look-and-feel, etc.
*/
public static final int CONFIG = 4;
/**
* FINE is a message level providing tracing information.
* <p>
* All of FINE, FINER, and FINEST are intended for relatively detailed
* tracing. The exact meaning of the three levels will vary between
* subsystems, but in general, FINEST should be used for the most voluminous
* detailed output, FINER for somewhat less detailed output, and FINE for
* the lowest volume (and most important) messages.
* <p>
* In general the FINE level should be used for information that will be
* broadly interesting to developers who do not have a specialized interest
* in the specific subsystem.
* <p>
* FINE messages might include things like minor (recoverable) failures.
* Issues indicating potential performance problems are also worth logging
* as FINE.
*/
public static final int FINE = 5;
/**
* FINER indicates a fairly detailed tracing message. By default logging
* calls for entering, returning, or throwing an exception are traced at
* this level.
*/
public static final int FINER = 6;
/**
* FINEST indicates a highly detailed tracing message.
*/
public static final int FINEST = 7;
/**
* Check if a message of the given level would actually be logged by this
* logger. This check is based on the Loggers effective level, which may be
* inherited from its parent.
*
* @param level
* a message logging level.
* @return true if the given message level is currently being logged.
*/
public boolean isLoggable(int level);
/**
* Log a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used.
*/
public void severe(String sourceClass, String sourceMethod, String msg);
/**
* Log a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void severe(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Log a message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @param thrown
* Throwable associated with log message.
*/
public void severe(String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown);
/**
* Log a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used.
*/
public void warning(String sourceClass, String sourceMethod, String msg);
/**
* Log a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void warning(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Log a message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @param thrown
* Throwable associated with log message.
*/
public void warning(String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown);
/**
* Log a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used.
*/
public void info(String sourceClass, String sourceMethod, String msg);
/**
* Log a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void info(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Log a message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @param thrown
* Throwable associated with log message.
*/
public void info(String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown);
/**
* Log a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used.
*/
public void config(String sourceClass, String sourceMethod, String msg);
/**
* Log a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void config(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Log a message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @param thrown
* Throwable associated with log message.
*/
public void config(String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown);
/**
* Trace a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used.
*/
public void fine(String sourceClass, String sourceMethod, String msg);
/**
* Trace a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used. The
* formatter uses java.text.MessageFormat style formatting to
* format parameters, so for example a format string "{0} {1}"
* would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void fine(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Trace a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used.
*/
public void finer(String sourceClass, String sourceMethod, String msg);
/**
* Trace a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used. The
* formatter uses java.text.MessageFormat style formatting to
* format parameters, so for example a format string "{0} {1}"
* would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void finer(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Trace a message, specifying source class and method, if the logger is
* currently enabled for the given message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used.
*/
public void finest(String sourceClass, String sourceMethod, String msg);
/**
* Trace a message, specifying source class and method, with an array of
* object arguments, if the logger is currently enabled for the given
* message level.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used. The
* formatter uses java.text.MessageFormat style formatting to
* format parameters, so for example a format string "{0} {1}"
* would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
*/
public void finest(String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Log a message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param level
* One of the message level identifiers, e.g. SEVERE.
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message, may be null.
* @param thrown
* Throwable associated with log message.
*/
public void log(int level, String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown);
/**
* Log a trace message, specifying source class and method, with an array of
* object arguments and a throwable, if the logger is currently enabled for
* the given message level.
*
* @param level
* One of the message level identifiers, e.g. SEVERE.
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message catalog for the message or the actual
* message itself. During formatting, if the logger has a mapping
* for the msg string, then the msg string is replaced by the
* value. Otherwise the original msg string is used. The
* formatter uses java.text.MessageFormat style formatting to
* format parameters, so for example a format string "{0} {1}"
* would format two inserts into the message.
* @param inserts
* Array of parameters to the message, may be null.
*/
public void trace(int level, String sourceClass, String sourceMethod, String msg, Object[] inserts);
/**
* Generate an FFDC.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @param thrown
* Throwable associated with log message.
* @param fatal
* True if the FFDC handler should shutdown/restart the component
* that issued the FFDC.
*/
public void ffdc(String sourceClass, String sourceMethod, String msg, Object[] inserts, Throwable thrown, boolean fatal);
/**
* Generate an FFDC.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param thrown
* Throwable associated with log message.
* @param fatal
* True if the FFDC handler should shutdown/restart the component
* that issued the FFDC.
*/
public void ffdc(String sourceClass, String sourceMethod, Throwable thrown, boolean fatal);
/**
* Generate an FFDC.
*
* @param sourceClass
* Name of class that issued the logging request.
* @param sourceMethod
* Name of method that issued the logging request.
* @param theThread
* The Thread which caused the problem. If that is the current
* thread, use the method without a Thread: @see
* {@link #ffdc(String sourceClass, String sourceMethod, Throwable thrown, boolean fatal)}.
* @param thrown
* Throwable associated with log message.
* @param fatal
* True if the FFDC handler should shutdown/restart the component
* that issued the FFDC.
*/
public void ffdc(String sourceClass, String sourceMethod, Thread theThread, Throwable thrown, boolean fatal);
/**
* Format a log message without causing it to be written to the log.
*
* @param msg
* The key in the message localization catalog for the message or
* the actual message itself. During formatting, if the logger
* has a mapping for the msg string, then the msg string is
* replaced by the localized value. Otherwise the original msg
* string is used. The formatter uses java.text.MessageFormat
* style formatting to format parameters, so for example a format
* string "{0} {1}" would format two inserts into the message.
* @param inserts
* Array of parameters to the message.
* @return The formatted message for the current locale.
*/
public String formatMessage(String msg, Object[] inserts);
}