View Javadoc

    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 org.apache.logging.log4j.Level;
    21  import org.apache.logging.log4j.Marker;
    22  import org.apache.logging.log4j.message.Message;
    23  import org.apache.logging.log4j.util.EnglishEnums;
    24
    25  /**
    26   * Interface that must be implemented to allow custom event filtering. It is highly recommended that
    27   * applications make use of the Filters provided with this implementation before creating their own.
    28   *
    29   * <p>This interface supports "global" filters (i.e. - all events must pass through them first), attached to
    30   * specific loggers and associated with Appenders. It is recommended that, where possible, Filter implementations
    31   * create a generic filtering method that can be called from any of the filter methods.</p>
    32   */
    33  public interface Filter extends LifeCycle {
    34
    35      /**
    36       * Main {@linkplain org.apache.logging.log4j.core.config.plugins.Plugin#elementType() plugin element type} for
    37       * Filter plugins.
    38       *
    39       * @since 2.1
    40       */
    41      String ELEMENT_TYPE = "filter";
    42
    43      /**
    44       * The result that can returned from a filter method call.
    45       */
    46       enum Result {
    47          /**
    48           * The event will be processed without further filtering based on the log Level.
    49           */
    50          ACCEPT,
    51          /**
    52           * No decision could be made, further filtering should occur.
    53           */
    54          NEUTRAL,
    55          /**
    56           * The event should not be processed.
    57           */
    58          DENY;
    59
    60          /**
    61           * Returns the Result for the given string.
    62           *
    63           * @param name The Result enum name, case-insensitive. If null, returns, null
    64           * @return a Result enum value or null if name is null
    65           */
    66          public static Result toResult(final String name) {
    67              return toResult(name, null);
    68          }
    69
    70          /**
    71           * Returns the Result for the given string.
    72           *
    73           * @param name The Result enum name, case-insensitive. If null, returns, defaultResult
    74           * @param defaultResult the Result to return if name is null
    75           * @return a Result enum value or null if name is null
    76           */
    77          public static Result toResult(final String name, final Result defaultResult) {
    78              return EnglishEnums.valueOf(Result.class, name, defaultResult);
    79          }
    80  }
    81
    82      /**
    83       * Returns the result that should be returned when the filter does not match the event.
    84       * @return the Result that should be returned when the filter does not match the event.
    85       */
    86      Result getOnMismatch();
    87      /**
    88       * Returns the result that should be returned when the filter matches the event.
    89       * @return the Result that should be returned when the filter matches the event.
    90       */
    91      Result getOnMatch();
    92
    93      /**
    94       * Filter an event.
    95       * @param logger The Logger.
    96       * @param level The event logging Level.
    97       * @param marker The Marker for the event or null.
    98       * @param msg String text to filter on.
    99       * @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 }