You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Richard Sitze <rs...@us.ibm.com> on 2004/12/09 21:28:30 UTC
[logging] Common Logging 2.0? EnterpriseLog.java
package org.apache.commons.logging;
/**
* <p>An advanced logging interface abstracting logging APIs. This
interface
* extends the simple logging interface decribed by {@link Log}, providing
* the following additional capabilities:</p>
* <ul>
* <li>the ability to capture internationalized data (e.g. translated
messages)
* <li>ability to identify the software capturing the event
* (i.e. class and method name)
* <li>ability to capture the execution of a program by tracing method
entry
* and exit.
* </ul>
* <p>This interface is instantiated using {@link EnterpriseLogFactory}.
The
* classes that implement this interface must have a constructor that
takes
* a single String parameter representing the "name" of this
* <code>EnterpriseLog</code>. Please note that a specific implementation
of
* Commons Logging can choose to support either the simple logging
interface
* (represented by {@link Log}) or the advanced logging interface
(represented
* by this interface). A user of a Common Logging implementation that
supports
* only the simple logging interface will not be able to instantiate a
* <code>EnterpriseLog</code>. Conversely, a user of a Common Logging
* implementation that supports the advanced logging interface will be
able to
* instantiate either a <code>Log</code> or <code>EnterpriseLog</code>.
*
* <p>Configuration of the underlying logging system will generally be
done
* external to the Logging APIs, through whatever mechanism is supported
by
* that system.</p>
*
*/
public interface EnterpriseLog extends Log
{
// ----------------------------------------------------- Logging
Properties
// ----------------------------------------------------- Logging
Methods
/**
* <p> Log a locale-specific (internationalized) error message with
* no message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
*/
public void error(Class clazz,
String method,
String key);
/**
* <p> Log a locale-specific (internationalized) error message with
* one message substitution value. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parm The value to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void error(Class clazz,
String method,
String key,
Object parm);
/**
* <p> Log a locale-specific (internationalized) error message with
* multiple message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parms The list of values to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void error(Class clazz,
String method,
String key,
Object[] parms);
/**
* <p> Log a locale-specific (internationalized) fatal error message
with
* no message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
*/
public void fatal(Class clazz,
String method,
String key);
/**
* <p> Log a locale-specific (internationalized) fatal error message
with
* one message substitution value. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parm The value to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void fatal(Class clazz,
String method,
String key,
Object parm);
/**
* <p> Log a locale-specific (internationalized) fatal error message
with
* multiple message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parms The list of values to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void fatal(Class clazz,
String method,
String key,
Object[] parms);
/**
* <p> Log a locale-specific (internationalized) informational message
with
* no message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
*/
public void info(Class clazz,
String method,
String key);
/**
* <p> Log a locale-specific (internationalized) informational message
with
* one message substitution value. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parm The value to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void info(Class clazz,
String method,
String key,
Object parm);
/**
* <p> Log a locale-specific (internationalized) informational message
with
* multiple message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parms The list of values to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void info(Class clazz,
String method,
String key,
Object[] parms);
/**
* <p> Log a locale-specific (internationalized) warning message with
* no message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
*/
public void warn(Class clazz,
String method,
String key);
/**
* <p> Log a locale-specific (internationalized) warning message with
* one message substitution value. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parm The value to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void warn(Class clazz,
String method,
String key,
Object parm);
/**
* <p> Log a locale-specific (internationalized) warning message with
* multiple message substitution values. </p>
*
* @param clazz The class containing the method
* @param method The name of the method logging the message
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle))
* @param parms The list of values to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void warn(Class clazz,
String method,
String key,
Object[] parms);
// ----------------------------------------------- Message Formatting
Methods
/**
* <p> Format a locale-specific (internationalized) message with
* no message substitution values. The format of the returned message
* will match the format used by the underlying logging
implementation.</p>
*
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
*/
public void formatMessage(String key);
/**
* <p> Format a locale-specific (internationalized) message with
* one message substitution value. The format of the returned message
* will match the format used by the underlying logging
implementation.</p>
*
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
* @param parm The value to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void formatMessage(String key,
Object parm);
/**
* <p> Format a locale-specific (internationalized) message with
* multiple message substitution values. The format of the returned
message
* will match the format used by the underlying logging
implementation.</p>
*
* @param key The key used to retrieve the message text
* (e.g. from a Java ResourceBundle (@link
ResourceBundle)
* @param parms The list of values to insert into the message text
* (e.g. when formatting a Java massage (@link
MessageFormat))
*/
public void formatMessage(String key,
Object[] parms);
// ----------------------------------------------------- Tracing
Methods
/**
* <p> Log entering a method, with no input arguments. </p>
*
* @param clazz The class containing the method
* @param method The name of the method
* @param message Optional text that provides more detail,
* may be null
*/
public void entry(Class clazz,
String method,
Object message);
/**
* <p> Log entering a method, with one input argument. </p>
*
* @param clazz The class containing the method
* @param method The name of the method
* @param inputArg The input argument
* @param message Optional text that provides more detail,
* may be null
*/
public void entry(Class clazz,
String method,
Object inputArg,
Object message);
/**
* <p> Log entering a method, with multiple input arguments. </p>
*
* @param clazz The class containing the method
* @param method The name of the method
* @param inputArgs The list of input arguments
* @param message Optional text that provides more detail,
* may be null
*/
public void entry(Class clazz,
String method,
Object[] inputArgs,
Object message);
/**
* <p> Log the normal completion of a method, along with any
* returned value. </p>
*
* @param clazz The class containing the method
* @param method The name of the method
* @param result The returned value (if any) from the method
* @param message Optional text that provides more detail,
* may be null. If there are multiple returns
* in the method, this might indicate which one
* (the location, in the method, of the return)
*/
public void exit(Class clazz,
String method,
Object result,
Object message);
/**
* <p> Log the abnormal (failed) completion of a method, along with
the
* thrown exception. </p>
*
* @param clazz The class containing the method
* @param method The name of the method
* @param t The thrown exception
* @param message Optional text that provides more detail,
* may be null. If there are multiple throws
* in the method, this might indicate which one
* (the location, in the method, of the throw -
* note that debug information in the class may
* not include line # info)
*/
public void exit(Class clazz,
String method,
Throwable t,
Object message);
}
*******************************************
Richard A. Sitze
IBM WebSphere WebServices Development
---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org