001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.logging;
019
020 /**
021 * A simple logging interface abstracting logging APIs. In order to be
022 * instantiated successfully by {@link LogFactory}, classes that implement
023 * this interface must have a constructor that takes a single String
024 * parameter representing the "name" of this Log.
025 * <p>
026 * The six logging levels used by <code>Log</code> are (in order):
027 * <ol>
028 * <li>trace (the least serious)</li>
029 * <li>debug</li>
030 * <li>info</li>
031 * <li>warn</li>
032 * <li>error</li>
033 * <li>fatal (the most serious)</li>
034 * </ol>
035 * The mapping of these log levels to the concepts used by the underlying
036 * logging system is implementation dependent.
037 * The implementation should ensure, though, that this ordering behaves
038 * as expected.
039 * <p>
040 * Performance is often a logging concern.
041 * By examining the appropriate property,
042 * a component can avoid expensive operations (producing information
043 * to be logged).
044 * <p>
045 * For example,
046 * <code><pre>
047 * if (log.isDebugEnabled()) {
048 * ... do something expensive ...
049 * log.debug(theResult);
050 * }
051 * </pre></code>
052 * <p>
053 * Configuration of the underlying logging system will generally be done
054 * external to the Logging APIs, through whatever mechanism is supported by
055 * that system.
056 *
057 * @version $Id: Log.html 862526 2013-05-20 17:07:42Z tn $
058 */
059 public interface Log {
060
061 // ----------------------------------------------------- Logging Properties
062
063 /**
064 * Is debug logging currently enabled?
065 * <p>
066 * Call this method to prevent having to perform expensive operations
067 * (for example, <code>String</code> concatenation)
068 * when the log level is more than debug.
069 *
070 * @return true if debug is enabled in the underlying logger.
071 */
072 public boolean isDebugEnabled();
073
074 /**
075 * Is error logging currently enabled?
076 * <p>
077 * Call this method to prevent having to perform expensive operations
078 * (for example, <code>String</code> concatenation)
079 * when the log level is more than error.
080 *
081 * @return true if error is enabled in the underlying logger.
082 */
083 public boolean isErrorEnabled();
084
085 /**
086 * Is fatal logging currently enabled?
087 * <p>
088 * Call this method to prevent having to perform expensive operations
089 * (for example, <code>String</code> concatenation)
090 * when the log level is more than fatal.
091 *
092 * @return true if fatal is enabled in the underlying logger.
093 */
094 public boolean isFatalEnabled();
095
096 /**
097 * Is info logging currently enabled?
098 * <p>
099 * Call this method to prevent having to perform expensive operations
100 * (for example, <code>String</code> concatenation)
101 * when the log level is more than info.
102 *
103 * @return true if info is enabled in the underlying logger.
104 */
105 public boolean isInfoEnabled();
106
107 /**
108 * Is trace logging currently enabled?
109 * <p>
110 * Call this method to prevent having to perform expensive operations
111 * (for example, <code>String</code> concatenation)
112 * when the log level is more than trace.
113 *
114 * @return true if trace is enabled in the underlying logger.
115 */
116 public boolean isTraceEnabled();
117
118 /**
119 * Is warn logging currently enabled?
120 * <p>
121 * Call this method to prevent having to perform expensive operations
122 * (for example, <code>String</code> concatenation)
123 * when the log level is more than warn.
124 *
125 * @return true if warn is enabled in the underlying logger.
126 */
127 public boolean isWarnEnabled();
128
129 // -------------------------------------------------------- Logging Methods
130
131 /**
132 * Log a message with trace log level.
133 *
134 * @param message log this message
135 */
136 public void trace(Object message);
137
138 /**
139 * Log an error with trace log level.
140 *
141 * @param message log this message
142 * @param t log this cause
143 */
144 public void trace(Object message, Throwable t);
145
146 /**
147 * Log a message with debug log level.
148 *
149 * @param message log this message
150 */
151 public void debug(Object message);
152
153 /**
154 * Log an error with debug log level.
155 *
156 * @param message log this message
157 * @param t log this cause
158 */
159 public void debug(Object message, Throwable t);
160
161 /**
162 * Log a message with info log level.
163 *
164 * @param message log this message
165 */
166 public void info(Object message);
167
168 /**
169 * Log an error with info log level.
170 *
171 * @param message log this message
172 * @param t log this cause
173 */
174 public void info(Object message, Throwable t);
175
176 /**
177 * Log a message with warn log level.
178 *
179 * @param message log this message
180 */
181 public void warn(Object message);
182
183 /**
184 * Log an error with warn log level.
185 *
186 * @param message log this message
187 * @param t log this cause
188 */
189 public void warn(Object message, Throwable t);
190
191 /**
192 * Log a message with error log level.
193 *
194 * @param message log this message
195 */
196 public void error(Object message);
197
198 /**
199 * Log an error with error log level.
200 *
201 * @param message log this message
202 * @param t log this cause
203 */
204 public void error(Object message, Throwable t);
205
206 /**
207 * Log a message with fatal log level.
208 *
209 * @param message log this message
210 */
211 public void fatal(Object message);
212
213 /**
214 * Log an error with fatal log level.
215 *
216 * @param message log this message
217 * @param t log this cause
218 */
219 public void fatal(Object message, Throwable t);
220 }