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 */ 017 018package org.apache.logging.log4j.core; 019 020import org.apache.logging.log4j.Level; 021import org.apache.logging.log4j.Marker; 022import org.apache.logging.log4j.message.Message; 023import org.apache.logging.log4j.util.EnglishEnums; 024 025/** 026 * Interface that must be implemented to allow custom event filtering. It is highly recommended that 027 * applications make use of the Filters provided with this implementation before creating their own. 028 * 029 * <p>This interface supports "global" filters (i.e. - all events must pass through them first), attached to 030 * specific loggers and associated with Appenders. It is recommended that, where possible, Filter implementations 031 * create a generic filtering method that can be called from any of the filter methods.</p> 032 */ 033public interface Filter extends LifeCycle { 034 035 /** 036 * The empty array. 037 */ 038 Filter[] EMPTY_ARRAY = {}; 039 040 /** 041 * Main {@linkplain org.apache.logging.log4j.core.config.plugins.Plugin#elementType() plugin element type} for 042 * Filter plugins. 043 * 044 * @since 2.1 045 */ 046 String ELEMENT_TYPE = "filter"; 047 048 /** 049 * The result that can returned from a filter method call. 050 */ 051 enum Result { 052 /** 053 * The event will be processed without further filtering based on the log Level. 054 */ 055 ACCEPT, 056 /** 057 * No decision could be made, further filtering should occur. 058 */ 059 NEUTRAL, 060 /** 061 * The event should not be processed. 062 */ 063 DENY; 064 065 /** 066 * Returns the Result for the given string. 067 * 068 * @param name The Result enum name, case-insensitive. If null, returns, null 069 * @return a Result enum value or null if name is null 070 */ 071 public static Result toResult(final String name) { 072 return toResult(name, null); 073 } 074 075 /** 076 * Returns the Result for the given string. 077 * 078 * @param name The Result enum name, case-insensitive. If null, returns, defaultResult 079 * @param defaultResult the Result to return if name is null 080 * @return a Result enum value or null if name is null 081 */ 082 public static Result toResult(final String name, final Result defaultResult) { 083 return EnglishEnums.valueOf(Result.class, name, defaultResult); 084 } 085} 086 087 /** 088 * Returns the result that should be returned when the filter does not match the event. 089 * @return the Result that should be returned when the filter does not match the event. 090 */ 091 Result getOnMismatch(); 092 /** 093 * Returns the result that should be returned when the filter matches the event. 094 * @return the Result that should be returned when the filter matches the event. 095 */ 096 Result getOnMatch(); 097 098 /** 099 * Filter an event. 100 * @param logger The Logger. 101 * @param level The event logging Level. 102 * @param marker The Marker for the event or null. 103 * @param msg String text to filter on. 104 * @param params An array of parameters or null. 105 * @return the Result. 106 */ 107 Result filter(Logger logger, Level level, Marker marker, String msg, Object... params); 108 109 /** 110 * Filter an event. 111 * 112 * @param logger The Logger. 113 * @param level the event logging level. 114 * @param marker The Marker for the event or null. 115 * @param message The message. 116 * @param p0 the message parameters 117 * @return the Result. 118 */ 119 Result filter(Logger logger, Level level, Marker marker, String message, Object p0); 120 121 /** 122 * Filter an event. 123 * 124 * @param logger The Logger. 125 * @param level the event logging level. 126 * @param marker The Marker for the event or null. 127 * @param message The message. 128 * @param p0 the message parameters 129 * @param p1 the message parameters 130 * @return the Result. 131 */ 132 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1); 133 134 /** 135 * Filter an event. 136 * 137 * @param logger The Logger. 138 * @param level the event logging level. 139 * @param marker The Marker for the event or null. 140 * @param message The message. 141 * @param p0 the message parameters 142 * @param p1 the message parameters 143 * @param p2 the message parameters 144 * @return the Result. 145 */ 146 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2); 147 148 /** 149 * Filter an event. 150 * 151 * @param logger The Logger. 152 * @param level the event logging level. 153 * @param marker The Marker for the event or null. 154 * @param message The message. 155 * @param p0 the message parameters 156 * @param p1 the message parameters 157 * @param p2 the message parameters 158 * @param p3 the message parameters 159 * @return the Result. 160 */ 161 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3); 162 163 /** 164 * Filter an event. 165 * 166 * @param logger The Logger. 167 * @param level the event logging level. 168 * @param marker The Marker for the event or null. 169 * @param message The message. 170 * @param p0 the message parameters 171 * @param p1 the message parameters 172 * @param p2 the message parameters 173 * @param p3 the message parameters 174 * @param p4 the message parameters 175 * @return the Result. 176 */ 177 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 178 Object p4); 179 180 /** 181 * Filter an event. 182 * 183 * @param logger The Logger. 184 * @param level the event logging level. 185 * @param marker The Marker for the event or null. 186 * @param message The message. 187 * @param p0 the message parameters 188 * @param p1 the message parameters 189 * @param p2 the message parameters 190 * @param p3 the message parameters 191 * @param p4 the message parameters 192 * @param p5 the message parameters 193 * @return the Result. 194 */ 195 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 196 Object p4, Object p5); 197 198 /** 199 * Filter an event. 200 * 201 * @param logger The Logger. 202 * @param level the event logging level. 203 * @param marker The Marker for the event or null. 204 * @param message The message. 205 * @param p0 the message parameters 206 * @param p1 the message parameters 207 * @param p2 the message parameters 208 * @param p3 the message parameters 209 * @param p4 the message parameters 210 * @param p5 the message parameters 211 * @param p6 the message parameters 212 * @return the Result. 213 */ 214 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 215 Object p4, Object p5, Object p6); 216 217 /** 218 * Filter an event. 219 * 220 * @param logger The Logger. 221 * @param level the event logging level. 222 * @param marker The Marker for the event or null. 223 * @param message The message. 224 * @param p0 the message parameters 225 * @param p1 the message parameters 226 * @param p2 the message parameters 227 * @param p3 the message parameters 228 * @param p4 the message parameters 229 * @param p5 the message parameters 230 * @param p6 the message parameters 231 * @param p7 the message parameters 232 * @return the Result. 233 */ 234 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 235 Object p4, Object p5, Object p6, Object p7); 236 237 /** 238 * Filter an event. 239 * 240 * @param logger The Logger. 241 * @param level the event logging level. 242 * @param marker The Marker for the event or null. 243 * @param message The message. 244 * @param p0 the message parameters 245 * @param p1 the message parameters 246 * @param p2 the message parameters 247 * @param p3 the message parameters 248 * @param p4 the message parameters 249 * @param p5 the message parameters 250 * @param p6 the message parameters 251 * @param p7 the message parameters 252 * @param p8 the message parameters 253 * @return the Result. 254 */ 255 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 256 Object p4, Object p5, Object p6, Object p7, Object p8); 257 258 /** 259 * Filter an event. 260 * 261 * @param logger The Logger. 262 * @param level the event logging level. 263 * @param marker The Marker for the event or null. 264 * @param message The message. 265 * @param p0 the message parameters 266 * @param p1 the message parameters 267 * @param p2 the message parameters 268 * @param p3 the message parameters 269 * @param p4 the message parameters 270 * @param p5 the message parameters 271 * @param p6 the message parameters 272 * @param p7 the message parameters 273 * @param p8 the message parameters 274 * @param p9 the message parameters 275 * @return the Result. 276 */ 277 Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3, 278 Object p4, Object p5, Object p6, Object p7, Object p8, Object p9); 279 280 /** 281 * Filter an event. 282 * @param logger The Logger. 283 * @param level The event logging Level. 284 * @param marker The Marker for the event or null. 285 * @param msg Any Object. 286 * @param t A Throwable or null. 287 * @return the Result. 288 */ 289 Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t); 290 291 /** 292 * Filter an event. 293 * @param logger The Logger. 294 * @param level The event logging Level. 295 * @param marker The Marker for the event or null. 296 * @param msg The Message 297 * @param t A Throwable or null. 298 * @return the Result. 299 */ 300 Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t); 301 302 /** 303 * Filter an event. 304 * @param event The Event to filter on. 305 * @return the Result. 306 */ 307 Result filter(LogEvent event); 308 309}