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 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     /**
174      * Returns the value of the running Java Virtual Machine's high-resolution time source when this event was created,
175      * or a dummy value if it is known that this value will not be used downstream.
176      * @return The value of the running Java Virtual Machine's high-resolution time source when this event was created.
177      * @since Log4J 2.4
178      */
179     long getNanoTime();
180 }