ChainHandler (Brazil 2.3)

java.lang.Object
- sunlabs.brazil.server.ChainHandler

All Implemented Interfaces:

Handler

Direct Known Subclasses:

ChainSawHandler
```
public class ChainHandler
extends java.lang.Object
implements Handler
```
Allows multiple handlers to be invoked sequentially for a single HTTP request. A list of handlers is supplied when this ChainHandler is initialized. When an HTTP request is received by this ChainHandler, each of the handlers from the list is called in turn until one of them responds and returns true.
A useful trick is that some handlers can be run by a ChainHandler for their side effects. The handler can modify the Request object and then return false; the next handler in the list will get a crack at the modified request.
The following configuration parameters eare used to initialize this Handler:

handlers
A list of Handler names that will be invoked in the given order to handle the request. These are considered the "wrapped" handlers. These handlers will all be initialized at startup by init(sunlabs.brazil.server.Server, java.lang.String). For each name in the list, the property name.class is examined to determine which class to use for this handler. Then name is used as the prefix in the handler's init() method.
report
If set, this property will be set to the name of the handler that handled the request (e.g. returned true).
exitOnError
If set, the server's initFailure will set any of the handlers fail to initialize. No handler prefix is required.
prefix, suffix, glob, match
Specify the URL that triggers this handler.

Version:

2.5

Author:

Stephen Uhler (stephen.uhler@sun.com), Colin Stevens (colin.stevens@sun.com)

See Also:

Handler

Field Summary

Fields
Modifier and Type	Field and Description
`boolean`	`exitOnError` A flag to require the successfull initialization of all handlers.
`Handler[]`	`handlers` The array of handlers that will be invoked to handle the request.
`MatchString`	`isMine` The URL that must match for this handler to run
`java.lang.String[]`	`names` The names of the above `handlers` as specified by the configuration parameters.
`java.lang.String`	`prefix` The prefix used to initialize this `ChainHandler`, used for logging.
`java.lang.String`	`report` The name (if any) of the property to receive the name of the handler that handled the request.

Constructor Summary

Constructors
Constructor and Description

ChainHandler()

Constructors
Constructor and Description
`ChainHandler()`

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`init(Server server, java.lang.String prefix)` Initializes this `ChainHandler` by initializing all the "wrapped" handlers in the list of handlers.
`static Handler`	`initHandler(Server server, java.lang.String prefix, java.lang.String name)` Helper function that allocates and initializes a new `Handler`, given its name.
`boolean`	`respond(Request request)` Calls each of the `Handler`s in turn until one of them returns `true`.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - handlers
```
public Handler[] handlers
```
    The array of handlers that will be invoked to handle the request.
  - names
```
public java.lang.String[] names
```
    The names of the above handlers as specified by the configuration parameters. Used for logging the names of each Handler as it is invoked.
  - prefix
```
public java.lang.String prefix
```
    The prefix used to initialize this ChainHandler, used for logging.
  - isMine
```
public MatchString isMine
```
    The URL that must match for this handler to run
  - report
```
public java.lang.String report
```
    The name (if any) of the property to receive the name of the handler that handled the request.
  - exitOnError
```
public boolean exitOnError
```
    A flag to require the successfull initialization of all handlers.
- Constructor Detail
  - ChainHandler
```
public ChainHandler()
```
- Method Detail
  - init
```
public boolean init(Server server,
                    java.lang.String prefix)
```
    Initializes this ChainHandler by initializing all the "wrapped" handlers in the list of handlers. If a wrapped handler cannot be initialized, this method logs a message and skips it. If no handlers were specified, or no handlers were successfully initialized, then the initialization of this ChainHandler is considered to have failed.
    
    Specified by:
    
    init in interface Handler
    
    Parameters:
    
    server - The HTTP server that created this ChainHandler.
    
    prefix - The prefix for this ChainHandler's properties.
    
    Returns:
    
    true if at least one of the wrapped handlers was successfully initialized.
  - initHandler
```
public static Handler initHandler(Server server,
                                  java.lang.String prefix,
                                  java.lang.String name)
```
    Helper function that allocates and initializes a new Handler, given its name. In addition to the ChainHandler, several other handlers contain embedded Handlers -- this method can be used to initialize those embedded Handlers.
    If there is an error initializing the specified Handler, this method will log a dignostic message to the server and return null. This happens if the specified class cannot be found or instantiated, if the specified class is not actually a Handler, if the Handler.init method returns false, or if there is any other exception.
    Parameters:
    
    server - The server that will own the new Handler. Mainly used for the server's properties, which contain the configuration parameters for the new handler.
    
    prefix - The prefix in the server's properties for the new Handler's configuration parameters. The prefix is prepended to the configuation parameters used by the Handler.
    name - The name of the new Handler. The name can be one of two forms:
    
    The name of the Java class for the Handler. This Handler will be initialized using the prefix specified above.
    A symbolic name. The configuration parameter name.class is the name of the Java class for the Handler. The above prefix will be ignored and this Handler will be initialized with the prefix "name." (the symbolic name followed by a ".").
    Returns:
    
    The newly allocated Handler, or null if the Handler could not be allocated.
  - respond
```
public boolean respond(Request request)
                throws java.io.IOException
```
    Calls each of the Handlers in turn until one of them returns true.
    
    Specified by:
    
    respond in interface Handler
    
    Parameters:
    
    request - The HTTP request.
    
    Returns:
    
    true if one of the Handlers returns true, false otherwise.
    
    Throws:
    
    java.io.IOException - if one of the Handlers throws an IOException while responding.

Class ChainHandler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

handlers

names

prefix

isMine

report

exitOnError

Constructor Detail

ChainHandler

Method Detail

init

initHandler

respond