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 }