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         * @doubt 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         * <p>
119         * Convenience method for {@code ThrowableProxy.getThrowable();}
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 Loggers and Appenders to
134         * signal to buffered downstream components when to flush to disk, as a more efficient alternative to the {@code immediateFlush=true}
135         * 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 this flag to
144         * determine whether to take a {@code StackTrace} snapshot or not before handing off this event to another thread.
145         * 
146         * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
147         * @see #getSource()
148         */
149        // see also LOG4J2-153
150        boolean isIncludeLocation();
151    
152        /**
153         * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to buffered downstream
154         * components when to flush to disk, as a more efficient alternative to the {@code immediateFlush=true} configuration.
155         * 
156         * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
157         */
158        void setEndOfBatch(boolean endOfBatch);
159    
160        /**
161         * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use this flag to determine
162         * whether to take a {@code StackTrace} snapshot or not before handing off this event to another thread.
163         * 
164         * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
165         * @see #getSource()
166         */
167        void setIncludeLocation(boolean locationRequired);
168    
169    }