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 org.apache.logging.log4j.Level; 020import org.apache.logging.log4j.core.Filter; 021import org.apache.logging.log4j.core.config.Configuration; 022import org.apache.logging.log4j.core.config.ConfigurationSource; 023import org.apache.logging.log4j.core.util.Builder; 024 025/** 026 * Interface for building logging configurations. 027 * @param <T> The Configuration type created by this builder. 028 * @since 2.4 029 */ 030public interface ConfigurationBuilder<T extends Configuration> extends Builder<T> { 031 032 033 /** 034 * Adds a ScriptComponent. 035 * @param builder The ScriptComponentBuilder with all of its attributes and sub components set. 036 * @return this builder instance. 037 */ 038 ConfigurationBuilder<T> add(ScriptComponentBuilder builder); 039 040 /** 041 * Adds a ScriptFileComponent. 042 * @param builder The ScriptFileComponentBuilder with all of its attributes and sub components set. 043 * @return this builder instance. 044 */ 045 ConfigurationBuilder<T> add(ScriptFileComponentBuilder builder); 046 047 /** 048 * Adds an AppenderComponent. 049 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set. 050 * @return this builder instance. 051 */ 052 ConfigurationBuilder<T> add(AppenderComponentBuilder builder); 053 054 /** 055 * Adds a CustomLevel component. 056 * @param builder The CustomLevelComponentBuilder with all of its attributes set. 057 * @return this builder instance. 058 */ 059 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder); 060 061 /** 062 * Adds a Filter component. 063 * @param builder the FilterComponentBuilder with all of its attributes and sub components set. 064 * @return this builder instance. 065 */ 066 ConfigurationBuilder<T> add(FilterComponentBuilder builder); 067 068 /** 069 * Adds a Logger component. 070 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set. 071 * @return this builder instance. 072 */ 073 ConfigurationBuilder<T> add(LoggerComponentBuilder builder); 074 075 /** 076 * Adds the root Logger component. 077 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set. 078 * @return this builder instance. 079 */ 080 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder); 081 082 /** 083 * Adds a Property key and value. 084 * @param key The property key. 085 * @param value The property value. 086 * @return this builder instance. 087 */ 088 ConfigurationBuilder<T> addProperty(String key, String value); 089 090 091 /** 092 * Returns a builder for creating Async Loggers. 093 * @param name The name of the Logger. 094 * @param language The script language 095 * @param text The script to execute. 096 * @return A new ScriptComponentBuilder. 097 */ 098 ScriptComponentBuilder newScript(String name, String language, String text); 099 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}