1 /* 2 * Copyright 2001-2004 The Apache Software Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 18 package org.apache.commons.logging; 19 20 /** 21 * <p>A simple logging interface abstracting logging APIs. In order to be 22 * instantiated successfully by {@link LogFactory}, classes that implement 23 * this interface must have a constructor that takes a single String 24 * parameter representing the "name" of this Log.</p> 25 * 26 * <p> The six logging levels used by <code>Log</code> are (in order): 27 * <ol> 28 * <li>trace (the least serious)</li> 29 * <li>debug</li> 30 * <li>info</li> 31 * <li>warn</li> 32 * <li>error</li> 33 * <li>fatal (the most serious)</li> 34 * </ol> 35 * The mapping of these log levels to the concepts used by the underlying 36 * logging system is implementation dependent. 37 * The implemention should ensure, though, that this ordering behaves 38 * as expected.</p> 39 * 40 * <p>Performance is often a logging concern. 41 * By examining the appropriate property, 42 * a component can avoid expensive operations (producing information 43 * to be logged).</p> 44 * 45 * <p> For example, 46 * <code><pre> 47 * if (log.isDebugEnabled()) { 48 * ... do something expensive ... 49 * log.debug(theResult); 50 * } 51 * </pre></code> 52 * </p> 53 * 54 * <p>Configuration of the underlying logging system will generally be done 55 * external to the Logging APIs, through whatever mechanism is supported by 56 * that system.</p> 57 * 58 * @author <a href="mailto:sanders@apache.org">Scott Sanders</a> 59 * @author Rod Waldhoff 60 * @version $Id: Log.java 381838 2006-02-28 23:57:11Z skitching $ 61 */ 62 public interface Log { 63 64 65 // ----------------------------------------------------- Logging Properties 66 67 68 /** 69 * <p> Is debug logging currently enabled? </p> 70 * 71 * <p> Call this method to prevent having to perform expensive operations 72 * (for example, <code>String</code> concatenation) 73 * when the log level is more than debug. </p> 74 * 75 * @return true if debug is enabled in the underlying logger. 76 */ isDebugEnabled()77 public boolean isDebugEnabled(); 78 79 80 /** 81 * <p> Is error logging currently enabled? </p> 82 * 83 * <p> Call this method to prevent having to perform expensive operations 84 * (for example, <code>String</code> concatenation) 85 * when the log level is more than error. </p> 86 * 87 * @return true if error is enabled in the underlying logger. 88 */ isErrorEnabled()89 public boolean isErrorEnabled(); 90 91 92 /** 93 * <p> Is fatal logging currently enabled? </p> 94 * 95 * <p> Call this method to prevent having to perform expensive operations 96 * (for example, <code>String</code> concatenation) 97 * when the log level is more than fatal. </p> 98 * 99 * @return true if fatal is enabled in the underlying logger. 100 */ isFatalEnabled()101 public boolean isFatalEnabled(); 102 103 104 /** 105 * <p> Is info logging currently enabled? </p> 106 * 107 * <p> Call this method to prevent having to perform expensive operations 108 * (for example, <code>String</code> concatenation) 109 * when the log level is more than info. </p> 110 * 111 * @return true if info is enabled in the underlying logger. 112 */ isInfoEnabled()113 public boolean isInfoEnabled(); 114 115 116 /** 117 * <p> Is trace logging currently enabled? </p> 118 * 119 * <p> Call this method to prevent having to perform expensive operations 120 * (for example, <code>String</code> concatenation) 121 * when the log level is more than trace. </p> 122 * 123 * @return true if trace is enabled in the underlying logger. 124 */ isTraceEnabled()125 public boolean isTraceEnabled(); 126 127 128 /** 129 * <p> Is warn logging currently enabled? </p> 130 * 131 * <p> Call this method to prevent having to perform expensive operations 132 * (for example, <code>String</code> concatenation) 133 * when the log level is more than warn. </p> 134 * 135 * @return true if warn is enabled in the underlying logger. 136 */ isWarnEnabled()137 public boolean isWarnEnabled(); 138 139 140 // -------------------------------------------------------- Logging Methods 141 142 143 /** 144 * <p> Log a message with trace log level. </p> 145 * 146 * @param message log this message 147 */ trace(Object message)148 public void trace(Object message); 149 150 151 /** 152 * <p> Log an error with trace log level. </p> 153 * 154 * @param message log this message 155 * @param t log this cause 156 */ trace(Object message, Throwable t)157 public void trace(Object message, Throwable t); 158 159 160 /** 161 * <p> Log a message with debug log level. </p> 162 * 163 * @param message log this message 164 */ debug(Object message)165 public void debug(Object message); 166 167 168 /** 169 * <p> Log an error with debug log level. </p> 170 * 171 * @param message log this message 172 * @param t log this cause 173 */ debug(Object message, Throwable t)174 public void debug(Object message, Throwable t); 175 176 177 /** 178 * <p> Log a message with info log level. </p> 179 * 180 * @param message log this message 181 */ info(Object message)182 public void info(Object message); 183 184 185 /** 186 * <p> Log an error with info log level. </p> 187 * 188 * @param message log this message 189 * @param t log this cause 190 */ info(Object message, Throwable t)191 public void info(Object message, Throwable t); 192 193 194 /** 195 * <p> Log a message with warn log level. </p> 196 * 197 * @param message log this message 198 */ warn(Object message)199 public void warn(Object message); 200 201 202 /** 203 * <p> Log an error with warn log level. </p> 204 * 205 * @param message log this message 206 * @param t log this cause 207 */ warn(Object message, Throwable t)208 public void warn(Object message, Throwable t); 209 210 211 /** 212 * <p> Log a message with error log level. </p> 213 * 214 * @param message log this message 215 */ error(Object message)216 public void error(Object message); 217 218 219 /** 220 * <p> Log an error with error log level. </p> 221 * 222 * @param message log this message 223 * @param t log this cause 224 */ error(Object message, Throwable t)225 public void error(Object message, Throwable t); 226 227 228 /** 229 * <p> Log a message with fatal log level. </p> 230 * 231 * @param message log this message 232 */ fatal(Object message)233 public void fatal(Object message); 234 235 236 /** 237 * <p> Log an error with fatal log level. </p> 238 * 239 * @param message log this message 240 * @param t log this cause 241 */ fatal(Object message, Throwable t)242 public void fatal(Object message, Throwable t); 243 244 245 } 246