The FilterHandler captures the output of some
Handler and then applies an number of
Filters to change that output
before it is returned to the client.
This handler provides one of the core services now associated with
the Brazil Server: the ability to dynamically rewrite web content
obtained from an arbitrary source.
For instance, the FilterHandler can be used as a proxy for
a PDA. The wrapped Handler would go to the web to
obtain the requested pages on behalf of the PDA. Then, a
Filter would examine all "text/html" pages and rewrite the
pages so they fit into the PDA's 200 pixel wide screen. Another
Filter would examine all requested images and dynamically
dither them to reduce the wireless bandwidth consumed by the PDA.
The following configuration parameters are used to initialize this
Handler:
prefix
Only URLs beginning with this string will be candidates for
filtering. The default is "/".
handler
The name of the Handler whose output will be captured
and then filtered. This is called the "wrapped handler".
filters
A list of Filter names. The filters are applied in
the specified order to the output of the wrapped handler.
A sample set of configuration parameters illustrating how to use this
handler follows:
These parameters set up a proxy server running on port 8081. As with a
normal proxy, this proxy server forwards all HTTP requests to the target
machine, but it then examines all HTML pages before they are returned to
the client and strips out all <img> tags. By applying
different filters, the developer could instead build a server
to automatically dither embedded images down to grayscale (instead
of simply stripping them all out)
to apply pattern recognition techniques to strip out only the
advertisements
to examine and change arbitrary URLs on the page
to extract the content from an HTML page and dynamically combine it
with another file to produce a different look-and-feel.
init(Server server,
String prefix)
Start the handler and filter classes.
boolean
respond(Request request)
Responds to an HTTP request by the forwarding the request to the
wrapped Handler and filtering the output of that
Handler before sending the output to the client.
server - The HTTP server that created this Handler.
Typical Handlers will use Server.props
to obtain run-time configuration information.
prefix - A prefix that this Handler may prepend to all
of the keys that it uses to extract configuration information
from Server.props. This is set (by the Server
and ChainHandler) to help avoid configuration parameter
namespace collisions.
For example, if a Handler uses the property
"account", and the specified prefix is "bank.", then the
Handler should actually examine the property
"bank.account" in Server.props.
Returns:
true if this Handler initialized
successfully, false otherwise. If
false is returned, this Handler
should not be used.
Responds to an HTTP request by the forwarding the request to the
wrapped Handler and filtering the output of that
Handler before sending the output to the client.
At several stages, the Filters are given a chance to
short-circuit this process:
Each Filter is given a chance to examine the
request before it is sent to the Handler. The
Filter may decide to change the request's properties.
A Filter may even return some content to the client now,
in which case, neither the Handler nor any further
Filters are invoked at all.
After the Handler has generated the response headers,
but before it has generated any content, each Filter is
asked if it would be interested in filtering the content. If no
Filter is, then the subsequent content from the
Handler will be sent directly to the client.
On the other hand, if any Filteris interested
in filtering the content, then the output of the Handler
will be sent to each of the interested Filters in order.
The output of each interested Filter is sent to the
next one; the output of the final Filter is sent to
the client. At this point, any one of the invoked Filters
can decide to reject the content completely, instead of rewriting it.
