1 /*
   2  * Copyright (c) 2005, 2010, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package com.sun.net.httpserver;
  27 
  28 import java.io.IOException;
  29 import java.util.*;
  30 
  31 /**
  32  * A filter used to pre- and post-process incoming requests. Pre-processing occurs
  33  * before the application's exchange handler is invoked, and post-processing
  34  * occurs after the exchange handler returns.  Filters
  35  * are organised in chains, and are associated with HttpContext instances.
  36  * <p>
  37  * Each Filter in the chain, invokes the next filter within its own
  38  * doFilter() implementation. The final Filter in the chain invokes the applications
  39  * exchange handler.
  40  * @since 1.6
  41  */
  42 @jdk.Supported
  43 public abstract class Filter {
  44 
  45     protected Filter () {}
  46 
  47     /**
  48      * a chain of filters associated with a HttpServer.
  49      * Each filter in the chain is given one of these
  50      * so it can invoke the next filter in the chain
  51      */
  52     @jdk.Supported
  53     public static class Chain {
  54         /* the last element in the chain must invoke the users
  55          * handler
  56          */
  57         private ListIterator<Filter> iter;
  58         private HttpHandler handler;
  59 
  60         public Chain (List<Filter> filters, HttpHandler handler) {
  61             iter = filters.listIterator();
  62             this.handler = handler;
  63         }
  64 
  65         /**
  66          * calls the next filter in the chain, or else
  67          * the users exchange handler, if this is the
  68          * final filter in the chain. The Filter may decide
  69          * to terminate the chain, by not calling this method.
  70          * In this case, the filter <b>must</b> send the
  71          * response to the request, because the application's
  72          * exchange handler will not be invoked.
  73          * @param exchange the HttpExchange
  74          * @throws IOException let exceptions pass up the stack
  75          * @throws NullPointerException if exchange is <code>null</code>
  76          */
  77         public void doFilter (HttpExchange exchange) throws IOException {
  78             if (!iter.hasNext()) {
  79                 handler.handle (exchange);
  80             } else {
  81                 Filter f = iter.next();
  82                 f.doFilter (exchange, this);
  83             }
  84         }
  85     }
  86 
  87     /**
  88      * Asks this filter to pre/post-process the given exchange. The filter
  89      * can :-
  90      * <ul><li>examine or modify the request headers</li>
  91      * <li>filter the request body or the response body, by creating suitable
  92      * filter streams and calling
  93      * {@link HttpExchange#setStreams(InputStream,OutputStream)}</li>
  94      * <li>set attribute Objects in the exchange, which other filters or the
  95      * exchange handler can access.</li>
  96      * <li>decide to either :-<ol>
  97      * <li>invoke the next filter in the chain, by calling
  98      * {@link Filter.Chain#doFilter(HttpExchange)}</li>
  99      * <li>terminate the chain of invocation, by <b>not</b> calling
 100      * {@link Filter.Chain#doFilter(HttpExchange)}</li></ol>
 101      * <li>if option 1. above taken, then when doFilter() returns all subsequent
 102      * filters in the Chain have been called, and the response headers can be
 103      * examined or modified.</li>
 104      * <li>if option 2. above taken, then this Filter must use the HttpExchange
 105      * to send back an appropriate response</li></ul><p>
 106      * @param exchange the <code>HttpExchange</code> to be filtered.
 107      * @param chain the Chain which allows the next filter to be invoked.
 108      * @throws IOException may be thrown by any filter module, and if
 109      *          caught, must be rethrown again.
 110      * @throws NullPointerException if either exchange or chain are <code>null</code>
 111      */
 112     public abstract void doFilter (HttpExchange exchange, Chain chain)
 113         throws IOException;
 114 
 115     /**
 116      * returns a short description of this Filter
 117      * @return a string describing the Filter
 118      */
 119     public abstract String description ();
 120 
 121 }