View Javadoc
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       * Adds an AppenderComponent.
34       * @param builder The AppenderComponentBuilder with all of its attributes and sub components set.
35       * @return this builder instance.
36       */
37      ConfigurationBuilder<T> add(AppenderComponentBuilder builder);
38  
39      /**
40       * Adds a CustomLevel component.
41       * @param builder The CustomLevelComponentBuilder with all of its attributes set.
42       * @return this builder instance.
43       */
44      ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder);
45  
46      /**
47       * Adds a Filter component.
48       * @param builder the FilterComponentBuilder with all of its attributes and sub components set.
49       * @return this builder instance.
50       */
51      ConfigurationBuilder<T> add(FilterComponentBuilder builder);
52  
53      /**
54       * Adds a Logger component.
55       * @param builder The LoggerComponentBuilder with all of its attributes and sub components set.
56       * @return this builder instance.
57       */
58      ConfigurationBuilder<T> add(LoggerComponentBuilder builder);
59  
60      /**
61       * Adds the root Logger component.
62       * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set.
63       * @return this builder instance.
64       */
65      ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder);
66  
67      /**
68       * Adds a Property key and value.
69       * @param key The property key.
70       * @param value The property value.
71       * @return this builder instance.
72       */
73      ConfigurationBuilder<T> addProperty(String key, String value);
74  
75      /**
76       * Returns a builder for creating Appenders.
77       * @param name The name of the Appender.
78       * @param pluginName The Plugin type of the Appender.
79       * @return A new AppenderComponentBuilder.
80       */
81      AppenderComponentBuilder newAppender(String name, String pluginName);
82  
83      /**
84       * Returns a builder for creating AppenderRefs.
85       * @param ref The name of the Appender being referenced.
86       * @return A new AppenderRefComponentBuilder.
87       */
88      AppenderRefComponentBuilder newAppenderRef(String ref);
89  
90      /**
91       * Returns a builder for creating Async Loggers.
92       * @param name The name of the Logger.
93       * @param level The logging Level to be assigned to the Logger.
94       * @return A new LoggerComponentBuilder.
95       */
96      LoggerComponentBuilder newAsyncLogger(String name, Level level);
97  
98      /**
99       * 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 }