001package org.apache.commons.jcs3.log;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one or more
005 * contributor license agreements. See the NOTICE file distributed with
006 * this work for additional information regarding copyright ownership.
007 * The ASF licenses this file to You under the Apache license, Version 2.0
008 * (the "License"); you may not use this file except in compliance with
009 * the License. You may obtain a copy of the License at
010 *
011 *      http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the license for the specific language governing permissions and
017 * limitations under the license.
018 */
019
020import java.util.function.Supplier;
021
022/**
023 * This is a borrowed and stripped-down version of the log4j2 Logger interface.
024 * All logging operations, except configuration, are done through this interface.
025 *
026 * <p>
027 * The canonical way to obtain a Logger for a class is through {@link LogManager#getLog(String)}}.
028 * Typically, each class should get its own Log named after its fully qualified class name
029 * </p>
030 *
031 * <pre>
032 * public class MyClass {
033 *     private static final Log log = LogManager.getLog(MyClass.class);
034 *     // ...
035 * }
036 * </pre>
037 */
038public interface Log
039{
040    /**
041     * Logs a message object with the DEBUG level.
042     *
043     * @param message the message string to log.
044     */
045    void debug(String message);
046
047    /**
048     * Logs a message object with the DEBUG level.
049     *
050     * @param message the message object to log.
051     */
052    void debug(Object message);
053
054    /**
055     * Logs a message with parameters at the DEBUG level.
056     *
057     * @param message the message to log; the format depends on the message factory.
058     * @param params parameters to the message.
059     */
060    void debug(String message, Object... params);
061
062    /**
063     * Logs a message with parameters which are only to be constructed if the
064     * logging level is the DEBUG level.
065     *
066     * @param message the message to log; the format depends on the message factory.
067     * @param paramSuppliers An array of functions, which when called, produce
068     *        the desired log message parameters.
069     */
070    void debug(String message, Supplier<?>... paramSuppliers);
071
072    /**
073     * Logs a message at the DEBUG level including the stack trace of the {@link Throwable}
074     * <code>t</code> passed as parameter.
075     *
076     * @param message the message to log.
077     * @param t the exception to log, including its stack trace.
078     */
079    void debug(String message, Throwable t);
080
081    /**
082     * Logs a message object with the ERROR level.
083     *
084     * @param message the message string to log.
085     */
086    void error(String message);
087
088    /**
089     * Logs a message object with the ERROR level.
090     *
091     * @param message the message object to log.
092     */
093    void error(Object message);
094
095    /**
096     * Logs a message with parameters at the ERROR level.
097     *
098     * @param message the message to log; the format depends on the message factory.
099     * @param params parameters to the message.
100     */
101    void error(String message, Object... params);
102
103    /**
104     * Logs a message with parameters which are only to be constructed if the
105     * logging level is the ERROR level.
106     *
107     * @param message the message to log; the format depends on the message factory.
108     * @param paramSuppliers An array of functions, which when called, produce
109     *        the desired log message parameters.
110     */
111    void error(String message, Supplier<?>... paramSuppliers);
112
113    /**
114     * Logs a message at the ERROR level including the stack trace of the {@link Throwable}
115     * <code>t</code> passed as parameter.
116     *
117     * @param message the message object to log.
118     * @param t the exception to log, including its stack trace.
119     */
120    void error(String message, Throwable t);
121
122    /**
123     * Logs a message object with the FATAL level.
124     *
125     * @param message the message string to log.
126     */
127    void fatal(String message);
128
129    /**
130     * Logs a message object with the FATAL level.
131     *
132     * @param message the message object to log.
133     */
134    void fatal(Object message);
135
136    /**
137     * Logs a message with parameters at the FATAL level.
138     *
139     * @param message the message to log; the format depends on the message factory.
140     * @param params parameters to the message.
141     */
142    void fatal(String message, Object... params);
143
144    /**
145     * Logs a message with parameters which are only to be constructed if the
146     * logging level is the FATAL level.
147     *
148     * @param message the message to log; the format depends on the message factory.
149     * @param paramSuppliers An array of functions, which when called, produce
150     *        the desired log message parameters.
151     */
152    void fatal(String message, Supplier<?>... paramSuppliers);
153
154    /**
155     * Logs a message at the FATAL level including the stack trace of the {@link Throwable}
156     * <code>t</code> passed as parameter.
157     *
158     * @param message the message object to log.
159     * @param t the exception to log, including its stack trace.
160     */
161    void fatal(String message, Throwable t);
162
163    /**
164     * Gets the logger name.
165     *
166     * @return the logger name.
167     */
168    String getName();
169
170    /**
171     * Logs a message object with the INFO level.
172     *
173     * @param message the message string to log.
174     */
175    void info(String message);
176
177    /**
178     * Logs a message object with the INFO level.
179     *
180     * @param message the message object to log.
181     */
182    void info(Object message);
183
184    /**
185     * Logs a message with parameters at the INFO level.
186     *
187     * @param message the message to log; the format depends on the message factory.
188     * @param params parameters to the message.
189     */
190    void info(String message, Object... params);
191
192    /**
193     * Logs a message with parameters which are only to be constructed if the
194     * logging level is the INFO level.
195     *
196     * @param message the message to log; the format depends on the message factory.
197     * @param paramSuppliers An array of functions, which when called, produce
198     *        the desired log message parameters.
199     */
200    void info(String message, Supplier<?>... paramSuppliers);
201
202    /**
203     * Logs a message at the INFO level including the stack trace of the {@link Throwable}
204     * <code>t</code> passed as parameter.
205     *
206     * @param message the message object to log.
207     * @param t the exception to log, including its stack trace.
208     */
209    void info(String message, Throwable t);
210
211    /**
212     * Checks whether this Logger is enabled for the DEBUG Level.
213     *
214     * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false}
215     *         otherwise.
216     */
217    boolean isDebugEnabled();
218
219    /**
220     * Checks whether this Logger is enabled for the ERROR Level.
221     *
222     * @return boolean - {@code true} if this Logger is enabled for level ERROR, {@code false}
223     *         otherwise.
224     */
225    boolean isErrorEnabled();
226
227    /**
228     * Checks whether this Logger is enabled for the FATAL Level.
229     *
230     * @return boolean - {@code true} if this Logger is enabled for level FATAL, {@code false}
231     *         otherwise.
232     */
233    boolean isFatalEnabled();
234
235    /**
236     * Checks whether this Logger is enabled for the INFO Level.
237     *
238     * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false}
239     *         otherwise.
240     */
241    boolean isInfoEnabled();
242
243    /**
244     * Checks whether this Logger is enabled for the TRACE level.
245     *
246     * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false}
247     *         otherwise.
248     */
249    boolean isTraceEnabled();
250
251    /**
252     * Checks whether this Logger is enabled for the WARN Level.
253     *
254     * @return boolean - {@code true} if this Logger is enabled for level WARN, {@code false}
255     *         otherwise.
256     */
257    boolean isWarnEnabled();
258
259    /**
260     * Logs a message object with the TRACE level.
261     *
262     * @param message the message string to log.
263     */
264    void trace(String message);
265
266    /**
267     * Logs a message object with the TRACE level.
268     *
269     * @param message the message object to log.
270     */
271    void trace(Object message);
272
273    /**
274     * Logs a message with parameters at the TRACE level.
275     *
276     * @param message the message to log; the format depends on the message factory.
277     * @param params parameters to the message.
278     */
279    void trace(String message, Object... params);
280
281    /**
282     * Logs a message with parameters which are only to be constructed if the
283     * logging level is the TRACE level.
284     *
285     * @param message the message to log; the format depends on the message factory.
286     * @param paramSuppliers An array of functions, which when called, produce
287     *        the desired log message parameters.
288     */
289    void trace(String message, Supplier<?>... paramSuppliers);
290
291    /**
292     * Logs a message at the TRACE level including the stack trace of the {@link Throwable}
293     * <code>t</code> passed as parameter.
294     *
295     * @param message the message object to log.
296     * @param t the exception to log, including its stack trace.
297     * @see #debug(String)
298     */
299    void trace(String message, Throwable t);
300
301    /**
302     * Logs a message object with the WARN level.
303     *
304     * @param message the message string to log.
305     */
306    void warn(String message);
307
308    /**
309     * Logs a message object with the WARN level.
310     *
311     * @param message the message object to log.
312     */
313    void warn(Object message);
314
315    /**
316     * Logs a message with parameters at the WARN level.
317     *
318     * @param message the message to log; the format depends on the message factory.
319     * @param params parameters to the message.
320     */
321    void warn(String message, Object... params);
322
323    /**
324     * Logs a message with parameters which are only to be constructed if the
325     * logging level is the WARN level.
326     *
327     * @param message the message to log; the format depends on the message factory.
328     * @param paramSuppliers An array of functions, which when called, produce
329     *        the desired log message parameters.
330     */
331    void warn(String message, Supplier<?>... paramSuppliers);
332
333    /**
334     * Logs a message at the WARN level including the stack trace of the {@link Throwable}
335     * <code>t</code> passed as parameter.
336     *
337     * @param message the message object to log.
338     * @param t the exception to log, including its stack trace.
339     */
340    void warn(String message, Throwable t);
341}