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

Chapter 12 Hypertext Transfer Protocol

The Hypertext Transfer Protocol (HTTP) is a protocol (a set of rules that describes how information is exchanged) that allows a client (such as a web browser) and a web server to communicate with each other.

HTTP is based on a request-response model. The browser opens a connection to the server and sends a request to the server. The server processes the request and generates a response, which it sends to the browser. The server then closes the connection.

This chapter provides a short introduction to a few HTTP basics. For more information on HTTP, see the IETF home page at:

This chapter has the following sections:


Sun Java System Web Server 6.1 supports HTTP/1.1. Previous versions of the server supported HTTP/1.0. The server is conditionally compliant with the HTTP/1.1 proposed standard, as approved by the Internet Engineering Steering Group (IESG), and the Internet Engineering Task Force (IETF) HTTP working group.

For more information on the criteria for being conditionally compliant, see the Hypertext Transfer Protocol -- HTTP/1.1 specification (RFC 2068) at:


A request from a browser to a server includes the following information:

Request Method, URI, and Protocol Version

A browser can request information using a number of methods. The commonly used methods include the following:

Request Headers

The browser can send headers to the server. Most are optional.

The following table lists some of the commonly used request headers.

Table 12–1 Common Request Headers

Request Header  



File types the browser can accept. 


Used if the browser wants to authenticate itself with a server. Information such as the user name and password are included. 


Name and version of the browser software. 


URL of the document where the user clicked on the link. 


Internet host and port number of the resource being requested. 

Request Data

If the browser has made a POST or PUT request, it sends data after the blank line following the request headers. If the browser sends a GET or HEAD request, there is no data to send.


The server’s response includes the following:

HTTP Protocol Version, Status Code, and Reason Phrase

The server sends back a three-digit numeric status code. The five categories of status codes are:

Table 12–2 Common HTTP Status Codes

Status Code  



OK, request has succeeded for the method used (GET, POST, HEAD).


The request has resulted in the creation of a new resource reference by the returned URI. 


The server has sent a response to byte range requests. 


Found. Redirection to a new URL. The original URL has moved. This is not an error and most browsers will get the new page. 


Use a local copy. If a browser already has a page in its cache, and the page is requested again, some browsers (such as Netscape Navigator) relay to the web server the “last-modified” timestamp on the browser’s cached copy. If the copy on the server is not newer than the browser’s copy, the server returns a 304 code instead of returning the page, reducing unnecessary network traffic. This is not an error. 


Sent if the request is not a valid HTTP/1.0 or HTTP/1.1 request. For example HTTP/1.1 requires a host to be specified either in the Host header or as part of the URI on the request line.


Unauthorized. The user requested a document but didn’t provide a valid user name or password. 


Forbidden. Access to this URL is forbidden. 


Not found. The document requested isn’t on the server. This code can also be sent if the server has been told to protect the document by telling unauthorized people that it doesn’t exist. 


If the client starts a request but does not complete it within the keep-alive timeout configured in the server, then this response will be sent and the connection closed. The request can be repeated with another open connection. 


The client submitted a POST request with chunked encoding, which is of variable length. However, the resource or application on the server requires a fixed length - a Content-Length header to be present. This code tells the client to resubmit its request with content-length.


Some applications (e.g., certain NSAPI plug-ins) cannot handle very large amounts of data, so they will return this code. 


The URI is longer than the maximum the web server is willing to serve. 


Data was requested outside the range of a file. 


Server error. A server-related error occurred. The server administrator should check the server’s error log to see what happened. 


Sent if the quality of service mechanism was enabled and bandwidth or connection limits were attained. The server will then serve requests with that code. See the "quality of service" section. 

Response Headers

The response headers contain information about the server and the response data.

The following table lists some common response headers.

Table 12–3 Common Response Headers

Response Header  



Name and version of the web server. 


Current date (in Greenwich Mean Time). 


Date when the document was last modified. 


Date when the document expires. 


Length of the data that follows (in bytes). 


MIME type of the following data. 


Used during authentication and includes information that tells the browser software what is necessary for authentication (such as user name and password). 

Response Data

The server sends a blank line after the last header. It then sends the response data such as an image or an HTML page.

Buffered Streams

Buffered streams improve the efficiency of network I/O (for example, the exchange of HTTP requests and responses), especially for dynamic content generation. Buffered streams are implemented as transparent NSPR I/O layers, which means even existing NSAPI modules can use them without any change.

The buffered streams layer adds the following features to the Sun Java System Web Server:

Note –

The UseOutputStreamSize parameter can be set to zero (0) in the obj.conf file to disable output stream buffering. For the magnus.conf file, setting UseOutputStreamSize to zero has no effect.

To override the default behavior when invoking an SAF that uses one of the functions net_read or netbuf_grab, you can specify the value of the parameter in obj.conf, for example:

Service fn="my-service-saf" type=perf UseOutputStreamSize=8192