This section summarizes the various APIs and programming technologies supported by Sun Java System Web Server 6.1, and describes how to get more information about them.
The main categories of extensions and modifications you can make to Sun Java System Web Server are listed below, and are used to do the following:
Dynamically generate responses (or parts of responses) to requests. The APIs and programming approaches that fall into this category are:
Java Servlets and JavaServer Pages (JSP)
Modify the behavior of the server itself by implementing server plugins. Most server plugins are written using Netscape Server Application Programming Interface (NSAPI). Specialized APIs also exist for writing server plugins, such as the Access Control List API (ACLAPI), which is used to control access to server resources. The APIs for modifying server behavior are:
Sun Java System Web Server 6.1 provides a C API for defining your own server-side tags. These tags can be used in addition to the standard server-side tags (such as config, include, and so on) in HTML files.
See Chapter 2, Server-parsed HTML Tags for more information about defining and using server-parsed tags.
Common Gateway Interface (CGI) programs run on the server and generate a response to return to the requesting client. CGI programs can be written in various languages, including C, C++, Java, and Perl, and as shell scripts. CGI programs are invoked through URL invocation.
Sun Java System Web Server complies with CGI specification version 1.1.
For more information about using CGI with Sun Java System Web Server 6.1, see Chapter 2, Server-parsed HTML Tags.
Sun Java System Web Server 6.1 supports the Java™ Servlet 2.3 specification, including web application and WAR file (Web ARchive file) support, and the JavaServer Pages™ (JSP™) 1.2 specification.
Java servlets are server-side Java programs that can be used to generate dynamic content in response to client requests in much the same way as CGI programs. Servlets are accessed through URL invocation.
You create servlets using the Java Servlets API. Sun Java System Web Server 6.1 includes all of the files necessary for developing and running Java servlets. You can compile servlets using any Java compiler you like, as long as the webserv-ext.jar file is accessible to your Java compiler. The webserv-ext.jar file is in the server installation directory at:
/bin/https/jar
For information about using the Java Servlet API, see
http://java.sun.com/products/servlet/index.jsp
A JSP page is a page that can be viewed in a web browser, much like an HTML page. However, in addition to HTML tags, it can include a set of JSP tags and directives intermixed with Java code that extend the ability of the web page designer to incorporate dynamic content in a page. These additional features provide functionality such as displaying property values and using simple conditionals.
For more information about creating web applications that use servlets and JSPs on Sun Java System Web Server 6.1, see the Sun Java System Web Server 6.1 SP6 Programmer’s Guide to Web Applications.
For more information about using JavaServer Pages, see
http://java.sun.com/products/jsp/index.jsp
Netscape Server Application Programming Interface (NSAPI) is a set of C functions for implementing extensions to the server. These extensions are known as server plugins.
Using NSAPI you can write plugins to extend the functionality of Sun Java System Web Server. An NSAPI plugin defines one or more Server Application Functions (SAFs). You can develop SAFs for implementing custom authorization, custom logging, and for other ways of modifying how Sun Java System Web Server handles requests. For more information, see the Sun Java System Web Server 6.1 SP6 NSAPI Programmer’s Guide.
The obj.conf file contains instructions known as directives that instructs the server how to process requests received from clients. Each instruction is processed either during server initialization or during a particular stage of the request-handling process. Each instruction invokes an SAF.
For example, the following instruction is invoked when the request method is GET and the requested resource is of type text/html. This instruction calls the append-trailer function with a trailer argument of <H4><font color=green>Served by 6.1</font></H4>. The append-trailer function simply returns the requested resource to the client and appends the given trailer to it.
Service method=GET type="text/html" fn=append-trailer trailer="<H4> <font color=green>Served by 6.1</font></H4>" |
Sun Java System Web Server 6.1 comes with a set of predefined SAFs. It also comes with a library of NSAPI functions for developing your own SAFs to modify the way the server handles requests. For more information about predefined SAFs, see the Sun Java System Web Server 6.1 SP6 Administrator’s Configuration File Reference. For more information about custom SAFs, see the Sun Java System Web Server 6.1 SP6 NSAPI Programmer’s Guide.
The file obj.conf is essential for the operation of the server. If it does not exist, the server cannot work, because it has no instructions to handle requests.
When defining new SAFs, include the header function nsapi.h (which is in server_root/plugins/include) to provide access to all NSAPI functions.
To load new NSAPI plugins containing customized SAFs into the server, add an Init directive to magnus.conf to load the shared library file that defines the new SAFs. This directive must call the load-modules function. This function takes the following arguments:
shlib: The shared library to load.
funcs: The functions to be made available to the server.
See the Sun Java System Web Server 6.1 SP6 NSAPI Programmer’s Guide for more information about the following topics:
Directives in obj.conf and how the server handles requests
NSAPI functions available for writing custom SAFs
Writing custom SAFs
Loading custom SAFs into Sun Java System Web Server by adding an Init directive to magnus.conf that calls load-modules
For more information about the predefined SAFs that are included with Sun Java System Web Server, see the Sun Java System Web Server 6.1 SP6 Administrator’s Configuration File Reference.
The Access Control API is a C API that allows you to programmatically control accessibility on Sun Java System Web Server.
Access control lists (ACLs) determine the access privileges to the resources on the server. Each ACL contains a list of access control entries. The following access control entry, for example, specifies that all access is denied to everyone for any resource having a URI that starts with /private.
acl "uri=/private/*"; deny (all) (user = "anyone"); |
To create access control lists, use the Restrict Access page in the Preferences tab of the Server Manager interface. You can also edit the files that contain the ACLs used by the server.
The default access control list resides in the directory server_root/httpacl. The default ACL file is generated.https-server_id.acl. There is also a file called genwork.https-server_id.acl that is a working copy the server uses until you save and apply your changes when working with the user interface. When editing the ACL file, you might want to work in the genwork file and then use the Server Manager to load and apply the changes.
With the Sun Java System Web Server 6.1, you can configure and reference multiple ACL files. For more information about configuring ACL files for virtual servers, see the Sun Java System Web Server 6.1 SP6 Administrator’s Guide.
With the Access Control API you can modify ACLs, read and write ACL files, and evaluate and test access to resources on the server.
You can also define your own attributes for authentication. For example, you can authenticate users based on e-mail address or on the URL that referred them to the resource:
allow (read) referer="*www.acme.com*"
You can also authenticate the client based on your own authentication methods and databases.
To tell the server to use your attributes for authentication, you must define your own Loadable Authentication Service (LAS), which is an NSAPI plugin. You load it into the server in the usual manner by adding the following directives to magnus.conf:
An Init directive that invokes the load-modules function to load the shared library.
An Init directive that calls the initialization function.
For information about changes to the Access Control API in Sun Java System Web Server 6.1, see the comments in the server_root/plugins/include/nsacl/aclapi.h file.
The Certificate-Mapping API consists of data structures and functions used to manage certificate mapping.
When a user authenticates to a Sun Java System server by sending a client certificate to the server, the server uses information in the certificate to search the user directory for the entry of the user.
You can configure some parts of this process by editing the file certmap.conf. This file specifies the following:
How the server searches the directory for the entry of the user.
Whether the server goes through an additional step of verifying that the user’s certificate matches the certificate presented to the server.
For more information about certmap.conf, see the Sun Java System Web Server 6.1 SP6 Administrator’s Configuration File Reference.
You can also modify this process programmatically. Sun Java System servers include a set of API functions (referred to here as the Certificate-Mapping API functions) that allow you to control this process. You can write your own functions to customize how certificate subject entries are found in the directory.
To use this API, you must have a copy of the Directory SDK. You can download a copy of this SDK from the following location:
http://developers.sun.com/index.html
For information about using the Certificate-Mapping API, see the Certificate-Mapping Programmer's Guide (http://developer.netscape.com/docs/manuals/certificate/contents.htm).