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 org.apache.logging.log4j.Level;
021    import org.apache.logging.log4j.Marker;
022    import org.apache.logging.log4j.message.Message;
023    import 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     * 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.
032     */
033    public interface Filter extends LifeCycle {
034    
035        /**
036         * The result that can returned from a filter method call.
037         */
038         enum Result {
039            /**
040             * The event will be processed without further filtering based on the log Level.
041             */
042            ACCEPT,
043            /**
044             * No decision could be made, further filtering should occur.
045             */
046            NEUTRAL,
047            /**
048             * The event should not be processed.
049             */
050            DENY;
051    
052            /**
053             * Returns the Result for the given string.
054             *
055             * @param name The Result enum name, case-insensitive. If null, returns, null
056             * @return a Result enum value or null if name is null
057             */
058            public static Result toResult(final String name) {
059                return toResult(name, null);
060            }
061    
062            /**
063             * Returns the Result for the given string.
064             *
065             * @param name The Result enum name, case-insensitive. If null, returns, defaultResult
066             * @param defaultResult the Result to return if name is null
067             * @return a Result enum value or null if name is null
068             */
069            public static Result toResult(final String name, final Result defaultResult) {
070                return EnglishEnums.valueOf(Result.class, name, defaultResult);
071            }
072    }
073    
074        /**
075         * Returns the result that should be returned when the filter does not match the event.
076         * @return the Result that should be returned when the filter does not match the event.
077         */
078        Result getOnMismatch();
079        /**
080         * Returns the result that should be returned when the filter matches the event.
081         * @return the Result that should be returned when the filter matches the event.
082         */
083        Result getOnMatch();
084    
085        /**
086         * Filter an event.
087         * @param logger The Logger.
088         * @param level The event logging Level.
089         * @param marker The Marker for the event or null.
090         * @param msg String text to filter on.
091         * @param params An array of parameters or null.
092         * @return the Result.
093         */
094        Result filter(Logger logger, Level level, Marker marker, String msg, Object... params);
095    
096        /**
097         * Filter an event.
098         * @param logger The Logger.
099         * @param level The event logging Level.
100         * @param marker The Marker for the event or null.
101         * @param msg Any Object.
102         * @param t A Throwable or null.
103         * @return the Result.
104         */
105        Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t);
106    
107        /**
108         * Filter an event.
109         * @param logger The Logger.
110         * @param level The event logging Level.
111         * @param marker The Marker for the event or null.
112         * @param msg The Message
113         * @param t A Throwable or null.
114         * @return the Result.
115         */
116        Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t);
117    
118        /**
119         * Filter an event.
120         * @param event The Event to filter on.
121         * @return the Result.
122         */
123        Result filter(LogEvent event);
124    
125    }