001: /*
002: * Handler.java
003: *
004: * Brazil project web application Framework,
005: * export version: 1.1
006: * Copyright (c) 1998-1999 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.5
024: * Created by suhler on 98/09/14
025: * Last modified by cstevens on 99/11/17 15:36:59
026: */
027:
028: package sunlabs.brazil.server;
029:
030: import java.io.IOException;
031:
032: /**
033: * The interface for writing HTTP handlers. Provides basic functionality
034: * to accept HTTP requests and dispatch to methods to handle the request.
035: * <p>
036: * The {@link #init(Server, String)} method is called before this
037: * <code>Handler</code> processes the first HTTP request, to allow it to
038: * prepare itself, such as by allocating any resources needed for the
039: * lifetime of the <code>Handler</code>.
040: * <p>
041: * The {@link #respond(Request)} method is called to handle an HTTP request.
042: * This method and all methods it calls must be thread-safe since they may
043: * handle HTTP requests from multiple sockets concurrently. However, each
044: * concurrent request gets its own individual {@link Request} object.
045: *
046: * @author Stephen Uhler (stephen.uhler@sun.com)
047: * @author Colin Stevens (colin.stevens@sun.com)
048: * @version 1.5, 99/11/17
049: */
050:
051: public interface Handler {
052: /**
053: * Initializes the handler.
054: *
055: * @param server
056: * The HTTP server that created this <code>Handler</code>.
057: * Typical <code>Handler</code>s will use {@link Server#props}
058: * to obtain run-time configuration information.
059: *
060: * @param prefix
061: * A prefix that this <code>Handler</code> may prepend to all
062: * of the keys that it uses to extract configuration information
063: * from {@link Server#props}. This is set (by the {@link Server}
064: * and {@link ChainHandler}) to help avoid configuration parameter
065: * namespace collisions.
066: * <p>
067: * For example, if a <code>Handler</code> uses the property
068: * "account", and the specified prefix is "bank.", then the
069: * <code>Handler</code> should actually examine the property
070: * "bank.account" in <code>Server.props</code>.
071: *
072: * @return <code>true</code> if this <code>Handler</code> initialized
073: * successfully, <code>false</code> otherwise. If
074: * <code>false</code> is returned, this <code>Handler</code>
075: * should not be used.
076: */
077: boolean init(Server server, String prefix);
078:
079: /**
080: * Responds to an HTTP request.
081: *
082: * @param request
083: * The <code>Request</code> object that represents the HTTP
084: * request.
085: *
086: * @return <code>true</code> if the request was handled. A request was
087: * handled if a response was supplied to the client, typically
088: * by calling <code>Request.sendResponse()</code> or
089: * <code>Request.sendError</code>.
090: *
091: * @throws IOException
092: * if there was an I/O error while sending the response to
093: * the client. Typically, in that case, the <code>Server</code>
094: * will (try to) send an error message to the client and then
095: * close the client's connection.
096: * <p>
097: * The <code>IOException</code> should not be used to silently
098: * ignore problems such as being unable to access some
099: * server-side resource (for example getting a
100: * <code>FileNotFoundException</code> due to not being able
101: * to open a file). In that case, the <code>Handler</code>'s
102: * duty is to turn that <code>IOException</code> into a
103: * HTTP response indicating, in this case, that a file could
104: * not be found.
105: */
106: boolean respond(Request request) throws IOException;
107: }
|