sunlabs.brazil.filter
Class FilterHandler

java.lang.Object
  sunlabs.brazil.filter.FilterHandler (view source)

All Implemented Interfaces:

Handler

public class FilterHandler
extends Object
implements Handler

The FilterHandler captures the output of another Handler and allows the ouput to be modified. One or more Filters may be specified 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, suffix, glob, match

Specify the URL that triggers this handler. (See MatchString).

typePrefix

If specified, only documents whose content-type starts with "typePrefix" are filtered; all other content is returned directly to the client. For example typePrefix=text/html causes only html documents to be considered for filtering. "typePrefix" looks at the content type of the returned document, where as "prefix" (and suffix...) look at the URL used to fetch it.

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. For each filter, the following properties are used:

• class: To find the filter implementation
  
• prefix, suffix, glob, match, ignoreCase, invert: to determine which URL's are processed by this filter. These properties are examined at each request, so "upstream" filters can effect the inclusion/exclusion of downstream filters. See MatchString for more information.
  exitOnError
  If set, the server's initFailure will set any of the filters fail to initialize. No handler prefix is required.

A sample set of configuration parameters illustrating how to use this handler follows:

 handler=filter
 port=8081

 filter.class=sunlabs.brazil.filter.FilterHandler
 filter.handler=proxy
 filter.filters=noimg

 proxy.class=sunlabs.brazil.proxy.ProxyHandler

 noimg.class=sunlabs.brazil.filter.TemplateFilter
 noimg.template=sunlabs.brazil.template.NoImageTemplate
 

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.

See the description under respond for a more detailed explaination.

Field Summary

sunlabs.brazil.filter.FilterHandler.FilterInfo[]	filters
Handler	handler

Constructor Summary

FilterHandler()

Method Summary

boolean	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.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

handler

public Handler handler

filters

public sunlabs.brazil.filter.FilterHandler.FilterInfo[] filters

Constructor Detail

FilterHandler

public FilterHandler()

Method Detail

init

public boolean init(Server server,
                    String prefix)

Start the handler and filter classes.

Specified by:

init in interface Handler

Parameters:

server - The HTTP server that created this Handler. Typical Handlers will use Server.props to obtain run-time configuration information.

prefix - The handlers name. The string 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.

Returns:

true if this Handler initialized successfully, false otherwise. If false is returned, this Handler should not be used.

respond

public boolean respond(Request request)
                throws IOException

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:

1. Each Filter is given a chance to examine the request before it is sent to the Handler by invoking its respond() method. The Filter may decide to change the request's properties. A Filter may even return some content to the client now, by (calling request.sendResponse() and returning true), in which case, neither the Handler nor any further Filters are invoked at all.
2. Assuming the respond() methods of all the filters returned false (which is normally the case), the handler's respond() method is called, and is expected to generate content. If no content is generated at this step, this handler returns false.
3. 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.
4. On the other hand, if any Filter is 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.
5. At this point, any one of the invoked Filters can decide to reject the content completely, instead of rewriting it.

See Filter for a description of how to cause filters to implement the various behaviors defined above.

Specified by:

respond in interface Handler

Parameters:

request - The HTTP request to be forwarded to one of the sub-servers.

Returns:

true if the request was handled and content was generated, false otherwise.

Throws:

IOException - if there was an I/O error while sending the response to the client.