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 }