This chapter summarizes the various APIs and programming technologies supported by Web Server.
This chapter has the following sections:
Web Server incorporates a modular architecture that integrates seamlessly with all products in the Sun Java TM System family of servers. In addition, Web Server supports a variety of APIs and programming technologies that enable you to do the following:
Generate dynamic content in response to client requests
Modify and extend the behavior of the server
Modify the content that is stored in the server
HTTP (Web Server)
The Content Handling engine enables you to manage your server’s content. You can create and store HTML pages, JavaServer Pages files JSP™, and other files such as graphics, text, sound, or video on your server. When clients connect to your server they can view your files provided they have access.
The Search engine enables Web Server users to search the contents and attributes of documents on the server. As a server administrator, you can create a customized text search interface that works with various types of document formats. Web Server converts many types of non-HTML documents into HTML as it indexes them, so users can use a web browser to view the documents that are found for their search.
Common Gateway Interface (CGI)
NetscapeTMServer Application Programming Interface (NSAPI)
Java Servlets and JavaServer Pages (JSP)
Netscape Server Application Programming Interface (NSAPI) implements the functions and server calls when processing a request. Server Application Functions or SAFs these functions, provide the core and extended functionality of Web Server. They enable the server to process requests and divide the requests into small steps that can be arranged in a variety of ways for speed and flexible configuration.
Java servlets and JavaServer Pages extensions enable all servlet and JSP meta functions, including instantiation, initialization, destruction, access from other components, and configuration management. Servlets and JSP files are reusable Java applications that run on a web server rather than in a web browser.
Web Server includes a set of runtime environments that support the server extensions. These runtime environments include the following:
The Web Server architecture includes a set of application services for various application-specific functions. These application services include the following:
You can configure the Web Server using the Administration user interfaces (UI) or through CLI. Most of the configuration files are in the directory install_dir/https-instance/config directory. For example, if Web Server is installed on a Windows machine in C:\Program Files\Sun\WebServer7, the configuration files for the server myserver.com are in:
The main configuration files are magnus.conf, server.xml, obj.conf, and mime.types. For more information about configuration files, see the Sun Java System Web Server 7.0 Update 3 Administrator’s Configuration File Reference.
This section summarizes the various APIs and programming technologies supported by Web Server, and describes how to get more information about them.
To modify the content of the server by adding, removing, or modifying resources and directories, use remote file manipulation.
Web Server 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.
For more information about defining and using server-parsed tags, see Chapter 2, Server-Parsed HTML 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 the C, C++, Java, and Perl languages and as shell scripts. CGI programs are invoked through URL invocation.
Web Server complies with the version 1.1 CGI specification.
For more information about using CGI with Web Server, see Chapter 2, Server-Parsed HTML Tags
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. Web Server includes all of the files necessary for developing and running Java servlets.
For information about using the Java Servlet API, see the documentation from Sun at 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 mixed 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 JSP files on Web Server, see the Sun Java System Web Server 7.0 Update 3 Developer’s Guide to Java Web Applications.
For more information about using JavaServer Page files, see the documentation from Sun at http://java.sun.com/products/jsp/index.jsp.
Using NSAPI, you can write plug-ins and filters to extend the functionality of Web Server. An NSAPI plug-in defines one or more Server Application Functions (SAFs). You can develop SAFs for implementing custom authorization, custom logging, and other modifications to how Sun Java System Web Server handles requests. For more information, see the Sun Java System Web Server 7.0 Update 3 NSAPI Developer’s Guide.
The file obj.conf contains instructions (known as directives) that tell the server how to process requests received from clients. Each instruction is enacted either during server initialization or during a particular stage of the request-handling process. Each instruction invokes a 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 7.0</font></H4>. The append-trailer function returns the requested resource to the client, in this case an HTML file, and appends the given trailer to it.
Service method=GET type="text/html" fn=append-trailer trailer= "<H4><font color=green>Served by 7.0</font></H4>"
Web Server has a set of predefined SAFs. It also has 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 7.0 Update 3 Administrator’s Configuration File Reference . For more information about custom SAFs, see the Sun Java System Web Server 7.0 Update 3 NSAPI Developer’s Guide.
The obj.conf file is essential for the operation of the server. If this file does not exist, the server cannot access instructions for how to handle requests. When defining new SAFs, include the header function nsapi.h (which is in install_dir/include) to have 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, which 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 7.0 Update 3 NSAPI Developer’s Guide for more information about the following topics:
Directives in obj.conf and how they determine how the server handles requests
NSAPI functions available for writing custom SAFs
Writing custom SAFs
For more information about the predefined SAFs that are included with Web Server, see the Sun Java System Web Server 7.0 Update 3 Administrator’s Configuration File Reference.
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");
Login to Admin Console
From the Common Task screen select the configuration from the drop-down list and click Edit Configurations tab.
Click the Access Control tab in the configuration screen.
Click the Access Control Lists (ACL) tab in the Authentication Databases screen.
Click New to create an ACL.
With Web Server 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 7.0 Update 3 Administrator’s Guide.
You can use the Access Control API to manipulate 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. The following example shows how you could authenticate users based on an e-mail address or on the URL that referred them to the resource:
allow (read) referrer="*www.acme.com*"
You can also authenticate the client based on your own authentication methods and databases.
You must define your own Loadable Authentication Service (LAS), which is an NSAPI plug-in in order for the server to use your attributes for authentication. Load this plug-in into the server 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
The Certificate-Mapping API consists of data structures and functions used to manage certificate mapping.
When a user authenticates to the Web Server by sending a client certificate, the server uses information in the certificate to search the user directory for the user’s entry.
You can configure some parts of this process by editing the certmap.conf file. This file specifies the following:
Instructs the server searches the directory for the user’s entry.
Determines 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 7.0 Update 3 Administrator’s Configuration File Reference.
You can also modify this process programmatically. Web Server includes a set of API functions, the Certificate-Mapping API functions that enable 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 http://developers.sun.com/index.html.
The following table lists the APIs available in Web Server.Table 1–1 APIs Available in Web Server
Interfaces for Generating Dynamic Content
Custom Server-parsed HTML Tags
HTML with additional JSP tags
CGI (one process per request)
C, C++, Perl, shell, and other languages
The Common Gateway Interface: http://hoohoo.ncsa.uiuc.edu/cgi/overview.html
APIs for Writing ServerPlugins
NSAPI (in-process shared object/DLL)
Changes from previous versions of Web Server are summarized in this section.
A new API for defining customized server-parsed tags as NSAPI plug-ins has been added. For more information, see Chapter 2, Server-Parsed HTML Tags.
NSAPI has new features.
Java Servlets 2.2.1 and JavaServer Pages 1.1 specifications are supported.
HTTP/1.1 cookies are supported.
Descriptions of CGI variables have been added to CGI Variables.
You can invoke servlets as SSI in HTML pages by using the <SERVLET\> tag, as discussed in Chapter 2, Server-Parsed HTML Tags.
NSAPI has new features.
Programs such as servlets modify a virtual server instead of the server as a whole. (To add programs as in iPlanet Web Server 4.1, you can configure only one virtual server.)
Web applications are now supported as described in the Java Servlet 2.2 API specification.
NSAPI has new features. For details, see the NSAPI Programmer’s Guide for Sun ONE Web Server.
Some configuration files have changed. For details, see the iPlanet Web Server 6.0 Programmer’s Guide (http://docs.sun.com/source/816-5687-10/index.html).
The Access Control API has changed. For details, see the comments in the server_root/plugins/include/nsacl/aclapi.h file.
Java Servlets 2.3 and JavaServer Pages 1.2 specifications are supported.
For information about migrating legacy servlets to web applications, see the Sun Java System Web Server 7.0 Developer's Guide to Web Applications.Sun Java System Web Server 7.0 Update 3 Developer’s Guide to Java Web Applications.
Java Servlets 2.4 and JavaServer Pages 2.0 specifications are supported.