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 */
017package org.apache.logging.log4j.core.filter;
018
019import org.apache.logging.log4j.Level;
020import org.apache.logging.log4j.Marker;
021import org.apache.logging.log4j.core.Filter;
022import org.apache.logging.log4j.core.LifeCycle;
023import org.apache.logging.log4j.core.LogEvent;
024import org.apache.logging.log4j.core.Logger;
025import org.apache.logging.log4j.message.Message;
026import org.apache.logging.log4j.status.StatusLogger;
027
028/**
029 * Users should extend this class to implement filters. Filters can be either context wide or attached to
030 * an appender. A filter may choose to support being called only from the context or only from an appender in
031 * which case it will only implement the required method(s). The rest will default to return NEUTRAL.
032 *
033 */
034public abstract class AbstractFilter implements Filter, LifeCycle {
035    
036    /**
037     * Allow subclasses access to the status logger without creating another instance.
038     */
039    protected static final org.apache.logging.log4j.Logger LOGGER = StatusLogger.getLogger();
040
041    /**
042     * The onMatch Result.
043     */
044    protected final Result onMatch;
045
046    /**
047     * The onMismatch Result.
048     */
049    protected final Result onMismatch;
050
051    private boolean started;
052
053    /**
054     * The default constructor.
055     */
056    protected AbstractFilter() {
057        this(null, null);
058    }
059
060    /**
061     * Constructor that allows the onMatch and onMismatch actions to be set.
062     * @param onMatch The result to return when a match occurs.
063     * @param onMismatch The result to return when a match dos not occur.
064     */
065    protected AbstractFilter(final Result onMatch, final Result onMismatch) {
066        this.onMatch = onMatch == null ? Result.NEUTRAL : onMatch;
067        this.onMismatch = onMismatch == null ? Result.DENY : onMismatch;
068    }
069
070    /**
071     * Mark the Filter as started.
072     */
073    @Override
074    public void start() {
075        started = true;
076    }
077
078    /**
079     * Determine if the the Filter has started.
080     * @return true if the Filter is started, false otherwise.
081     */
082    @Override
083    public boolean isStarted() {
084        return started;
085    }
086
087    /**
088     * Mark the Filter as stopped.
089     */
090    @Override
091    public void stop() {
092        started = false;
093    }
094
095    /**
096     * Returns the Result to be returned when a match does not occur.
097     * @return the onMismatch Result.
098     */
099    @Override
100    public final Result getOnMismatch() {
101        return onMismatch;
102    }
103
104    /**
105     * Returns the Result to be returned when a match occurs.
106     * @return the onMatch Result.
107     */
108    @Override
109    public final Result getOnMatch() {
110        return onMatch;
111    }
112
113    @Override
114    public String toString() {
115        return this.getClass().getSimpleName();
116    }
117
118    /**
119     * Appender Filter method. The default returns NEUTRAL.
120     * @param logger the Logger.
121     * @param level The logging Level.
122     * @param marker The Marker, if any.
123     * @param msg The message, if present.
124     * @param params An array of parameters or null.
125     * @return The Result of filtering.
126     */
127    @Override
128    public Result filter(final Logger logger, final Level level, final Marker marker, final String msg,
129                         final Object... params) {
130        return Result.NEUTRAL;
131    }
132
133    /**
134     * Appender Filter method. The default returns NEUTRAL.
135     * @param logger the Logger.
136     * @param level The logging Level.
137     * @param marker The Marker, if any.
138     * @param msg The message, if present.
139     * @param t A throwable or null.
140     * @return The Result of filtering.
141     */
142    @Override
143    public Result filter(final Logger logger, final Level level, final Marker marker, final Object msg,
144                         final Throwable t) {
145        return Result.NEUTRAL;
146    }
147
148    /**
149     * Appender Filter method. The default returns NEUTRAL.
150     * @param logger the Logger.
151     * @param level The logging Level.
152     * @param marker The Marker, if any.
153     * @param msg The message, if present.
154     * @param t A throwable or null.
155     * @return The Result of filtering.
156     */
157    @Override
158    public Result filter(final Logger logger, final Level level, final Marker marker, final Message msg,
159                         final Throwable t) {
160        return Result.NEUTRAL;
161    }
162
163    /**
164     * Context Filter method. The default returns NEUTRAL.
165     * @param event The LogEvent.
166     * @return The Result of filtering.
167     */
168    @Override
169    public Result filter(final LogEvent event) {
170        return Result.NEUTRAL;
171    }
172}