Interface Handler

src/sunlabs/brazil/server/Handler.java:103–155

The interface for writing HTTP handlers. Provides basic functionality to accept HTTP requests and dispatch to methods that handle the request. The #init(Server, String) method is called before this Handler processes the first HTTP request, to allow it to prepare itself, suc

 */

public interface Handler {
    /**
     * Initializes the handler.
     *
     * @param	server
     *		The HTTP server that created this <code>Handler</code>.
     *		Typical <code>Handler</code>s will use {@link Server#props}
     *		to obtain run-time configuration information.
     *
     * @param	prefix
     *		The handlers <i>name</i>.
     *		The string this <code>Handler</code> may prepend to all
     *		of the keys that it uses to extract configuration information
     *		from {@link Server#props}.  This is set (by the {@link Server}
     *		and {@link ChainHandler}) to help avoid configuration parameter
     *		namespace collisions.
     *
     * @return	<code>true</code> if this <code>Handler</code> initialized
     *		successfully, <code>false</code> otherwise.  If
     *		<code>false</code> is returned, this <code>Handler</code>
     *		should not be used.
     */
    boolean init(Server server, String prefix);

    /**
     * Responds to an HTTP request.
     *
     * @param	request
     *		The <code>Request</code> object that represents the HTTP
     *		request.
     *
     * @return	<code>true</code> if the request was handled.  A request was
     *		handled if a response was supplied to the client, typically
     *		by calling <code>Request.sendResponse()</code> or
     *		<code>Request.sendError</code>.
     *
     * @throws	IOException
     *		if there was an I/O error while sending the response to
     *		the client.  Typically, in that case, the <code>Server</code>
     *		will (try to) send an error message to the client and then
     *		close the client's connection.
     *		<p>
     *		The <code>IOException</code> should not be used to silently
     *		ignore problems such as being unable to access some
     *		server-side resource (for example getting a
     *		<code>FileNotFoundException</code> due to not being able
     *		to open a file).  In that case, the <code>Handler</code>'s
     *		duty is to turn that <code>IOException</code> into a
     *		HTTP response indicating, in this case, that a file could
     *		not be found.
     */
    boolean respond(Request request) throws IOException;
}