1 /** 2 * Copyright (c) 2004-2021 QOS.ch 3 * All rights reserved. 4 * 5 * Permission is hereby granted, free of charge, to any person obtaining 6 * a copy of this software and associated documentation files (the 7 * "Software"), to deal in the Software without restriction, including 8 * without limitation the rights to use, copy, modify, merge, publish, 9 * distribute, sublicense, and/or sell copies of the Software, and to 10 * permit persons to whom the Software is furnished to do so, subject to 11 * the following conditions: 12 * 13 * The above copyright notice and this permission notice shall be 14 * included in all copies or substantial portions of the Software. 15 * 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 17 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 19 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE 20 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 22 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 23 * 24 */ 25 package org.slf4j.spi; 26 27 import java.util.function.Supplier; 28 29 import org.slf4j.Marker; 30 31 import org.slf4j.helpers.CheckReturnValue; 32 33 /** 34 * This is the main interface in slf4j's fluent API for creating 35 * {@link org.slf4j.event.LoggingEvent logging events}. 36 * 37 * @author Ceki Gülcü 38 * @since 2.0.0 39 */ 40 public interface LoggingEventBuilder { 41 42 /** 43 * Set the cause for the logging event being built. 44 * @param cause a throwable 45 * @return a LoggingEventBuilder, usually <b>this</b>. 46 */ 47 @CheckReturnValue setCause(Throwable cause)48 LoggingEventBuilder setCause(Throwable cause); 49 50 /** 51 * A {@link Marker marker} to the event being built. 52 * 53 * @param marker a Marker instance to add. 54 * @return a LoggingEventBuilder, usually <b>this</b>. 55 */ 56 @CheckReturnValue addMarker(Marker marker)57 LoggingEventBuilder addMarker(Marker marker); 58 59 /** 60 * Add an argument to the event being built. 61 * 62 * @param p an Object to add. 63 * @return a LoggingEventBuilder, usually <b>this</b>. 64 */ 65 @CheckReturnValue addArgument(Object p)66 LoggingEventBuilder addArgument(Object p); 67 68 /** 69 * Add an argument supplier to the event being built. 70 * 71 * @param objectSupplier an Object supplier to add. 72 * @return a LoggingEventBuilder, usually <b>this</b>. 73 */ 74 @CheckReturnValue addArgument(Supplier<?> objectSupplier)75 LoggingEventBuilder addArgument(Supplier<?> objectSupplier); 76 77 78 /** 79 * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built. 80 * 81 * @param key the key of the key value pair. 82 * @param value the value of the key value pair. 83 * @return a LoggingEventBuilder, usually <b>this</b>. 84 */ 85 @CheckReturnValue addKeyValue(String key, Object value)86 LoggingEventBuilder addKeyValue(String key, Object value); 87 88 /** 89 * Add a {@link org.slf4j.event.KeyValuePair key value pair} to the event being built. 90 * 91 * @param key the key of the key value pair. 92 * @param valueSupplier a supplier of a value for the key value pair. 93 * @return a LoggingEventBuilder, usually <b>this</b>. 94 */ 95 @CheckReturnValue addKeyValue(String key, Supplier<Object> valueSupplier)96 LoggingEventBuilder addKeyValue(String key, Supplier<Object> valueSupplier); 97 98 /** 99 * Sets the message of the logging event. 100 * 101 * @since 2.0.0-beta0 102 */ 103 @CheckReturnValue setMessage(String message)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 setMessage(Supplier<String> messageSupplier)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 */ log()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 */ log(String message)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 */ log(String message, Object arg)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 */ log(String message, Object arg0, Object arg1)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 */ log(String message, Object... args)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 */ log(Supplier<String> messageSupplier)167 void log(Supplier<String> messageSupplier); 168 169 } 170