001/**
002 * Copyright (c) 2004-2021 QOS.ch
003 * All rights reserved.
004 *
005 * Permission is hereby granted, free  of charge, to any person obtaining
006 * a  copy  of this  software  and  associated  documentation files  (the
007 * "Software"), to  deal in  the Software without  restriction, including
008 * without limitation  the rights to  use, copy, modify,  merge, publish,
009 * distribute,  sublicense, and/or sell  copies of  the Software,  and to
010 * permit persons to whom the Software  is furnished to do so, subject to
011 * the following conditions:
012 *
013 * The  above  copyright  notice  and  this permission  notice  shall  be
014 * included in all copies or substantial portions of the Software.
015 *
016 * THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
017 * EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
018 * MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
020 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
021 * OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
022 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
023 *
024 */
025package org.slf4j.spi;
026
027import java.util.function.Supplier;
028
029import org.slf4j.Marker;
030
031import org.slf4j.helpers.CheckReturnValue;
032
033/**
034 * This is the main interface in slf4j's fluent API for creating
035 * {@link org.slf4j.event.LoggingEvent logging events}.
036 * 
037 * @author Ceki Gülcü
038 * @since 2.0.0
039 */
040public interface LoggingEventBuilder {
041
042    /**
043     * Set the cause for the logging event being built.
044     * @param cause a throwable
045     * @return a LoggingEventBuilder, usually <b>this</b>.
046     */
047    @CheckReturnValue
048    LoggingEventBuilder setCause(Throwable cause);
049
050    /**
051     * A {@link Marker marker} to the event being built.
052     *
053     * @param marker a Marker instance to add.
054     * @return a LoggingEventBuilder, usually <b>this</b>.
055     */
056    @CheckReturnValue
057    LoggingEventBuilder addMarker(Marker marker);
058
059    /**
060     * Add an argument to the event being built.
061     *
062     * @param p an Object to add.
063     * @return a LoggingEventBuilder, usually <b>this</b>.
064     */
065    @CheckReturnValue
066    LoggingEventBuilder addArgument(Object p);
067
068    /**
069     * Add an argument supplier to the event being built.
070     *
071     * @param objectSupplier an Object supplier to add.
072     * @return a LoggingEventBuilder, usually <b>this</b>.
073     */
074    @CheckReturnValue
075    LoggingEventBuilder addArgument(Supplier<?> objectSupplier);
076
077
078    /**
079     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
080     *
081     * @param key the key of the key value pair.
082     * @param value the value of the key value pair.
083     * @return a LoggingEventBuilder, usually <b>this</b>.
084     */
085    @CheckReturnValue
086    LoggingEventBuilder addKeyValue(String key, Object value);
087
088    /**
089     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
090     *
091     * @param key the key of the key value pair.
092     * @param valueSupplier a supplier of a value for the key value pair.
093     * @return a LoggingEventBuilder, usually <b>this</b>.
094     */
095    @CheckReturnValue
096    LoggingEventBuilder addKeyValue(String key, Supplier<Object> valueSupplier);
097
098    /**
099     *  Sets the message of the logging event.
100     *
101     *  @since 2.0.0-beta0
102     */
103    @CheckReturnValue
104    LoggingEventBuilder setMessage(String message);
105
106    /**
107     * Sets the message of the event via a message supplier.
108     *
109     * @param messageSupplier supplies a String to be used as the message for the event
110     * @since 2.0.0-beta0
111     */
112    @CheckReturnValue
113    LoggingEventBuilder setMessage(Supplier<String> messageSupplier);
114
115    /**
116     * After the logging event is built, performs actual logging. This method must be called
117     * for logging to occur.
118     *
119     * If the call to {@link #log()}  is omitted, a {@link org.slf4j.event.LoggingEvent LoggingEvent}
120     * will be built but no logging will occur.
121     *
122     * @since 2.0.0-beta0
123     */
124    void log();
125
126    /**
127     * Equivalent to calling {@link #setMessage(String)} followed by {@link #log()};
128     *
129     * @param message the message to log
130     */
131    void log(String message);
132
133    /**
134     * Equivalent to calling {@link #setMessage(String)} followed by {@link #addArgument(Object)}}
135     * and then {@link #log()}
136     *
137     * @param message the message to log
138     * @param arg an argument to be used with the message to log
139     */
140    void log(String message, Object arg);
141
142    /**
143     * Equivalent to calling {@link #setMessage(String)} followed by two calls to
144     * {@link #addArgument(Object)} and then {@link #log()}
145     *
146     * @param message the message to log
147     * @param arg0 first argument to be used with the message to log
148     * @param arg1 second argument to be used with the message to log
149     */
150    void log(String message, Object arg0, Object arg1);
151
152
153    /**
154     * Equivalent to calling {@link #setMessage(String)} followed by zero or more calls to
155     * {@link #addArgument(Object)} (depending on the size of args array) and then {@link #log()}
156     *
157     * @param message the message to log
158     * @param args a list (actually an array) of arguments to be used with the message to log
159     */
160    void log(String message, Object... args);
161
162    /**
163     * Equivalent to calling {@link #setMessage(Supplier)} followed by {@link #log()}
164     *
165     * @param messageSupplier a Supplier returning a message of type String
166     */
167    void log(Supplier<String> messageSupplier);
168
169}