View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements. See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache license, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License. You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the license for the specific language governing permissions and
15   * limitations under the license.
16   */
17  
18  package org.apache.logging.log4j.core;
19  
20  import java.io.Serializable;
21  import java.util.Map;
22  
23  import org.apache.logging.log4j.Level;
24  import org.apache.logging.log4j.Marker;
25  import org.apache.logging.log4j.ThreadContext;
26  import org.apache.logging.log4j.core.impl.ThrowableProxy;
27  import org.apache.logging.log4j.message.Message;
28  
29  /**
30   * Provides contextual information about a logged message. A LogEvent must be {@link java.io.Serializable} so that it
31   * may be transmitted over a network connection, output in a
32   * {@link org.apache.logging.log4j.core.layout.SerializedLayout}, and many other uses. Besides containing a
33   * {@link org.apache.logging.log4j.message.Message}, a LogEvent has a corresponding
34   * {@link org.apache.logging.log4j.Level} that the message was logged at. If a
35   * {@link org.apache.logging.log4j.Marker} was used, then it is included here. The contents of the
36   * {@link org.apache.logging.log4j.ThreadContext} at the time of the log call are provided via
37   * {@link #getContextMap()} and {@link #getContextStack()}. If a {@link java.lang.Throwable} was included in the log
38   * call, then it is provided via {@link #getThrown()}. When this class is serialized, the attached Throwable will
39   * be wrapped into a {@link org.apache.logging.log4j.core.impl.ThrowableProxy} so that it may be safely serialized
40   * and deserialized properly without causing problems if the exception class is not available on the other end.
41   */
42  public interface LogEvent extends Serializable {
43  
44      /**
45       * Gets the context map (also know as Mapped Diagnostic Context or MDC).
46       *
47       * @return The context map, never {@code null}.
48       */
49      Map<String, String> getContextMap();
50  
51      /**
52       * Gets the context stack (also known as Nested Diagnostic Context or NDC).
53       *
54       * @return The context stack, never {@code null}.
55       */
56      ThreadContext.ContextStack getContextStack();
57  
58      /**
59       * Returns the fully qualified class name of the caller of the logging API.
60       *
61       * @return The fully qualified class name of the caller.
62       */
63      String getLoggerFqcn();
64  
65      /**
66       * Gets the level.
67       *
68       * @return level.
69       */
70      Level getLevel();
71  
72      /**
73       * Gets the logger name.
74       *
75       * @return logger name, may be {@code null}.
76       */
77      String getLoggerName();
78  
79      /**
80       * Gets the Marker associated with the event.
81       *
82       * @return Marker or {@code null} if no Marker was defined on this LogEvent
83       */
84      Marker getMarker();
85  
86      /**
87       * Gets the message associated with the event.
88       *
89       * @return message.
90       */
91      Message getMessage();
92  
93      /**
94       * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
95       *
96       * @return milliseconds since midnight, January 1, 1970 UTC.
97       * @see java.lang.System#currentTimeMillis()
98       */
99      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 the 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 the thread ID.
118      *
119      * @return thread ID.
120      * @since 2.6
121      */
122     long getThreadId();
123 
124     /**
125      * Gets the thread priority.
126      *
127      * @return thread priority.
128      * @since 2.6
129      */
130     int getThreadPriority();
131 
132     /**
133      * Gets throwable associated with logging request.
134      *
135      * <p>Convenience method for {@code ThrowableProxy.getThrowable();}</p>
136      *
137      * @return throwable, may be null.
138      */
139     Throwable getThrown();
140 
141     /**
142      * Gets throwable proxy associated with logging request.
143      *
144      * @return throwable, may be null.
145      */
146     ThrowableProxy getThrownProxy();
147 
148     /**
149      * Returns {@code true} if this event is the last one in a batch, {@code false} otherwise. Used by asynchronous
150      * Loggers and Appenders to signal to buffered downstream components when to flush to disk, as a more efficient
151      * alternative to the {@code immediateFlush=true} configuration.
152      *
153      * @return whether this event is the last one in a batch.
154      */
155     // see also LOG4J2-164
156     boolean isEndOfBatch();
157 
158     /**
159      * Returns whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
160      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
161      * another thread.
162      *
163      * @return {@code true} if the source of the logging request is required downstream, {@code false} otherwise.
164      * @see #getSource()
165      */
166     // see also LOG4J2-153
167     boolean isIncludeLocation();
168 
169     /**
170      * Sets whether this event is the last one in a batch. Used by asynchronous Loggers and Appenders to signal to
171      * buffered downstream components when to flush to disk, as a more efficient alternative to the
172      * {@code immediateFlush=true} configuration.
173      *
174      * @param endOfBatch {@code true} if this event is the last one in a batch, {@code false} otherwise.
175      */
176     void setEndOfBatch(boolean endOfBatch);
177 
178     /**
179      * Sets whether the source of the logging request is required downstream. Asynchronous Loggers and Appenders use
180      * this flag to determine whether to take a {@code StackTrace} snapshot or not before handing off this event to
181      * another thread.
182      *
183      * @param locationRequired {@code true} if the source of the logging request is required downstream, {@code false}
184      *                         otherwise.
185      * @see #getSource()
186      */
187     void setIncludeLocation(boolean locationRequired);
188 
189     /**
190      * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
191      * or a dummy value if it is known that this value will not be used downstream.
192      * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
193      * @since Log4J 2.4
194      */
195     long getNanoTime();
196 }