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ülcü 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}