lib/servlet-api/javax/servlet/Filter.java

   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 package javax.servlet;
  18
  19 import java.io.IOException;
  20
  21 /**
  22  * A filter is an object that performs filtering tasks on either the request to
  23  * a resource (a servlet or static content), or on the response from a resource,
  24  * or both. <br>
  25  * <br>
  26  * Filters perform filtering in the <code>doFilter</code> method. Every Filter
  27  * has access to a FilterConfig object from which it can obtain its
  28  * initialization parameters, a reference to the ServletContext which it can
  29  * use, for example, to load resources needed for filtering tasks.
  30  * <p>
  31  * Filters are configured in the deployment descriptor of a web application
  32  * <p>
  33  * Examples that have been identified for this design are<br>
  34  * 1) Authentication Filters <br>
  35  * 2) Logging and Auditing Filters <br>
  36  * 3) Image conversion Filters <br>
  37  * 4) Data compression Filters <br>
  38  * 5) Encryption Filters <br>
  39  * 6) Tokenizing Filters <br>
  40  * 7) Filters that trigger resource access events <br>
  41  * 8) XSL/T filters <br>
  42  * 9) Mime-type chain Filter <br>
  43  *
  44  * @since Servlet 2.3
  45  */
  46 public interface Filter {
  47
  48     /**
  49      * Called by the web container to indicate to a filter that it is being
  50      * placed into service. The servlet container calls the init method exactly
  51      * once after instantiating the filter. The init method must complete
  52      * successfully before the filter is asked to do any filtering work. <br>
  53      * <br>
  54      * The web container cannot place the filter into service if the init method
  55      * either<br>
  56      * 1.Throws a ServletException <br>
  57      * 2.Does not return within a time period defined by the web container
  58      */
  59     public void init(FilterConfig filterConfig) throws ServletException;
  60
  61     /**
  62      * The <code>doFilter</code> method of the Filter is called by the container
  63      * each time a request/response pair is passed through the chain due to a
  64      * client request for a resource at the end of the chain. The FilterChain
  65      * passed in to this method allows the Filter to pass on the request and
  66      * response to the next entity in the chain.
  67      * <p>
  68      * A typical implementation of this method would follow the following
  69      * pattern:- <br>
  70      * 1. Examine the request<br>
  71      * 2. Optionally wrap the request object with a custom implementation to
  72      * filter content or headers for input filtering <br>
  73      * 3. Optionally wrap the response object with a custom implementation to
  74      * filter content or headers for output filtering <br>
  75      * 4. a) <strong>Either</strong> invoke the next entity in the chain using
  76      * the FilterChain object (<code>chain.doFilter()</code>), <br>
  77      * 4. b) <strong>or</strong> not pass on the request/response pair to the
  78      * next entity in the filter chain to block the request processing<br>
  79      * 5. Directly set headers on the response after invocation of the next
  80      * entity in the filter chain.
  81      **/
  82     public void doFilter(ServletRequest request, ServletResponse response,
  83             FilterChain chain) throws IOException, ServletException;
  84
  85     /**
  86      * Called by the web container to indicate to a filter that it is being
  87      * taken out of service. This method is only called once all threads within
  88      * the filter's doFilter method have exited or after a timeout period has
  89      * passed. After the web container calls this method, it will not call the
  90      * doFilter method again on this instance of the filter. <br>
  91      * <br>
  92      *
  93      * This method gives the filter an opportunity to clean up any resources
  94      * that are being held (for example, memory, file handles, threads) and make
  95      * sure that any persistent state is synchronized with the filter's current
  96      * state in memory.
  97      */
  98     public void destroy();
  99
 100 }