Creating and Using Custom Filters

Custom filters are defined in shared libraries that are loaded and called by the server.

To create a custom filter

1. Writing the Source Code using the NSAPI functions.

2. Compiling and Linking the source code to create a shared library (.so, .sl, or .dll) file.

3. Loading and Initializing the Filter by editing the magnus.conf file.

4. Instructing the Server to Insert the Filter by editing the obj.conf file to insert your custom filter(s) at the appropriate time.

5. Restarting the Server.

6. Testing the Filter by accessing your server from a browser with a URL that triggers your filter.

   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, see Overview of NSAPI Functions for Filter Development. For a summary of general purpose NSAPI functions, see Chapter 4, NSAPI Function Reference Each filter method must be implemented as a separate function. See 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. See nsapi_module_init and filter_create for more information.

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 might 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 Chapter 3, Syntax and Use of the magnus.conf File, in Sun Java System Web Proxy Server 4.0.11 Configuration File Reference.

Keep the following in mind when writing your filter:

• Write thread-safe code

• IO should only be performed using the NSAPI functions documented in File I/O and Network I/O.

• Thread synchronization should only be performed using the NSAPI functions documented in Threads.

• Blocking can affect performance.

• Carefully check and handle all errors.

For examples of custom filters, see server_root/plugins/nsapi/examples and also Chapter 3, Examples of Custom SAFs and Filters

Compiling and Linking

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

Loading and Initializing the Filter

For each shared library (plug-in) containing custom SAFs to be loaded into the Sun Java System Web Proxy Server, add an Init directive that invokes the load-modules SAF to obj.conf. The syntax for a directive that loads a filter plug-in is:

Init fn=load-modules shlib=[path]sharedlibname NativeThread="no"

• shlib is the local file system path to the shared library (plug-in).

• NativeThread indicates whether the plug-in requires native threads. Filters should be written to run on any type of thread. For more information, see Writing the Source Code.

When the server encounters such a directive, server calls the plug-in’s nsapi_module_init function to initialize the filter.

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”]

• Directive is Input or Output.

• filter-name is the name of the filter, as passed to filter_create, to insert.

• nameN="valueN" are the names and values of parameters that are passed to the filter’s insert filter method.

Filters that process incoming data should be inserted using an Input directive. Filters that process outgoing data should be inserted using an Output directive.

To ensure that your filter is inserted whenever a client sends a request, add the Input or Output directive to the default object. For example, the following portion of obj.conf instructs the server to insert a filter named example-replace and pass it two parameters, from and to:

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

         

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 SAF by accessing your server from a browser. You should disable caching in your browser so that the server is sure to be accessed. In Netscape Navigator, press the Shift key while clicking the Reload button to ensure that the cache is not used. If the images are already in the cache, this action does not always force the client to fetch images from source. Examine the access and error logs to help with debugging.