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    }