Sun Java System Web Server 7.0 Update 3 NSAPI Developer's Guide

Creating and Using Custom Filters

Custom filters are defined in shared libraries that are loaded and called by the server. The general steps for creating a custom filter are as follows:

These steps are described in greater detail in the following sections.

Writing the Source Code

Write your custom filter methods using NSAPI functions. For a summary of the NSAPI functions specific to filter development, seeOverview of NSAPI Functions for Filter Development and Filter Methods for the filter method prototypes.

The filter must be created by a call to filter_create. Typically, each plug-in defines an nsapi_module_init function that is used to call filter_create and perform any other initialization tasks. For more information, see nsapi_module_init() Function and filter_create() Function.

Filter methods are invoked whenever the server or an SAF calls certain NSAPI functions such as net_write or filter_insert. As a result, filter methods can be invoked from any thread and should only block using NSAPI functions. For example, crit_enter and net_read. If a filter method blocks using other functions, for example, the Windows WaitForMultipleObjects and ReadFile functions, the server could hang. Also, shared objects that define filters should be loaded with the NativeThread="no" flag, as described in Loading and Initializing the Filter.

If a filter method must block using a non-NSAPI function, KernelThreads 1 should be set in magnus.conf. For more information about KernelThreads, see the description in the chapter Syntax and Use of magnus.conf in the Sun Java System Web Server 7.0 Update 3 Administrator’s Configuration File Reference.

Keep the following in mind when writing your filter:

For examples of custom filters, see Chapter 4, Examples of Custom SAFs and Filters.

Compiling and Linking

Filters are compiled and linked in the same way as SAFs. For more information, see Compiling and Linking.

Loading and Initializing the Filter

For each shared library (plug-in) containing custom filters to be loaded into the server, add an Init directive that invokes the load-modules SAF to magnus.conf. The syntax for a directive that loads a filter plug-in is:

Init fn=load-modules shlib=path NativeThread="no"

Instructing the Server to Insert the Filter

Add an Input or Output directive to obj.conf to instruct the server to insert your filter into the filter stack. The format of the directive is as follows:

Directive fn=insert-filter filter="filter-name" [name1="value1"]...[nameN="valueN"]

<Object name="default">
Output fn=insert-filter
       from="Old String"
       to="New String"


Restarting the Server

For the server to load your plug-in, you must restart the server. A restart is required for all plug-ins that implement SAFs and/or filters.

Testing the Filter

Test your filter by accessing your server from a web browser. You should disable caching in your web browser so that the server is sure to be accessed. In Mozilla Firefox, you may hold the shift key while clicking the Reload button to ensure that the cache is not used. Examine the access and error logs to help with debugging.