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 * Returns a builder for creating Async Loggers. 139 * @param name The name of the Logger. 140 * @param level The logging Level to be assigned to the Logger. 141 * @return A new LoggerComponentBuilder. 142 */ 143 LoggerComponentBuilder newAsyncLogger(String name, Level level); 144 145 /** 146 * Returns a builder for creating Async Loggers. 147 * @param name The name of the Logger. 148 * @param level The logging Level to be assigned to the Logger. 149 * @param includeLocation If true include location information. 150 * @return A new LoggerComponentBuilder. 151 */ 152 LoggerComponentBuilder newAsyncLogger(String name, Level level, boolean includeLocation); 153 154 /** 155 * Returns a builder for creating Async Loggers. 156 * @param name The name of the Logger. 157 * @param level The logging Level to be assigned to the Logger. 158 * @return A new LoggerComponentBuilder. 159 */ 160 LoggerComponentBuilder newAsyncLogger(String name, String level); 161 162 /** 163 * Returns a builder for creating Async Loggers. 164 * @param name The name of the Logger. 165 * @param level The logging Level to be assigned to the Logger. 166 * @param includeLocation If true include location information. 167 * @return A new LoggerComponentBuilder. 168 */ 169 LoggerComponentBuilder newAsyncLogger(String name, String level, boolean includeLocation); 170 171 /** 172 * Returns a builder for creating the async root Logger. 173 * @param level The logging Level to be assigned to the root Logger. 174 * @return A new RootLoggerComponentBuilder. 175 */ 176 RootLoggerComponentBuilder newAsyncRootLogger(Level level); 177 178 179 /** 180 * Returns a builder for creating the async root Logger. 181 * @param level The logging Level to be assigned to the root Logger. 182 * @param includeLocation If true include location information. 183 * @return A new RootLoggerComponentBuilder. 184 */ 185 RootLoggerComponentBuilder newAsyncRootLogger(Level level, boolean includeLocation); 186 187 /** 188 * Returns a builder for creating the async root Logger. 189 * @param level The logging Level to be assigned to the root Logger. 190 * @return A new RootLoggerComponentBuilder. 191 */ 192 RootLoggerComponentBuilder newAsyncRootLogger(String level); 193 194 195 /** 196 * Returns a builder for creating the async root Logger. 197 * @param level The logging Level to be assigned to the root Logger. 198 * @param includeLocation If true include location information. 199 * @return A new RootLoggerComponentBuilder. 200 */ 201 RootLoggerComponentBuilder newAsyncRootLogger(String level, boolean includeLocation); 202 203 /** 204 * Returns a builder for creating generic components. 205 * @param <B> ComponentBuilder target type 206 * @param pluginName The Plugin type of the component. 207 * @return A new ComponentBuilder. 208 */ 209 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String pluginName); 210 211 /** 212 * Returns a builder for creating generic components. 213 * @param <B> ComponentBuilder target type 214 * @param name The name of the component (may be null). 215 * @param pluginName The Plugin type of the component. 216 * @return A new ComponentBuilder. 217 */ 218 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName); 219 220 /** 221 * Returns a builder for creating generic components. 222 * @param <B> ComponentBuilder target type 223 * @param name The name of the component (may be null). 224 * @param pluginName The Plugin type of the component. 225 * @param value The value of the component. 226 * @return A new ComponentBuilder. 227 */ 228 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value); 229 230 231 /** 232 * Returns a builder for creating CustomLevels 233 * @param name The name of the custom level. 234 * @param level The integer value to be assigned to the level. 235 * @return A new CustomLevelComponentBuilder. 236 */ 237 CustomLevelComponentBuilder newCustomLevel(String name, int level); 238 239 /** 240 * Returns a builder for creating Filters. 241 * @param pluginName The Plugin type of the Filter. 242 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 243 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 244 * @return A new FilterComponentBuilder. 245 */ 246 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch); 247 248 /** 249 * Returns a builder for creating Filters. 250 * @param pluginName The Plugin type of the Filter. 251 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 252 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 253 * @return A new FilterComponentBuilder. 254 */ 255 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch); 256 257 /** 258 * Returns a builder for creating Layouts. 259 * @param pluginName The Plugin type of the Layout. 260 * @return A new LayoutComponentBuilder. 261 */ 262 LayoutComponentBuilder newLayout(String pluginName); 263 264 /** 265 * Returns a builder for creating Loggers. 266 * @param name The name of the Logger. 267 * @param level The logging Level to be assigned to the Logger. 268 * @return A new LoggerComponentBuilder. 269 */ 270 LoggerComponentBuilder newLogger(String name, Level level); 271 272 /** 273 * Returns a builder for creating Loggers. 274 * @param name The name of the Logger. 275 * @param level The logging Level to be assigned to the Logger. 276 * @param includeLocation If true include location information. 277 * @return A new LoggerComponentBuilder. 278 */ 279 LoggerComponentBuilder newLogger(String name, Level level, boolean includeLocation); 280 281 /** 282 * Returns a builder for creating Loggers. 283 * @param name The name of the Logger. 284 * @param level The logging Level to be assigned to the Logger. 285 * @return A new LoggerComponentBuilder. 286 */ 287 LoggerComponentBuilder newLogger(String name, String level); 288 289 /** 290 * Returns a builder for creating Loggers. 291 * @param name The name of the Logger. 292 * @param level The logging Level to be assigned to the Logger. 293 * @param includeLocation If true include location information. 294 * @return A new LoggerComponentBuilder. 295 */ 296 LoggerComponentBuilder newLogger(String name, String level, boolean includeLocation); 297 298 /** 299 * Returns a builder for creating the root Logger. 300 * @param level The logging Level to be assigned to the root Logger. 301 * @return A new RootLoggerComponentBuilder. 302 */ 303 RootLoggerComponentBuilder newRootLogger(Level level); 304 305 /** 306 * Returns a builder for creating the root Logger. 307 * @param level The logging Level to be assigned to the root Logger. 308 * @param includeLocation If true include location information. 309 * @return A new RootLoggerComponentBuilder. 310 */ 311 RootLoggerComponentBuilder newRootLogger(Level level, boolean includeLocation); 312 313 /** 314 * Returns a builder for creating the root Logger. 315 * @param level The logging Level to be assigned to the root Logger. 316 * 317 * @return A new RootLoggerComponentBuilder. 318 */ 319 RootLoggerComponentBuilder newRootLogger(String level); 320 321 /** 322 * Returns a builder for creating the root Logger. 323 * @param level The logging Level to be assigned to the root Logger. 324 * 325 * @return A new RootLoggerComponentBuilder. 326 */ 327 RootLoggerComponentBuilder newRootLogger(String level, boolean includeLocation); 328 329 /** 330 * Set the Advertiser Plugin name. 331 * @param advertiser The Advertiser Plugin name. 332 * @return this builder instance. 333 */ 334 ConfigurationBuilder<T> setAdvertiser(String advertiser); 335 336 /** 337 * Sets the name of the configuration. 338 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}. 339 * @return this builder instance. 340 */ 341 ConfigurationBuilder<T> setConfigurationName(String name); 342 343 /** 344 * Sets the configuration source, if one exists. 345 * @param configurationSource the ConfigurationSource. 346 * @return this builder instance. 347 */ 348 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource); 349 350 /** 351 * Sets the interval at which the configuration file should be checked for changes. 352 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file. 353 * @return this builder instance. 354 */ 355 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds); 356 357 /** 358 * Sets the list of packages to search for plugins. 359 * @param packages The comma separated list of packages. 360 * @return this builder instance. 361 */ 362 ConfigurationBuilder<T> setPackages(String packages); 363 364 /** 365 * Sets whether the shutdown hook should be disabled. 366 * @param flag "disable" will prevent the shutdown hook from being set. 367 * @return this builder instance. 368 */ 369 ConfigurationBuilder<T> setShutdownHook(String flag); 370 371 /** 372 * How long appenders and background tasks will get to shutdown when the JVM shuts down. 373 * Default is zero which mean that each appender uses its default timeout, and don't wait for background 374 * tasks. Not all appenders will honor this, it is a hint and not an absolute guarantee that the shutdown 375 * procedure will not take longer. Setting this too low increase the risk of losing outstanding log events 376 * not yet written to the final destination. (Not used if {@link #setShutdownHook(String)} is set to "disable".) 377 * @return this builder instance. 378 * 379 * @see LoggerContext#stop(long, TimeUnit) 380 */ 381 ConfigurationBuilder<T> setShutdownTimeout(long timeout, TimeUnit timeUnit); 382 383 /** 384 * Sets the level of the StatusLogger. 385 * @param level The logging level. 386 * @return this builder instance. 387 */ 388 ConfigurationBuilder<T> setStatusLevel(Level level); 389 390 391 /** 392 * Sets whether the logging should include constructing Plugins. 393 * @param verbosity "disable" will hide messages from plugin construction. 394 * @return this builder instance. 395 */ 396 ConfigurationBuilder<T> setVerbosity(String verbosity); 397 398 /** 399 * Specifies the destination for StatusLogger events. This can be {@code out} (default) for using 400 * {@link System#out standard out}, {@code err} for using {@link System#err standard error}, or a file URI to 401 * which log events will be written. If the provided URI is invalid, then the default destination of standard 402 * out will be used. 403 * 404 * @param destination where status log messages should be output. 405 * @return this builder instance. 406 */ 407 ConfigurationBuilder<T> setDestination(String destination); 408 409 /** 410 * Sets the logger context. 411 * @param loggerContext the logger context. 412 */ 413 void setLoggerContext(LoggerContext loggerContext); 414 415 /** 416 * Add the properties for the root node. 417 * @param key The property key. 418 * @param value The property value. 419 * @return this builder instance. 420 */ 421 ConfigurationBuilder<T> addRootProperty(String key, String value); 422 423 /** 424 * Build the configuration and optionally initialize it. 425 * @param initialize true if the configuration should be initialized, false otherwise. Generally, Configurations 426 * should not be initialized when they are constructed. 427 * @return The constructed Configuration. 428 */ 429 T build(boolean initialize); 430 431 /** 432 * Constructs an XML configuration from this builder. 433 * 434 * @param output OutputStream to write to, will not be closed 435 * 436 * @since 2.7 437 */ 438 void writeXmlConfiguration(OutputStream output) throws IOException; 439 440 /** 441 * Constructs an XML configuration from this builder. 442 * 443 * @return XML configuration 444 * 445 * @since 2.7 446 */ 447 String toXmlConfiguration(); 448}