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 * Adds an AppenderComponent. 34 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set. 35 * @return this builder instance. 36 */ 37 ConfigurationBuilder<T> add(AppenderComponentBuilder builder); 38 39 /** 40 * Adds a CustomLevel component. 41 * @param builder The CustomLevelComponentBuilder with all of its attributes set. 42 * @return this builder instance. 43 */ 44 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder); 45 46 /** 47 * Adds a Filter component. 48 * @param builder the FilterComponentBuilder with all of its attributes and sub components set. 49 * @return this builder instance. 50 */ 51 ConfigurationBuilder<T> add(FilterComponentBuilder builder); 52 53 /** 54 * Adds a Logger component. 55 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set. 56 * @return this builder instance. 57 */ 58 ConfigurationBuilder<T> add(LoggerComponentBuilder builder); 59 60 /** 61 * Adds the root Logger component. 62 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set. 63 * @return this builder instance. 64 */ 65 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder); 66 67 /** 68 * Adds a Property key and value. 69 * @param key The property key. 70 * @param value The property value. 71 * @return this builder instance. 72 */ 73 ConfigurationBuilder<T> addProperty(String key, String value); 74 75 /** 76 * Returns a builder for creating Appenders. 77 * @param name The name of the Appender. 78 * @param pluginName The Plugin type of the Appender. 79 * @return A new AppenderComponentBuilder. 80 */ 81 AppenderComponentBuilder newAppender(String name, String pluginName); 82 83 /** 84 * Returns a builder for creating AppenderRefs. 85 * @param ref The name of the Appender being referenced. 86 * @return A new AppenderRefComponentBuilder. 87 */ 88 AppenderRefComponentBuilder newAppenderRef(String ref); 89 90 /** 91 * Returns a builder for creating Async Loggers. 92 * @param name The name of the Logger. 93 * @param level The logging Level to be assigned to the Logger. 94 * @return A new LoggerComponentBuilder. 95 */ 96 LoggerComponentBuilder newAsyncLogger(String name, Level level); 97 98 /** 99 * Returns a builder for creating Async Loggers. 100 * @param name The name of the Logger. 101 * @param level The logging Level to be assigned to the Logger. 102 * @return A new LoggerComponentBuilder. 103 */ 104 LoggerComponentBuilder newAsyncLogger(String name, String level); 105 106 /** 107 * Returns a builder for creating the async root Logger. 108 * @param level The logging Level to be assigned to the root Logger. 109 * @return A new RootLoggerComponentBuilder. 110 */ 111 RootLoggerComponentBuilder newAsyncRootLogger(Level level); 112 113 /** 114 * Returns a builder for creating the async root Logger. 115 * @param level The logging Level to be assigned to the root Logger. 116 * @return A new RootLoggerComponentBuilder. 117 */ 118 RootLoggerComponentBuilder newAsyncRootLogger(String level); 119 120 /** 121 * Returns a builder for creating generic components. 122 * @param <B> ComponentBuilder target type 123 * @param name The name of the component (may be null). 124 * @param pluginName The Plugin type of the component. 125 * @return A new ComponentBuilder. 126 */ 127 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName); 128 129 /** 130 * Returns a builder for creating generic components. 131 * @param <B> ComponentBuilder target type 132 * @param name The name of the component (may be null). 133 * @param pluginName The Plugin type of the component. 134 * @param value The value of the component. 135 * @return A new ComponentBuilder. 136 */ 137 <B extends ComponentBuilder<B>> ComponentBuilder<B> newComponent(String name, String pluginName, String value); 138 139 140 /** 141 * Returns a builder for creating CustomLevels 142 * @param name The name of the custom level. 143 * @param level The integer value to be assigned to the level. 144 * @return A new CustomLevelComponentBuilder. 145 */ 146 CustomLevelComponentBuilder newCustomLevel(String name, int level); 147 148 /** 149 * Returns a builder for creating Filters. 150 * @param pluginName The Plugin type of the Filter. 151 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 152 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 153 * @return A new FilterComponentBuilder. 154 */ 155 FilterComponentBuilder newFilter(String pluginName, Filter.Result onMatch, Filter.Result onMisMatch); 156 157 /** 158 * Returns a builder for creating Filters. 159 * @param pluginName The Plugin type of the Filter. 160 * @param onMatch "ACCEPT", "DENY", or "NEUTRAL" 161 * @param onMisMatch "ACCEPT", "DENY", or "NEUTRAL" 162 * @return A new FilterComponentBuilder. 163 */ 164 FilterComponentBuilder newFilter(String pluginName, String onMatch, String onMisMatch); 165 166 /** 167 * Returns a builder for creating Layouts. 168 * @param pluginName The Plugin type of the Layout. 169 * @return A new LayoutComponentBuilder. 170 */ 171 LayoutComponentBuilder newLayout(String pluginName); 172 173 /** 174 * Returns a builder for creating Loggers. 175 * @param name The name of the Logger. 176 * @param level The logging Level to be assigned to the Logger. 177 * @return A new LoggerComponentBuilder. 178 */ 179 LoggerComponentBuilder newLogger(String name, Level level); 180 181 /** 182 * Returns a builder for creating Loggers. 183 * @param name The name of the Logger. 184 * @param level The logging Level to be assigned to the Logger. 185 * @return A new LoggerComponentBuilder. 186 */ 187 LoggerComponentBuilder newLogger(String name, String level); 188 189 /** 190 * Returns a builder for creating the root Logger. 191 * @param level The logging Level to be assigned to the root Logger. 192 * @return A new RootLoggerComponentBuilder. 193 */ 194 RootLoggerComponentBuilder newRootLogger(Level level); 195 196 /** 197 * Returns a builder for creating the root Logger. 198 * @param level The logging Level to be assigned to the root Logger. 199 * @return A new RootLoggerComponentBuilder. 200 */ 201 RootLoggerComponentBuilder newRootLogger(String level); 202 203 /** 204 * Set the Advertiser Plugin name. 205 * @param advertiser The Advertiser Plugin name. 206 * @return this builder instance. 207 */ 208 ConfigurationBuilder<T> setAdvertiser(String advertiser); 209 210 /** 211 * Sets the name of the configuration. 212 * @param name the name of the {@link Configuration}. By default is {@code "Constructed"}. 213 * @return this builder instance. 214 */ 215 ConfigurationBuilder<T> setConfigurationName(String name); 216 217 /** 218 * Sets the configuration source, if one exists. 219 * @param configurationSource the ConfigurationSource. 220 * @return this builder instance. 221 */ 222 ConfigurationBuilder<T> setConfigurationSource(ConfigurationSource configurationSource); 223 224 /** 225 * Sets the interval at which the configuration file should be checked for changes. 226 * @param intervalSeconds The number of seconds that should pass between checks of the configuration file. 227 * @return this builder instance. 228 */ 229 ConfigurationBuilder<T> setMonitorInterval(String intervalSeconds); 230 231 /** 232 * Sets the list of packages to search for plugins. 233 * @param packages The comma separated list of packages. 234 * @return this builder instance. 235 */ 236 ConfigurationBuilder<T> setPackages(String packages); 237 238 /** 239 * Sets whether the shutdown hook should be disabled. 240 * @param flag "disable" will prevent the shutdown hook from being set. 241 * @return this builder instance. 242 */ 243 ConfigurationBuilder<T> setShutdownHook(String flag); 244 245 246 /** 247 * Sets the level of the StatusLogger. 248 * @param level The logging level. 249 * @return this builder instance. 250 */ 251 ConfigurationBuilder<T> setStatusLevel(Level level); 252 253 254 /** 255 * Sets whether the logging should include constructing Plugins. 256 * @param verbosity "disable" will hide messages from plugin construction. 257 * @return this builder instance. 258 */ 259 ConfigurationBuilder<T> setVerbosity(String verbosity); 260 }