commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Richard Sitze <rsi...@us.ibm.com>
Subject [logging] Common Logging 2.0? EnterpriseLog.java
Date Thu, 09 Dec 2004 20:28:30 GMT
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


Mime
View raw message