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
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
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
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
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
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
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
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 }