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     * Adds an AppenderComponent.
034     * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
035     * @return this builder instance.
036     */
037    ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
038
039    /**
040     * Adds a CustomLevel component.
041     * @param builder The CustomLevelComponentBuilder with all of its attributes set.
042     * @return this builder instance.
043     */
044    ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
045
046    /**
047     * Adds a Filter component.
048     * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
049     * @return this builder instance.
050     */
051    ConfigurationBuilder<T> add(FilterComponentBuilder builder);
052
053    /**
054     * Adds a Logger component.
055     * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
056     * @return this builder instance.
057     */
058    ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
059
060    /**
061     * Adds the root Logger component.
062     * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
063     * @return this builder instance.
064     */
065    ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
066
067    /**
068     * Adds a Property key and value.
069     * @param key The property key.
070     * @param value The property value.
071     * @return this builder instance.
072     */
073    ConfigurationBuilder<T> addProperty(String key, String value);
074
075    /**
076     * Returns a builder for creating Appenders.
077     * @param name The name of the Appender.
078     * @param pluginName The Plugin type of the Appender.
079     * @return A new AppenderComponentBuilder.
080     */
081    AppenderComponentBuilder newAppender(String name, String pluginName);
082
083    /**
084     * Returns a builder for creating AppenderRefs.
085     * @param ref The name of the Appender being referenced.
086     * @return A new AppenderRefComponentBuilder.
087     */
088    AppenderRefComponentBuilder newAppenderRef(String ref);
089
090    /**
091     * Returns a builder for creating Async Loggers.
092     * @param name The name of the Logger.
093     * @param level The logging Level to be assigned to the Logger.
094     * @return A new LoggerComponentBuilder.
095     */
096    LoggerComponentBuilder newAsyncLogger(String name, Level level);
097
098    /**
099     * Returns a builder for creating Async Loggers.
100     * @param name The name of the Logger.
101     * @param level The logging Level to be assigned to the Logger.
102     * @return A new LoggerComponentBuilder.
103     */
104    LoggerComponentBuilder newAsyncLogger(String name, String level);
105
106    /**
107     * Returns a builder for creating the async root Logger.
108     * @param level The logging Level to be assigned to the root Logger.
109     * @return A new RootLoggerComponentBuilder.
110     */
111    RootLoggerComponentBuilder newAsyncRootLogger(Level level);
112
113    /**
114     * Returns a builder for creating the async root Logger.
115     * @param level The logging Level to be assigned to the root Logger.
116     * @return A new RootLoggerComponentBuilder.
117     */
118    RootLoggerComponentBuilder newAsyncRootLogger(String level);
119
120    /**
121     * Returns a builder for creating generic components.
122     * @param <B> ComponentBuilder target type
123     * @param name The name of the component (may be null).
124     * @param pluginName The Plugin type of the component.
125     * @return A new ComponentBuilder.
126     */
127    <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName);
128
129    /**
130     * Returns a builder for creating generic components.
131     * @param <B> ComponentBuilder target type
132     * @param name The name of the component (may be null).
133     * @param pluginName The Plugin type of the component.
134     * @param value The value of the component.
135     * @return A new ComponentBuilder.
136     */
137    <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value);
138
139
140    /**
141     * Returns a builder for creating CustomLevels
142     * @param name The name of the custom level.
143     * @param level The integer value to be assigned to the level.
144     * @return A new CustomLevelComponentBuilder.
145     */
146    CustomLevelComponentBuilder newCustomLevel(String name, int level);
147
148    /**
149     * Returns a builder for creating Filters.
150     * @param pluginName The Plugin type of the Filter.
151     * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
152     * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
153     * @return A new FilterComponentBuilder.
154     */
155    FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch);
156
157    /**
158     * Returns a builder for creating Filters.
159     * @param pluginName The Plugin type of the Filter.
160     * @param onMatch "ACCEPT", "DENY", or "NEUTRAL"
161     * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL"
162     * @return A new FilterComponentBuilder.
163     */
164    FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch);
165
166    /**
167     * Returns a builder for creating Layouts.
168     * @param pluginName The Plugin type of the Layout.
169     * @return A new LayoutComponentBuilder.
170     */
171    LayoutComponentBuilder newLayout(String pluginName);
172
173    /**
174     * Returns a builder for creating Loggers.
175     * @param name The name of the Logger.
176     * @param level The logging Level to be assigned to the Logger.
177     * @return A new LoggerComponentBuilder.
178     */
179    LoggerComponentBuilder newLogger(String name, Level level);
180
181    /**
182     * Returns a builder for creating Loggers.
183     * @param name The name of the Logger.
184     * @param level The logging Level to be assigned to the Logger.
185     * @return A new LoggerComponentBuilder.
186     */
187    LoggerComponentBuilder newLogger(String name, String level);
188
189    /**
190     * Returns a builder for creating the root Logger.
191     * @param level The logging Level to be assigned to the root Logger.
192     * @return A new RootLoggerComponentBuilder.
193     */
194    RootLoggerComponentBuilder newRootLogger(Level level);
195
196    /**
197     * Returns a builder for creating the root Logger.
198     * @param level The logging Level to be assigned to the root Logger.
199     * @return A new RootLoggerComponentBuilder.
200     */
201    RootLoggerComponentBuilder newRootLogger(String level);
202
203    /**
204     * Set the Advertiser Plugin name.
205     * @param advertiser The Advertiser Plugin name.
206     * @return this builder instance.
207     */
208    ConfigurationBuilder<T> setAdvertiser(String advertiser);
209
210    /**
211     * Sets the name of the configuration.
212     * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}.
213     * @return this builder instance.
214     */
215    ConfigurationBuilder<T> setConfigurationName(String name);
216
217    /**
218     * Sets the configuration source, if one exists.
219     * @param configurationSource the ConfigurationSource.
220     * @return this builder instance.
221     */
222    ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource);
223
224    /**
225     * Sets the interval at which the configuration file should be checked for changes.
226     * @param intervalSeconds The number of seconds that should pass between checks of the configuration file.
227     * @return this builder instance.
228     */
229    ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds);
230
231    /**
232     * Sets the list of packages to search for plugins.
233     * @param packages The comma separated list of packages.
234     * @return this builder instance.
235     */
236    ConfigurationBuilder<T> setPackages(String packages);
237
238    /**
239     * Sets whether the shutdown hook should be disabled.
240     * @param flag "disable" will prevent the shutdown hook from being set.
241     * @return this builder instance.
242     */
243    ConfigurationBuilder<T> setShutdownHook(String flag);
244
245
246    /**
247     * Sets the level of the StatusLogger.
248     * @param level The logging level.
249     * @return this builder instance.
250     */
251    ConfigurationBuilder<T> setStatusLevel(Level level);
252
253
254    /**
255     * Sets whether the logging should include constructing Plugins.
256     * @param verbosity "disable" will hide messages from plugin construction.
257     * @return this builder instance.
258     */
259    ConfigurationBuilder<T> setVerbosity(String verbosity);
260}