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 19 package org.apache.catalina; 20 21 import java.io.IOException; 22 23 import javax.servlet.Filter; 24 import javax.servlet.ServletException; 25 26 /** 27 * A Comet filter, similar to regular filters, performs filtering tasks on either 28 * the request to a resource (a Comet servlet), or on the response from a resource, or both. 29 * <br><br> 30 * Filters perform filtering in the <code>doFilterEvent</code> method. Every Filter has access to 31 * a FilterConfig object from which it can obtain its initialization parameters, a 32 * reference to the ServletContext which it can use, for example, to load resources 33 * needed for filtering tasks. 34 * <p> 35 * Filters are configured in the deployment descriptor of a web application 36 * <p> 37 * Examples that have been identified for this design are<br> 38 * 1) Authentication Filters <br> 39 * 2) Logging and Auditing Filters <br> 40 * 3) Image conversion Filters <br> 41 * 4) Data compression Filters <br> 42 * 5) Encryption Filters <br> 43 * 6) Tokenizing Filters <br> 44 * 7) Filters that trigger resource access events <br> 45 * 8) XSL/T filters <br> 46 * 9) Mime-type chain Filter <br> 47 * <br> 48 * 49 * @author Remy Maucherat 50 * @author Filip Hanik 51 */ 52 public interface CometFilter extends Filter { 53 54 55 /** 56 * The <code>doFilterEvent</code> method of the CometFilter is called by the container 57 * each time a request/response pair is passed through the chain due 58 * to a client event for a resource at the end of the chain. The CometFilterChain passed in to this 59 * method allows the Filter to pass on the event to the next entity in the 60 * chain.<p> 61 * A typical implementation of this method would follow the following pattern:- <br> 62 * 1. Examine the request<br> 63 * 2. Optionally wrap the request object contained in the event with a custom implementation to 64 * filter content or headers for input filtering and pass a CometEvent instance containing 65 * the wrapped request to the next filter<br> 66 * 3. Optionally wrap the response object contained in the event with a custom implementation to 67 * filter content or headers for output filtering and pass a CometEvent instance containing 68 * the wrapped request to the next filter<br> 69 * 4. a) <strong>Either</strong> invoke the next entity in the chain using the CometFilterChain object (<code>chain.doFilterEvent()</code>), <br> 70 * 4. b) <strong>or</strong> not pass on the request/response pair to the next entity in the filter chain to block the event processing<br> 71 * 5. Directly set fields on the response after invocation of the next entity in the filter chain. 72 * 73 * @param event the event that is being processed. Another event may be passed along the chain. 74 * @param chain 75 * @throws IOException 76 * @throws ServletException 77 */ 78 public void doFilterEvent(CometEvent event, CometFilterChain chain) 79 throws IOException, ServletException; 80 81 82 } 83