1054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu/* 2054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * Copyright 2001-2004 The Apache Software Foundation. 37ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 4054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * Licensed under the Apache License, Version 2.0 (the "License"); 5054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * you may not use this file except in compliance with the License. 6054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * You may obtain a copy of the License at 77ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 8054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * http://www.apache.org/licenses/LICENSE-2.0 97ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu * 10054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * Unless required by applicable law or agreed to in writing, software 11054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * distributed under the License is distributed on an "AS IS" BASIS, 12054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * See the License for the specific language governing permissions and 14054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu * limitations under the License. 157ba0605dc97fb81bde8311510d27b3ccba170008Ceki Gulcu */ 16054ed393bd95a6f7c34398accc5cefe36fae8989Ceki Gulcu 172230e3843573f99392572d238d34e935b8705c78Ceki Gulcupackage org.apache.commons.logging; 182230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 192230e3843573f99392572d238d34e935b8705c78Ceki Gulcu/** 209f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p>A simple logging interface abstracting logging APIs. In order to be 212230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * instantiated successfully by {@link LogFactory}, classes that implement 222230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * this interface must have a constructor that takes a single String 232230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * parameter representing the "name" of this Log.</p> 242230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 259f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> The six logging levels used by <code>Log</code> are (in order): 262230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <ol> 272230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>trace (the least serious)</li> 282230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>debug</li> 292230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>info</li> 302230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>warn</li> 312230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>error</li> 322230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <li>fatal (the most serious)</li> 332230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * </ol> 342230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * The mapping of these log levels to the concepts used by the underlying 359f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * logging system is implementation dependent. 36272ceb2f051b02650a524eb730119d8d68872ec6Ceki Gulcu * The implementation should ensure, though, that this ordering behaves 372230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * as expected.</p> 382230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 399f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p>Performance is often a logging concern. 402230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * By examining the appropriate property, 412230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * a component can avoid expensive operations (producing information 422230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * to be logged).</p> 432230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 442230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> For example, 452230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <code><pre> 462230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * if (log.isDebugEnabled()) { 472230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * ... do something expensive ... 482230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * log.debug(theResult); 492230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * } 502230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * </pre></code> 512230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * </p> 522230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 539f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p>Configuration of the underlying logging system will generally be done 542230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * external to the Logging APIs, through whatever mechanism is supported by 552230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * that system.</p> 562230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 57272ceb2f051b02650a524eb730119d8d68872ec6Ceki Gulcu * <p style="color: #E40; font-weight: bold;">Please note that this interface is identical to that found in JCL 1.1.1.</p> 582230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 592230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @author <a href="mailto:sanders@apache.org">Scott Sanders</a> 602230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @author Rod Waldhoff 612230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @version $Id: Log.java,v 1.19 2004/06/06 21:16:04 rdonkin Exp $ 622230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 632230e3843573f99392572d238d34e935b8705c78Ceki Gulcupublic interface Log { 642230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 652230e3843573f99392572d238d34e935b8705c78Ceki Gulcu // ----------------------------------------------------- Logging Properties 662230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 672230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 689f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is debug logging currently enabled? </p> 692230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 702230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 712230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 722230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than debug. </p> 732230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 742230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isDebugEnabled(); 752230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 762230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 779f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is error logging currently enabled? </p> 782230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 792230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 802230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 812230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than error. </p> 822230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 832230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isErrorEnabled(); 842230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 852230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 869f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is fatal logging currently enabled? </p> 872230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 882230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 892230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 902230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than fatal. </p> 912230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 922230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isFatalEnabled(); 932230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 942230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 959f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is info logging currently enabled? </p> 962230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 972230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 982230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 992230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than info. </p> 1003b040e36ff55b7e98fe16e09a4c813d3dab524d6Ceki Gulcu * 1013b040e36ff55b7e98fe16e09a4c813d3dab524d6Ceki Gulcu * @return true if info enabled, false otherwise 1022230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1032230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isInfoEnabled(); 1042230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1052230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1069f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is trace logging currently enabled? </p> 1072230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1082230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 1092230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 1102230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than trace. </p> 1113b040e36ff55b7e98fe16e09a4c813d3dab524d6Ceki Gulcu * 1123b040e36ff55b7e98fe16e09a4c813d3dab524d6Ceki Gulcu * @return true if trace enabled, false otherwise 1132230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1142230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isTraceEnabled(); 1152230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1162230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1179f10490a05f7344f4b3ef657e8991f5d51934e2fCeki Gulcu * <p> Is warn logging currently enabled? </p> 1182230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1192230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Call this method to prevent having to perform expensive operations 1202230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * (for example, <code>String</code> concatenation) 1212230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * when the log level is more than warn. </p> 1222230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1232230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public boolean isWarnEnabled(); 1242230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1252230e3843573f99392572d238d34e935b8705c78Ceki Gulcu // -------------------------------------------------------- Logging Methods 1262230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1272230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1282230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with trace log level. </p> 1292230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1302230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1312230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1322230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void trace(Object message); 1332230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1342230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1352230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with trace log level. </p> 1362230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1372230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1382230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 1392230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1402230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void trace(Object message, Throwable t); 1412230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1422230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1432230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with debug log level. </p> 1442230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1452230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1462230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1472230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void debug(Object message); 1482230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1492230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1502230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with debug log level. </p> 1512230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1522230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1532230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 1542230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1552230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void debug(Object message, Throwable t); 1562230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1572230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1582230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with info log level. </p> 1592230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1602230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1612230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1622230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void info(Object message); 1632230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1642230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1652230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with info log level. </p> 1662230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1672230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1682230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 1692230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1702230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void info(Object message, Throwable t); 1712230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1722230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1732230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with warn log level. </p> 1742230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1752230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1762230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1772230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void warn(Object message); 1782230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1792230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1802230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with warn log level. </p> 1812230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1822230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1832230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 1842230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1852230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void warn(Object message, Throwable t); 1862230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1872230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1882230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with error log level. </p> 1892230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1902230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1912230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 1922230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void error(Object message); 1932230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 1942230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 1952230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with error log level. </p> 1962230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 1972230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 1982230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 1992230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 2002230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void error(Object message, Throwable t); 2012230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 2022230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 2032230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log a message with fatal log level. </p> 2042230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 2052230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 2062230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 2072230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void fatal(Object message); 2082230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 2092230e3843573f99392572d238d34e935b8705c78Ceki Gulcu /** 2102230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * <p> Log an error with fatal log level. </p> 2112230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * 2122230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param message log this message 2132230e3843573f99392572d238d34e935b8705c78Ceki Gulcu * @param t log this cause 2142230e3843573f99392572d238d34e935b8705c78Ceki Gulcu */ 2152230e3843573f99392572d238d34e935b8705c78Ceki Gulcu public void fatal(Object message, Throwable t); 2162230e3843573f99392572d238d34e935b8705c78Ceki Gulcu 2172230e3843573f99392572d238d34e935b8705c78Ceki Gulcu} 218