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 org.apache.logging.log4j.Level;
020import org.apache.logging.log4j.core.Filter;
021import org.apache.logging.log4j.core.config.Configuration;
022import org.apache.logging.log4j.core.config.ConfigurationSource;
023import org.apache.logging.log4j.core.util.Builder;
024
025/**
026 * Interface for building logging configurations.
027 * @param <T> The Configuration type created by this builder.
028 * @since 2.4
029 */
030public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> {
031
032
033    /**
034     * Adds a ScriptComponent.
035     * @param builder The ScriptComponentBuilder with all of its attributes and sub components set.
036     * @return this builder instance.
037     */
038    ConfigurationBuilder<T> add(ScriptComponentBuilder builder);
039
040    /**
041     * Adds a ScriptFileComponent.
042     * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set.
043     * @return this builder instance.
044     */
045    ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder);
046
047    /**
048     * Adds an AppenderComponent.
049     * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
050     * @return this builder instance.
051     */
052    ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
053
054    /**
055     * Adds a CustomLevel component.
056     * @param builder The CustomLevelComponentBuilder with all of its attributes set.
057     * @return this builder instance.
058     */
059    ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
060
061    /**
062     * Adds a Filter component.
063     * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
064     * @return this builder instance.
065     */
066    ConfigurationBuilder<T> add(FilterComponentBuilder builder);
067
068    /**
069     * Adds a Logger component.
070     * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
071     * @return this builder instance.
072     */
073    ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
074
075    /**
076     * Adds the root Logger component.
077     * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
078     * @return this builder instance.
079     */
080    ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
081
082    /**
083     * Adds a Property key and value.
084     * @param key The property key.
085     * @param value The property value.
086     * @return this builder instance.
087     */
088    ConfigurationBuilder<T> addProperty(String key, String value);
089
090
091    /**
092     * Returns a builder for creating Async Loggers.
093     * @param name The name of the Logger.
094     * @param language The script language
095     * @param text The script to execute.
096     * @return A new ScriptComponentBuilder.
097     */
098    ScriptComponentBuilder newScript(String name, String language, String text);
099
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     * @return A new LoggerComponentBuilder.
145     */
146    LoggerComponentBuilder newAsyncLogger(String name, String level);
147
148    /**
149     * Returns a builder for creating the async root Logger.
150     * @param level The logging Level to be assigned to the root Logger.
151     * @return A new RootLoggerComponentBuilder.
152     */
153    RootLoggerComponentBuilder newAsyncRootLogger(Level level);
154
155    /**
156     * Returns a builder for creating the async root Logger.
157     * @param level The logging Level to be assigned to the root Logger.
158     * @return A new RootLoggerComponentBuilder.
159     */
160    RootLoggerComponentBuilder newAsyncRootLogger(String level);
161
162    /**
163     * Returns a builder for creating generic components.
164     * @param <B> ComponentBuilder target type
165     * @param pluginName The Plugin type of the component.
166     * @return A new ComponentBuilder.
167     */
168    <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName);
169
170    /**
171     * Returns a builder for creating generic components.
172     * @param <B> ComponentBuilder target type
173     * @param name The name of the component (may be null).
174     * @param pluginName The Plugin type of the component.
175     * @return A new ComponentBuilder.
176     */
177    <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName);
178
179    /**
180     * Returns a builder for creating generic components.
181     * @param <B> ComponentBuilder target type
182     * @param name The name of the component (may be null).
183     * @param pluginName The Plugin type of the component.
184     * @param value The value of the component.
185     * @return A new ComponentBuilder.
186     */
187    <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value);
188
189
190    /**
191     * Returns a builder for creating CustomLevels
192     * @param name The name of the custom level.
193     * @param level The integer value to be assigned to the level.
194     * @return A new CustomLevelComponentBuilder.
195     */
196    CustomLevelComponentBuilder newCustomLevel(String name, int level);
197
198    /**
199     * Returns a builder for creating Filters.
200     * @param pluginName The Plugin type of the Filter.
201     * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
202     * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
203     * @return A new FilterComponentBuilder.
204     */
205    FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch);
206
207    /**
208     * Returns a builder for creating Filters.
209     * @param pluginName The Plugin type of the Filter.
210     * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
211     * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
212     * @return A new FilterComponentBuilder.
213     */
214    FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch);
215
216    /**
217     * Returns a builder for creating Layouts.
218     * @param pluginName The Plugin type of the Layout.
219     * @return A new LayoutComponentBuilder.
220     */
221    LayoutComponentBuilder newLayout(String pluginName);
222
223    /**
224     * Returns a builder for creating Loggers.
225     * @param name The name of the Logger.
226     * @param level The logging Level to be assigned to the Logger.
227     * @return A new LoggerComponentBuilder.
228     */
229    LoggerComponentBuilder newLogger(String name, Level level);
230
231    /**
232     * Returns a builder for creating Loggers.
233     * @param name The name of the Logger.
234     * @param level The logging Level to be assigned to the Logger.
235     * @return A new LoggerComponentBuilder.
236     */
237    LoggerComponentBuilder newLogger(String name, String level);
238
239    /**
240     * Returns a builder for creating the root Logger.
241     * @param level The logging Level to be assigned to the root Logger.
242     * @return A new RootLoggerComponentBuilder.
243     */
244    RootLoggerComponentBuilder newRootLogger(Level level);
245
246    /**
247     * Returns a builder for creating the root Logger.
248     * @param level The logging Level to be assigned to the root Logger.
249     * @return A new RootLoggerComponentBuilder.
250     */
251    RootLoggerComponentBuilder newRootLogger(String level);
252
253    /**
254     * Set the Advertiser Plugin name.
255     * @param advertiser The Advertiser Plugin name.
256     * @return this builder instance.
257     */
258    ConfigurationBuilder<T> setAdvertiser(String advertiser);
259
260    /**
261     * Sets the name of the configuration.
262     * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}.
263     * @return this builder instance.
264     */
265    ConfigurationBuilder<T> setConfigurationName(String name);
266
267    /**
268     * Sets the configuration source, if one exists.
269     * @param configurationSource the ConfigurationSource.
270     * @return this builder instance.
271     */
272    ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource);
273
274    /**
275     * Sets the interval at which the configuration file should be checked for changes.
276     * @param intervalSeconds The number of seconds that should pass between checks of the configuration file.
277     * @return this builder instance.
278     */
279    ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds);
280
281    /**
282     * Sets the list of packages to search for plugins.
283     * @param packages The comma separated list of packages.
284     * @return this builder instance.
285     */
286    ConfigurationBuilder<T> setPackages(String packages);
287
288    /**
289     * Sets whether the shutdown hook should be disabled.
290     * @param flag "disable" will prevent the shutdown hook from being set.
291     * @return this builder instance.
292     */
293    ConfigurationBuilder<T> setShutdownHook(String flag);
294
295
296    /**
297     * Sets the level of the StatusLogger.
298     * @param level The logging level.
299     * @return this builder instance.
300     */
301    ConfigurationBuilder<T> setStatusLevel(Level level);
302
303
304    /**
305     * Sets whether the logging should include constructing Plugins.
306     * @param verbosity "disable" will hide messages from plugin construction.
307     * @return this builder instance.
308     */
309    ConfigurationBuilder<T> setVerbosity(String verbosity);
310}