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