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      * @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 }