1   /**
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v1.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  package ch.qos.logback.classic.spi;
15  
16  import java.time.Instant;
17  import java.util.List;
18  import java.util.Map;
19  
20  import org.slf4j.Marker;
21  import org.slf4j.event.KeyValuePair;
22  
23  import ch.qos.logback.classic.Level;
24  import ch.qos.logback.core.spi.DeferredProcessingAware;
25  
26  /**
27   * The central interface in logback-classic. In a nutshell, logback-classic is
28   * nothing more than a processing chain built around this interface.
29   * 
30   * @author Ceki Gülcü
31   * @since 0.9.16
32   */
33  public interface ILoggingEvent extends DeferredProcessingAware {
34  
35      String getThreadName();
36  
37      Level getLevel();
38  
39      String getMessage();
40  
41      Object[] getArgumentArray();
42  
43      String getFormattedMessage();
44  
45      String getLoggerName();
46  
47      LoggerContextVO getLoggerContextVO();
48  
49      IThrowableProxy getThrowableProxy();
50  
51      /**
52       * Return caller data associated with this event. Note that calling this event
53       * may trigger the computation of caller data.
54       * 
55       * @return the caller data associated with this event.
56       * 
57       * @see #hasCallerData()
58       */
59      StackTraceElement[] getCallerData();
60  
61      /**
62       * If this event has caller data, then true is returned. Otherwise the returned
63       * value is null.
64       * 
65       * <p>
66       * Logback components wishing to use caller data if available without causing it
67       * to be computed can invoke this method before invoking
68       * {@link #getCallerData()}.
69       * 
70       * @return whether this event has caller data
71       */
72      boolean hasCallerData();
73  
74      /**
75       * Returns the first marker is the marker list or null if no markers are
76       * available.
77       * 
78       * This method is deprecated and exists solely for backward compatibility
79       * reasons. Logback components should use {@link #getMarkerList()} and cater for
80       * all available markers and not only the first one.
81       * 
82       * @deprecated Replaced by {@link #getMarkerList()}
83       * @return the first marker in the marker list or null if no markers are
84       *         available
85       */
86      default Marker getMarker() {
87          List<Marker> markers = getMarkerList();
88          if (markers == null || markers.isEmpty())
89              return null;
90  
91          // return the first marker. Assuming that only the first marker is useful
92          // is obviously incorrect. However, we have no other choice if we wish
93          // to preserve binary compatibility.
94          return markers.get(0);
95      }
96  
97      /**
98       * Since SLF4J 2.0.0, the slf4j logging API assumes the possibility of multiple
99       * Marker instances in a logging event. Consequently, ILoggingEvent needs to
100      * cater for this possibility.
101      * 
102      * @return the marker list, may be null
103      * @since 1.3.0
104      */
105     List<Marker> getMarkerList();
106 
107     /**
108      * Returns the MDC map. The returned value can be an empty map but not null.
109      */
110     Map<String, String> getMDCPropertyMap();
111 
112     /**
113      * Synonym for [@link #getMDCPropertyMap}.
114      * 
115      * @deprecated Replaced by [@link #getMDCPropertyMap}
116      */
117     Map<String, String> getMdc();
118 
119     /**
120      * Return the number of elapsed milliseconds since epoch.
121      * 
122      * @return the number of elapsed milliseconds since epoch
123      * @since 1.3
124      */
125     long getTimeStamp();
126 
127     /**
128      * Return the number of elapsed nanoseconds found in {@link #getInstant()}
129      * 
130      * May return -1 if data unavailable.
131      *
132      * @return the number of elapsed nanoseconds as found in {@link #getInstant()}
133      * @since 1.3
134      */
135     int getNanoseconds();
136 
137     /**
138      * Return the {@link java.time.Instant Instant} the event was created.
139      * 
140      * Default implementation returns the instant corresponding to the value returned by @link
141      * {@link #getTimeStamp()}.
142      * 
143      * @return the  {@link java.time.Instant Instant}  the event was created.
144      * @since 1.3
145      */
146     default Instant getInstant() {
147         return Instant.ofEpochMilli(getTimeStamp());
148     }
149 
150     /**
151      * The sequence number associated with this event.
152      * 
153      * <p>
154      * Sequence numbers, if present, should be increasing monotonically.
155      * 
156      * @since 1.3.0
157      */
158     long getSequenceNumber();
159 
160     /**
161      * A list of {@link KeyValuePair} objects. The returned list may be null.
162      * 
163      * @return may be null
164      * @since 1.3.0
165      */
166     List<KeyValuePair> getKeyValuePairs();
167 
168     void prepareForDeferredProcessing();
169 
170 }