View Javadoc
1   /*
2    * Copyright 2012 The Netty Project
3    *
4    * The Netty Project licenses this file to you under the Apache License,
5    * version 2.0 (the "License"); you may not use this file except in compliance
6    * with the License. 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, WITHOUT
12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13   * License for the specific language governing permissions and limitations
14   * under the License.
15   */
16  /**
17   * Copyright (c) 2004-2011 QOS.ch
18   * All rights reserved.
19   *
20   * Permission is hereby granted, free  of charge, to any person obtaining
21   * a  copy  of this  software  and  associated  documentation files  (the
22   * "Software"), to  deal in  the Software without  restriction, including
23   * without limitation  the rights to  use, copy, modify,  merge, publish,
24   * distribute,  sublicense, and/or sell  copies of  the Software,  and to
25   * permit persons to whom the Software  is furnished to do so, subject to
26   * the following conditions:
27   *
28   * The  above  copyright  notice  and  this permission  notice  shall  be
29   * included in all copies or substantial portions of the Software.
30   *
31   * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
32   * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
33   * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
34   * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
35   * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
36   * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
37   * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
38   *
39   */
40  package io.netty.util.internal.logging;
41  
42  /**
43   * <em>Internal-use-only</em> logger used by Netty.  <strong>DO NOT</strong>
44   * access this class outside of Netty.
45   */
46  public interface InternalLogger {
47  
48      /**
49       * Return the name of this {@link InternalLogger} instance.
50       *
51       * @return name of this logger instance
52       */
53      String name();
54  
55      /**
56       * Is the logger instance enabled for the TRACE level?
57       *
58       * @return True if this Logger is enabled for the TRACE level,
59       *         false otherwise.
60       */
61      boolean isTraceEnabled();
62  
63      /**
64       * Log a message at the TRACE level.
65       *
66       * @param msg the message string to be logged
67       */
68      void trace(String msg);
69  
70      /**
71       * Log a message at the TRACE level according to the specified format
72       * and argument.
73       * <p/>
74       * <p>This form avoids superfluous object creation when the logger
75       * is disabled for the TRACE level. </p>
76       *
77       * @param format the format string
78       * @param arg    the argument
79       */
80      void trace(String format, Object arg);
81  
82      /**
83       * Log a message at the TRACE level according to the specified format
84       * and arguments.
85       * <p/>
86       * <p>This form avoids superfluous object creation when the logger
87       * is disabled for the TRACE level. </p>
88       *
89       * @param format the format string
90       * @param argA   the first argument
91       * @param argB   the second argument
92       */
93      void trace(String format, Object argA, Object argB);
94  
95      /**
96       * Log a message at the TRACE level according to the specified format
97       * and arguments.
98       * <p/>
99       * <p>This form avoids superfluous string concatenation when the logger
100      * is disabled for the TRACE level. However, this variant incurs the hidden
101      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
102      * even if this logger is disabled for TRACE. The variants taking {@link #trace(String, Object) one} and
103      * {@link #trace(String, Object, Object) two} arguments exist solely in order to avoid this hidden cost.</p>
104      *
105      * @param format    the format string
106      * @param arguments a list of 3 or more arguments
107      */
108     void trace(String format, Object... arguments);
109 
110     /**
111      * Log an exception (throwable) at the TRACE level with an
112      * accompanying message.
113      *
114      * @param msg the message accompanying the exception
115      * @param t   the exception (throwable) to log
116      */
117     void trace(String msg, Throwable t);
118 
119     /**
120      * Is the logger instance enabled for the DEBUG level?
121      *
122      * @return True if this Logger is enabled for the DEBUG level,
123      *         false otherwise.
124      */
125     boolean isDebugEnabled();
126 
127     /**
128      * Log a message at the DEBUG level.
129      *
130      * @param msg the message string to be logged
131      */
132     void debug(String msg);
133 
134     /**
135      * Log a message at the DEBUG level according to the specified format
136      * and argument.
137      * <p/>
138      * <p>This form avoids superfluous object creation when the logger
139      * is disabled for the DEBUG level. </p>
140      *
141      * @param format the format string
142      * @param arg    the argument
143      */
144     void debug(String format, Object arg);
145 
146     /**
147      * Log a message at the DEBUG level according to the specified format
148      * and arguments.
149      * <p/>
150      * <p>This form avoids superfluous object creation when the logger
151      * is disabled for the DEBUG level. </p>
152      *
153      * @param format the format string
154      * @param argA   the first argument
155      * @param argB   the second argument
156      */
157     void debug(String format, Object argA, Object argB);
158 
159     /**
160      * Log a message at the DEBUG level according to the specified format
161      * and arguments.
162      * <p/>
163      * <p>This form avoids superfluous string concatenation when the logger
164      * is disabled for the DEBUG level. However, this variant incurs the hidden
165      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
166      * even if this logger is disabled for DEBUG. The variants taking
167      * {@link #debug(String, Object) one} and {@link #debug(String, Object, Object) two}
168      * arguments exist solely in order to avoid this hidden cost.</p>
169      *
170      * @param format    the format string
171      * @param arguments a list of 3 or more arguments
172      */
173     void debug(String format, Object... arguments);
174 
175     /**
176      * Log an exception (throwable) at the DEBUG level with an
177      * accompanying message.
178      *
179      * @param msg the message accompanying the exception
180      * @param t   the exception (throwable) to log
181      */
182     void debug(String msg, Throwable t);
183 
184     /**
185      * Is the logger instance enabled for the INFO level?
186      *
187      * @return True if this Logger is enabled for the INFO level,
188      *         false otherwise.
189      */
190     boolean isInfoEnabled();
191 
192     /**
193      * Log a message at the INFO level.
194      *
195      * @param msg the message string to be logged
196      */
197     void info(String msg);
198 
199     /**
200      * Log a message at the INFO level according to the specified format
201      * and argument.
202      * <p/>
203      * <p>This form avoids superfluous object creation when the logger
204      * is disabled for the INFO level. </p>
205      *
206      * @param format the format string
207      * @param arg    the argument
208      */
209     void info(String format, Object arg);
210 
211     /**
212      * Log a message at the INFO level according to the specified format
213      * and arguments.
214      * <p/>
215      * <p>This form avoids superfluous object creation when the logger
216      * is disabled for the INFO level. </p>
217      *
218      * @param format the format string
219      * @param argA   the first argument
220      * @param argB   the second argument
221      */
222     void info(String format, Object argA, Object argB);
223 
224     /**
225      * Log a message at the INFO level according to the specified format
226      * and arguments.
227      * <p/>
228      * <p>This form avoids superfluous string concatenation when the logger
229      * is disabled for the INFO level. However, this variant incurs the hidden
230      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
231      * even if this logger is disabled for INFO. The variants taking
232      * {@link #info(String, Object) one} and {@link #info(String, Object, Object) two}
233      * arguments exist solely in order to avoid this hidden cost.</p>
234      *
235      * @param format    the format string
236      * @param arguments a list of 3 or more arguments
237      */
238     void info(String format, Object... arguments);
239 
240     /**
241      * Log an exception (throwable) at the INFO level with an
242      * accompanying message.
243      *
244      * @param msg the message accompanying the exception
245      * @param t   the exception (throwable) to log
246      */
247     void info(String msg, Throwable t);
248 
249     /**
250      * Is the logger instance enabled for the WARN level?
251      *
252      * @return True if this Logger is enabled for the WARN level,
253      *         false otherwise.
254      */
255     boolean isWarnEnabled();
256 
257     /**
258      * Log a message at the WARN level.
259      *
260      * @param msg the message string to be logged
261      */
262     void warn(String msg);
263 
264     /**
265      * Log a message at the WARN level according to the specified format
266      * and argument.
267      * <p/>
268      * <p>This form avoids superfluous object creation when the logger
269      * is disabled for the WARN level. </p>
270      *
271      * @param format the format string
272      * @param arg    the argument
273      */
274     void warn(String format, Object arg);
275 
276     /**
277      * Log a message at the WARN level according to the specified format
278      * and arguments.
279      * <p/>
280      * <p>This form avoids superfluous string concatenation when the logger
281      * is disabled for the WARN level. However, this variant incurs the hidden
282      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
283      * even if this logger is disabled for WARN. The variants taking
284      * {@link #warn(String, Object) one} and {@link #warn(String, Object, Object) two}
285      * arguments exist solely in order to avoid this hidden cost.</p>
286      *
287      * @param format    the format string
288      * @param arguments a list of 3 or more arguments
289      */
290     void warn(String format, Object... arguments);
291 
292     /**
293      * Log a message at the WARN level according to the specified format
294      * and arguments.
295      * <p/>
296      * <p>This form avoids superfluous object creation when the logger
297      * is disabled for the WARN level. </p>
298      *
299      * @param format the format string
300      * @param argA   the first argument
301      * @param argB   the second argument
302      */
303     void warn(String format, Object argA, Object argB);
304 
305     /**
306      * Log an exception (throwable) at the WARN level with an
307      * accompanying message.
308      *
309      * @param msg the message accompanying the exception
310      * @param t   the exception (throwable) to log
311      */
312     void warn(String msg, Throwable t);
313 
314     /**
315      * Is the logger instance enabled for the ERROR level?
316      *
317      * @return True if this Logger is enabled for the ERROR level,
318      *         false otherwise.
319      */
320     boolean isErrorEnabled();
321 
322     /**
323      * Log a message at the ERROR level.
324      *
325      * @param msg the message string to be logged
326      */
327     void error(String msg);
328 
329     /**
330      * Log a message at the ERROR level according to the specified format
331      * and argument.
332      * <p/>
333      * <p>This form avoids superfluous object creation when the logger
334      * is disabled for the ERROR level. </p>
335      *
336      * @param format the format string
337      * @param arg    the argument
338      */
339     void error(String format, Object arg);
340 
341     /**
342      * Log a message at the ERROR level according to the specified format
343      * and arguments.
344      * <p/>
345      * <p>This form avoids superfluous object creation when the logger
346      * is disabled for the ERROR level. </p>
347      *
348      * @param format the format string
349      * @param argA   the first argument
350      * @param argB   the second argument
351      */
352     void error(String format, Object argA, Object argB);
353 
354     /**
355      * Log a message at the ERROR level according to the specified format
356      * and arguments.
357      * <p/>
358      * <p>This form avoids superfluous string concatenation when the logger
359      * is disabled for the ERROR level. However, this variant incurs the hidden
360      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
361      * even if this logger is disabled for ERROR. The variants taking
362      * {@link #error(String, Object) one} and {@link #error(String, Object, Object) two}
363      * arguments exist solely in order to avoid this hidden cost.</p>
364      *
365      * @param format    the format string
366      * @param arguments a list of 3 or more arguments
367      */
368     void error(String format, Object... arguments);
369 
370     /**
371      * Log an exception (throwable) at the ERROR level with an
372      * accompanying message.
373      *
374      * @param msg the message accompanying the exception
375      * @param t   the exception (throwable) to log
376      */
377     void error(String msg, Throwable t);
378 
379     /**
380      * Is the logger instance enabled for the specified {@code level}?
381      *
382      * @return True if this Logger is enabled for the specified {@code level},
383      *         false otherwise.
384      */
385     boolean isEnabled(InternalLogLevel level);
386 
387     /**
388      * Log a message at the specified {@code level}.
389      *
390      * @param msg the message string to be logged
391      */
392     void log(InternalLogLevel level, String msg);
393 
394     /**
395      * Log a message at the specified {@code level} according to the specified format
396      * and argument.
397      * <p/>
398      * <p>This form avoids superfluous object creation when the logger
399      * is disabled for the specified {@code level}. </p>
400      *
401      * @param format the format string
402      * @param arg    the argument
403      */
404     void log(InternalLogLevel level, String format, Object arg);
405 
406     /**
407      * Log a message at the specified {@code level} according to the specified format
408      * and arguments.
409      * <p/>
410      * <p>This form avoids superfluous object creation when the logger
411      * is disabled for the specified {@code level}. </p>
412      *
413      * @param format the format string
414      * @param argA   the first argument
415      * @param argB   the second argument
416      */
417     void log(InternalLogLevel level, String format, Object argA, Object argB);
418 
419     /**
420      * Log a message at the specified {@code level} according to the specified format
421      * and arguments.
422      * <p/>
423      * <p>This form avoids superfluous string concatenation when the logger
424      * is disabled for the specified {@code level}. However, this variant incurs the hidden
425      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
426      * even if this logger is disabled for the specified {@code level}. The variants taking
427      * {@link #log(InternalLogLevel, String, Object) one} and
428      * {@link #log(InternalLogLevel, String, Object, Object) two} arguments exist solely
429      * in order to avoid this hidden cost.</p>
430      *
431      * @param format    the format string
432      * @param arguments a list of 3 or more arguments
433      */
434     void log(InternalLogLevel level, String format, Object... arguments);
435 
436     /**
437      * Log an exception (throwable) at the specified {@code level} with an
438      * accompanying message.
439      *
440      * @param msg the message accompanying the exception
441      * @param t   the exception (throwable) to log
442      */
443     void log(InternalLogLevel level, String msg, Throwable t);
444 }