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