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 /**
139 * Returns a builder for creating Async Loggers.
140 * @param name The name of the Logger.
141 * @return A new LoggerComponentBuilder.
142 */
143 LoggerComponentBuilder newAsyncLogger(String name);
144
145 /**
146 * Returns a builder for creating Async Loggers.
147 * @param name The name of the Logger.
148 * @param includeLocation If true include location information.
149 * @return A new LoggerComponentBuilder.
150 */
151 LoggerComponentBuilder newAsyncLogger(String name, boolean includeLocation);
152
153 /**
154 * Returns a builder for creating Async Loggers.
155 * @param name The name of the Logger.
156 * @param level The logging Level to be assigned to the Logger.
157 * @return A new LoggerComponentBuilder.
158 */
159 LoggerComponentBuilder newAsyncLogger(String name, Level level);
160
161 /**
162 * Returns a builder for creating Async Loggers.
163 * @param name The name of the Logger.
164 * @param level The logging Level to be assigned to the Logger.
165 * @param includeLocation If true include location information.
166 * @return A new LoggerComponentBuilder.
167 */
168 LoggerComponentBuilder newAsyncLogger(String name, Level level, boolean includeLocation);
169
170 /**
171 * Returns a builder for creating Async Loggers.
172 * @param name The name of the Logger.
173 * @param level The logging Level to be assigned to the Logger.
174 * @return A new LoggerComponentBuilder.
175 */
176 LoggerComponentBuilder newAsyncLogger(String name, String level);
177
178 /**
179 * Returns a builder for creating Async Loggers.
180 * @param name The name of the Logger.
181 * @param level The logging Level to be assigned to the Logger.
182 * @param includeLocation If true include location information.
183 * @return A new LoggerComponentBuilder.
184 */
185 LoggerComponentBuilder newAsyncLogger(String name, String level, boolean includeLocation);
186
187 /**
188 * Returns a builder for creating the async root Logger.
189 * @return A new RootLoggerComponentBuilder.
190 */
191 RootLoggerComponentBuilder newAsyncRootLogger();
192
193
194 /**
195 * Returns a builder for creating the async root Logger.
196 * @param includeLocation If true include location information.
197 * @return A new RootLoggerComponentBuilder.
198 */
199 RootLoggerComponentBuilder newAsyncRootLogger(boolean includeLocation);
200
201 /**
202 * Returns a builder for creating the async root Logger.
203 * @param level The logging Level to be assigned to the root Logger.
204 * @return A new RootLoggerComponentBuilder.
205 */
206 RootLoggerComponentBuilder newAsyncRootLogger(Level level);
207
208
209 /**
210 * Returns a builder for creating the async root Logger.
211 * @param level The logging Level to be assigned to the root Logger.
212 * @param includeLocation If true include location information.
213 * @return A new RootLoggerComponentBuilder.
214 */
215 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation);
216
217 /**
218 * Returns a builder for creating the async root Logger.
219 * @param level The logging Level to be assigned to the root Logger.
220 * @return A new RootLoggerComponentBuilder.
221 */
222 RootLoggerComponentBuilder newAsyncRootLogger(String level);
223
224
225 /**
226 * Returns a builder for creating the async root Logger.
227 * @param level The logging Level to be assigned to the root Logger.
228 * @param includeLocation If true include location information.
229 * @return A new RootLoggerComponentBuilder.
230 */
231 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation);
232
233 /**
234 * Returns a builder for creating generic components.
235 * @param <B> ComponentBuilder target type
236 * @param pluginName The Plugin type of the component.
237 * @return A new ComponentBuilder.
238 */
239 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName);
240
241 /**
242 * Returns a builder for creating generic components.
243 * @param <B> ComponentBuilder target type
244 * @param name The name of the component (may be null).
245 * @param pluginName The Plugin type of the component.
246 * @return A new ComponentBuilder.
247 */
248 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName);
249
250 /**
251 * Returns a builder for creating generic components.
252 * @param <B> ComponentBuilder target type
253 * @param name The name of the component (may be null).
254 * @param pluginName The Plugin type of the component.
255 * @param value The value of the component.
256 * @return A new ComponentBuilder.
257 */
258 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value);
259
260 /**
261 * Returns a builder for creating Property:s
262 * @param name The name of the property.
263 * @param value The value of the component.
264 * @return A new PropertyComponentBuilder.
265 */
266 PropertyComponentBuilder newProperty(String name, String value);
267
268 /**
269 * Returns a builder for creating KeyValuePair:s
270 * @param key The name
271 * @param value The value
272 * @return A new KeyValuePairComponentBuilder.
273 */
274 KeyValuePairComponentBuilder newKeyValuePair(String key, String value);
275
276 /**
277 * Returns a builder for creating CustomLevels
278 * @param name The name of the custom level.
279 * @param level The integer value to be assigned to the level.
280 * @return A new CustomLevelComponentBuilder.
281 */
282 CustomLevelComponentBuilder newCustomLevel(String name, int level);
283
284 /**
285 * Returns a builder for creating Filters.
286 * @param pluginName The Plugin type of the Filter.
287 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
288 * @param onMismatch "ACCEPT", "DENY", or "NEUTRAL"
289 * @return A new FilterComponentBuilder.
290 */
291 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMismatch);
292
293 /**
294 * Returns a builder for creating Filters.
295 * @param pluginName The Plugin type of the Filter.
296 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
297 * @param onMismatch "ACCEPT", "DENY", or "NEUTRAL"
298 * @return A new FilterComponentBuilder.
299 */
300 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMismatch);
301
302 /**
303 * Returns a builder for creating Layouts.
304 * @param pluginName The Plugin type of the Layout.
305 * @return A new LayoutComponentBuilder.
306 */
307 LayoutComponentBuilder newLayout(String pluginName);
308
309 /**
310 * Returns a builder for creating Loggers.
311 * @param name The name of the Logger.
312 * @return A new LoggerComponentBuilder.
313 */
314 LoggerComponentBuilder newLogger(String name);
315
316 /**
317 * Returns a builder for creating Loggers.
318 * @param name The name of the Logger.
319 * @param includeLocation If true include location information.
320 * @return A new LoggerComponentBuilder.
321 */
322 LoggerComponentBuilder newLogger(String name, boolean includeLocation);
323
324 /**
325 * Returns a builder for creating Loggers.
326 * @param name The name of the Logger.
327 * @param level The logging Level to be assigned to the Logger.
328 * @return A new LoggerComponentBuilder.
329 */
330 LoggerComponentBuilder newLogger(String name, Level level);
331
332 /**
333 * Returns a builder for creating Loggers.
334 * @param name The name of the Logger.
335 * @param level The logging Level to be assigned to the Logger.
336 * @param includeLocation If true include location information.
337 * @return A new LoggerComponentBuilder.
338 */
339 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation);
340
341 /**
342 * Returns a builder for creating Loggers.
343 * @param name The name of the Logger.
344 * @param level The logging Level to be assigned to the Logger.
345 * @return A new LoggerComponentBuilder.
346 */
347 LoggerComponentBuilder newLogger(String name, String level);
348
349 /**
350 * Returns a builder for creating Loggers.
351 * @param name The name of the Logger.
352 * @param level The logging Level to be assigned to the Logger.
353 * @param includeLocation If true include location information.
354 * @return A new LoggerComponentBuilder.
355 */
356 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation);
357
358 /**
359 * Returns a builder for creating the root Logger.
360 * @return A new RootLoggerComponentBuilder.
361 */
362 RootLoggerComponentBuilder newRootLogger();
363
364 /**
365 * Returns a builder for creating the root Logger.
366 * @param includeLocation If true include location information.
367 * @return A new RootLoggerComponentBuilder.
368 */
369 RootLoggerComponentBuilder newRootLogger(boolean includeLocation);
370
371 /**
372 * Returns a builder for creating the root Logger.
373 * @param level The logging Level to be assigned to the root Logger.
374 * @return A new RootLoggerComponentBuilder.
375 */
376 RootLoggerComponentBuilder newRootLogger(Level level);
377
378 /**
379 * Returns a builder for creating the root Logger.
380 * @param level The logging Level to be assigned to the root Logger.
381 * @param includeLocation If true include location information.
382 * @return A new RootLoggerComponentBuilder.
383 */
384 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation);
385
386 /**
387 * Returns a builder for creating the root Logger.
388 * @param level The logging Level to be assigned to the root Logger.
389 *
390 * @return A new RootLoggerComponentBuilder.
391 */
392 RootLoggerComponentBuilder newRootLogger(String level);
393
394 /**
395 * Returns a builder for creating the root Logger.
396 * @param level The logging Level to be assigned to the root Logger.
397 *
398 * @return A new RootLoggerComponentBuilder.
399 */
400 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation);
401
402 /**
403 * Set the Advertiser Plugin name.
404 * @param advertiser The Advertiser Plugin name.
405 * @return this builder instance.
406 */
407 ConfigurationBuilder<T> setAdvertiser(String advertiser);
408
409 /**
410 * Sets the name of the configuration.
411 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}.
412 * @return this builder instance.
413 */
414 ConfigurationBuilder<T> setConfigurationName(String name);
415
416 /**
417 * Sets the configuration source, if one exists.
418 * @param configurationSource the ConfigurationSource.
419 * @return this builder instance.
420 */
421 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource);
422
423 /**
424 * Sets the interval at which the configuration file should be checked for changes.
425 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file.
426 * @return this builder instance.
427 */
428 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds);
429
430 /**
431 * Sets the list of packages to search for plugins.
432 * @param packages The comma separated list of packages.
433 * @return this builder instance.
434 */
435 ConfigurationBuilder<T> setPackages(String packages);
436
437 /**
438 * Sets whether the shutdown hook should be disabled.
439 * @param flag "disable" will prevent the shutdown hook from being set.
440 * @return this builder instance.
441 */
442 ConfigurationBuilder<T> setShutdownHook(String flag);
443
444 /**
445 * How long appenders and background tasks will get to shutdown when the JVM shuts down.
446 * Default is zero which mean that each appender uses its default timeout, and don't wait for background
447 * tasks. Not all appenders will honor this, it is a hint and not an absolute guarantee that the shutdown
448 * procedure will not take longer. Setting this too low increase the risk of losing outstanding log events
449 * not yet written to the final destination. (Not used if {@link #setShutdownHook(String)} is set to "disable".)
450 * @return this builder instance.
451 *
452 * @see LoggerContext#stop(long, TimeUnit)
453 */
454 ConfigurationBuilder<T> setShutdownTimeout(long timeout, TimeUnit timeUnit);
455
456 /**
457 * Sets the level of the StatusLogger.
458 * @param level The logging level.
459 * @return this builder instance.
460 */
461 ConfigurationBuilder<T> setStatusLevel(Level level);
462
463
464 /**
465 * Sets whether the logging should include constructing Plugins.
466 * @param verbosity "disable" will hide messages from plugin construction.
467 * @return this builder instance.
468 */
469 ConfigurationBuilder<T> setVerbosity(String verbosity);
470
471 /**
472 * Specifies the destination for StatusLogger events. This can be {@code out} (default) for using
473 * {@link System#out standard out}, {@code err} for using {@link System#err standard error}, or a file URI to
474 * which log events will be written. If the provided URI is invalid, then the default destination of standard
475 * out will be used.
476 *
477 * @param destination where status log messages should be output.
478 * @return this builder instance.
479 */
480 ConfigurationBuilder<T> setDestination(String destination);
481
482 /**
483 * Sets the logger context.
484 * @param loggerContext the logger context.
485 */
486 void setLoggerContext(LoggerContext loggerContext);
487
488 /**
489 * Add the properties for the root node.
490 * @param key The property key.
491 * @param value The property value.
492 * @return this builder instance.
493 */
494 ConfigurationBuilder<T> addRootProperty(String key, String value);
495
496 /**
497 * Build the configuration and optionally initialize it.
498 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations
499 * should not be initialized when they are constructed.
500 * @return The constructed Configuration.
501 */
502 T build(boolean initialize);
503
504 /**
505 * Constructs an XML configuration from this builder.
506 *
507 * @param output OutputStream to write to, will not be closed
508 *
509 * @since 2.7
510 */
511 void writeXmlConfiguration(OutputStream output) throws IOException;
512
513 /**
514 * Constructs an XML configuration from this builder.
515 *
516 * @return XML configuration
517 *
518 * @since 2.7
519 */
520 String toXmlConfiguration();
521 }