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      /**
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      * @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 }