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

Server Instructions in obj.conf

The obj.conf file contains directives that instruct the server how to handle requests received from clients such as browsers. These directives appear inside OBJECT tags.

Each directive calls a function, indicating when to call it and specifying arguments for it.

The syntax of each directive is:

Directive fn=func-name name1="value1"...nameN="valueN"

For example:

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

Directive indicates when this instruction is executed during the request-handling process. The value is one of AuthTrans, NameTrans, PathCheck, ObjectType, Service, AddLog, and Error.

The value of the fn argument is the name of the SAF to execute. All directives must supply a value for the fn parameter; if there’s no function, the instruction won’t do anything.

The remaining parameters are the arguments needed by the function, and they vary from function to function.

Sun Java System Web Server is shipped with a set of built-in SAFs that you can use to create and modify directives in obj.conf. For more information about these predefined SAFs, see the Sun Java System Web Server 6.1 SP12 Administrator’s Configuration File Reference. You can also define new SAFs, as discussed in Chapter 3, Creating Custom SAFs

The magnus.conf file contains Init directive SAFs that initialize the server. For more information, see Chapter 2, SAFs in the magnus.conf File

Summary of the Directives

Following are the categories of server directives and a description of what each does. Each category corresponds to a stage in the request-handling process. The section Flow of Control in obj.conf explains exactly how the server decides which directive or directives to execute in each stage.

Note –

For detailed information about the standard directives and predefined SAFs that are used in the obj.conf file, see Sun Java System Web Server 6.1 SP12 Administrator’s Configuration File Reference.

AuthTrans

Verifies any authorization information (normally sent in the Authorization header) provided in the HTTP request and translates it into a user and/or a group. Server access control occurs in two stages. AuthTrans verifies the authenticity of the user. Later, PathCheck tests the user’s access privileges for the requested resource.
```
AuthTrans fn=basic-auth userfn=ntauth auth-type=basic userdb=none
```
This example calls the basic-auth function, which calls a custom function (in this case ntauth, to verify authorization information sent by the client. The Authorization header is sent as part of the basic server authorization scheme.
NameTrans

Translates the URL specified in the request from a logical URL to a physical file system path for the requested resource. This may also result in redirection to another site. For example:
```
NameTrans fn="document-root" root="D:/Sun/WebServer61/server1/docs"
```
This example calls the document-root function with a root argument of D:/Sun/WebServer61/server1/docs. The function document-root function translates the http://server_name/ part of the requested URL to the document root, which in this case is D:/Sun/WebServer61/server1/docs. Thus a request for http://server-name/doc1.html is translated to D:/Sun/WebServer61/server1/docs/doc1.html.
PathCheck

Performs tests on the physical path determined by the NameTrans step. In general, these tests determine whether the path is valid and whether the client is allowed to access the requested resource. For example:
```
PathCheck fn="find-index" index-names="index.html,home.html"
```
This example calls the find-index function with an index-names argument of index.html,home.html. If the requested URL is a directory, this function instructs the server to look for a file called either index.html or home.html in the requested directory.
ObjectType

Determines the MIME (Multi-purpose Internet Mail Encoding) type of the requested resource. The MIME type has attributes type (which indicates content type), encoding, and language. The MIME type is sent in the headers of the response to the client. The MIME type also helps determine which Service directive the server should execute.

The resulting type may be:
- A common document type such as text/html or image/gif (for example, the file name extension .gif translates to the MIME type image/gif).
- An internal server type. Internal types always begin with magnus-internal.
  
  For example:
```
ObjectType fn="type-by-extension"
```
  This example calls the type-by-extension function, which causes the server to determine the MIME type according to the requested resource’s file extension.
Input

Selects filters that will process incoming request data read by the Service step. The Input directive allows you to invoke the insert-filter SAF in order to install filters that process incoming data. All Input directives are executed when the server or a plug-in first attempts to read entity body data from the client. The Input directives are executed at most once per request. For example:
```
Input fn="insert-filter" filter="http-decompression"
```
This directive instructs the insert-filter function to add a filter named http-decompression to the filter stack, which would decompress incoming HTTP request data before passing it to the Service step.
Output

Selects filters that will process outgoing response data generated by the Service step. The Output directive allows you to invoke the insert-filter SAF to install filters that process outgoing data. All Output directives are executed when the server or a plug-in first attempts to write entity body data from the client. The Output directives are executed at most once per request. For example:
```
Output fn="insert-filter" filter="http-compression"
```
This directive instructs the insert-filter function to add a filter named http-compression to the filter stack, which would compress outgoing HTTP response data generated by the Service step.
Service

Generates and sends the response to the client. This involves setting the HTTP result status, setting up response headers (such as content-type and Content-Length), and generating and sending the response data. The default response is to invoke the send-file function to send the contents of the requested file along with the appropriate header files to the client.

The default Service directive is:
```
Service method="(GET|HEAD|POST)" type="*~magnus-internal/*" fn="send-file"
```
This directive instructs the server to call the send-file function in response to any request whose method is GET, HEAD, or POST, and whose type does not begin with magnus-internal/. (Note the use of the special characters *~ to mean “does not match.”)

Another example is:
```
Service method="(GET|HEAD)" type="magnus-internal/imagemap" fn="imagemap"
```
In this case, if the method of the request is either GET or HEAD, and the type of the requested resource is "magnus-internal/imagemap," the function imagemap is called.
AddLog

Adds an entry to a log file to record information about the transaction. For example:
```
AddLog fn="flex-log" name="access"
```
This example calls the flex-log function to log information about the current request in the log file named access.
Error

Handles an HTTP error. This directive is invoked if a previous directive results in an error. Typically the server handles an error by sending a custom HTML document to the user describing the problem and possible solutions.

For example:
```
Error fn="send-error" reason="Unauthorized" 
path="D:/Sun/WebServer61/server1/errors/unauthorized.html"
```
In this example, the server sends the file in D:/Sun/WebServer61/server1/errors/unauthorized.html whenever a client requests a resource that it is not authorized to access.