Required Behavior of SAFs for Each Directive

When writing a new SAF, you should define it to accomplish certain actions, depending on which stage of the request-handling process will invoke it. For example, SAFs to be invoked during the Init stage must conform to different requirements than SAFs to be invoked during the Service stage.

The rq parameter is the primary mechanism for passing along information throughout the request-response process. On input to a SAF, rq contains whatever values were inserted or modified by previously executed SAFs. On output, rq contains any modifications or additional information inserted by the SAF. Some SAFs depend on the existence of specific information provided at an earlier step in the process. For example, a PathCheck SAF retrieves values in rq->vars that were previously inserted by an AuthTrans SAF.

This section outlines the expected behavior of SAFs used at each stage in the request-handling process. The SAFs are described in the following sections:

• Init() SAFs

• AuthTrans() SAFs

• NameTrans() SAFs

• PathCheck() SAFs

• ObjectType() SAFs

• Input() SAFs

• Output() SAFs

• Service() SAFs

• Error() SAFs

• AddLog() SAFs

For more detailed information about these SAFs, see the Sun Java System Web Server 7.0 Update 3 Administrator’s Configuration File Reference.

Init() SAFs

• Purpose: Initialize at startup.

• Called at server startup and restart.

• rq and sn are NULL.

• Initialize any shared resources such as files and global variables.

• Can register callback function with daemon_atrestart() to clean up.

• On error, insert error parameter into pb describing the error and return REQ_ABORTED.

• If successful, return REQ_PROCEED.

AuthTrans() SAFs

• Purpose: Verify any authorization information.

• Return REQ_PROCEED if the user was successfully and completely authenticated, REQ_NOACTION otherwise.

NameTrans() SAFs

• Purpose: Convert logical URI to physical path.

• Perform operations on logical path (ppath in rq->vars) to convert it into a full local file system path.

• Return REQ_PROCEED if ppath in rq->vars contains the full local file system path, or REQ_NOACTION if not.

• To redirect the client to another site, add url to rq->vars with full URL. For example, http://www.sun.com/. Call protocol_status() to set HTTP response status to PROTOCOL_REDIRECT, NULL. Return REQ_ABORTED.

PathCheck() SAFs

• Purpose: Check path validity and user’s access rights.

• Check auth-type, auth-user, and/or auth-group in rq->vars.

• Return REQ_PROCEED if user and group is authorized for this area, ppath in rq->vars.

• If not authorized, insert WWW-Authenticate to rq->srvhdrs with a value such as: Basic; Realm=\"Our private area\". Call protocol_status() to set HTTP response status to PROTOCOL_UNAUTHORIZED. Return REQ_ABORTED.

ObjectType() SAFs

• Purpose: Determine content-type of data.

• If content-type in rq->srvhdrs already exists, return REQ_NOACTION.

• Determine the MIME type and create content-type in rq->srvhdrs

• Return REQ_PROCEED if content-type is created, REQ_NOACTION otherwise.

Input() SAFs

• Purpose: Insert filters that process incoming (client-to-server) data.

• Input SAFs are executed when a plug-in or the server first attempts to read entity body data from the client.

• Input SAFs are executed at most once per request.

• Return REQ_PROCEED to indicate success, or REQ_NOACTION to indicate it performed no action.

Output() SAFs

• Purpose: Insert filters that process outgoing server-to-client data.

• Output SAFs are executed when a plug-in or the server first attempts to write entity body data from the client.

• Output SAFs are executed at most once per request.

• Return REQ_PROCEED to indicate success, or REQ_NOACTION to indicate it performed no action.

Service() SAFs

• Purpose: Generate and send the response to the client.

• A Service SAF is only called if each of the optional parameters type, method, and query specified in the directive in obj.conf match the request.

• Remove existing content-type from rq->srvhdrs. Insert correct content-type in rq->srvhdrs.

• Create any other headers in rq->srvhdrs.

• Call protocol_status to set HTTP response status. For more information, see protocol_status() Function.

• Call protocol_start_response to send HTTP response and headers. For more information, see protocol_start_response() Function.

• Generate and send data to the client using net_write. For more information, see net_write() Function.

• Return REQ_PROCEED if successful, REQ_EXIT on write error, REQ_ABORTED on other failures.

Error() SAFs

• Purpose: Respond to an HTTP status error condition.

• The Error SAF is only called if each of the optional parameters code and reason specified in the directive in obj.conf match the current error.

• Error SAFs do the same as Service SAFs, but only in response to an HTTP status error condition.

AddLog() SAFs

• Purpose: Log the transaction to a log file.

• AddLog SAFs can use any data available in pb, sn, or rq to log this transaction.

• Return REQ_PROCEED.