This chapter provides an overview of the Netscape Server API (NSAPI).
The NSAPI is an extension that enables you to extend or customize the core functionality of Sun Java System Web Server to provide a scalable, efficient mechanism for building interfaces between the HTTP server and back-end applications.
The NSAPI provides solutions to solve performance and efficiency problems common to installations that make liberal use of Common Gateway Interface (CGI ) functionality. CGI is common across most HTTP server implementations for running external programs, or gateways, between the information server and external applications.
This sections provides the logical breakdown of the HTTP request-response process.
After the client sends its request to a server, it is helpful to define a set of logical steps which the server must perform before a response is sent.
The following steps are performed in the normal response process:
Respond to request
Log the transaction
If at any time one of these steps fail, another step must be performed to handle the error and inform the client about what happened.
Server Application Functions (SAFs) are used to perform the steps to generate a HTTP request-response. These functions take the request, and server configuration database as input, and return a response to the client as output. The set of functions which are applied are determined by the inputs.
Server application functions have a particular class, where the class corresponds to the request-response step it helps implement. There is an additional class of application function, the initialization function, which is executed upon server startup and performs static data initialization for the various server modules.
Server application functions have a single class and are not informed by the server which class they are being used for. The server keeps an internal table of available functions, and maps these function pointers to unique character strings which identify them. By using this string in the configuration database, a function can be called to carry out one of the above steps.
You can create custom Server Application Functions (SAFs). Creation of SAFs allow you to modify or extend the Sun Java System Web Server's built-in functionality. For example, you can modify the server to handle user authorization in a special way or generate dynamic HTML pages based on information in a database.
For more information about how to create a custom server application function, see Chapter 2, Creating Custom Server Application Functions.
The parameter block is the fundamental data structure within the server code. The parameter block, or pblock, is a hash table keyed on the name string, which maps these name strings onto their value character strings.
For more information about the parameter block, see pblock Data Structure.
All server application functions have the following syntax:
int function(pblock *pb, Session *sn, Request *rq);
Where, pb is the parameter block with the parameters given by the site administrator for this function invocation. This parameter should be considered read-only, and any data modification should be performed on copies of the data. Doing otherwise is unsafe in threaded server architectures, and yields unpredictable results in multi-process server architectures.