Java example source code file (Filter.java)

This example Java source code file (Filter.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

chain, filter, httpexchange, httphandler, ioexception, listiterator, string, util

The Filter.java Java example source code

/*
 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package com.sun.net.httpserver;

import java.io.IOException;
import java.util.*;

/**
 * A filter used to pre- and post-process incoming requests. Pre-processing occurs
 * before the application's exchange handler is invoked, and post-processing
 * occurs after the exchange handler returns.  Filters
 * are organised in chains, and are associated with HttpContext instances.
 * <p>
 * Each Filter in the chain, invokes the next filter within its own
 * doFilter() implementation. The final Filter in the chain invokes the applications
 * exchange handler.
 * @since 1.6
 */
@jdk.Exported
public abstract class Filter {

    protected Filter () {}

    /**
     * a chain of filters associated with a HttpServer.
     * Each filter in the chain is given one of these
     * so it can invoke the next filter in the chain
     */
    @jdk.Exported
    public static class Chain {
        /* the last element in the chain must invoke the users
         * handler
         */
        private ListIterator<Filter> iter;
        private HttpHandler handler;

        public Chain (List<Filter> filters, HttpHandler handler) {
            iter = filters.listIterator();
            this.handler = handler;
        }

        /**
         * calls the next filter in the chain, or else
         * the users exchange handler, if this is the
         * final filter in the chain. The Filter may decide
         * to terminate the chain, by not calling this method.
         * In this case, the filter <b>must send the
         * response to the request, because the application's
         * exchange handler will not be invoked.
         * @param exchange the HttpExchange
         * @throws IOException let exceptions pass up the stack
         * @throws NullPointerException if exchange is <code>null
         */
        public void doFilter (HttpExchange exchange) throws IOException {
            if (!iter.hasNext()) {
                handler.handle (exchange);
            } else {
                Filter f = iter.next();
                f.doFilter (exchange, this);
            }
        }
    }

    /**
     * Asks this filter to pre/post-process the given exchange. The filter
     * can :-
     * <ul>
examine or modify the request headers
     * <li>filter the request body or the response body, by creating suitable
     * filter streams and calling
     * {@link HttpExchange#setStreams(InputStream,OutputStream)}</li>
     * <li>set attribute Objects in the exchange, which other filters or the
     * exchange handler can access.</li>
     * <li>decide to either :-

     * <li>invoke the next filter in the chain, by calling
     * {@link Filter.Chain#doFilter(HttpExchange)}</li>
     * <li>terminate the chain of invocation, by not calling
     * {@link Filter.Chain#doFilter(HttpExchange)}</li>
     * <li>if option 1. above taken, then when doFilter() returns all subsequent
     * filters in the Chain have been called, and the response headers can be
     * examined or modified.</li>
     * <li>if option 2. above taken, then this Filter must use the HttpExchange
     * to send back an appropriate response</li>

     * @param exchange the <code>HttpExchange to be filtered.
     * @param chain the Chain which allows the next filter to be invoked.
     * @throws IOException may be thrown by any filter module, and if
     *          caught, must be rethrown again.
     * @throws NullPointerException if either exchange or chain are <code>null
     */
    public abstract void doFilter (HttpExchange exchange, Chain chain)
        throws IOException;

    /**
     * returns a short description of this Filter
     * @return a string describing the Filter
     */
    public abstract String description ();

}