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