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 * Adds an AppenderComponent. 034 * @param builder The AppenderComponentBuilder with all of its attributes and sub components set. 035 * @return this builder instance. 036 */ 037 ConfigurationBuilder<T> add(AppenderComponentBuilder builder); 038 039 /** 040 * Adds a CustomLevel component. 041 * @param builder The CustomLevelComponentBuilder with all of its attributes set. 042 * @return this builder instance. 043 */ 044 ConfigurationBuilder<T> add(CustomLevelComponentBuilder builder); 045 046 /** 047 * Adds a Filter component. 048 * @param builder the FilterComponentBuilder with all of its attributes and sub components set. 049 * @return this builder instance. 050 */ 051 ConfigurationBuilder<T> add(FilterComponentBuilder builder); 052 053 /** 054 * Adds a Logger component. 055 * @param builder The LoggerComponentBuilder with all of its attributes and sub components set. 056 * @return this builder instance. 057 */ 058 ConfigurationBuilder<T> add(LoggerComponentBuilder builder); 059 060 /** 061 * Adds the root Logger component. 062 * @param builder The RootLoggerComponentBuilder with all of its attributes and sub components set. 063 * @return this builder instance. 064 */ 065 ConfigurationBuilder<T> add(RootLoggerComponentBuilder builder); 066 067 /** 068 * Adds a Property key and value. 069 * @param key The property key. 070 * @param value The property value. 071 * @return this builder instance. 072 */ 073 ConfigurationBuilder<T> addProperty(String key, String value); 074 075 /** 076 * Returns a builder for creating Appenders. 077 * @param name The name of the Appender. 078 * @param pluginName The Plugin type of the Appender. 079 * @return A new AppenderComponentBuilder. 080 */ 081 AppenderComponentBuilder newAppender(String name, String pluginName); 082 083 /** 084 * Returns a builder for creating AppenderRefs. 085 * @param ref The name of the Appender being referenced. 086 * @return A new AppenderRefComponentBuilder. 087 */ 088 AppenderRefComponentBuilder newAppenderRef(String ref); 089 090 /** 091 * Returns a builder for creating Async Loggers. 092 * @param name The name of the Logger. 093 * @param level The logging Level to be assigned to the Logger. 094 * @return A new LoggerComponentBuilder. 095 */ 096 LoggerComponentBuilder newAsyncLogger(String name, Level level); 097 098 /** 099 * 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}