    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
    018    package org.apache.logging.log4j.core;
    019
    020    import java.io.Serializable;
    021    import java.util.Map;
    022
    023    import org.apache.logging.log4j.Level;
    024    import org.apache.logging.log4j.Marker;
    025    import org.apache.logging.log4j.ThreadContext;
    026    import org.apache.logging.log4j.core.impl.ThrowableProxy;
    027    import org.apache.logging.log4j.message.Message;
    028
    029    /**
    030     * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
    031     * may be transmitted over a network connection, output in a
    032     * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
    033     * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
    034     * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
    035     * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
    036     * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
    037     * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
    038     * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
    039     * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
    040     * and deserialized properly without causing problems if the exception class is not available on the other end.
    041     */
    042    public interface LogEvent extends Serializable {
    043
    044        /**
    045         * Gets the context map (also know as Mapped Diagnostic Context or MDC).
    046         *
    047         * @return The context map, never {@code null}.
    048         */
    049        Map<String, String> getContextMap();
    050
    051        /**
    052         * Gets the context stack (also known as Nested Diagnostic Context or NDC).
    053         *
    054         * @return The context stack, never {@code null}.
    055         */
    056        ThreadContext.ContextStack getContextStack();
    057
    058        /**
    059         * Returns the fully qualified class name of the caller of the logging API.
    060         *
    061         * @return The fully qualified class name of the caller.
    062         */
    063        String getLoggerFqcn();
    064
    065        /**
    066         * Gets the level.
    067         *
    068         * @return level.
    069         */
    070        Level getLevel();
    071
    072        /**
    073         * Gets the logger name.
    074         *
    075         * @return logger name, may be {@code null}.
    076         */
    077        String getLoggerName();
    078
    079        /**
    080         * Gets the Marker associated with the event.
    081         *
    082         * @return Marker or {@code null} if no Marker was defined on this LogEvent
    083         */
    084        Marker getMarker();
    085
    086        /**
    087         * Gets the message associated with the event.
    088         *
    089         * @return message.
    090         */
    091        Message getMessage();
    092
    093        /**
    094         * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
    095         *
    096         * @return milliseconds since midnight, January 1, 1970 UTC.
    097         * @see java.lang.System#currentTimeMillis()
    098         */
    099        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    }