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    
018    package org.apache.logging.log4j.core;
019    
020    import java.util.Locale;
021    
022    import org.apache.logging.log4j.Level;
023    import org.apache.logging.log4j.Marker;
024    import org.apache.logging.log4j.core.net.Protocol;
025    import org.apache.logging.log4j.message.Message;
026    import org.apache.logging.log4j.util.EnglishEnums;
027    
028    /**
029     * Interface that must be implemented to allow custom event filtering. It is highly recommended that
030     * applications make use of the Filters provided with this implementation before creating their own.
031     *
032     * This interface supports "global" filters (i.e. - all events must pass through them first), attached to
033     * specific loggers and associated with Appenders. It is recommended that, where possible, Filter implementations
034     * create a generic filtering method that can be called from any of the filter methods.
035     */
036    public interface Filter {
037    
038        /**
039         * The result that can returned from a filter method call.
040         */
041        public enum Result {
042            /**
043             * The event will be processed without further filtering based on the log Level.
044             */
045            ACCEPT,
046            /**
047             * No decision could be made, further filtering should occur.
048             */
049            NEUTRAL,
050            /**
051             * The event should not be processed.
052             */
053            DENY;
054            
055            /**
056             * Returns the Result for the given string.
057             * 
058             * @param name The Result enum name, case-insensitive. If null, returns, null
059             * @return a Result enum value or null if name is null
060             */
061            public static Result toResult(String name) {
062                return toResult(name, null);
063            }
064    
065            /**
066             * Returns the Result for the given string.
067             * 
068             * @param name The Result enum name, case-insensitive. If null, returns, defaultResult
069             * @param defaultResult the Result to return if name is null
070             * @return a Result enum value or null if name is null
071             */
072            public static Result toResult(String name, Result defaultResult) {
073                return EnglishEnums.valueOf(Result.class, name, defaultResult);
074            }
075    }
076    
077        /**
078         * Returns the result that should be returned when the filter does not match the event.
079         * @return the Result that should be returned when the filter does not match the event.
080         */
081        Result getOnMismatch();
082        /**
083         * Returns the result that should be returned when the filter matches the event.
084         * @return the Result that should be returned when the filter matches the event.
085         */
086        Result getOnMatch();
087    
088        /**
089         * Filter an event.
090         * @param logger The Logger.
091         * @param level The event logging Level.
092         * @param marker The Marker for the event or null.
093         * @param msg String text to filter on.
094         * @param params An array of parameters or null.
095         * @return the Result.
096         */
097        Result filter(Logger logger, Level level, Marker marker, String msg, Object... params);
098    
099        /**
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    }