1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache license, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the license for the specific language governing permissions and
15 * limitations under the license.
16 */
17 package org.apache.logging.log4j.core.config.builder.api;
18
19 import java.io.IOException;
20 import java.io.OutputStream;
21 import java.util.concurrent.TimeUnit;
22
23 import org.apache.logging.log4j.Level;
24 import org.apache.logging.log4j.core.Filter;
25 import org.apache.logging.log4j.core.LoggerContext;
26 import org.apache.logging.log4j.core.config.Configuration;
27 import org.apache.logging.log4j.core.config.ConfigurationSource;
28 import org.apache.logging.log4j.core.util.Builder;
29
30 /**
31 * Interface for building logging configurations.
32 * @param <T> The Configuration type created by this builder.
33 * @since 2.4
34 */
35 public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> {
36
37
38 /**
39 * Adds a ScriptComponent.
40 * @param builder The ScriptComponentBuilder with all of its attributes and sub components set.
41 * @return this builder instance.
42 */
43 ConfigurationBuilder<T> add(ScriptComponentBuilder builder);
44
45 /**
46 * Adds a ScriptFileComponent.
47 * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set.
48 * @return this builder instance.
49 */
50 ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder);
51
52 /**
53 * Adds an AppenderComponent.
54 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
55 * @return this builder instance.
56 */
57 ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
58
59 /**
60 * Adds a CustomLevel component.
61 * @param builder The CustomLevelComponentBuilder with all of its attributes set.
62 * @return this builder instance.
63 */
64 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
65
66 /**
67 * Adds a Filter component.
68 * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
69 * @return this builder instance.
70 */
71 ConfigurationBuilder<T> add(FilterComponentBuilder builder);
72
73 /**
74 * Adds a Logger component.
75 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
76 * @return this builder instance.
77 */
78 ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
79
80 /**
81 * Adds the root Logger component.
82 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
83 * @return this builder instance.
84 */
85 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
86
87 /**
88 * Adds a Property key and value.
89 * @param key The property key.
90 * @param value The property value.
91 * @return this builder instance.
92 */
93 ConfigurationBuilder<T> addProperty(String key, String value);
94
95
96 /**
97 * Returns a builder for creating Async Loggers.
98 * @param name The name of the Logger.
99 * @param language The script language
100 * @param text The script to execute.
101 * @return A new ScriptComponentBuilder.
102 */
103 ScriptComponentBuilder newScript(String name, String language, String text);
104
105 /**
106 * Returns a builder for creating Async Loggers.
107 * @param path The location of the script file.
108 * @return A new ScriptFileComponentBuilder.
109 */
110 ScriptFileComponentBuilder newScriptFile(String path);
111
112
113 /**
114 * Returns a builder for creating Async Loggers.
115 * @param name The name of the script file.
116 * @param path The location of the script file.
117 * @return A new ScriptFileComponentBuilder.
118 */
119 ScriptFileComponentBuilder newScriptFile(String name, String path);
120
121
122 /**
123 * Returns a builder for creating Appenders.
124 * @param name The name of the Appender.
125 * @param pluginName The Plugin type of the Appender.
126 * @return A new AppenderComponentBuilder.
127 */
128 AppenderComponentBuilder newAppender(String name, String pluginName);
129
130 /**
131 * Returns a builder for creating AppenderRefs.
132 * @param ref The name of the Appender being referenced.
133 * @return A new AppenderRefComponentBuilder.
134 */
135 AppenderRefComponentBuilder newAppenderRef(String ref);
136
137 /**
138 * Returns a builder for creating Async Loggers.
139 * @param name The name of the Logger.
140 * @param level The logging Level to be assigned to the Logger.
141 * @return A new LoggerComponentBuilder.
142 */
143 LoggerComponentBuilder newAsyncLogger(String name, Level level);
144
145 /**
146 * Returns a builder for creating Async Loggers.
147 * @param name The name of the Logger.
148 * @param level The logging Level to be assigned to the Logger.
149 * @param includeLocation If true include location information.
150 * @return A new LoggerComponentBuilder.
151 */
152 LoggerComponentBuilder newAsyncLogger(String name, Level level, boolean includeLocation);
153
154 /**
155 * Returns a builder for creating Async Loggers.
156 * @param name The name of the Logger.
157 * @param level The logging Level to be assigned to the Logger.
158 * @return A new LoggerComponentBuilder.
159 */
160 LoggerComponentBuilder newAsyncLogger(String name, String level);
161
162 /**
163 * Returns a builder for creating Async Loggers.
164 * @param name The name of the Logger.
165 * @param level The logging Level to be assigned to the Logger.
166 * @param includeLocation If true include location information.
167 * @return A new LoggerComponentBuilder.
168 */
169 LoggerComponentBuilder newAsyncLogger(String name, String level, boolean includeLocation);
170
171 /**
172 * Returns a builder for creating the async root Logger.
173 * @param level The logging Level to be assigned to the root Logger.
174 * @return A new RootLoggerComponentBuilder.
175 */
176 RootLoggerComponentBuilder newAsyncRootLogger(Level level);
177
178
179 /**
180 * Returns a builder for creating the async root Logger.
181 * @param level The logging Level to be assigned to the root Logger.
182 * @param includeLocation If true include location information.
183 * @return A new RootLoggerComponentBuilder.
184 */
185 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation);
186
187 /**
188 * Returns a builder for creating the async root Logger.
189 * @param level The logging Level to be assigned to the root Logger.
190 * @return A new RootLoggerComponentBuilder.
191 */
192 RootLoggerComponentBuilder newAsyncRootLogger(String level);
193
194
195 /**
196 * Returns a builder for creating the async root Logger.
197 * @param level The logging Level to be assigned to the root Logger.
198 * @param includeLocation If true include location information.
199 * @return A new RootLoggerComponentBuilder.
200 */
201 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation);
202
203 /**
204 * Returns a builder for creating generic components.
205 * @param <B> ComponentBuilder target type
206 * @param pluginName The Plugin type of the component.
207 * @return A new ComponentBuilder.
208 */
209 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName);
210
211 /**
212 * Returns a builder for creating generic components.
213 * @param <B> ComponentBuilder target type
214 * @param name The name of the component (may be null).
215 * @param pluginName The Plugin type of the component.
216 * @return A new ComponentBuilder.
217 */
218 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName);
219
220 /**
221 * Returns a builder for creating generic components.
222 * @param <B> ComponentBuilder target type
223 * @param name The name of the component (may be null).
224 * @param pluginName The Plugin type of the component.
225 * @param value The value of the component.
226 * @return A new ComponentBuilder.
227 */
228 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value);
229
230 /**
231 * Returns a builder for creating Property:s
232 * @param name The name of the property.
233 * @param value The value of the component.
234 * @return A new PropertyComponentBuilder.
235 */
236 PropertyComponentBuilder newProperty(String name, String value);
237
238 /**
239 * Returns a builder for creating KeyValuePair:s
240 * @param key The name
241 * @param value The value
242 * @return A new KeyValuePairComponentBuilder.
243 */
244 KeyValuePairComponentBuilder newKeyValuePair(String key, String value);
245
246 /**
247 * Returns a builder for creating CustomLevels
248 * @param name The name of the custom level.
249 * @param level The integer value to be assigned to the level.
250 * @return A new CustomLevelComponentBuilder.
251 */
252 CustomLevelComponentBuilder newCustomLevel(String name, int level);
253
254 /**
255 * Returns a builder for creating Filters.
256 * @param pluginName The Plugin type of the Filter.
257 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
258 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
259 * @return A new FilterComponentBuilder.
260 */
261 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch);
262
263 /**
264 * Returns a builder for creating Filters.
265 * @param pluginName The Plugin type of the Filter.
266 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
267 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
268 * @return A new FilterComponentBuilder.
269 */
270 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch);
271
272 /**
273 * Returns a builder for creating Layouts.
274 * @param pluginName The Plugin type of the Layout.
275 * @return A new LayoutComponentBuilder.
276 */
277 LayoutComponentBuilder newLayout(String pluginName);
278
279 /**
280 * Returns a builder for creating Loggers.
281 * @param name The name of the Logger.
282 * @param level The logging Level to be assigned to the Logger.
283 * @return A new LoggerComponentBuilder.
284 */
285 LoggerComponentBuilder newLogger(String name, Level level);
286
287 /**
288 * Returns a builder for creating Loggers.
289 * @param name The name of the Logger.
290 * @param level The logging Level to be assigned to the Logger.
291 * @param includeLocation If true include location information.
292 * @return A new LoggerComponentBuilder.
293 */
294 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation);
295
296 /**
297 * Returns a builder for creating Loggers.
298 * @param name The name of the Logger.
299 * @param level The logging Level to be assigned to the Logger.
300 * @return A new LoggerComponentBuilder.
301 */
302 LoggerComponentBuilder newLogger(String name, String level);
303
304 /**
305 * Returns a builder for creating Loggers.
306 * @param name The name of the Logger.
307 * @param level The logging Level to be assigned to the Logger.
308 * @param includeLocation If true include location information.
309 * @return A new LoggerComponentBuilder.
310 */
311 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation);
312
313 /**
314 * Returns a builder for creating the root Logger.
315 * @param level The logging Level to be assigned to the root Logger.
316 * @return A new RootLoggerComponentBuilder.
317 */
318 RootLoggerComponentBuilder newRootLogger(Level level);
319
320 /**
321 * Returns a builder for creating the root Logger.
322 * @param level The logging Level to be assigned to the root Logger.
323 * @param includeLocation If true include location information.
324 * @return A new RootLoggerComponentBuilder.
325 */
326 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation);
327
328 /**
329 * Returns a builder for creating the root Logger.
330 * @param level The logging Level to be assigned to the root Logger.
331 *
332 * @return A new RootLoggerComponentBuilder.
333 */
334 RootLoggerComponentBuilder newRootLogger(String level);
335
336 /**
337 * Returns a builder for creating the root Logger.
338 * @param level The logging Level to be assigned to the root Logger.
339 *
340 * @return A new RootLoggerComponentBuilder.
341 */
342 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation);
343
344 /**
345 * Set the Advertiser Plugin name.
346 * @param advertiser The Advertiser Plugin name.
347 * @return this builder instance.
348 */
349 ConfigurationBuilder<T> setAdvertiser(String advertiser);
350
351 /**
352 * Sets the name of the configuration.
353 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}.
354 * @return this builder instance.
355 */
356 ConfigurationBuilder<T> setConfigurationName(String name);
357
358 /**
359 * Sets the configuration source, if one exists.
360 * @param configurationSource the ConfigurationSource.
361 * @return this builder instance.
362 */
363 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource);
364
365 /**
366 * Sets the interval at which the configuration file should be checked for changes.
367 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file.
368 * @return this builder instance.
369 */
370 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds);
371
372 /**
373 * Sets the list of packages to search for plugins.
374 * @param packages The comma separated list of packages.
375 * @return this builder instance.
376 */
377 ConfigurationBuilder<T> setPackages(String packages);
378
379 /**
380 * Sets whether the shutdown hook should be disabled.
381 * @param flag "disable" will prevent the shutdown hook from being set.
382 * @return this builder instance.
383 */
384 ConfigurationBuilder<T> setShutdownHook(String flag);
385
386 /**
387 * How long appenders and background tasks will get to shutdown when the JVM shuts down.
388 * Default is zero which mean that each appender uses its default timeout, and don't wait for background
389 * tasks. Not all appenders will honor this, it is a hint and not an absolute guarantee that the shutdown
390 * procedure will not take longer. Setting this too low increase the risk of losing outstanding log events
391 * not yet written to the final destination. (Not used if {@link #setShutdownHook(String)} is set to "disable".)
392 * @return this builder instance.
393 *
394 * @see LoggerContext#stop(long, TimeUnit)
395 */
396 ConfigurationBuilder<T> setShutdownTimeout(long timeout, TimeUnit timeUnit);
397
398 /**
399 * Sets the level of the StatusLogger.
400 * @param level The logging level.
401 * @return this builder instance.
402 */
403 ConfigurationBuilder<T> setStatusLevel(Level level);
404
405
406 /**
407 * Sets whether the logging should include constructing Plugins.
408 * @param verbosity "disable" will hide messages from plugin construction.
409 * @return this builder instance.
410 */
411 ConfigurationBuilder<T> setVerbosity(String verbosity);
412
413 /**
414 * Specifies the destination for StatusLogger events. This can be {@code out} (default) for using
415 * {@link System#out standard out}, {@code err} for using {@link System#err standard error}, or a file URI to
416 * which log events will be written. If the provided URI is invalid, then the default destination of standard
417 * out will be used.
418 *
419 * @param destination where status log messages should be output.
420 * @return this builder instance.
421 */
422 ConfigurationBuilder<T> setDestination(String destination);
423
424 /**
425 * Sets the logger context.
426 * @param loggerContext the logger context.
427 */
428 void setLoggerContext(LoggerContext loggerContext);
429
430 /**
431 * Add the properties for the root node.
432 * @param key The property key.
433 * @param value The property value.
434 * @return this builder instance.
435 */
436 ConfigurationBuilder<T> addRootProperty(String key, String value);
437
438 /**
439 * Build the configuration and optionally initialize it.
440 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations
441 * should not be initialized when they are constructed.
442 * @return The constructed Configuration.
443 */
444 T build(boolean initialize);
445
446 /**
447 * Constructs an XML configuration from this builder.
448 *
449 * @param output OutputStream to write to, will not be closed
450 *
451 * @since 2.7
452 */
453 void writeXmlConfiguration(OutputStream output) throws IOException;
454
455 /**
456 * Constructs an XML configuration from this builder.
457 *
458 * @return XML configuration
459 *
460 * @since 2.7
461 */
462 String toXmlConfiguration();
463 }