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.log4j.spi;
019
020
021
022/**
023   Users should extend this class to implement customized logging
024   event filtering. Note that {@link org.apache.log4j.Category} and {@link
025   org.apache.log4j.AppenderSkeleton}, the parent class of all standard
026   appenders, have built-in filtering rules. It is suggested that you
027   first use and understand the built-in rules before rushing to write
028   your own custom filters.
029
030   <p>This abstract class assumes and also imposes that filters be
031   organized in a linear chain. The {@link #decide
032   decide(LoggingEvent)} method of each filter is called sequentially,
033   in the order of their addition to the chain.
034
035   <p>The {@link #decide decide(LoggingEvent)} method must return one
036   of the integer constants {@link #DENY}, {@link #NEUTRAL} or {@link
037   #ACCEPT}.
038
039   <p>If the value {@link #DENY} is returned, then the log event is
040   dropped immediately without consulting with the remaining
041   filters. 
042
043   <p>If the value {@link #NEUTRAL} is returned, then the next filter
044   in the chain is consulted. If there are no more filters in the
045   chain, then the log event is logged. Thus, in the presence of no
046   filters, the default behaviour is to log all logging events.
047
048   <p>If the value {@link #ACCEPT} is returned, then the log
049   event is logged without consulting the remaining filters. 
050
051   <p>The philosophy of log4j filters is largely inspired from the
052   Linux ipchains. 
053
054   <p>Note that filtering is only supported by the {@link
055   org.apache.log4j.xml.DOMConfigurator DOMConfigurator}. The {@link
056   org.apache.log4j.PropertyConfigurator PropertyConfigurator} does not
057   support filters.
058
059   @author Ceki G&uuml;lc&uuml;
060   @since 0.9.0 */
061public abstract class Filter implements OptionHandler {
062
063  /**
064     Points to the next filter in the filter chain.
065
066     @deprecated As of 1.2.12, use {@link #getNext} and {@link #setNext} instead
067   */
068  public Filter next;
069
070  /**
071     The log event must be dropped immediately without consulting
072     with the remaining filters, if any, in the chain.  */
073  public static final int DENY    = -1;
074  
075  /**
076     This filter is neutral with respect to the log event. The
077     remaining filters, if any, should be consulted for a final decision.
078  */
079  public static final int NEUTRAL = 0;
080
081  /**
082     The log event must be logged immediately without consulting with
083     the remaining filters, if any, in the chain.  */
084  public static final int ACCEPT  = 1;
085
086
087  /**
088     Usually filters options become active when set. We provide a
089     default do-nothing implementation for convenience.
090  */
091  public
092  void activateOptions() {
093  }
094
095
096
097  /**     
098     <p>If the decision is <code>DENY</code>, then the event will be
099     dropped. If the decision is <code>NEUTRAL</code>, then the next
100     filter, if any, will be invoked. If the decision is ACCEPT then
101     the event will be logged without consulting with other filters in
102     the chain.
103
104     @param event The LoggingEvent to decide upon.
105     @return decision The decision of the filter.  */
106  abstract
107  public
108  int decide(LoggingEvent event);
109
110  /**
111   * Set the next filter pointer.
112   */ 
113  public void setNext(Filter next) {
114    this.next = next;
115  }
116 
117  /**
118   * Return the pointer to the next filter;
119   */ 
120  public Filter getNext() {
121        return next;
122  }
123
124}