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 }