001/**
002 * Logback: the reliable, generic, fast and flexible logging framework.
003 * Copyright (C) 1999-2015, QOS.ch. All rights reserved.
004 *
005 * This program and the accompanying materials are dual-licensed under
006 * either the terms of the Eclipse Public License v1.0 as published by
007 * the Eclipse Foundation
008 *
009 *   or (per the licensee's choosing)
010 *
011 * under the terms of the GNU Lesser General Public License version 2.1
012 * as published by the Free Software Foundation.
013 */
014package ch.qos.logback.classic.spi;
015
016import java.time.Instant;
017import java.util.List;
018import java.util.Map;
019
020import org.slf4j.Marker;
021import org.slf4j.event.KeyValuePair;
022
023import ch.qos.logback.classic.Level;
024import ch.qos.logback.core.spi.DeferredProcessingAware;
025
026/**
027 * The central interface in logback-classic. In a nutshell, logback-classic is
028 * nothing more than a processing chain built around this interface.
029 * 
030 * @author Ceki Gülcü
031 * @since 0.9.16
032 */
033public interface ILoggingEvent extends DeferredProcessingAware {
034
035    String getThreadName();
036
037    Level getLevel();
038
039    String getMessage();
040
041    Object[] getArgumentArray();
042
043    String getFormattedMessage();
044
045    String getLoggerName();
046
047    LoggerContextVO getLoggerContextVO();
048
049    IThrowableProxy getThrowableProxy();
050
051    /**
052     * Return caller data associated with this event. Note that calling this event
053     * may trigger the computation of caller data.
054     * 
055     * @return the caller data associated with this event.
056     * 
057     * @see #hasCallerData()
058     */
059    StackTraceElement[] getCallerData();
060
061    /**
062     * If this event has caller data, then true is returned. Otherwise the returned
063     * value is null.
064     * 
065     * <p>
066     * Logback components wishing to use caller data if available without causing it
067     * to be computed can invoke this method before invoking
068     * {@link #getCallerData()}.
069     * 
070     * @return whether this event has caller data
071     */
072    boolean hasCallerData();
073
074    /**
075     * Returns the first marker is the marker list or null if no markers are
076     * available.
077     * 
078     * This method is deprecated and exists solely for backward compatibility
079     * reasons. Logback components should use {@link #getMarkerList()} and cater for
080     * all available markers and not only the first one.
081     * 
082     * @deprecated Replaced by {@link #getMarkerList()}
083     * @return the first marker in the marker list or null if no markers are
084     *         available
085     */
086    default Marker getMarker() {
087        List<Marker> markers = getMarkerList();
088        if (markers == null || markers.isEmpty())
089            return null;
090
091        // return the first marker. Assuming that only the first marker is useful
092        // is obviously incorrect. However, we have no other choice if we wish
093        // to preserve binary compatibility.
094        return markers.get(0);
095    }
096
097    /**
098     * Since SLF4J 2.0.0, the slf4j logging API assumes the possibility of multiple
099     * 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}