001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache license, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the license for the specific language governing permissions and
015 * limitations under the license.
016 */
017package org.apache.logging.log4j.core.config.builder.api;
018
019import java.io.IOException;
020import java.io.OutputStream;
021import java.util.concurrent.TimeUnit;
022
023import org.apache.logging.log4j.Level;
024import org.apache.logging.log4j.core.Filter;
025import org.apache.logging.log4j.core.LoggerContext;
026import org.apache.logging.log4j.core.config.Configuration;
027import org.apache.logging.log4j.core.config.ConfigurationSource;
028import org.apache.logging.log4j.core.util.Builder;
029
030/**
031 * Interface for building logging configurations.
032 * @param <T> The Configuration type created by this builder.
033 * @since 2.4
034 */
035public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> {
036
037
038    /**
039     * Adds a ScriptComponent.
040     * @param builder The ScriptComponentBuilder with all of its attributes and sub components set.
041     * @return this builder instance.
042     */
043    ConfigurationBuilder<T> add(ScriptComponentBuilder builder);
044
045    /**
046     * Adds a ScriptFileComponent.
047     * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set.
048     * @return this builder instance.
049     */
050    ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder);
051
052    /**
053     * Adds an AppenderComponent.
054     * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
055     * @return this builder instance.
056     */
057    ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
058
059    /**
060     * Adds a CustomLevel component.
061     * @param builder The CustomLevelComponentBuilder with all of its attributes set.
062     * @return this builder instance.
063     */
064    ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
065
066    /**
067     * Adds a Filter component.
068     * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
069     * @return this builder instance.
070     */
071    ConfigurationBuilder<T> add(FilterComponentBuilder builder);
072
073    /**
074     * Adds a Logger component.
075     * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
076     * @return this builder instance.
077     */
078    ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
079
080    /**
081     * Adds the root Logger component.
082     * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
083     * @return this builder instance.
084     */
085    ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
086
087    /**
088     * Adds a Property key and value.
089     * @param key The property key.
090     * @param value The property value.
091     * @return this builder instance.
092     */
093    ConfigurationBuilder<T> addProperty(String key, String value);
094
095
096    /**
097     * Returns a builder for creating Async Loggers.
098     * @param name The name of the Logger.
099     * @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}