Overview of Filter Development

                                                                                                                                                                                                                                                                                                                                      Back to [Book]     [Topic]

Overview of Filter Development

This section discusses the position of filters in a stack and provides information on the NSAPI functions used to create filters. There are certain types of filters that can alter content-length of requests and responses. This section provides information about these filters.

The following topics are discussed in this section:

• Position of Filters in the Filter Stack
• NSAPI Functions for Filter Developement
• Filters That Alter Content-Length

Position of Filters in the Filter Stack

All data sent to the server, such as the result of an HTML form, or sent from the server, such as the output of a JSP page, is passed through a set of filters known as a filter stack. The server creates a separate filter stack for each connection. While processing a request, individual filters can be inserted into and removed from the stack.

Different types of filters occupy different positions within a filter stack. Filters that deal with application-level content (such filters that translates a page from XHTML to HTML) occupy a higher position than filters that deal with protocol-level issues (such as filters that format HTTP responses). When two or more filters are defined to occupy the same position in the filter stack, filters that were inserted later will appear higher than filters that were inserted earlier.

Filters positioned higher in the filter stack are given an earlier opportunity to process outgoing data, while filters positioned lower in the stack are given an earlier opportunity to process incoming data.

When you create a filter with the filter_create function, you specify what position your filter should occupy in the stack. You can also use the init-filter-order Init SAF to control the position of specific filters within filter stacks. For example, init-filter-order can be used to ensure that a filter that converts outgoing XML to XHTML is inserted above a filter that converts outgoing XHTML to HTML.

For more information, see filter_create() Function and init-filter-order in the Sun Java System Web Server Administrator's Configuration File Reference.

NSAPI Functions for Filter Development

NSAPI provides a set of C functions that are used to implement SAFs and filters. All of the public routines are described in detail in Chapter 6 NSAPI Function and Macro Reference.

The NSAPI functions specific to the development of filters are:

• filter_create() creates a new filter
• filter_insert() inserts the specified filter into a filter stack
• filter_remove() removes the specified filter from a filter stack
• filter_name() returns the name of the specified filter
• filter_find() finds an existing filter given a filter name
• filter_layer() returns the layer in a filter stack that corresponds to the specified filter

Filters That Alter Content-Length

Filters that can alter the length of an incoming request body or outgoing response body must take special steps to ensure interoperability with other filters and SAFs.

Filters that process incoming data are referred to as input filters, where an input filter can alter the length of the incoming request body. For example, if a filter decompresses incoming data and a Content-Length header is in the rq->headers pblock, the filter's insert filter method should remove the Content-Length header and replace it with a Transfer-encoding: identity header as follows:

pb_param *pp;

pp = pblock_remove("content-length", layer->context->rq->headers);
if (pp != NULL) {
   param_free(pp);
   pblock_nvinsert("transfer-encoding", "identity", layer->context->rq->headers);
}    

Because some SAFs expect a content-length header when a request body is present, before calling the first Service SAF, the server will insert all relevant filters, read the entire request body, and compute the length of the request body after it has been passed through all input filters. However, by default, the server will read at most 8192 bytes of request body data. If the request body exceeds 8192 bytes after being passed through the relevant input filters, the request will be cancelled. For more information, see the description of ChunkedRequestBufferSize in the “Syntax and Use of obj.conf” chapter in the Sun Java System Web Server Administrator's Configuration File Reference.

Filters that process outgoing data are referred to as output filters, where an output filter can alter the length of the outgoing response body. For example, if the filter compresses outgoing data, the filter's insert filter method should remove the Content-Length header from rq->srvhdrs as follows:

pb_param *pp;

pp = pblock_remove("content-length", layer->context->rq->srvhdrs);
if (pp != NULL)
   param_free(pp);