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 18 package org.apache.logging.log4j.core; 19 20 import java.util.Locale; 21 22 import org.apache.logging.log4j.Level; 23 import org.apache.logging.log4j.Marker; 24 import org.apache.logging.log4j.core.net.Protocol; 25 import org.apache.logging.log4j.message.Message; 26 import org.apache.logging.log4j.util.EnglishEnums; 27 28 /** 29 * Interface that must be implemented to allow custom event filtering. It is highly recommended that 30 * applications make use of the Filters provided with this implementation before creating their own. 31 * 32 * This interface supports "global" filters (i.e. - all events must pass through them first), attached to 33 * specific loggers and associated with Appenders. It is recommended that, where possible, Filter implementations 34 * create a generic filtering method that can be called from any of the filter methods. 35 */ 36 public interface Filter { 37 38 /** 39 * The result that can returned from a filter method call. 40 */ 41 public enum Result { 42 /** 43 * The event will be processed without further filtering based on the log Level. 44 */ 45 ACCEPT, 46 /** 47 * No decision could be made, further filtering should occur. 48 */ 49 NEUTRAL, 50 /** 51 * The event should not be processed. 52 */ 53 DENY; 54 55 /** 56 * Returns the Result for the given string. 57 * 58 * @param name The Result enum name, case-insensitive. If null, returns, null 59 * @return a Result enum value or null if name is null 60 */ 61 public static Result toResult(String name) { 62 return toResult(name, null); 63 } 64 65 /** 66 * Returns the Result for the given string. 67 * 68 * @param name The Result enum name, case-insensitive. If null, returns, defaultResult 69 * @param defaultResult the Result to return if name is null 70 * @return a Result enum value or null if name is null 71 */ 72 public static Result toResult(String name, Result defaultResult) { 73 return EnglishEnums.valueOf(Result.class, name, defaultResult); 74 } 75 } 76 77 /** 78 * Returns the result that should be returned when the filter does not match the event. 79 * @return the Result that should be returned when the filter does not match the event. 80 */ 81 Result getOnMismatch(); 82 /** 83 * Returns the result that should be returned when the filter matches the event. 84 * @return the Result that should be returned when the filter matches the event. 85 */ 86 Result getOnMatch(); 87 88 /** 89 * Filter an event. 90 * @param logger The Logger. 91 * @param level The event logging Level. 92 * @param marker The Marker for the event or null. 93 * @param msg String text to filter on. 94 * @param params An array of parameters or null. 95 * @return the Result. 96 */ 97 Result filter(Logger logger, Level level, Marker marker, String msg, Object... params); 98 99 /** 100 * Filter an event. 101 * @param logger The Logger. 102 * @param level The event logging Level. 103 * @param marker The Marker for the event or null. 104 * @param msg Any Object. 105 * @param t A Throwable or null. 106 * @return the Result. 107 */ 108 Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t); 109 110 /** 111 * Filter an event. 112 * @param logger The Logger. 113 * @param level The event logging Level. 114 * @param marker The Marker for the event or null. 115 * @param msg The Message 116 * @param t A Throwable or null. 117 * @return the Result. 118 */ 119 Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t); 120 121 /** 122 * Filter an event. 123 * @param event The Event to filter on. 124 * @return the Result. 125 */ 126 Result filter(LogEvent event); 127 128 }