    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    }