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.util.Map; 020import org.apache.logging.log4j.Level; 021import org.apache.logging.log4j.core.Filter; 022import org.apache.logging.log4j.core.config.Configuration; 023import org.apache.logging.log4j.core.config.ConfigurationSource; 024import org.apache.logging.log4j.core.util.Builder; 025 026/** 027 * Interface for building logging configurations. 028 * @param <T> The Configuration type created by this builder. 029 * @since 2.4 030 */ 031public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> { 032 033 034 /** 035 * Adds a ScriptComponent. 036 * @param builder The ScriptComponentBuilder with all of its attributes and sub components set. 037 * @return this builder instance. 038 */ 039 ConfigurationBuilder<T> add(ScriptComponentBuilder builder); 040 041 /** 042 * Adds a ScriptFileComponent. 043 * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set. 044 * @return this builder instance. 045 */ 046 ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder); 047 048 /** 049 * Adds an AppenderComponent. 050 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set. 051 * @return this builder instance. 052 */ 053 ConfigurationBuilder<T> add(AppenderComponentBuilder builder); 054 055 /** 056 * Adds a CustomLevel component. 057 * @param builder The CustomLevelComponentBuilder with all of its attributes set. 058 * @return this builder instance. 059 */ 060 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder); 061 062 /** 063 * Adds a Filter component. 064 * @param builder the FilterComponentBuilder with all of its attributes and sub components set. 065 * @return this builder instance. 066 */ 067 ConfigurationBuilder<T> add(FilterComponentBuilder builder); 068 069 /** 070 * Adds a Logger component. 071 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set. 072 * @return this builder instance. 073 */ 074 ConfigurationBuilder<T> add(LoggerComponentBuilder builder); 075 076 /** 077 * Adds the root Logger component. 078 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set. 079 * @return this builder instance. 080 */ 081 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder); 082 083 /** 084 * Adds a Property key and value. 085 * @param key The property key. 086 * @param value The property value. 087 * @return this builder instance. 088 */ 089 ConfigurationBuilder<T> addProperty(String key, String value); 090 091 092 /** 093 * Returns a builder for creating Async Loggers. 094 * @param name The name of the Logger. 095 * @param language The script language 096 * @param text The script to execute. 097 * @return A new ScriptComponentBuilder. 098 */ 099 ScriptComponentBuilder newScript(String name, String language, String text); 100 101 /** 102 * Returns a builder for creating Async Loggers. 103 * @param path The location of the script file. 104 * @return A new ScriptFileComponentBuilder. 105 */ 106 ScriptFileComponentBuilder newScriptFile(String path); 107 108 109 /** 110 * Returns a builder for creating Async Loggers. 111 * @param name The name of the script file. 112 * @param path The location of the script file. 113 * @return A new ScriptFileComponentBuilder. 114 */ 115 ScriptFileComponentBuilder newScriptFile(String name, String path); 116 117 118 /** 119 * Returns a builder for creating Appenders. 120 * @param name The name of the Appender. 121 * @param pluginName The Plugin type of the Appender. 122 * @return A new AppenderComponentBuilder. 123 */ 124 AppenderComponentBuilder newAppender(String name, String pluginName); 125 126 /** 127 * Returns a builder for creating AppenderRefs. 128 * @param ref The name of the Appender being referenced. 129 * @return A new AppenderRefComponentBuilder. 130 */ 131 AppenderRefComponentBuilder newAppenderRef(String ref); 132 133 /** 134 * Returns a builder for creating Async Loggers. 135 * @param name The name of the Logger. 136 * @param level The logging Level to be assigned to the Logger. 137 * @return A new LoggerComponentBuilder. 138 */ 139 LoggerComponentBuilder newAsyncLogger(String name, Level level); 140 141 /** 142 * Returns a builder for creating Async Loggers. 143 * @param name The name of the Logger. 144 * @param level The logging Level to be assigned to the Logger. 145 * @param includeLocation If true include location information. 146 * @return A new LoggerComponentBuilder. 147 */ 148 LoggerComponentBuilder newAsyncLogger(String name, Level level, boolean includeLocation); 149 150 /** 151 * Returns a builder for creating Async Loggers. 152 * @param name The name of the Logger. 153 * @param level The logging Level to be assigned to the Logger. 154 * @return A new LoggerComponentBuilder. 155 */ 156 LoggerComponentBuilder newAsyncLogger(String name, String level); 157 158 /** 159 * Returns a builder for creating Async Loggers. 160 * @param name The name of the Logger. 161 * @param level The logging Level to be assigned to the Logger. 162 * @param includeLocation If true include location information. 163 * @return A new LoggerComponentBuilder. 164 */ 165 LoggerComponentBuilder newAsyncLogger(String name, String level, boolean includeLocation); 166 167 /** 168 * Returns a builder for creating the async root Logger. 169 * @param level The logging Level to be assigned to the root Logger. 170 * @return A new RootLoggerComponentBuilder. 171 */ 172 RootLoggerComponentBuilder newAsyncRootLogger(Level level); 173 174 175 /** 176 * Returns a builder for creating the async root Logger. 177 * @param level The logging Level to be assigned to the root Logger. 178 * @param includeLocation If true include location information. 179 * @return A new RootLoggerComponentBuilder. 180 */ 181 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation); 182 183 /** 184 * Returns a builder for creating the async root Logger. 185 * @param level The logging Level to be assigned to the root Logger. 186 * @return A new RootLoggerComponentBuilder. 187 */ 188 RootLoggerComponentBuilder newAsyncRootLogger(String level); 189 190 191 /** 192 * Returns a builder for creating the async root Logger. 193 * @param level The logging Level to be assigned to the root Logger. 194 * @param includeLocation If true include location information. 195 * @return A new RootLoggerComponentBuilder. 196 */ 197 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation); 198 199 /** 200 * Returns a builder for creating generic components. 201 * @param <B> ComponentBuilder target type 202 * @param pluginName The Plugin type of the component. 203 * @return A new ComponentBuilder. 204 */ 205 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName); 206 207 /** 208 * Returns a builder for creating generic components. 209 * @param <B> ComponentBuilder target type 210 * @param name The name of the component (may be null). 211 * @param pluginName The Plugin type of the component. 212 * @return A new ComponentBuilder. 213 */ 214 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName); 215 216 /** 217 * Returns a builder for creating generic components. 218 * @param <B> ComponentBuilder target type 219 * @param name The name of the component (may be null). 220 * @param pluginName The Plugin type of the component. 221 * @param value The value of the component. 222 * @return A new ComponentBuilder. 223 */ 224 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value); 225 226 227 /** 228 * Returns a builder for creating CustomLevels 229 * @param name The name of the custom level. 230 * @param level The integer value to be assigned to the level. 231 * @return A new CustomLevelComponentBuilder. 232 */ 233 CustomLevelComponentBuilder newCustomLevel(String name, int level); 234 235 /** 236 * Returns a builder for creating Filters. 237 * @param pluginName The Plugin type of the Filter. 238 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 239 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 240 * @return A new FilterComponentBuilder. 241 */ 242 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch); 243 244 /** 245 * Returns a builder for creating Filters. 246 * @param pluginName The Plugin type of the Filter. 247 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 248 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 249 * @return A new FilterComponentBuilder. 250 */ 251 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch); 252 253 /** 254 * Returns a builder for creating Layouts. 255 * @param pluginName The Plugin type of the Layout. 256 * @return A new LayoutComponentBuilder. 257 */ 258 LayoutComponentBuilder newLayout(String pluginName); 259 260 /** 261 * Returns a builder for creating Loggers. 262 * @param name The name of the Logger. 263 * @param level The logging Level to be assigned to the Logger. 264 * @return A new LoggerComponentBuilder. 265 */ 266 LoggerComponentBuilder newLogger(String name, Level level); 267 268 /** 269 * Returns a builder for creating Loggers. 270 * @param name The name of the Logger. 271 * @param level The logging Level to be assigned to the Logger. 272 * @param includeLocation If true include location information. 273 * @return A new LoggerComponentBuilder. 274 */ 275 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation); 276 277 /** 278 * Returns a builder for creating Loggers. 279 * @param name The name of the Logger. 280 * @param level The logging Level to be assigned to the Logger. 281 * @return A new LoggerComponentBuilder. 282 */ 283 LoggerComponentBuilder newLogger(String name, String level); 284 285 /** 286 * Returns a builder for creating Loggers. 287 * @param name The name of the Logger. 288 * @param level The logging Level to be assigned to the Logger. 289 * @param includeLocation If true include location information. 290 * @return A new LoggerComponentBuilder. 291 */ 292 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation); 293 294 /** 295 * Returns a builder for creating the root Logger. 296 * @param level The logging Level to be assigned to the root Logger. 297 * @return A new RootLoggerComponentBuilder. 298 */ 299 RootLoggerComponentBuilder newRootLogger(Level level); 300 301 /** 302 * Returns a builder for creating the root Logger. 303 * @param level The logging Level to be assigned to the root Logger. 304 * @param includeLocation If true include location information. 305 * @return A new RootLoggerComponentBuilder. 306 */ 307 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation); 308 309 /** 310 * Returns a builder for creating the root Logger. 311 * @param level The logging Level to be assigned to the root Logger. 312 * 313 * @return A new RootLoggerComponentBuilder. 314 */ 315 RootLoggerComponentBuilder newRootLogger(String level); 316 317 /** 318 * Returns a builder for creating the root Logger. 319 * @param level The logging Level to be assigned to the root Logger. 320 * 321 * @return A new RootLoggerComponentBuilder. 322 */ 323 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation); 324 325 /** 326 * Set the Advertiser Plugin name. 327 * @param advertiser The Advertiser Plugin name. 328 * @param includeLocation If true include location information. 329 * @return this builder instance. 330 */ 331 ConfigurationBuilder<T> setAdvertiser(String advertiser); 332 333 /** 334 * Sets the name of the configuration. 335 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}. 336 * @return this builder instance. 337 */ 338 ConfigurationBuilder<T> setConfigurationName(String name); 339 340 /** 341 * Sets the configuration source, if one exists. 342 * @param configurationSource the ConfigurationSource. 343 * @return this builder instance. 344 */ 345 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource); 346 347 /** 348 * Sets the interval at which the configuration file should be checked for changes. 349 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file. 350 * @return this builder instance. 351 */ 352 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds); 353 354 /** 355 * Sets the list of packages to search for plugins. 356 * @param packages The comma separated list of packages. 357 * @return this builder instance. 358 */ 359 ConfigurationBuilder<T> setPackages(String packages); 360 361 /** 362 * Sets whether the shutdown hook should be disabled. 363 * @param flag "disable" will prevent the shutdown hook from being set. 364 * @return this builder instance. 365 */ 366 ConfigurationBuilder<T> setShutdownHook(String flag); 367 368 369 /** 370 * Sets the level of the StatusLogger. 371 * @param level The logging level. 372 * @return this builder instance. 373 */ 374 ConfigurationBuilder<T> setStatusLevel(Level level); 375 376 377 /** 378 * Sets whether the logging should include constructing Plugins. 379 * @param verbosity "disable" will hide messages from plugin construction. 380 * @return this builder instance. 381 */ 382 ConfigurationBuilder<T> setVerbosity(String verbosity); 383 384 /** 385 * Add the properties for the root node. 386 * @param key The property key. 387 * @param value The property value. 388 * @return this builder instance. 389 */ 390 ConfigurationBuilder<T> addRootProperty(String key, String value); 391 392 /** 393 * Build the configuration and optionally initialize it. 394 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations 395 * should not be initialized when they are constructed. 396 * @return The constructed Configuration. 397 */ 398 T build(boolean initialize); 399}