001: /*
002: * Filter.java
003: *
004: * Brazil project web application Framework,
005: * export version: 1.1
006: * Copyright (c) 1999-2000 Sun Microsystems, Inc.
007: *
008: * Sun Public License Notice
009: *
010: * The contents of this file are subject to the Sun Public License Version
011: * 1.0 (the "License"). You may not use this file except in compliance with
012: * the License. A copy of the License is included as the file "license.terms",
013: * and also available at http://www.sun.com/
014: *
015: * The Original Code is from:
016: * Brazil project web application Framework release 1.1.
017: * The Initial Developer of the Original Code is: suhler.
018: * Portions created by suhler are Copyright (C) Sun Microsystems, Inc.
019: * All Rights Reserved.
020: *
021: * Contributor(s): cstevens, suhler.
022: *
023: * Version: 1.8
024: * Created by suhler on 99/07/29
025: * Last modified by suhler on 00/05/31 13:43:20
026: */
027:
028: package sunlabs.brazil.filter;
029:
030: import sunlabs.brazil.server.Handler;
031: import sunlabs.brazil.server.Request;
032: import sunlabs.brazil.util.http.MimeHeaders;
033:
034: /**
035: * The <code>Filter</code> interface is used by the
036: * {@link FilterHandler}
037: * to examine and dynamically rewrite the contents of web pages obtained from
038: * some source before returning that page to the client.
039: * <p>
040: * A chain of filters can be established in the manner of a pipeline. The
041: * <code>FilterHandler</code> sends the output of a <code>Filter</code>
042: * to the input of the next <code>Filter</code>.
043: * <p>
044: * The <code>init</code> and <code>respond</code> methods inherited from
045: * the <code>Handler</code> interface are called as for ordinary handlers:
046: * <dl>
047: * <dt> {@link Handler#init}
048: * <dd> is called when the server starts, to obtain run-time
049: * configuration information.
050: *
051: * <dt> {@link Handler#respond}
052: * <dd> is called when the request comes in, before the request is sent to
053: * the wrapped handler. This method returns true to indicate that the
054: * request has been completely handled by this <code>Filter</code>, and
055: * no further processing filtering takes place.
056: * </dl>
057: *
058: * @author Stephen Uhler (stephen.uhler@sun.com)
059: * @author Colin Stevens (colin.stevens@sun.com)
060: * @version 1.8 00/05/31
061: */
062:
063: public interface Filter extends Handler {
064: /**
065: * Gives this <code>Filter</code> the chance to examine the HTTP
066: * response headers from the wrapped <code>Handler</code>, before the
067: * content has been retrieved.
068: * <p>
069: * If this <code>Filter</code> <b>does</b> want to examine and possibly
070: * rewrite the content, it should return <code>true</code>; once the
071: * content is available, the <code>filter</code> method will be invoked.
072: * For instance, if this <code>Filter</code> is only interested in
073: * rewriting "text/html" pages, it should return <code>false</code> if
074: * the "Content-Type" is "image/jpeg".
075: * If all filters return <code>false</code> for the
076: * <code>shouldFilter</code> method, the {@link FilterHandler} can
077: * switch to a more effient mechanism of delivering content to the client.
078: * <p>
079: * The MIME headers may also be modified by this <code>Filter</code>,
080: * for instance, to change the "Content-Type" of a web page. The
081: * "Content-Length" will automatically be computed.
082: *
083: * @param request
084: * The in-progress HTTP request.
085: *
086: * @param headers
087: * The MIME headers generated by the wrapped <code>Handler</code>.
088: *
089: * @return <code>true</code> if this filter would like to examine and
090: * possibly rewrite the content, <code>false</code> otherwise.
091: */
092: public boolean shouldFilter(Request request, MimeHeaders headers);
093:
094: /**
095: * Filters the content generated by the wrapped <code>Handler</code>.
096: * The content may be arbitrarily rewritten by this method.
097: * <p>
098: * The MIME headers may also be modified by this <code>Filter</code>,
099: * for instance, to change the "Content-Type" of a web page.
100: * The "Content-Length" will automatically be computed by the
101: * <code>FilterHandler</code>.
102: *
103: * @param request
104: * The finished HTTP request.
105: *
106: * @param headers
107: * The MIME headers generated by the <code>Handler</code>.
108: *
109: * @param content
110: * The output from the <code>Handler</code> that this
111: * <code>Filter</code> may rewrite.
112: *
113: * @return The rewritten content. The <code>Filter</code> may return
114: * the original <code>content</code> unchanged. The
115: * <code>Filter</code> may return <code>null</code> to indicate
116: * that the <code>FilterHandler</code> should stop processing the
117: * request and should not return any content to the client.
118: */
119: public byte[] filter(Request request, MimeHeaders headers,
120: byte[] content);
121: }
|