Sun Java System Web Server 6.1 SP6 NSAPI Programmer's Guide

How the Server Handles Requests from Clients

Sun Java System Web Server is a web server that accepts and responds to Hypertext Transfer Protocol (HTTP) requests. Browsers such as Netscape™ Communicator communicate using several protocols including HTTP and FTP. The Sun Java System Web Server handles HTTP specifically.

For more information about the HTTP protocol, refer to Chapter 12, Hypertext Transfer Protocol specification.

HTTP Basics

As a quick summary, the HTTP/1.1 protocol works as follows:

The client (usually a browser) opens a connection to the server and sends a request.
The server processes the request, generates a response, and closes the connection if it finds a Connection: Close header.

The request consists of a line indicating a method such as GET or POST, a Uniform Resource Identifier (URI) indicating which resource is being requested, and an HTTP protocol version separated by spaces.

This is normally followed by a number of headers, a blank line indicating the end of the headers, and sometimes body data. Headers may provide various information about the request or the client body data. Headers are typically only sent for POST and PUT methods.

The example request shown below would be sent by a Netscape browser to request the server foo.com to send back the resource in /index.html. In this example, no body data is sent because the method is GET (the point of the request is to get some data, not to send it).

GET /index.html HTTP/1.0
User-agent: Mozilla
Accept: text/html, text/plain, image/jpeg, image/gif, */*
Host: foo.com

The server receives the request and processes it. It handles each request individually, although it may process many requests simultaneously. Each request is broken down into a series of steps that together make up the request-handling process.

The server generates a response that includes the HTTP protocol version, HTTP status code, and a reason phrase separated by spaces. This is normally followed by a number of headers. The end of the headers is indicated by a blank line. The body data of the response follows. A typical HTTP response might look like this:

HTTP/1.0 200 OK
Server: Sun-Java System-Web-Server/6.1
content-type: text/html
Content-length: 83

<HTML>
<HEAD><TITLE>Hello World</Title></HEAD>
<BODY>Hello World</BODY>
</HTML>

The status code and reason phrase tell the client how the server handled the request. Normally the status code 200 is returned, indicating that the request was handled successfully and the body data contains the requested item. Other result codes indicate redirection to another server or the browser’s cache, or various types of HTTP errors such as 404 Not Found.

NSAPI Filters

In previous versions of the Web Server, the NSAPI API allowed multiple SAFs to interact in request processing. For example, one SAF could be used to authenticate the client after which a second SAF would generate the content.

In addition to the existing NSAPI interfaces, Sun Java System Web Server introduces NSAPI filters that enable a function to intercept (and potentially modify) the content presented to or generated by another function.

For more information on NSAPI filters in Sun Java System Web Server 6.1, see Chapter 4, Creating Custom Filters.

Two new NSAPI stages, Input and Output, can be used to insert filters in obj.conf. The Input and Output stages are described later in this chapter.

Request-handling Process

When the server first starts up it performs some initialization and then waits for an HTTP request from a client (such as a browser). When it receives a request, it first selects a virtual server. For details about how the virtual server is determined, see the Sun Java System Web Server 6.1 SP6 Administrator’s Configuration File Reference.

After the virtual server is selected, the obj.conf file for the virtual server class specifies how the request is handled in the following steps:

To handle request

AuthTrans (authorization translation)

Verify any authorization information (such as name and password) sent in the request.

NameTrans (name translation)

Translate the logical URI into a local file system path.

PathCheck (path checking)

Check the local file system path for validity and check that the requestor has access privileges to the requested resource on the file system.

ObjectType (object typing)

Determine the MIME-type (Multi-purpose Internet Mail Encoding) of the requested resource (for example, text/html, image/gif, and so on).

Input (prepare to read input)

Select filters that will process incoming request data read by the Service step.

Output (prepare to send output)

Select filters that will process outgoing response data generated by the Service step.

Service (generate the response)

Generate and return the response to the client.

AddLog (adding log entries)

Add entries to log file(s).

Error (service)

This step is executed only if an error occurs in the previous steps. If an error occurs, the server logs an error message and aborts the process.

Directives for Handling Requests

The file obj.conf contains a series of instructions, known as directives, that tell the Sun Java System Web Server what to do at each stage in the request-handling process. Each directive invokes a SAF with one or more arguments. Each directive applies to a specific stage in the request-handling process. The stages are AuthTrans, NameTrans, PathCheck, ObjectType, Input, Output, Service, and AddLog.

For example, the following directive applies during the NameTrans stage. It calls the document-root function with the root argument set to D://Sun/WebServer61/server1/docs. (The document-root function translates the http://server_name/ part of the URL to the document root, which in this example is D://Sun/WebServer61/server1/docs.)

NameTrans fn="document-root" root="D:/Sun/WebServer61/server1/docs"

The functions invoked by the directives in obj.conf are known as SAFs.