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
    18  package org.apache.logging.log4j.core;
    19
    20  import java.io.Serializable;
    21  import java.util.Map;
    22
    23  import org.apache.logging.log4j.Level;
    24  import org.apache.logging.log4j.Marker;
    25  import org.apache.logging.log4j.ThreadContext;
    26  import org.apache.logging.log4j.core.impl.ThrowableProxy;
    27  import org.apache.logging.log4j.message.Message;
    28
    29  /**
    30   * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
    31   * may be transmitted over a network connection, output in a
    32   * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
    33   * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
    34   * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
    35   * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
    36   * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
    37   * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
    38   * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
    39   * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
    40   * and deserialized properly without causing problems if the exception class is not available on the other end.
    41   */
    42  public interface LogEvent extends Serializable {
    43
    44      /**
    45       * Gets the context map (also know as Mapped Diagnostic Context or MDC).
    46       *
    47       * @return The context map, never {@code null}.
    48       */
    49      Map<String, String> getContextMap();
    50
    51      /**
    52       * Gets the context stack (also known as Nested Diagnostic Context or NDC).
    53       *
    54       * @return The context stack, never {@code null}.
    55       */
    56      ThreadContext.ContextStack getContextStack();
    57
    58      /**
    59       * Returns the fully qualified class name of the caller of the logging API.
    60       *
    61       * @return The fully qualified class name of the caller.
    62       */
    63      String getLoggerFqcn();
    64
    65      /**
    66       * Gets the level.
    67       *
    68       * @return level.
    69       */
    70      Level getLevel();
    71
    72      /**
    73       * Gets the logger name.
    74       *
    75       * @return logger name, may be {@code null}.
    76       */
    77      String getLoggerName();
    78
    79      /**
    80       * Gets the Marker associated with the event.
    81       *
    82       * @return Marker or {@code null} if no Marker was defined on this LogEvent
    83       */
    84      Marker getMarker();
    85
    86      /**
    87       * Gets the message associated with the event.
    88       *
    89       * @return message.
    90       */
    91      Message getMessage();
    92
    93      /**
    94       * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
    95       *
    96       * @return milliseconds since midnight, January 1, 1970 UTC.
    97       * @see java.lang.System#currentTimeMillis()
    98       */
    99      long getTimeMillis();
    100
    101     /**
    102      * Gets the source of logging request.
    103      *
    104      * @return source of logging request, may be null.
    105      */
    106     StackTraceElement getSource();
    107
    108     /**
    109      * Gets thread name.
    110      *
    111      * @return thread name, may be null.
    112      * TODO guess this could go into a thread context object too. (RG) Why?
    113      */
    114     String getThreadName();
    115
    116     /**
    117      * Gets throwable associated with logging request.
    118      *
    119      * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
    120      *
    121      * @return throwable, may be null.
    122      */
    123     Throwable getThrown();
    124
    125     /**
    126      * Gets throwable proxy associated with logging request.
    127      *
    128      * @return throwable, may be null.
    129      */
    130     ThrowableProxy getThrownProxy();
    131
    132     /**
    133      * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
    134      * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
    135      * alternative to the {@code immediateFlush=true} configuration.
    136      *
    137      * @return whether this event is the last one in a batch.
    138      */
    139     // see also LOG4J2-164
    140     boolean isEndOfBatch();
    141
    142     /**
    143      * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
    144      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
    145      * another thread.
    146      *
    147      * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
    148      * @see #getSource()
    149      */
    150     // see also LOG4J2-153
    151     boolean isIncludeLocation();
    152
    153     /**
    154      * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
    155      * buffered downstream components when to flush to disk, as a more efficient alternative to the
    156      * {@code immediateFlush=true} configuration.
    157      *
    158      * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
    159      */
    160     void setEndOfBatch(boolean endOfBatch);
    161
    162     /**
    163      * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
    164      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
    165      * another thread.
    166      *
    167      * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
    168      *                         otherwise.
    169      * @see #getSource()
    170      */
    171     void setIncludeLocation(boolean locationRequired);
    172
    173 }