org.apache.tomcat.core
Class Handler

java.lang.Object
  |
  +--org.apache.tomcat.core.Handler
Direct Known Subclasses:
ServletHandler

public class Handler
extends java.lang.Object

The class that will generate the actual response or response fragment. Each Handler has a "name" that will determine the content that it will handle. The choice to not use "mime/type" as Apache, NES, IIS is based on the fact that most of the time servlets have "names", and the mime handling is very different in servlet API. It is possible to use mime types as a name, and special interceptors can take advantage of that ( to better integrate with the server ), but this is not a basic feature. Handlers will implement doService, doInit, doDestroy - all methods are protected and can't be called from outside. This ensures the only entry points are service(), init(), destroy() and the state and error handling is consistent. Common properties:

Author:
Costin Manolache

Field Summary
protected  ContextManager contextM
           
protected  int debug
           
protected  java.lang.Exception errorException
           
protected  Log logger
           
protected  BaseInterceptor module
           
protected  java.lang.String name
           
protected  Handler next
           
protected  Handler prev
           
protected  int state
           
static int STATE_ADDED
          The handler is added to an application and can be initialized.
static int STATE_DISABLED
          Handler is unable to perform - any attempt to use it should report an internal error.
static int STATE_NEW
          The handler is new, not part of any application.
 
Constructor Summary
Handler()
          Creates a new handler.
 
Method Summary
 void destroy()
           
protected  void doService(Request req, Response res)
           
 java.lang.Exception getErrorException()
          Gets the exception that relates to the servlet's ability to execute.
 BaseInterceptor getModule()
           
 java.lang.String getName()
           
 Handler getNext()
           
 java.lang.Object getNote(int pos)
           
 java.lang.Object getNote(java.lang.String name)
           
 Handler getPrevious()
           
 int getState()
           
protected  void handleServiceError(Request req, Response res, java.lang.Throwable t)
           
 void init()
           
protected  void invoke(Request req, Response res)
          This is the actual content generator.
protected  void log(java.lang.String s)
           
protected  void log(java.lang.String s, java.lang.Throwable t)
           
 void reload()
          Reload notification.
 void service(Request req, Response res)
          Call the service method, and notify all listeners
 void setContextManager(ContextManager cm)
           
 void setDebug(int d)
          Debug level for this handler.
 void setErrorException(java.lang.Exception ex)
          Sets an exception that relates to the ability of the servlet to execute.
 void setModule(BaseInterceptor module)
          A handler is part of a module.
 void setName(java.lang.String handlerName)
           
 void setNext(Handler next)
          A handler may either directly generate the response or it can act as a part of a pipeline.
 void setNote(int pos, java.lang.Object value)
           
 void setNote(java.lang.String name, java.lang.Object value)
           
 void setPrevious(Handler prev)
           
 void setState(int i)
           
 java.lang.String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

STATE_NEW

public static final int STATE_NEW
The handler is new, not part of any application. You must to add the handler to application before doing anything else. To ADDED by calling Context.addHandler(). From ADDED by calling Context.removeHandler();

STATE_ADDED

public static final int STATE_ADDED
The handler is added to an application and can be initialized. To READY by calling init(), if success TO DISABLED by calling init if it fails ( exception ) From READY by calling destroy()

STATE_DISABLED

public static final int STATE_DISABLED
Handler is unable to perform - any attempt to use it should report an internal error. This is the result of an internal exception or an error in init() To ADDED by calling destroy() From ADDED by calling init() ( if failure )

module

protected BaseInterceptor module

contextM

protected ContextManager contextM

name

protected java.lang.String name

state

protected int state

errorException

protected java.lang.Exception errorException

debug

protected int debug

logger

protected Log logger

next

protected Handler next

prev

protected Handler prev
Constructor Detail

Handler

public Handler()
Creates a new handler.
Method Detail

setModule

public void setModule(BaseInterceptor module)
A handler is part of a module. The module can create a number of handlers. Since the module is configurable, it can also configure the handlers - including debug, etc. The handler shares the same log file with the module ( it can log to different logs, but the default for debug information is shared with the other components of a module ).

setContextManager

public void setContextManager(ContextManager cm)

getModule

public BaseInterceptor getModule()

getState

public int getState()

setState

public void setState(int i)

getName

public java.lang.String getName()

setName

public void setName(java.lang.String handlerName)

setErrorException

public void setErrorException(java.lang.Exception ex)
Sets an exception that relates to the ability of the servlet to execute. An exception may be set by an interceptor if there is an error during the creation of the servlet.

getErrorException

public java.lang.Exception getErrorException()
Gets the exception that relates to the servlet's ability to execute.

init

public void init()
          throws TomcatException

destroy

public void destroy()
             throws TomcatException

service

public void service(Request req,
                    Response res)
             throws java.lang.Exception
Call the service method, and notify all listeners
Throws:
java.lang.Exception - if an error happens during handling of the request. Common errors are:
  • IOException if an input/output error occurs and we are processing an included servlet (otherwise it is swallowed and handled by the top level error handler mechanism)
  • ServletException if a servlet throws an exception and we are processing an included servlet (otherwise it is swallowed and handled by the top level error handler mechanism)
Tomcat should be able to handle and log any other exception ( including runtime exceptions )

setNext

public void setNext(Handler next)
A handler may either directly generate the response or it can act as a part of a pipeline. Next/Prev allow modules to generically set the pipeline. Most handlers will generate the content themself. Few handlers may prepare the request/response - one example is the Servlet handler that wraps them and calls a servlet. Modules may do choose to either hook into the server using the provided callbacks, or use a pipeline of handler ( valves ).

getNext

public Handler getNext()

getPrevious

public Handler getPrevious()

setPrevious

public void setPrevious(Handler prev)

handleServiceError

protected void handleServiceError(Request req,
                                  Response res,
                                  java.lang.Throwable t)
                           throws java.lang.Exception

reload

public void reload()
Reload notification. This hook is called whenever the application ( this handler ) is reloaded

doService

protected void doService(Request req,
                         Response res)
                  throws java.lang.Exception

invoke

protected void invoke(Request req,
                      Response res)
               throws java.lang.Exception
This is the actual content generator. A handler must generate the response - either itself or by calling another class, after setting/changing request properties or altering/wrapping the request and response. A Handler should use the "next" property if it is part of a pipeline ( "valve")

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

setDebug

public void setDebug(int d)
Debug level for this handler.

log

protected void log(java.lang.String s)

log

protected void log(java.lang.String s,
                   java.lang.Throwable t)

setNote

public final void setNote(int pos,
                          java.lang.Object value)

getNote

public final java.lang.Object getNote(int pos)

getNote

public java.lang.Object getNote(java.lang.String name)
                         throws TomcatException

setNote

public void setNote(java.lang.String name,
                    java.lang.Object value)
             throws TomcatException


Copyright © 2001 Apache Software Foundation. All Rights Reserved.