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