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    *   https://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      * Log an exception (throwable) at the TRACE level.
121      *
122      * @param t   the exception (throwable) to log
123      */
124     void trace(Throwable t);
125 
126     /**
127      * Is the logger instance enabled for the DEBUG level?
128      *
129      * @return True if this Logger is enabled for the DEBUG level,
130      *         false otherwise.
131      */
132     boolean isDebugEnabled();
133 
134     /**
135      * Log a message at the DEBUG level.
136      *
137      * @param msg the message string to be logged
138      */
139     void debug(String msg);
140 
141     /**
142      * Log a message at the DEBUG level according to the specified format
143      * and argument.
144      * <p/>
145      * <p>This form avoids superfluous object creation when the logger
146      * is disabled for the DEBUG level. </p>
147      *
148      * @param format the format string
149      * @param arg    the argument
150      */
151     void debug(String format, Object arg);
152 
153     /**
154      * Log a message at the DEBUG level according to the specified format
155      * and arguments.
156      * <p/>
157      * <p>This form avoids superfluous object creation when the logger
158      * is disabled for the DEBUG level. </p>
159      *
160      * @param format the format string
161      * @param argA   the first argument
162      * @param argB   the second argument
163      */
164     void debug(String format, Object argA, Object argB);
165 
166     /**
167      * Log a message at the DEBUG level according to the specified format
168      * and arguments.
169      * <p/>
170      * <p>This form avoids superfluous string concatenation when the logger
171      * is disabled for the DEBUG level. However, this variant incurs the hidden
172      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
173      * even if this logger is disabled for DEBUG. The variants taking
174      * {@link #debug(String, Object) one} and {@link #debug(String, Object, Object) two}
175      * arguments exist solely in order to avoid this hidden cost.</p>
176      *
177      * @param format    the format string
178      * @param arguments a list of 3 or more arguments
179      */
180     void debug(String format, Object... arguments);
181 
182     /**
183      * Log an exception (throwable) at the DEBUG level with an
184      * accompanying message.
185      *
186      * @param msg the message accompanying the exception
187      * @param t   the exception (throwable) to log
188      */
189     void debug(String msg, Throwable t);
190 
191     /**
192      * Log an exception (throwable) at the DEBUG level.
193      *
194      * @param t   the exception (throwable) to log
195      */
196     void debug(Throwable t);
197 
198     /**
199      * Is the logger instance enabled for the INFO level?
200      *
201      * @return True if this Logger is enabled for the INFO level,
202      *         false otherwise.
203      */
204     boolean isInfoEnabled();
205 
206     /**
207      * Log a message at the INFO level.
208      *
209      * @param msg the message string to be logged
210      */
211     void info(String msg);
212 
213     /**
214      * Log a message at the INFO level according to the specified format
215      * and argument.
216      * <p/>
217      * <p>This form avoids superfluous object creation when the logger
218      * is disabled for the INFO level. </p>
219      *
220      * @param format the format string
221      * @param arg    the argument
222      */
223     void info(String format, Object arg);
224 
225     /**
226      * Log a message at the INFO level according to the specified format
227      * and arguments.
228      * <p/>
229      * <p>This form avoids superfluous object creation when the logger
230      * is disabled for the INFO level. </p>
231      *
232      * @param format the format string
233      * @param argA   the first argument
234      * @param argB   the second argument
235      */
236     void info(String format, Object argA, Object argB);
237 
238     /**
239      * Log a message at the INFO level according to the specified format
240      * and arguments.
241      * <p/>
242      * <p>This form avoids superfluous string concatenation when the logger
243      * is disabled for the INFO level. However, this variant incurs the hidden
244      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
245      * even if this logger is disabled for INFO. The variants taking
246      * {@link #info(String, Object) one} and {@link #info(String, Object, Object) two}
247      * arguments exist solely in order to avoid this hidden cost.</p>
248      *
249      * @param format    the format string
250      * @param arguments a list of 3 or more arguments
251      */
252     void info(String format, Object... arguments);
253 
254     /**
255      * Log an exception (throwable) at the INFO level with an
256      * accompanying message.
257      *
258      * @param msg the message accompanying the exception
259      * @param t   the exception (throwable) to log
260      */
261     void info(String msg, Throwable t);
262 
263     /**
264      * Log an exception (throwable) at the INFO level.
265      *
266      * @param t   the exception (throwable) to log
267      */
268     void info(Throwable t);
269 
270     /**
271      * Is the logger instance enabled for the WARN level?
272      *
273      * @return True if this Logger is enabled for the WARN level,
274      *         false otherwise.
275      */
276     boolean isWarnEnabled();
277 
278     /**
279      * Log a message at the WARN level.
280      *
281      * @param msg the message string to be logged
282      */
283     void warn(String msg);
284 
285     /**
286      * Log a message at the WARN level according to the specified format
287      * and argument.
288      * <p/>
289      * <p>This form avoids superfluous object creation when the logger
290      * is disabled for the WARN level. </p>
291      *
292      * @param format the format string
293      * @param arg    the argument
294      */
295     void warn(String format, Object arg);
296 
297     /**
298      * Log a message at the WARN level according to the specified format
299      * and arguments.
300      * <p/>
301      * <p>This form avoids superfluous string concatenation when the logger
302      * is disabled for the WARN level. However, this variant incurs the hidden
303      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
304      * even if this logger is disabled for WARN. The variants taking
305      * {@link #warn(String, Object) one} and {@link #warn(String, Object, Object) two}
306      * arguments exist solely in order to avoid this hidden cost.</p>
307      *
308      * @param format    the format string
309      * @param arguments a list of 3 or more arguments
310      */
311     void warn(String format, Object... arguments);
312 
313     /**
314      * Log a message at the WARN level according to the specified format
315      * and arguments.
316      * <p/>
317      * <p>This form avoids superfluous object creation when the logger
318      * is disabled for the WARN level. </p>
319      *
320      * @param format the format string
321      * @param argA   the first argument
322      * @param argB   the second argument
323      */
324     void warn(String format, Object argA, Object argB);
325 
326     /**
327      * Log an exception (throwable) at the WARN level with an
328      * accompanying message.
329      *
330      * @param msg the message accompanying the exception
331      * @param t   the exception (throwable) to log
332      */
333     void warn(String msg, Throwable t);
334 
335     /**
336      * Log an exception (throwable) at the WARN level.
337      *
338      * @param t   the exception (throwable) to log
339      */
340     void warn(Throwable t);
341 
342     /**
343      * Is the logger instance enabled for the ERROR level?
344      *
345      * @return True if this Logger is enabled for the ERROR level,
346      *         false otherwise.
347      */
348     boolean isErrorEnabled();
349 
350     /**
351      * Log a message at the ERROR level.
352      *
353      * @param msg the message string to be logged
354      */
355     void error(String msg);
356 
357     /**
358      * Log a message at the ERROR level according to the specified format
359      * and argument.
360      * <p/>
361      * <p>This form avoids superfluous object creation when the logger
362      * is disabled for the ERROR level. </p>
363      *
364      * @param format the format string
365      * @param arg    the argument
366      */
367     void error(String format, Object arg);
368 
369     /**
370      * Log a message at the ERROR level according to the specified format
371      * and arguments.
372      * <p/>
373      * <p>This form avoids superfluous object creation when the logger
374      * is disabled for the ERROR level. </p>
375      *
376      * @param format the format string
377      * @param argA   the first argument
378      * @param argB   the second argument
379      */
380     void error(String format, Object argA, Object argB);
381 
382     /**
383      * Log a message at the ERROR level according to the specified format
384      * and arguments.
385      * <p/>
386      * <p>This form avoids superfluous string concatenation when the logger
387      * is disabled for the ERROR level. However, this variant incurs the hidden
388      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
389      * even if this logger is disabled for ERROR. The variants taking
390      * {@link #error(String, Object) one} and {@link #error(String, Object, Object) two}
391      * arguments exist solely in order to avoid this hidden cost.</p>
392      *
393      * @param format    the format string
394      * @param arguments a list of 3 or more arguments
395      */
396     void error(String format, Object... arguments);
397 
398     /**
399      * Log an exception (throwable) at the ERROR level with an
400      * accompanying message.
401      *
402      * @param msg the message accompanying the exception
403      * @param t   the exception (throwable) to log
404      */
405     void error(String msg, Throwable t);
406 
407     /**
408      * Log an exception (throwable) at the ERROR level.
409      *
410      * @param t   the exception (throwable) to log
411      */
412     void error(Throwable t);
413 
414     /**
415      * Is the logger instance enabled for the specified {@code level}?
416      *
417      * @return True if this Logger is enabled for the specified {@code level},
418      *         false otherwise.
419      */
420     boolean isEnabled(InternalLogLevel level);
421 
422     /**
423      * Log a message at the specified {@code level}.
424      *
425      * @param msg the message string to be logged
426      */
427     void log(InternalLogLevel level, String msg);
428 
429     /**
430      * Log a message at the specified {@code level} according to the specified format
431      * and argument.
432      * <p/>
433      * <p>This form avoids superfluous object creation when the logger
434      * is disabled for the specified {@code level}. </p>
435      *
436      * @param format the format string
437      * @param arg    the argument
438      */
439     void log(InternalLogLevel level, String format, Object arg);
440 
441     /**
442      * Log a message at the specified {@code level} according to the specified format
443      * and arguments.
444      * <p/>
445      * <p>This form avoids superfluous object creation when the logger
446      * is disabled for the specified {@code level}. </p>
447      *
448      * @param format the format string
449      * @param argA   the first argument
450      * @param argB   the second argument
451      */
452     void log(InternalLogLevel level, String format, Object argA, Object argB);
453 
454     /**
455      * Log a message at the specified {@code level} according to the specified format
456      * and arguments.
457      * <p/>
458      * <p>This form avoids superfluous string concatenation when the logger
459      * is disabled for the specified {@code level}. However, this variant incurs the hidden
460      * (and relatively small) cost of creating an {@code Object[]} before invoking the method,
461      * even if this logger is disabled for the specified {@code level}. The variants taking
462      * {@link #log(InternalLogLevel, String, Object) one} and
463      * {@link #log(InternalLogLevel, String, Object, Object) two} arguments exist solely
464      * in order to avoid this hidden cost.</p>
465      *
466      * @param format    the format string
467      * @param arguments a list of 3 or more arguments
468      */
469     void log(InternalLogLevel level, String format, Object... arguments);
470 
471     /**
472      * Log an exception (throwable) at the specified {@code level} with an
473      * accompanying message.
474      *
475      * @param msg the message accompanying the exception
476      * @param t   the exception (throwable) to log
477      */
478     void log(InternalLogLevel level, String msg, Throwable t);
479 
480     /**
481      * Log an exception (throwable) at the specified {@code level}.
482      *
483      * @param t   the exception (throwable) to log
484      */
485     void log(InternalLogLevel level, Throwable t);
486 }