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     *
031     */
032    public interface LogEvent extends Serializable {
033    
034        /**
035         * Gets the context map (also know as Mapped Diagnostic Context or MDC).
036         * 
037         * @return The context map, never {@code null}.
038         */
039        Map<String, String> getContextMap();
040    
041        /**
042         * Gets the context stack (also known as Nested Diagnostic Context or NDC).
043         * 
044         * @return The context stack, never {@code null}.
045         */
046        ThreadContext.ContextStack getContextStack();
047    
048        /**
049         * Returns the fully qualified class name of the caller of the logging API.
050         * 
051         * @return The fully qualified class name of the caller.
052         */
053        String getLoggerFqcn();
054    
055        /**
056         * Gets the level.
057         * 
058         * @return level.
059         */
060        Level getLevel();
061    
062        /**
063         * Gets the logger name.
064         * 
065         * @return logger name, may be null.
066         */
067        String getLoggerName();
068    
069        /**
070         * Gets the Marker associated with the event.
071         * 
072         * @return Marker
073         */
074        Marker getMarker();
075    
076        /**
077         * Gets the message associated with the event.
078         * 
079         * @return message.
080         */
081        Message getMessage();
082    
083        /**
084         * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
085         * 
086         * @return milliseconds since midnight, January 1, 1970 UTC.
087         * @see java.lang.System#currentTimeMillis()
088         */
089        long getTimeMillis();
090    
091        /**
092         * Gets the source of logging request.
093         * 
094         * @return source of logging request, may be null.
095         */
096        StackTraceElement getSource();
097    
098        /**
099         * Gets thread name.
100         * 
101         * @return thread name, may be null.
102         * @doubt guess this could go into a thread context object too. (RG) Why?
103         */
104        String getThreadName();
105    
106        /**
107         * Gets throwable associated with logging request.
108         * <p>
109         * Convenience method for {@code ThrowableProxy.getThrowable();}
110         * 
111         * @return throwable, may be null.
112         */
113        Throwable getThrown();
114    
115        /**
116         * Gets throwable proxy associated with logging request.
117         * 
118         * @return throwable, may be null.
119         */
120        ThrowableProxy getThrownProxy();
121    
122        /**
123         * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous Loggers and Appenders to
124         * signal to buffered downstream components when to flush to disk, as a more efficient alternative to the {@code immediateFlush=true}
125         * configuration.
126         * 
127         * @return whether this event is the last one in a batch.
128         */
129        // see also LOG4J2-164
130        boolean isEndOfBatch();
131    
132        /**
133         * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use this flag to
134         * determine whether to take a {@code StackTrace} snapshot or not before handing off this event to another thread.
135         * 
136         * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
137         * @see #getSource()
138         */
139        // see also LOG4J2-153
140        boolean isIncludeLocation();
141    
142        /**
143         * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to buffered downstream
144         * components when to flush to disk, as a more efficient alternative to the {@code immediateFlush=true} configuration.
145         * 
146         * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
147         */
148        void setEndOfBatch(boolean endOfBatch);
149    
150        /**
151         * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use this flag to determine
152         * whether to take a {@code StackTrace} snapshot or not before handing off this event to another thread.
153         * 
154         * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
155         * @see #getSource()
156         */
157        void setIncludeLocation(boolean locationRequired);
158    
159    }