    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    package org.apache.logging.log4j;
    018
    019    import org.apache.logging.log4j.message.Message;
    020    import org.apache.logging.log4j.message.MessageFactory;
    021
    022    /**
    023     * This is the central interface in the log4j package. Most logging operations, except configuration, are done through
    024     * this interface.
    025     *
    026     * <p>
    027     * The canonical way to obtain a Logger for a class is through {@link LogManager#getLogger()}. Typically, each class
    028     * gets its own Logger named after its fully qualified class name (the default Logger name when obtained through the
    029     * {@link LogManager#getLogger()} method). Thus, the simplest way to use this would be like so:
    030     * </p>
    031     *
    032     * <pre>
    033     * public class MyClass {
    034     *     private static final Logger LOGGER = LogManager.getLogger();
    035     *     // ...
    036     * }
    037     * </pre>
    038     * <p>
    039     * For ease of filtering, searching, sorting, etc., it is generally a good idea to create Loggers for each class rather
    040     * than sharing Loggers. Instead, {@link Marker Markers} should be used for shared, filterable identification.
    041     * </p>
    042     * <p>
    043     * For service provider implementations, it is recommended to extend the
    044     * {@link org.apache.logging.log4j.spi.AbstractLogger} class rather than implementing this interface directly.
    045     * </p>
    046     */
    047    public interface LevelLogger {
    048
    049        /**
    050         * Logs an exception or error that has been caught. Normally, one may wish to provide additional information with an
    051         * exception while logging it; in these cases, one would not use this method. In other cases where simply logging
    052         * the fact that an exception was swallowed somewhere (e.g., at the top of the stack trace in a {@code main()}
    053         * method), this method is ideal for it.
    054         *
    055         * @param t
    056         *        The Throwable.
    057         */
    058        void catching(Throwable t);
    059
    060        /**
    061         * Logs entry to a method. Used when the method in question has no parameters or when the parameters should not be
    062         * logged.
    063         */
    064        void entry();
    065
    066        /**
    067         * Logs entry to a method along with its parameters. For example,
    068         *
    069         * <pre>
    070         * public void doSomething(String foo, int bar) {
    071         *     LOGGER.entry(foo, bar);
    072         *     // do something
    073         * }
    074         * </pre>
    075         * <p>
    076         * The use of methods such as this are more effective when combined with aspect-oriented programming or other
    077         * bytecode manipulation tools. It can be rather tedious (and messy) to use this type of method manually.
    078         * </p>
    079         *
    080         * @param params
    081         *        The parameters to the method. TODO Use of varargs results in array creation which can be a substantial
    082         *        portion of no-op case. LogMF/LogSF provides several overrides to avoid vararg except in edge cases. (RG)
    083         *        LogMF and LogSF implement these in LogXF which calls logger.callAppenders. callAppenders is part of the
    084         *        implementation and cannot be used by the API. Adding more methods here and in AbstractLogger is
    085         *        sufficient.
    086         */
    087        void entry(Object... params);
    088
    089        /**
    090         * Logs exit from a method. Used for methods that do not return anything.
    091         */
    092        void exit();
    093
    094        /**
    095         * Logs exiting from a method with the result. This may be coded as:
    096         *
    097         * <pre>
    098         * return LOGGER.exit(myResult);
    099         * </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    }