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
22 import org.apache.logging.log4j.Level;
23 import org.apache.logging.log4j.core.Filter;
24 import org.apache.logging.log4j.core.LoggerContext;
25 import org.apache.logging.log4j.core.config.Configuration;
26 import org.apache.logging.log4j.core.config.ConfigurationSource;
27 import org.apache.logging.log4j.core.util.Builder;
28
29 /**
30 * Interface for building logging configurations.
31 * @param <T> The Configuration type created by this builder.
32 * @since 2.4
33 */
34 public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> {
35
36
37 /**
38 * Adds a ScriptComponent.
39 * @param builder The ScriptComponentBuilder with all of its attributes and sub components set.
40 * @return this builder instance.
41 */
42 ConfigurationBuilder<T> add(ScriptComponentBuilder builder);
43
44 /**
45 * Adds a ScriptFileComponent.
46 * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set.
47 * @return this builder instance.
48 */
49 ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder);
50
51 /**
52 * Adds an AppenderComponent.
53 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
54 * @return this builder instance.
55 */
56 ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
57
58 /**
59 * Adds a CustomLevel component.
60 * @param builder The CustomLevelComponentBuilder with all of its attributes set.
61 * @return this builder instance.
62 */
63 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
64
65 /**
66 * Adds a Filter component.
67 * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
68 * @return this builder instance.
69 */
70 ConfigurationBuilder<T> add(FilterComponentBuilder builder);
71
72 /**
73 * Adds a Logger component.
74 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
75 * @return this builder instance.
76 */
77 ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
78
79 /**
80 * Adds the root Logger component.
81 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
82 * @return this builder instance.
83 */
84 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
85
86 /**
87 * Adds a Property key and value.
88 * @param key The property key.
89 * @param value The property value.
90 * @return this builder instance.
91 */
92 ConfigurationBuilder<T> addProperty(String key, String value);
93
94
95 /**
96 * Returns a builder for creating Async Loggers.
97 * @param name The name of the Logger.
98 * @param language The script language
99 * @param text The script to execute.
100 * @return A new ScriptComponentBuilder.
101 */
102 ScriptComponentBuilder newScript(String name, String language, String text);
103
104 /**
105 * Returns a builder for creating Async Loggers.
106 * @param path The location of the script file.
107 * @return A new ScriptFileComponentBuilder.
108 */
109 ScriptFileComponentBuilder newScriptFile(String path);
110
111
112 /**
113 * Returns a builder for creating Async Loggers.
114 * @param name The name of the script file.
115 * @param path The location of the script file.
116 * @return A new ScriptFileComponentBuilder.
117 */
118 ScriptFileComponentBuilder newScriptFile(String name, String path);
119
120
121 /**
122 * Returns a builder for creating Appenders.
123 * @param name The name of the Appender.
124 * @param pluginName The Plugin type of the Appender.
125 * @return A new AppenderComponentBuilder.
126 */
127 AppenderComponentBuilder newAppender(String name, String pluginName);
128
129 /**
130 * Returns a builder for creating AppenderRefs.
131 * @param ref The name of the Appender being referenced.
132 * @return A new AppenderRefComponentBuilder.
133 */
134 AppenderRefComponentBuilder newAppenderRef(String ref);
135
136 /**
137 * Returns a builder for creating Async Loggers.
138 * @param name The name of the Logger.
139 * @param level The logging Level to be assigned to the Logger.
140 * @return A new LoggerComponentBuilder.
141 */
142 LoggerComponentBuilder newAsyncLogger(String name, Level level);
143
144 /**
145 * Returns a builder for creating Async Loggers.
146 * @param name The name of the Logger.
147 * @param level The logging Level to be assigned to the Logger.
148 * @param includeLocation If true include location information.
149 * @return A new LoggerComponentBuilder.
150 */
151 LoggerComponentBuilder newAsyncLogger(String name, Level level, 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, String 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, String level, boolean includeLocation);
169
170 /**
171 * Returns a builder for creating the async root Logger.
172 * @param level The logging Level to be assigned to the root Logger.
173 * @return A new RootLoggerComponentBuilder.
174 */
175 RootLoggerComponentBuilder newAsyncRootLogger(Level level);
176
177
178 /**
179 * Returns a builder for creating the async root Logger.
180 * @param level The logging Level to be assigned to the root Logger.
181 * @param includeLocation If true include location information.
182 * @return A new RootLoggerComponentBuilder.
183 */
184 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation);
185
186 /**
187 * Returns a builder for creating the async root Logger.
188 * @param level The logging Level to be assigned to the root Logger.
189 * @return A new RootLoggerComponentBuilder.
190 */
191 RootLoggerComponentBuilder newAsyncRootLogger(String level);
192
193
194 /**
195 * Returns a builder for creating the async root Logger.
196 * @param level The logging Level to be assigned to the root Logger.
197 * @param includeLocation If true include location information.
198 * @return A new RootLoggerComponentBuilder.
199 */
200 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation);
201
202 /**
203 * Returns a builder for creating generic components.
204 * @param <B> ComponentBuilder target type
205 * @param pluginName The Plugin type of the component.
206 * @return A new ComponentBuilder.
207 */
208 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName);
209
210 /**
211 * Returns a builder for creating generic components.
212 * @param <B> ComponentBuilder target type
213 * @param name The name of the component (may be null).
214 * @param pluginName The Plugin type of the component.
215 * @return A new ComponentBuilder.
216 */
217 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName);
218
219 /**
220 * Returns a builder for creating generic components.
221 * @param <B> ComponentBuilder target type
222 * @param name The name of the component (may be null).
223 * @param pluginName The Plugin type of the component.
224 * @param value The value of the component.
225 * @return A new ComponentBuilder.
226 */
227 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value);
228
229
230 /**
231 * Returns a builder for creating CustomLevels
232 * @param name The name of the custom level.
233 * @param level The integer value to be assigned to the level.
234 * @return A new CustomLevelComponentBuilder.
235 */
236 CustomLevelComponentBuilder newCustomLevel(String name, int level);
237
238 /**
239 * Returns a builder for creating Filters.
240 * @param pluginName The Plugin type of the Filter.
241 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
242 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
243 * @return A new FilterComponentBuilder.
244 */
245 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch);
246
247 /**
248 * Returns a builder for creating Filters.
249 * @param pluginName The Plugin type of the Filter.
250 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
251 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
252 * @return A new FilterComponentBuilder.
253 */
254 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch);
255
256 /**
257 * Returns a builder for creating Layouts.
258 * @param pluginName The Plugin type of the Layout.
259 * @return A new LayoutComponentBuilder.
260 */
261 LayoutComponentBuilder newLayout(String pluginName);
262
263 /**
264 * Returns a builder for creating Loggers.
265 * @param name The name of the Logger.
266 * @param level The logging Level to be assigned to the Logger.
267 * @return A new LoggerComponentBuilder.
268 */
269 LoggerComponentBuilder newLogger(String name, Level level);
270
271 /**
272 * Returns a builder for creating Loggers.
273 * @param name The name of the Logger.
274 * @param level The logging Level to be assigned to the Logger.
275 * @param includeLocation If true include location information.
276 * @return A new LoggerComponentBuilder.
277 */
278 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation);
279
280 /**
281 * Returns a builder for creating Loggers.
282 * @param name The name of the Logger.
283 * @param level The logging Level to be assigned to the Logger.
284 * @return A new LoggerComponentBuilder.
285 */
286 LoggerComponentBuilder newLogger(String name, String level);
287
288 /**
289 * Returns a builder for creating Loggers.
290 * @param name The name of the Logger.
291 * @param level The logging Level to be assigned to the Logger.
292 * @param includeLocation If true include location information.
293 * @return A new LoggerComponentBuilder.
294 */
295 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation);
296
297 /**
298 * Returns a builder for creating the root Logger.
299 * @param level The logging Level to be assigned to the root Logger.
300 * @return A new RootLoggerComponentBuilder.
301 */
302 RootLoggerComponentBuilder newRootLogger(Level level);
303
304 /**
305 * Returns a builder for creating the root Logger.
306 * @param level The logging Level to be assigned to the root Logger.
307 * @param includeLocation If true include location information.
308 * @return A new RootLoggerComponentBuilder.
309 */
310 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation);
311
312 /**
313 * Returns a builder for creating the root Logger.
314 * @param level The logging Level to be assigned to the root Logger.
315 *
316 * @return A new RootLoggerComponentBuilder.
317 */
318 RootLoggerComponentBuilder newRootLogger(String 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 *
324 * @return A new RootLoggerComponentBuilder.
325 */
326 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation);
327
328 /**
329 * Set the Advertiser Plugin name.
330 * @param advertiser The Advertiser Plugin name.
331 * @return this builder instance.
332 */
333 ConfigurationBuilder<T> setAdvertiser(String advertiser);
334
335 /**
336 * Sets the name of the configuration.
337 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}.
338 * @return this builder instance.
339 */
340 ConfigurationBuilder<T> setConfigurationName(String name);
341
342 /**
343 * Sets the configuration source, if one exists.
344 * @param configurationSource the ConfigurationSource.
345 * @return this builder instance.
346 */
347 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource);
348
349 /**
350 * Sets the interval at which the configuration file should be checked for changes.
351 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file.
352 * @return this builder instance.
353 */
354 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds);
355
356 /**
357 * Sets the list of packages to search for plugins.
358 * @param packages The comma separated list of packages.
359 * @return this builder instance.
360 */
361 ConfigurationBuilder<T> setPackages(String packages);
362
363 /**
364 * Sets whether the shutdown hook should be disabled.
365 * @param flag "disable" will prevent the shutdown hook from being set.
366 * @return this builder instance.
367 */
368 ConfigurationBuilder<T> setShutdownHook(String flag);
369
370
371 /**
372 * Sets the level of the StatusLogger.
373 * @param level The logging level.
374 * @return this builder instance.
375 */
376 ConfigurationBuilder<T> setStatusLevel(Level level);
377
378
379 /**
380 * Sets whether the logging should include constructing Plugins.
381 * @param verbosity "disable" will hide messages from plugin construction.
382 * @return this builder instance.
383 */
384 ConfigurationBuilder<T> setVerbosity(String verbosity);
385
386 /**
387 * Specifies the destination for StatusLogger events. This can be {@code out} (default) for using
388 * {@link System#out standard out}, {@code err} for using {@link System#err standard error}, or a file URI to
389 * which log events will be written. If the provided URI is invalid, then the default destination of standard
390 * out will be used.
391 *
392 * @param destination where status log messages should be output.
393 * @return this builder instance.
394 */
395 ConfigurationBuilder<T> setDestination(String destination);
396
397 /**
398 * Sets the logger context.
399 * @param loggerContext the logger context.
400 */
401 void setLoggerContext(LoggerContext loggerContext);
402
403 /**
404 * Add the properties for the root node.
405 * @param key The property key.
406 * @param value The property value.
407 * @return this builder instance.
408 */
409 ConfigurationBuilder<T> addRootProperty(String key, String value);
410
411 /**
412 * Build the configuration and optionally initialize it.
413 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations
414 * should not be initialized when they are constructed.
415 * @return The constructed Configuration.
416 */
417 T build(boolean initialize);
418
419 /**
420 * Constructs an XML configuration from this builder.
421 *
422 * @param output OutputStream to write to, will not be closed
423 *
424 * @since 2.7
425 */
426 void writeXmlConfiguration(OutputStream output) throws IOException;
427
428 /**
429 * Constructs an XML configuration from this builder.
430 *
431 * @return XML configuration
432 *
433 * @since 2.7
434 */
435 String toXmlConfiguration();
436 }