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