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   *
31   */
32  public interface LogEvent extends Serializable {
33  
34      /**
35       * Gets the context map (also know as Mapped Diagnostic Context or MDC).
36       * 
37       * @return The context map, never {@code null}.
38       */
39      Map<String, String> getContextMap();
40  
41      /**
42       * Gets the context stack (also known as Nested Diagnostic Context or NDC).
43       * 
44       * @return The context stack, never {@code null}.
45       */
46      ThreadContext.ContextStack getContextStack();
47  
48      /**
49       * Returns the fully qualified class name of the caller of the logging API.
50       * 
51       * @return The fully qualified class name of the caller.
52       */
53      String getLoggerFqcn();
54  
55      /**
56       * Gets the level.
57       * 
58       * @return level.
59       */
60      Level getLevel();
61  
62      /**
63       * Gets the logger name.
64       * 
65       * @return logger name, may be null.
66       */
67      String getLoggerName();
68  
69      /**
70       * Gets the Marker associated with the event.
71       * 
72       * @return Marker
73       */
74      Marker getMarker();
75  
76      /**
77       * Gets the message associated with the event.
78       * 
79       * @return message.
80       */
81      Message getMessage();
82  
83      /**
84       * Gets event time in milliseconds since midnight, January 1, 1970 UTC.
85       * 
86       * @return milliseconds since midnight, January 1, 1970 UTC.
87       * @see java.lang.System#currentTimeMillis()
88       */
89      long getTimeMillis();
90  
91      /**
92       * Gets the source of logging request.
93       * 
94       * @return source of logging request, may be null.
95       */
96      StackTraceElement getSource();
97  
98      /**
99       * 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 }