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
018package org.apache.logging.log4j.core;
019
020import org.apache.logging.log4j.Level;
021import org.apache.logging.log4j.Marker;
022import org.apache.logging.log4j.message.Message;
023import 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 */
033public interface Filter extends LifeCycle {
034
035    /**
036     * The empty array.
037     */
038    Filter[] EMPTY_ARRAY = {};
039
040    /**
041     * Main {@linkplain org.apache.logging.log4j.core.config.plugins.Plugin#elementType() plugin element type} for
042     * Filter plugins.
043     *
044     * @since 2.1
045     */
046    String ELEMENT_TYPE = "filter";
047
048    /**
049     * The result that can returned from a filter method call.
050     */
051     enum Result {
052        /**
053         * The event will be processed without further filtering based on the log Level.
054         */
055        ACCEPT,
056        /**
057         * No decision could be made, further filtering should occur.
058         */
059        NEUTRAL,
060        /**
061         * The event should not be processed.
062         */
063        DENY;
064
065        /**
066         * Returns the Result for the given string.
067         *
068         * @param name The Result enum name, case-insensitive. If null, returns, null
069         * @return a Result enum value or null if name is null
070         */
071        public static Result toResult(final String name) {
072            return toResult(name, null);
073        }
074
075        /**
076         * Returns the Result for the given string.
077         *
078         * @param name The Result enum name, case-insensitive. If null, returns, defaultResult
079         * @param defaultResult the Result to return if name is null
080         * @return a Result enum value or null if name is null
081         */
082        public static Result toResult(final String name, final Result defaultResult) {
083            return EnglishEnums.valueOf(Result.class, name, defaultResult);
084        }
085}
086
087    /**
088     * Returns the result that should be returned when the filter does not match the event.
089     * @return the Result that should be returned when the filter does not match the event.
090     */
091    Result getOnMismatch();
092    /**
093     * Returns the result that should be returned when the filter matches the event.
094     * @return the Result that should be returned when the filter matches the event.
095     */
096    Result getOnMatch();
097
098    /**
099     * Filter an event.
100     * @param logger The Logger.
101     * @param level The event logging Level.
102     * @param marker The Marker for the event or null.
103     * @param msg String text to filter on.
104     * @param params An array of parameters or null.
105     * @return the Result.
106     */
107    Result filter(Logger logger, Level level, Marker marker, String msg, Object... params);
108
109    /**
110     * Filter an event.
111     *
112     * @param logger The Logger.
113     * @param level the event logging level.
114     * @param marker The Marker for the event or null.
115     * @param message The message.
116     * @param p0 the message parameters
117     * @return the Result.
118     */
119    Result filter(Logger logger, Level level, Marker marker, String message, Object p0);
120
121    /**
122     * Filter an event.
123     *
124     * @param logger The Logger.
125     * @param level the event logging level.
126     * @param marker The Marker for the event or null.
127     * @param message The message.
128     * @param p0 the message parameters
129     * @param p1 the message parameters
130     * @return the Result.
131     */
132    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1);
133
134    /**
135     * Filter an event.
136     *
137     * @param logger The Logger.
138     * @param level the event logging level.
139     * @param marker The Marker for the event or null.
140     * @param message The message.
141     * @param p0 the message parameters
142     * @param p1 the message parameters
143     * @param p2 the message parameters
144     * @return the Result.
145     */
146    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2);
147
148    /**
149     * Filter an event.
150     *
151     * @param logger The Logger.
152     * @param level the event logging level.
153     * @param marker The Marker for the event or null.
154     * @param message The message.
155     * @param p0 the message parameters
156     * @param p1 the message parameters
157     * @param p2 the message parameters
158     * @param p3 the message parameters
159     * @return the Result.
160     */
161    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3);
162
163    /**
164     * Filter an event.
165     *
166     * @param logger The Logger.
167     * @param level the event logging level.
168     * @param marker The Marker for the event or null.
169     * @param message The message.
170     * @param p0 the message parameters
171     * @param p1 the message parameters
172     * @param p2 the message parameters
173     * @param p3 the message parameters
174     * @param p4 the message parameters
175     * @return the Result.
176     */
177    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
178            Object p4);
179
180    /**
181     * Filter an event.
182     *
183     * @param logger The Logger.
184     * @param level the event logging level.
185     * @param marker The Marker for the event or null.
186     * @param message The message.
187     * @param p0 the message parameters
188     * @param p1 the message parameters
189     * @param p2 the message parameters
190     * @param p3 the message parameters
191     * @param p4 the message parameters
192     * @param p5 the message parameters
193     * @return the Result.
194     */
195    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
196            Object p4, Object p5);
197
198    /**
199     * Filter an event.
200     *
201     * @param logger The Logger.
202     * @param level the event logging level.
203     * @param marker The Marker for the event or null.
204     * @param message The message.
205     * @param p0 the message parameters
206     * @param p1 the message parameters
207     * @param p2 the message parameters
208     * @param p3 the message parameters
209     * @param p4 the message parameters
210     * @param p5 the message parameters
211     * @param p6 the message parameters
212     * @return the Result.
213     */
214    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
215            Object p4, Object p5, Object p6);
216
217    /**
218     * Filter an event.
219     *
220     * @param logger The Logger.
221     * @param level the event logging level.
222     * @param marker The Marker for the event or null.
223     * @param message The message.
224     * @param p0 the message parameters
225     * @param p1 the message parameters
226     * @param p2 the message parameters
227     * @param p3 the message parameters
228     * @param p4 the message parameters
229     * @param p5 the message parameters
230     * @param p6 the message parameters
231     * @param p7 the message parameters
232     * @return the Result.
233     */
234    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
235            Object p4, Object p5, Object p6, Object p7);
236
237    /**
238     * Filter an event.
239     *
240     * @param logger The Logger.
241     * @param level the event logging level.
242     * @param marker The Marker for the event or null.
243     * @param message The message.
244     * @param p0 the message parameters
245     * @param p1 the message parameters
246     * @param p2 the message parameters
247     * @param p3 the message parameters
248     * @param p4 the message parameters
249     * @param p5 the message parameters
250     * @param p6 the message parameters
251     * @param p7 the message parameters
252     * @param p8 the message parameters
253     * @return the Result.
254     */
255    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
256            Object p4, Object p5, Object p6, Object p7, Object p8);
257
258    /**
259     * Filter an event.
260     *
261     * @param logger The Logger.
262     * @param level the event logging level.
263     * @param marker The Marker for the event or null.
264     * @param message The message.
265     * @param p0 the message parameters
266     * @param p1 the message parameters
267     * @param p2 the message parameters
268     * @param p3 the message parameters
269     * @param p4 the message parameters
270     * @param p5 the message parameters
271     * @param p6 the message parameters
272     * @param p7 the message parameters
273     * @param p8 the message parameters
274     * @param p9 the message parameters
275     * @return the Result.
276     */
277    Result filter(Logger logger, Level level, Marker marker, String message, Object p0, Object p1, Object p2, Object p3,
278            Object p4, Object p5, Object p6, Object p7, Object p8, Object p9);
279
280    /**
281     * Filter an event.
282     * @param logger The Logger.
283     * @param level The event logging Level.
284     * @param marker The Marker for the event or null.
285     * @param msg Any Object.
286     * @param t A Throwable or null.
287     * @return the Result.
288     */
289    Result filter(Logger logger, Level level, Marker marker, Object msg, Throwable t);
290
291    /**
292     * Filter an event.
293     * @param logger The Logger.
294     * @param level The event logging Level.
295     * @param marker The Marker for the event or null.
296     * @param msg The Message
297     * @param t A Throwable or null.
298     * @return the Result.
299     */
300    Result filter(Logger logger, Level level, Marker marker, Message msg, Throwable t);
301
302    /**
303     * Filter an event.
304     * @param event The Event to filter on.
305     * @return the Result.
306     */
307    Result filter(LogEvent event);
308
309}