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 central interface in slf4j's fluent API for creating
035 * {@link org.slf4j.event.LoggingEvent logging events}.
036 *
037 *
038 * @author Ceki Gülcü
039 * @since 2.0.0
040 */
041public interface LoggingEventBuilder {
042
043    /**
044     * Set the cause for the logging event being built.
045     * @param cause a throwable
046     * @return a LoggingEventBuilder instance, usually <b>this</b>.
047     */
048    @CheckReturnValue
049    LoggingEventBuilder setCause(Throwable cause);
050
051    /**
052     * A {@link Marker marker} to the event being built.
053     *
054     * @param marker a Marker instance to add.
055     * @return a LoggingEventBuilder instance, usually <b>this</b>.
056     */
057    @CheckReturnValue
058    LoggingEventBuilder addMarker(Marker marker);
059
060    /**
061     * Add an argument to the event being built.
062     * Synonymous with {@link #arg(Object)} method.
063     *
064     * @param p an Object to add.
065     * @return a LoggingEventBuilder instance, usually <b>this</b>.
066     */
067    @CheckReturnValue
068    LoggingEventBuilder addArgument(Object p);
069
070    /**
071     * Add an argument to the event being built.
072     * Synonymous with {@link #addArgument(Object)} method.
073     *
074     * @param p an Object to add.
075     * @return a LoggingEventBuilder instance, usually <b>this</b>.
076     * @since  2.1.0
077     */
078    @CheckReturnValue
079    default LoggingEventBuilder arg(Object p) {
080        return addArgument(p);
081    }
082
083    /**
084     * <p>Add an argument supplier to the event being built.
085     * Synonymous with {@link #arg(Supplier)} method.
086     *  </p>
087     * @param objectSupplier an Object supplier to add.
088     * @return a LoggingEventBuilder instance, usually <b>this</b>.
089     */
090    @CheckReturnValue
091    LoggingEventBuilder addArgument(Supplier<?> objectSupplier);
092
093
094    /**
095     * <p>Add an argument supplier to the event being built.
096     * Synonymous with {@link #addArgument(Supplier)} method.
097     * </p>
098     *
099     * @param objectSupplier an Object supplier to add.
100     * @return a LoggingEventBuilder instance, usually <b>this</b>.
101     * @since 2.1.0
102     */
103    @CheckReturnValue
104    default LoggingEventBuilder arg(Supplier<?> objectSupplier) {
105        return addArgument(objectSupplier);
106    }
107
108    /**
109     * Add a value of type <code>boolean</code> to the event being built.
110     *
111     * <p>The default implementation simply casts to <code>Boolean</code>. However, the NOP implementation, i.e.
112     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
113     *
114     * @param b a value of type <code>boolean</code> value to add.
115     * @return a LoggingEventBuilder instance, usually <b>this</b>.
116     * @since  2.1.0
117     */
118    default public LoggingEventBuilder arg(boolean b) {
119        return addArgument((Boolean) b);
120    }
121
122    /**
123     * Add a value of type <code>char</code> to the event being built.
124     *
125     * <p>The default implementation simply casts to <code>Character</code>. However, the NOP implementation, i.e.
126     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
127     *
128     * @param c a value of type <code>char</code> value to add.
129     * @return a LoggingEventBuilder instance, usually <b>this</b>.
130     * @since  2.1.0
131     */
132    default public LoggingEventBuilder arg(char c) {
133        return addArgument((Character) c);
134    }
135
136    /**
137     * Add a value of type <code>byte</code> to the event being built.
138     *
139     * <p>The default implementation simply casts to <code>Byte</code>. However, the NOP implementation, i.e.
140     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
141     *
142     * @param b a value of type <code>byte</code> value to add.
143     * @return a LoggingEventBuilder instance, usually <b>this</b>.
144     * @since  2.1.0
145     */
146    default public LoggingEventBuilder arg(byte b) {
147        return addArgument((Byte) b);
148    }
149
150    /**
151     * Add a value of type <code>short</code> to the event being built.
152     *
153     * <p>The default implementation simply casts to <code>Short</code>. However, the NOP implementation, i.e.
154     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
155     *
156     * @param s a value of type <code>short</code> value to add.
157     * @return a LoggingEventBuilder instance, usually <b>this</b>.
158     * @since  2.1.0
159     */
160    default public LoggingEventBuilder arg(short s) {
161        return addArgument((Short) s);
162    }
163
164    /**
165     * Add a value of type <code>int</code> to the event being built.
166     *
167     * <p>The default implementation simply casts to <code>Integer</code>. However, the NOP implementation, i.e.
168     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
169     *
170     * @param i a value of type <code>int</code> value to add.
171     * @return a LoggingEventBuilder instance, usually <b>this</b>.
172     * @since  2.1.0
173     */
174    default public LoggingEventBuilder arg(int i) {
175        return addArgument((Integer) i);
176    }
177
178    /**
179     * Add a value of type <code>long</code> to the event being built.
180     *
181     * <p>The default implementation simply casts to <code>Long</code>. However, the NOP implementation, i.e.
182     *  {@link NOPLoggingEventBuilder}, skips the cast.</p>
183     *
184     * @param l a value of type <code>long</code> value to add.
185     * @return a LoggingEventBuilder instance, usually <b>this</b>.
186     * @since  2.1.0
187     */
188    default public LoggingEventBuilder arg(long l) {
189        return addArgument((Long) l);
190    }
191
192    /**
193     * Add a value of type <code>float</code> to the event being built.
194     *
195     * <p>The default implementation simply casts to <code>Float</code>. However, the NOP implementation, i.e.
196     * {@link NOPLoggingEventBuilder}, skips the cast.</p>
197     *
198     * @param f a value of type <code>float</code> value to add.
199     * @return a LoggingEventBuilder instance, usually <b>this</b>.
200     * @since  2.1.0
201     */
202    default public LoggingEventBuilder arg(float f) {
203        return addArgument((Float) f);
204    }
205
206    /**
207     * Add a value of type <code>double</code> to the event being built.
208     *
209     * <p>The default implementation simply casts to <code>Double</code>. However, the NOP implementation skips the cast.</p>
210     *
211     * @param d a value of type  <code>double</code> value to add.
212     * @return a LoggingEventBuilder instance, usually <b>this</b>.
213     * @since  2.1.0
214     */
215    default LoggingEventBuilder arg(double d) {
216        return arg((Double) d);
217    }
218
219
220    /**
221     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
222     *
223     * @param key the key of the key value pair.
224     * @param value the value of the key value pair.
225     * @return a LoggingEventBuilder instance, usually <b>this</b>.
226     */
227    @CheckReturnValue
228    LoggingEventBuilder addKeyValue(String key, Object value);
229
230    /**
231     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
232     * Synonymous with {@link #addKeyValue(String, Object)}  method.
233     *
234     * @param key the key of the key value pair.
235     * @param value the value of the key value pair.
236     * @return a LoggingEventBuilder instance, usually <b>this</b>.
237     *
238     * @since 2.1.0
239     */
240    @CheckReturnValue
241    default LoggingEventBuilder kv(String key, Object value) {
242        return addKeyValue(key,value);
243    }
244
245
246    /**
247     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
248     *
249     * @param key the key of the key value pair.
250     * @param valueSupplier a supplier of a value for the key value pair.
251     * @return a LoggingEventBuilder instance, usually <b>this</b>.
252     */
253    @CheckReturnValue
254    LoggingEventBuilder addKeyValue(String key, Supplier<Object> valueSupplier);
255
256    /**
257     * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built.
258     * Synonymous with {@link #addKeyValue(String, Supplier)} method.
259     *
260     * @param key the key of the key value pair.
261     * @param valueSupplier a supplier of a value for the key value pair.
262     * @return a LoggingEventBuilder instance, usually <b>this</b>.
263     *
264     * @since 2.1.0
265     */
266    @CheckReturnValue
267    default LoggingEventBuilder kv(String key, Supplier<Object> valueSupplier) {
268        return addKeyValue(key, valueSupplier);
269    }
270
271
272    /**
273     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
274     * of type <code>boolean</code>.
275     * </p>
276     * <p></p>
277     * <p>The default implementation simply casts to value part to <code>Boolean</code> before calling
278     * {@link #addKeyValue(String, Object)}. However, the
279     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
280     *
281     * @param key the key of the key value pair.
282     * @param  b the value of type <code>boolean</code> of the key value pair.
283     * @return a LoggingEventBuilder instance, usually <b>this</b>.
284     *
285     * @since 2.1.0
286     */
287    default public LoggingEventBuilder kv(String key, boolean b) {
288        return addKeyValue(key, (Boolean) b);
289    }
290
291    /**
292     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
293     * of type <code>char</code>.
294     * </p>
295     * <p></p>
296     * <p>The default implementation simply casts to value part to <code>Character</code> before calling
297     * {@link #addKeyValue(String, Object)}. However, the
298     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
299     *
300     * @param key the key of the key value pair.
301     * @param c the value of type <code>char</code> of the key value pair.
302     * @return a LoggingEventBuilder instance, usually <b>this</b>.
303     *
304     * @since 2.1.0
305     */
306    default public LoggingEventBuilder kv(String key, char c) {
307        return addKeyValue(key, (Character) c);
308    }
309
310    /**
311     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
312     * of type <code>byte</code>.
313     * </p>
314     * <p></p>
315     * <p>The default implementation simply casts to value part to <code>Byte</code> before calling
316     * {@link #addKeyValue(String, Object)}. However, the
317     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
318     *
319     * @param key the key of the key value pair.
320     * @param b the value of type <code>byte</code> of the key value pair.
321     * @return a LoggingEventBuilder instance, usually <b>this</b>.
322     *
323     * @since 2.1.0
324     */
325    default public LoggingEventBuilder kv(String key, byte b) {
326        return addKeyValue(key, (Byte) b);
327    }
328
329    /**
330     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
331     * of type <code>short</code>.
332     * </p>
333     * <p></p>
334     * <p>The default implementation simply casts to value part to <code>Short</code> before calling
335     * {@link #addKeyValue(String, Object)}. However, the
336     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
337     *
338     * @param key the key of the key value pair.
339     * @param s the value of type <code>short</code> of the key value pair.
340     * @return a LoggingEventBuilder instance, usually <b>this</b>.
341     *
342     * @since 2.1.0
343     */
344    default public LoggingEventBuilder kv(String key, short s) {
345        return addKeyValue(key, (Short) s);
346    }
347
348
349
350    /**
351     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
352     * of type <code>int</code>.
353     * </p>
354     * <p></p>
355     * <p>The default implementation simply casts to value part to <code>Integer</code> before calling
356     * {@link #addKeyValue(String, Object)}. However, the
357     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
358     *
359     * @param key the key of the key value pair.
360     * @param i the value of type <code>int</code> of the key value pair.
361     * @return a LoggingEventBuilder instance, usually <b>this</b>.
362     *
363     * @since 2.1.0
364     */
365    default public LoggingEventBuilder kv(String key, int i) {
366        return addKeyValue(key, (Integer) i);
367    }
368
369    /**
370     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
371     * of type <code>long</code>.
372     * </p>
373     * <p></p>
374     * <p>The default implementation simply casts to value part to <code>Integer</code> before calling
375     * {@link #addKeyValue(String, Object)}. However, the
376     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
377     *
378     * @param key the key of the key value pair.
379     * @param l the value of type <code>long</code> of the key value pair.
380     * @return a LoggingEventBuilder instance, usually <b>this</b>.
381     *
382     * @since 2.1.0
383     */
384    default public LoggingEventBuilder kv(String key, long l) {
385        return addKeyValue(key, (Long) l);
386    }
387
388    /**
389     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
390     * of type <code>float</code>.
391     * </p>
392     * <p></p>
393     * <p>The default implementation simply casts to value part to <code>Float</code> before calling
394     * {@link #addKeyValue(String, Object)}. However, the
395     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
396     *
397     * @param key the key of the key value pair.
398     * @param f the value of type <code>float</code> of the key value pair.
399     * @return a LoggingEventBuilder instance, usually <b>this</b>.
400     *
401     * @since 2.1.0
402     */
403    default public LoggingEventBuilder kv(String key, float f) {
404        return addKeyValue(key, (Float) f);
405    }
406
407    /**
408     * <p>Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built, with the value part being
409     * of type <code>double</code>.
410     * </p>
411     * <p></p>
412     * <p>The default implementation simply casts to value part to <code>Double</code> before calling
413     * {@link #addKeyValue(String, Object)}. However, the
414     * NOP implementation, i.e {@link NOPLoggingEventBuilder}, skips the cast.</p>
415     *
416     * @param key the key of the key value pair.
417     * @param f the value of type <code>double</code> of the key value pair.
418     * @return a LoggingEventBuilder instance, usually <b>this</b>.
419     *
420     * @since 2.1.0
421     */
422    default public LoggingEventBuilder kv(String key, double f) {
423        return addKeyValue(key, (Double) f);
424    }
425
426    /**
427     *  Sets the message of the logging event.
428     *
429     * @param message the message of the event
430     * @return a LoggingEventBuilder instance, usually <b>this</b>.
431     * @since 2.0.0
432     */
433    @CheckReturnValue
434    LoggingEventBuilder setMessage(String message);
435
436    /**
437     * Sets the message of the event via a message supplier.
438     *
439     * @param messageSupplier supplies a String to be used as the message for the event
440     * @return a LoggingEventBuilder instance, usually <b>this</b>.
441     * @since 2.0.0-beta0
442     */
443    @CheckReturnValue
444    LoggingEventBuilder setMessage(Supplier<String> messageSupplier);
445
446    /**
447     * After the logging event is built, performs actual logging. This method must be called
448     * for logging to occur.
449     *
450     * If the call to {@link #log()}  is omitted, a {@link org.slf4j.event.LoggingEvent LoggingEvent}
451     * will be built but no logging will occur.
452     *
453     * @since 2.0.0-beta0
454     */
455    void log();
456
457    /**
458     * Equivalent to calling {@link #setMessage(String)} followed by {@link #log()};
459     *
460     * @param message the message to log
461     */
462    void log(String message);
463
464    /**
465     * Equivalent to calling {@link #setMessage(String)} followed by {@link #addArgument(Object)}}
466     * and then {@link #log()}
467     *
468     * @param message the message to log
469     * @param arg an argument to be used with the message to log
470     */
471    void log(String message, Object arg);
472
473    /**
474     * Equivalent to calling {@link #setMessage(String)} followed by two calls to
475     * {@link #addArgument(Object)} and then {@link #log()}
476     *
477     * @param message the message to log
478     * @param arg0 first argument to be used with the message to log
479     * @param arg1 second argument to be used with the message to log
480     */
481    void log(String message, Object arg0, Object arg1);
482
483
484    /**
485     * Equivalent to calling {@link #setMessage(String)} followed by zero or more calls to
486     * {@link #addArgument(Object)} (depending on the size of args array) and then {@link #log()}
487     *
488     * @param message the message to log
489     * @param args a list (actually an array) of arguments to be used with the message to log
490     */
491    void log(String message, Object... args);
492
493    /**
494     * Equivalent to calling {@link #setMessage(Supplier)} followed by {@link #log()}
495     *
496     * @param messageSupplier a Supplier returning a message of type String
497     */
498    void log(Supplier<String> messageSupplier);
499
500}