001    /*
002     * HapiLog.java
003     * 
004     * Created on May 7, 2003 at 3:53:44 PM
005     */
006    package ca.uhn.log;
007    
008    import org.apache.commons.logging.Log;
009    
010    /**
011     * A logging interface that enhances the <code> Log </code>
012     * interface with ancillary method to easy up the log messages generation
013     * by adding MessageFormat like functionality.
014     * 
015     * Instantiate using {@link HapiLogFactory#getLog( Class clazz)}
016     * or {@link HapiLogFactory#getLog( String name)}
017     * 
018     * <pre>
019     *  USASE PATTERN:
020     *  (look at the jakarta-commons-logging and log4j documentation first)
021     * 
022     *      ...
023     *      import ca.uhn.log.*;
024     *      ...
025     *      class A {
026     *          private static final HapiLog log = HapiLogFactory.getHapiLog( A.class );
027     * 
028     *          public boolean methodA( Object param1 ) {
029     *              boolean retVal = true;
030     * 
031     *              //log debug messages (to be printed only when the debug mode is specified
032     *              //in the configuration file)
033     *              log.debug( "param1 = " + param1 );
034     *              
035     *              Object copy = null;
036     *              try {
037     *                  copy = param1.clone();
038     *              }
039     *              catch( CloneNotSupportedException e ) {
040     *                  //log the error
041     *                  log.error( "param1 must be cloneable", e );
042     *                  retVal = false;
043     *              }
044     * 
045     *              log.debug( "retVal = " + retVal );
046     *              return retVal;
047     *          }
048     * 
049     *          ...
050     * 
051     *      }
052     * </pre>
053     * 
054     * @author <a href="mailto:alexei.guevara@uhn.on.ca">Alexei Guevara</a>
055     * @version $Revision: 1.1 $ updated on $Date: 2007/02/19 02:24:52 $ by $Author: jamesagnew $
056     */
057    public interface HapiLog extends Log {
058        
059        /**
060         * 
061         * @see MessageFormat#format( ... )
062         * 
063         * @param msgPattern
064         * @param values
065         * @param e
066         */
067        public void debug( String msgPattern, Object[] values, Throwable e );
068    
069    
070    }