sunlabs.brazil.server.Handler Maven / Gradle / Ivy
Show all versions of sunlabs.brazil Show documentation
/*
* Handler.java
*
* Brazil project web application toolkit,
* export version: 2.3
* Copyright (c) 1998-2004 Sun Microsystems, Inc.
*
* Sun Public License Notice
*
* The contents of this file are subject to the Sun Public License Version
* 1.0 (the "License"). You may not use this file except in compliance with
* the License. A copy of the License is included as the file "license.terms",
* and also available at http://www.sun.com/
*
* The Original Code is from:
* Brazil project web application toolkit release 2.3.
* The Initial Developer of the Original Code is: suhler.
* Portions created by suhler are Copyright (C) Sun Microsystems, Inc.
* All Rights Reserved.
*
* Contributor(s): cstevens, suhler.
*
* Version: 2.3
* Created by suhler on 98/09/14
* Last modified by suhler on 04/11/30 15:19:41
*
* Version Histories:
*
* 2.3 04/11/30-15:19:41 (suhler)
* fixed sccs version string
*
* 2.2 03/07/28-09:17:39 (suhler)
* streamline docs (this is included a lot)
*
* 2.1 02/10/01-16:34:51 (suhler)
* version change
*
* 1.8 01/08/21-10:58:46 (suhler)
* doc lint
*
* 1.7 01/08/07-11:38:36 (suhler)
* doc updates
*
* 1.6 01/08/07-11:03:07 (suhler)
* added documentation
*
* 1.5 99/11/17-15:36:59 (cstevens)
* documentation
*
* 1.4 99/10/14-13:10:59 (cstevens)
* @author & @version
*
* 1.3 99/03/30-09:24:49 (suhler)
* documentation updates
*
* 1.2 98/09/21-14:51:08 (suhler)
* changed the package names
*
* 1.2 98/09/14-18:03:06 (Codemgr)
* SunPro Code Manager data about conflicts, renames, etc...
* Name history : 2 1 server/Handler.java
* Name history : 1 0 Handler.java
*
* 1.1 98/09/14-18:03:05 (suhler)
* date and time created 98/09/14 18:03:05 by suhler
*
*/
package sunlabs.brazil.server;
import java.io.IOException;
/**
* The interface for writing HTTP handlers. Provides basic functionality
* to accept HTTP requests and dispatch to methods that handle the request.
*
* The {@link #init(Server, String)} method is called before this
* Handler processes the first HTTP request, to allow it to
* prepare itself, such as by allocating any resources needed for the
* lifetime of the server.
*
* The {@link #respond(Request)} method is called to handle an HTTP request.
* This method, and all methods it calls must be thread-safe since they may
* handle HTTP requests from multiple sockets concurrently. However, each
* concurrent request gets its own individual {@link Request} object.
*
* Any instance variables should be initialized in the
* {@link #init(Server, String)}, and only referenced, but not set in the
* {@link #respond(Request)} method. If any state needs to be retained,
* it should be done either by associating it with the {@link Request}
* object, or using the
* {@link sunlabs.brazil.session.SessionManager session manager}.
* Class statics should be avoided, as it is possible, and even common to
* run multiple unrelated Brazil servers in the same JVM. As above, the
* {@link sunlabs.brazil.session.SessionManager session manager}
* should be used instead.
*
* @author Stephen Uhler ([email protected])
* @author Colin Stevens ([email protected])
* @version 2.3
*/
public interface Handler {
/**
* Initializes the handler.
*
* @param server
* The HTTP server that created this Handler.
* Typical Handlers will use {@link Server#props}
* to obtain run-time configuration information.
*
* @param prefix
* The handlers name.
* The string this Handler 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 true if this Handler initialized
* successfully, false otherwise. If
* false is returned, this Handler
* should not be used.
*/
boolean init(Server server, String prefix);
/**
* Responds to an HTTP request.
*
* @param request
* The Request object that represents the HTTP
* request.
*
* @return true if the request was handled. A request was
* handled if a response was supplied to the client, typically
* by calling Request.sendResponse() or
* Request.sendError.
*
* @throws IOException
* if there was an I/O error while sending the response to
* the client. Typically, in that case, the Server
* will (try to) send an error message to the client and then
* close the client's connection.
*
* The IOException should not be used to silently
* ignore problems such as being unable to access some
* server-side resource (for example getting a
* FileNotFoundException due to not being able
* to open a file). In that case, the Handler's
* duty is to turn that IOException into a
* HTTP response indicating, in this case, that a file could
* not be found.
*/
boolean respond(Request request) throws IOException;
}