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.io.IOException; 020import java.io.OutputStream; 021import java.util.concurrent.TimeUnit; 022 023import org.apache.logging.log4j.Level; 024import org.apache.logging.log4j.core.Filter; 025import org.apache.logging.log4j.core.LoggerContext; 026import org.apache.logging.log4j.core.config.Configuration; 027import org.apache.logging.log4j.core.config.ConfigurationSource; 028import org.apache.logging.log4j.core.util.Builder; 029 030/** 031 * Interface for building logging configurations. 032 * @param <T> The Configuration type created by this builder. 033 * @since 2.4 034 */ 035public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> { 036 037 038 /** 039 * Adds a ScriptComponent. 040 * @param builder The ScriptComponentBuilder with all of its attributes and sub components set. 041 * @return this builder instance. 042 */ 043 ConfigurationBuilder<T> add(ScriptComponentBuilder builder); 044 045 /** 046 * Adds a ScriptFileComponent. 047 * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set. 048 * @return this builder instance. 049 */ 050 ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder); 051 052 /** 053 * Adds an AppenderComponent. 054 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set. 055 * @return this builder instance. 056 */ 057 ConfigurationBuilder<T> add(AppenderComponentBuilder builder); 058 059 /** 060 * Adds a CustomLevel component. 061 * @param builder The CustomLevelComponentBuilder with all of its attributes set. 062 * @return this builder instance. 063 */ 064 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder); 065 066 /** 067 * Adds a Filter component. 068 * @param builder the FilterComponentBuilder with all of its attributes and sub components set. 069 * @return this builder instance. 070 */ 071 ConfigurationBuilder<T> add(FilterComponentBuilder builder); 072 073 /** 074 * Adds a Logger component. 075 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set. 076 * @return this builder instance. 077 */ 078 ConfigurationBuilder<T> add(LoggerComponentBuilder builder); 079 080 /** 081 * Adds the root Logger component. 082 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set. 083 * @return this builder instance. 084 */ 085 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder); 086 087 /** 088 * Adds a Property key and value. 089 * @param key The property key. 090 * @param value The property value. 091 * @return this builder instance. 092 */ 093 ConfigurationBuilder<T> addProperty(String key, String value); 094 095 096 /** 097 * Returns a builder for creating Async Loggers. 098 * @param name The name of the Logger. 099 * @param language The script language 100 * @param text The script to execute. 101 * @return A new ScriptComponentBuilder. 102 */ 103 ScriptComponentBuilder newScript(String name, String language, String text); 104 105 /** 106 * Returns a builder for creating Async Loggers. 107 * @param path The location of the script file. 108 * @return A new ScriptFileComponentBuilder. 109 */ 110 ScriptFileComponentBuilder newScriptFile(String path); 111 112 113 /** 114 * Returns a builder for creating Async Loggers. 115 * @param name The name of the script file. 116 * @param path The location of the script file. 117 * @return A new ScriptFileComponentBuilder. 118 */ 119 ScriptFileComponentBuilder newScriptFile(String name, String path); 120 121 122 /** 123 * Returns a builder for creating Appenders. 124 * @param name The name of the Appender. 125 * @param pluginName The Plugin type of the Appender. 126 * @return A new AppenderComponentBuilder. 127 */ 128 AppenderComponentBuilder newAppender(String name, String pluginName); 129 130 /** 131 * Returns a builder for creating AppenderRefs. 132 * @param ref The name of the Appender being referenced. 133 * @return A new AppenderRefComponentBuilder. 134 */ 135 AppenderRefComponentBuilder newAppenderRef(String ref); 136 137 138 /** 139 * Returns a builder for creating Async Loggers. 140 * @param name The name of the Logger. 141 * @return A new LoggerComponentBuilder. 142 */ 143 LoggerComponentBuilder newAsyncLogger(String name); 144 145 /** 146 * Returns a builder for creating Async Loggers. 147 * @param name The name of the Logger. 148 * @param includeLocation If true include location information. 149 * @return A new LoggerComponentBuilder. 150 */ 151 LoggerComponentBuilder newAsyncLogger(String name, boolean includeLocation); 152 153 /** 154 * Returns a builder for creating Async Loggers. 155 * @param name The name of the Logger. 156 * @param level The logging Level to be assigned to the Logger. 157 * @return A new LoggerComponentBuilder. 158 */ 159 LoggerComponentBuilder newAsyncLogger(String name, Level level); 160 161 /** 162 * Returns a builder for creating Async Loggers. 163 * @param name The name of the Logger. 164 * @param level The logging Level to be assigned to the Logger. 165 * @param includeLocation If true include location information. 166 * @return A new LoggerComponentBuilder. 167 */ 168 LoggerComponentBuilder newAsyncLogger(String name, Level level, boolean includeLocation); 169 170 /** 171 * Returns a builder for creating Async Loggers. 172 * @param name The name of the Logger. 173 * @param level The logging Level to be assigned to the Logger. 174 * @return A new LoggerComponentBuilder. 175 */ 176 LoggerComponentBuilder newAsyncLogger(String name, String level); 177 178 /** 179 * Returns a builder for creating Async Loggers. 180 * @param name The name of the Logger. 181 * @param level The logging Level to be assigned to the Logger. 182 * @param includeLocation If true include location information. 183 * @return A new LoggerComponentBuilder. 184 */ 185 LoggerComponentBuilder newAsyncLogger(String name, String level, boolean includeLocation); 186 187 /** 188 * Returns a builder for creating the async root Logger. 189 * @return A new RootLoggerComponentBuilder. 190 */ 191 RootLoggerComponentBuilder newAsyncRootLogger(); 192 193 194 /** 195 * Returns a builder for creating the async root Logger. 196 * @param includeLocation If true include location information. 197 * @return A new RootLoggerComponentBuilder. 198 */ 199 RootLoggerComponentBuilder newAsyncRootLogger(boolean includeLocation); 200 201 /** 202 * Returns a builder for creating the async root Logger. 203 * @param level The logging Level to be assigned to the root Logger. 204 * @return A new RootLoggerComponentBuilder. 205 */ 206 RootLoggerComponentBuilder newAsyncRootLogger(Level level); 207 208 209 /** 210 * Returns a builder for creating the async root Logger. 211 * @param level The logging Level to be assigned to the root Logger. 212 * @param includeLocation If true include location information. 213 * @return A new RootLoggerComponentBuilder. 214 */ 215 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation); 216 217 /** 218 * Returns a builder for creating the async root Logger. 219 * @param level The logging Level to be assigned to the root Logger. 220 * @return A new RootLoggerComponentBuilder. 221 */ 222 RootLoggerComponentBuilder newAsyncRootLogger(String level); 223 224 225 /** 226 * Returns a builder for creating the async root Logger. 227 * @param level The logging Level to be assigned to the root Logger. 228 * @param includeLocation If true include location information. 229 * @return A new RootLoggerComponentBuilder. 230 */ 231 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation); 232 233 /** 234 * Returns a builder for creating generic components. 235 * @param <B> ComponentBuilder target type 236 * @param pluginName The Plugin type of the component. 237 * @return A new ComponentBuilder. 238 */ 239 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName); 240 241 /** 242 * Returns a builder for creating generic components. 243 * @param <B> ComponentBuilder target type 244 * @param name The name of the component (may be null). 245 * @param pluginName The Plugin type of the component. 246 * @return A new ComponentBuilder. 247 */ 248 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName); 249 250 /** 251 * Returns a builder for creating generic components. 252 * @param <B> ComponentBuilder target type 253 * @param name The name of the component (may be null). 254 * @param pluginName The Plugin type of the component. 255 * @param value The value of the component. 256 * @return A new ComponentBuilder. 257 */ 258 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value); 259 260 /** 261 * Returns a builder for creating Property:s 262 * @param name The name of the property. 263 * @param value The value of the component. 264 * @return A new PropertyComponentBuilder. 265 */ 266 PropertyComponentBuilder newProperty(String name, String value); 267 268 /** 269 * Returns a builder for creating KeyValuePair:s 270 * @param key The name 271 * @param value The value 272 * @return A new KeyValuePairComponentBuilder. 273 */ 274 KeyValuePairComponentBuilder newKeyValuePair(String key, String value); 275 276 /** 277 * Returns a builder for creating CustomLevels 278 * @param name The name of the custom level. 279 * @param level The integer value to be assigned to the level. 280 * @return A new CustomLevelComponentBuilder. 281 */ 282 CustomLevelComponentBuilder newCustomLevel(String name, int level); 283 284 /** 285 * Returns a builder for creating Filters. 286 * @param pluginName The Plugin type of the Filter. 287 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 288 * @param onMismatch "ACCEPT", "DENY", or "NEUTRAL" 289 * @return A new FilterComponentBuilder. 290 */ 291 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMismatch); 292 293 /** 294 * Returns a builder for creating Filters. 295 * @param pluginName The Plugin type of the Filter. 296 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 297 * @param onMismatch "ACCEPT", "DENY", or "NEUTRAL" 298 * @return A new FilterComponentBuilder. 299 */ 300 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMismatch); 301 302 /** 303 * Returns a builder for creating Layouts. 304 * @param pluginName The Plugin type of the Layout. 305 * @return A new LayoutComponentBuilder. 306 */ 307 LayoutComponentBuilder newLayout(String pluginName); 308 309 /** 310 * Returns a builder for creating Loggers. 311 * @param name The name of the Logger. 312 * @return A new LoggerComponentBuilder. 313 */ 314 LoggerComponentBuilder newLogger(String name); 315 316 /** 317 * Returns a builder for creating Loggers. 318 * @param name The name of the Logger. 319 * @param includeLocation If true include location information. 320 * @return A new LoggerComponentBuilder. 321 */ 322 LoggerComponentBuilder newLogger(String name, boolean includeLocation); 323 324 /** 325 * Returns a builder for creating Loggers. 326 * @param name The name of the Logger. 327 * @param level The logging Level to be assigned to the Logger. 328 * @return A new LoggerComponentBuilder. 329 */ 330 LoggerComponentBuilder newLogger(String name, Level level); 331 332 /** 333 * Returns a builder for creating Loggers. 334 * @param name The name of the Logger. 335 * @param level The logging Level to be assigned to the Logger. 336 * @param includeLocation If true include location information. 337 * @return A new LoggerComponentBuilder. 338 */ 339 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation); 340 341 /** 342 * Returns a builder for creating Loggers. 343 * @param name The name of the Logger. 344 * @param level The logging Level to be assigned to the Logger. 345 * @return A new LoggerComponentBuilder. 346 */ 347 LoggerComponentBuilder newLogger(String name, String level); 348 349 /** 350 * Returns a builder for creating Loggers. 351 * @param name The name of the Logger. 352 * @param level The logging Level to be assigned to the Logger. 353 * @param includeLocation If true include location information. 354 * @return A new LoggerComponentBuilder. 355 */ 356 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation); 357 358 /** 359 * Returns a builder for creating the root Logger. 360 * @return A new RootLoggerComponentBuilder. 361 */ 362 RootLoggerComponentBuilder newRootLogger(); 363 364 /** 365 * Returns a builder for creating the root Logger. 366 * @param includeLocation If true include location information. 367 * @return A new RootLoggerComponentBuilder. 368 */ 369 RootLoggerComponentBuilder newRootLogger(boolean includeLocation); 370 371 /** 372 * Returns a builder for creating the root Logger. 373 * @param level The logging Level to be assigned to the root Logger. 374 * @return A new RootLoggerComponentBuilder. 375 */ 376 RootLoggerComponentBuilder newRootLogger(Level level); 377 378 /** 379 * Returns a builder for creating the root Logger. 380 * @param level The logging Level to be assigned to the root Logger. 381 * @param includeLocation If true include location information. 382 * @return A new RootLoggerComponentBuilder. 383 */ 384 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation); 385 386 /** 387 * Returns a builder for creating the root Logger. 388 * @param level The logging Level to be assigned to the root Logger. 389 * 390 * @return A new RootLoggerComponentBuilder. 391 */ 392 RootLoggerComponentBuilder newRootLogger(String level); 393 394 /** 395 * Returns a builder for creating the root Logger. 396 * @param level The logging Level to be assigned to the root Logger. 397 * 398 * @return A new RootLoggerComponentBuilder. 399 */ 400 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation); 401 402 /** 403 * Set the Advertiser Plugin name. 404 * @param advertiser The Advertiser Plugin name. 405 * @return this builder instance. 406 */ 407 ConfigurationBuilder<T> setAdvertiser(String advertiser); 408 409 /** 410 * Sets the name of the configuration. 411 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}. 412 * @return this builder instance. 413 */ 414 ConfigurationBuilder<T> setConfigurationName(String name); 415 416 /** 417 * Sets the configuration source, if one exists. 418 * @param configurationSource the ConfigurationSource. 419 * @return this builder instance. 420 */ 421 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource); 422 423 /** 424 * Sets the interval at which the configuration file should be checked for changes. 425 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file. 426 * @return this builder instance. 427 */ 428 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds); 429 430 /** 431 * Sets the list of packages to search for plugins. 432 * @param packages The comma separated list of packages. 433 * @return this builder instance. 434 */ 435 ConfigurationBuilder<T> setPackages(String packages); 436 437 /** 438 * Sets whether the shutdown hook should be disabled. 439 * @param flag "disable" will prevent the shutdown hook from being set. 440 * @return this builder instance. 441 */ 442 ConfigurationBuilder<T> setShutdownHook(String flag); 443 444 /** 445 * How long appenders and background tasks will get to shutdown when the JVM shuts down. 446 * Default is zero which mean that each appender uses its default timeout, and don't wait for background 447 * tasks. Not all appenders will honor this, it is a hint and not an absolute guarantee that the shutdown 448 * procedure will not take longer. Setting this too low increase the risk of losing outstanding log events 449 * not yet written to the final destination. (Not used if {@link #setShutdownHook(String)} is set to "disable".) 450 * @return this builder instance. 451 * 452 * @see LoggerContext#stop(long, TimeUnit) 453 */ 454 ConfigurationBuilder<T> setShutdownTimeout(long timeout, TimeUnit timeUnit); 455 456 /** 457 * Sets the level of the StatusLogger. 458 * @param level The logging level. 459 * @return this builder instance. 460 */ 461 ConfigurationBuilder<T> setStatusLevel(Level level); 462 463 464 /** 465 * Sets whether the logging should include constructing Plugins. 466 * @param verbosity "disable" will hide messages from plugin construction. 467 * @return this builder instance. 468 */ 469 ConfigurationBuilder<T> setVerbosity(String verbosity); 470 471 /** 472 * Specifies the destination for StatusLogger events. This can be {@code out} (default) for using 473 * {@link System#out standard out}, {@code err} for using {@link System#err standard error}, or a file URI to 474 * which log events will be written. If the provided URI is invalid, then the default destination of standard 475 * out will be used. 476 * 477 * @param destination where status log messages should be output. 478 * @return this builder instance. 479 */ 480 ConfigurationBuilder<T> setDestination(String destination); 481 482 /** 483 * Sets the logger context. 484 * @param loggerContext the logger context. 485 */ 486 void setLoggerContext(LoggerContext loggerContext); 487 488 /** 489 * Add the properties for the root node. 490 * @param key The property key. 491 * @param value The property value. 492 * @return this builder instance. 493 */ 494 ConfigurationBuilder<T> addRootProperty(String key, String value); 495 496 /** 497 * Build the configuration and optionally initialize it. 498 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations 499 * should not be initialized when they are constructed. 500 * @return The constructed Configuration. 501 */ 502 T build(boolean initialize); 503 504 /** 505 * Constructs an XML configuration from this builder. 506 * 507 * @param output OutputStream to write to, will not be closed 508 * 509 * @since 2.7 510 */ 511 void writeXmlConfiguration(OutputStream output) throws IOException; 512 513 /** 514 * Constructs an XML configuration from this builder. 515 * 516 * @return XML configuration 517 * 518 * @since 2.7 519 */ 520 String toXmlConfiguration(); 521}