public abstract class HttpHandler implements Comparable {  
  /**
   * Indicates preference as to when this handler should be invoked 
   * with respect to other handlers 
   */
  protected HandlerOrder orderConstraint;
  
  /**
   * This is used to order handler processing in the server.  That is,
   * the server will call handlers in ascending order as indicated by
   * their compareTo methods.
   *
   * @param that the other object to compare to for ordering.
   */
  public int compareTo(Object that) {
    if (that instanceof HttpHandler) {
      HttpHandler handler = (HttpHandler)that;
      return (this.orderConstraint.compareTo(handler.orderConstraint));
    }
    throw new ClassCastException();
  }
  
  /**
   * This is the "update" method of the Observer pattern, which will
   * be called whenever a valid connection request has been received
   * by the server.  It is itself implemented using the Template
   * Method pattern: it calls two abstract methods that must be
   * implemented by classes that subclass it.  The first,
   * matchRequest, determines whether or not this handler will deal
   * with this request, and the second, writeResponse, writes out
   * the response (in HTML) on the given output stream.
   * 
   * In the case that the handler does not match the given request, it
   * will return false.  If it is does match and is able to properly process
   * it, it will return true.  Finally, if it does match but an error
   * occurs in writing the response, the exception HandlerException will
   * be thrown (actually it is thrown by writeResponse below), which contains
   * the error and the response to send to the client.  When the exception
   * is raised, any data written to out should be considered invalid.
   *
   * @param request this is the HTTP request to be dealt with (or not).
   * @param out this is the output buffer to write the response on (if any)
   */
  public boolean handleRequest(HttpRequest request,
			       StringBuffer out) throws HandlerException {
    if (matchRequest(request)) {
      writeResponse(out);
      return true;
    }
    return false;
  }

  /**
   * Indicates whether this is an "exclusive" handler.  That is, it should
   * only if another exclusive handler has not run already.
   */
  public abstract boolean isExclusive();
  
  /**
   * This one of the methods of the Template Method pattern; it
   * will return true if this request will be handled by this
   * handler.  It should also store relevant information from the
   * request to allow writeResponse to write the proper output.
   *
   * @param request the HTTP request to be handled (or not)
   */
  protected abstract boolean matchRequest(HttpRequest request);

  /**
   * This one of the methods of the Template Method pattern; it will
   * write the response to the HTTP request passed to its
   * matchRequest method.  It assumes that matchRequest was
   * called first, so it knows relevant information.
   * 
   * If something goes wrong, writeResponse will throw an exception
   * HandlerException.  If this happens, any data written to out
   * should be considered bogus.  The HandlerException will contain
   * a description of the error and HTML to send back to the client.
   *
   * @param out the StringBuffer to write the response to
   */
  protected abstract void writeResponse(StringBuffer out)
      throws HandlerException;
}