View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements. See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache license, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License. You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the license for the specific language governing permissions and
    15   * limitations under the license.
    16   */
    17  package org.apache.logging.log4j;
    18
    19  import org.apache.logging.log4j.message.Message;
    20  import org.apache.logging.log4j.message.MessageFactory;
    21
    22  /**
    23   * This is the central interface in the log4j package. Most logging operations, except configuration, are done through
    24   * this interface.
    25   *
    26   * <p>
    27   * The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
    28   * gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
    29   * {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
    30   * </p>
    31   *
    32   * <pre>
    33   * public class MyClass {
    34   *     private static final Logger LOGGER = LogManager.getLogger();
    35   *     // ...
    36   * }
    37   * </pre>
    38   * <p>
    39   * For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
    40   * than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
    41   * </p>
    42   * <p>
    43   * For service provider implementations, it is recommended to extend the
    44   * {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
    45   * </p>
    46   */
    47  public interface LevelLogger {
    48
    49      /**
    50       * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
    51       * exception while logging it; in these cases, one would not use this method. In other cases where simply logging
    52       * the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a {@code main()}
    53       * method), this method is ideal for it.
    54       *
    55       * @param t
    56       *        The Throwable.
    57       */
    58      void catching(Throwable t);
    59
    60      /**
    61       * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
    62       * logged.
    63       */
    64      void entry();
    65
    66      /**
    67       * Logs entry to a method along with its parameters. For example,
    68       *
    69       * <pre>
    70       * public void doSomething(String foo, int bar) {
    71       *     LOGGER.entry(foo, bar);
    72       *     // do something
    73       * }
    74       * </pre>
    75       * <p>
    76       * The use of methods such as this are more effective when combined with aspect-oriented programming or other
    77       * bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.
    78       * </p>
    79       *
    80       * @param params
    81       *        The parameters to the method. TODO Use of varargs results in array creation which can be a substantial
    82       *        portion of no-op case. LogMF/LogSF provides several overrides to avoid vararg except in edge cases. (RG)
    83       *        LogMF and LogSF implement these in LogXF which calls logger.callAppenders. callAppenders is part of the
    84       *        implementation and cannot be used by the API. Adding more methods here and in AbstractLogger is
    85       *        sufficient.
    86       */
    87      void entry(Object... params);
    88
    89      /**
    90       * Logs exit from a method. Used for methods that do not return anything.
    91       */
    92      void exit();
    93
    94      /**
    95       * Logs exiting from a method with the result. This may be coded as:
    96       *
    97       * <pre>
    98       * return LOGGER.exit(myResult);
    99       * </pre>
    100      *
    101      * @param <R>
    102      *        The type of the parameter and object being returned.
    103      * @param result
    104      *        The result being returned from the method call.
    105      * @return the result.
    106      */
    107     <R> R exit(R result);
    108
    109     /**
    110      * Gets the Level associated with the Logger.
    111      *
    112      * @return the Level associate with the Logger.
    113      */
    114     Level getLevel();
    115
    116     /**
    117      * Gets the message factory used to convert message Objects and Strings into actual log Messages.
    118      *
    119      * @return the message factory.
    120      */
    121     MessageFactory getMessageFactory();
    122
    123     /**
    124      * Gets the logger name.
    125      *
    126      * @return the logger name.
    127      */
    128     String getName();
    129
    130     /**
    131      * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
    132      *
    133      * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
    134      */
    135     boolean isDebugEnabled();
    136
    137     /**
    138      * Checks whether this Logger is enabled for the {@link Level#DEBUG DEBUG} Level.
    139      *
    140      * @param marker
    141      *        The marker data specific to this log statement.
    142      * @return boolean - {@code true} if this Logger is enabled for level DEBUG, {@code false} otherwise.
    143      */
    144     boolean isDebugEnabled(Marker marker);
    145
    146     /**
    147      * Checks whether this Logger is enabled for the the given Level.
    148      * <p>
    149      * Note that passing in {@link Level#OFF OFF} always returns {@code true}.
    150      * </p>
    151      *
    152      * @return boolean - {@code true} if this Logger is enabled for level, {@code false} otherwise.
    153      */
    154     boolean isEnabled(Level level);
    155
    156     /**
    157      * Checks whether this logger is enabled at the specified level and an optional Marker.
    158      *
    159      * @param marker
    160      *        The marker data specific to this log statement.
    161      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
    162      *         otherwise.
    163      */
    164     boolean isEnabled(Marker marker);
    165
    166     /**
    167      * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
    168      *
    169      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
    170      *         otherwise.
    171      */
    172     boolean isErrorEnabled();
    173
    174     /**
    175      * Checks whether this Logger is enabled for the {@link Level#ERROR ERROR} Level.
    176      *
    177      * @param marker
    178      *        The marker data specific to this log statement.
    179      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#ERROR ERROR}, {@code false}
    180      *         otherwise.
    181      */
    182     boolean isErrorEnabled(Marker marker);
    183
    184     /**
    185      * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
    186      *
    187      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
    188      *         otherwise.
    189      */
    190     boolean isFatalEnabled();
    191
    192     /**
    193      * Checks whether this Logger is enabled for the {@link Level#FATAL FATAL} Level.
    194      *
    195      * @param marker
    196      *        The marker data specific to this log statement.
    197      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#FATAL FATAL}, {@code false}
    198      *         otherwise.
    199      */
    200     boolean isFatalEnabled(Marker marker);
    201
    202     /**
    203      * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
    204      *
    205      * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
    206      */
    207     boolean isInfoEnabled();
    208
    209     /**
    210      * Checks whether this Logger is enabled for the {@link Level#INFO INFO} Level.
    211      *
    212      * @param marker
    213      *        The marker data specific to this log statement.
    214      * @return boolean - {@code true} if this Logger is enabled for level INFO, {@code false} otherwise.
    215      */
    216     boolean isInfoEnabled(Marker marker);
    217
    218     /**
    219      * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
    220      *
    221      * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
    222      */
    223     boolean isTraceEnabled();
    224
    225     /**
    226      * Checks whether this Logger is enabled for the {@link Level#TRACE TRACE} level.
    227      *
    228      * @param marker
    229      *        The marker data specific to this log statement.
    230      * @return boolean - {@code true} if this Logger is enabled for level TRACE, {@code false} otherwise.
    231      */
    232     boolean isTraceEnabled(Marker marker);
    233
    234     /**
    235      * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
    236      *
    237      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
    238      *         otherwise.
    239      */
    240     boolean isWarnEnabled();
    241
    242     /**
    243      * Checks whether this Logger is enabled for the {@link Level#WARN WARN} Level.
    244      *
    245      * @param marker
    246      *        The marker data specific to this log statement.
    247      * @return boolean - {@code true} if this Logger is enabled for level {@link Level#WARN WARN}, {@code false}
    248      *         otherwise.
    249      */
    250     boolean isWarnEnabled(Marker marker);
    251
    252     /**
    253      * Logs a message with the specific Marker at the given level.
    254      *
    255      *
    256      * @param marker
    257      *        the marker data specific to this log statement
    258      * @param msg
    259      *        the message string to be logged
    260      */
    261     void log(Marker marker, Message msg);
    262
    263     /**
    264      * Logs a message with the specific Marker at the given level.
    265      *
    266      * @param marker
    267      *        the marker data specific to this log statement
    268      * @param msg
    269      *        the message string to be logged
    270      * @param t
    271      *        A Throwable or null.
    272      */
    273     void log(Marker marker, Message msg, Throwable t);
    274
    275     /**
    276      * Logs a message object with the given level.
    277      *
    278      * @param marker
    279      *        the marker data specific to this log statement
    280      * @param message
    281      *        the message object to log.
    282      */
    283     void log(Marker marker, Object message);
    284
    285     /**
    286      * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
    287      * parameter.
    288      *
    289      * @param marker
    290      *        the marker data specific to this log statement
    291      * @param message
    292      *        the message to log.
    293      * @param t
    294      *        the exception to log, including its stack trace.
    295      */
    296     void log(Marker marker, Object message, Throwable t);
    297
    298     /**
    299      * Logs a message object with the given level.
    300      *
    301      *
    302      * @param marker
    303      *        the marker data specific to this log statement
    304      * @param message
    305      *        the message object to log.
    306      */
    307     void log(Marker marker, String message);
    308
    309     /**
    310      * Logs a message with parameters at the given level.
    311      *
    312      * @param marker
    313      *        the marker data specific to this log statement
    314      * @param message
    315      *        the message to log; the format depends on the message factory.
    316      * @param params
    317      *        parameters to the message.
    318      * @see #getMessageFactory()
    319      */
    320     void log(Marker marker, String message, Object... params);
    321
    322     /**
    323      * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
    324      * parameter.
    325      *
    326      * @param marker
    327      *        the marker data specific to this log statement
    328      * @param message
    329      *        the message to log.
    330      * @param t
    331      *        the exception to log, including its stack trace.
    332      */
    333     void log(Marker marker, String message, Throwable t);
    334
    335     /**
    336      * Logs a message with the specific Marker at the given level.
    337      *
    338      * @param msg
    339      *        the message string to be logged
    340      */
    341     void log(Message msg);
    342
    343     /**
    344      * Logs a message with the specific Marker at the given level.
    345      *
    346      * @param msg
    347      *        the message string to be logged
    348      * @param t
    349      *        A Throwable or null.
    350      */
    351     void log(Message msg, Throwable t);
    352
    353     /**
    354      * Logs a message object with the given level.
    355      *
    356      * @param message
    357      *        the message object to log.
    358      */
    359     void log(Object message);
    360
    361     /**
    362      * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
    363      * parameter.
    364      *
    365      * @param message
    366      *        the message to log.
    367      * @param t
    368      *        the exception to log, including its stack trace.
    369      */
    370     void log(Object message, Throwable t);
    371
    372     /**
    373      * Logs a message object with the given level.
    374      *
    375      * @param message
    376      *        the message string to log.
    377      */
    378     void log(String message);
    379
    380     /**
    381      * Logs a message with parameters at the given level.
    382      *
    383      *
    384      * @param message
    385      *        the message to log; the format depends on the message factory.
    386      * @param params
    387      *        parameters to the message.
    388      * @see #getMessageFactory()
    389      */
    390     void log(String message, Object... params);
    391
    392     /**
    393      * Logs a message at the given level including the stack trace of the {@link Throwable} <code>t</code> passed as
    394      * parameter.
    395      *
    396      *
    397      * @param message
    398      *        the message to log.
    399      * @param t
    400      *        the exception to log, including its stack trace.
    401      */
    402     void log(String message, Throwable t);
    403
    404     /**
    405      * Logs a formatted message using the specified format string and arguments.
    406      *
    407      *
    408      * @param marker
    409      *        the marker data specific to this log statement.
    410      * @param format
    411      *        The format String.
    412      * @param params
    413      *        Arguments specified by the format.
    414      */
    415     void printf(Marker marker, String format, Object... params);
    416
    417     /**
    418      * Logs a formatted message using the specified format string and arguments.
    419      *
    420      *
    421      * @param format
    422      *        The format String.
    423      * @param params
    424      *        Arguments specified by the format.
    425      */
    426     void printf(String format, Object... params);
    427
    428     /**
    429      * Logs an exception or error to be thrown. This may be coded as:
    430      *
    431      * <pre>
    432      * throw logger.throwing(myException);
    433      * </pre>
    434      *
    435      * @param <T>
    436      *        the Throwable type.
    437      * @param t
    438      *        The Throwable.
    439      * @return the Throwable.
    440      */
    441     <T extends Throwable> T throwing(T t);
    442 }