Sun ONE Web Server 6.1 Programmer's Guide |
Chapter 1
Technology OverviewThis chapter summarizes the various APIs and programming technologies supported by Sun Open Net Environment (Sun ONE) Web Server 6.1. More information about each API or programming technology is provided either in a chapter in this guide, or in a separate guide (reference information is provided).
This chapter has the following sections:
Sun ONE Web Server ArchitectureSun ONE Web Server incorporates a modular architecture that integrates seamlessly with all products in the Sun ONE family of servers. In addition, Sun ONE Web Server 6.1 supports a variety of APIs and programming technologies that enable you to do the following:
Sun ONE Web Server includes a number of software modules, which are discussed in the topics in this section:
Content Engines
Sun ONE Web Server content engines are designed for manipulating customer data. The following three content engines make up the Web Publishing layer of the Sun ONE Web Server architecture:
The HTTP engine represents the core of Sun ONE Web Server. From a functional perspective, the rest of the Sun ONE Web Server architecture resides on top of this engine for performance and integration functionality.
The Content Management engine enables you to manage your server’s content. You create and store HTML pages, JavaServer Pages (JSP) pages, 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 to them).
The Search engine enables Sun ONE Web Server users to search the contents and attributes of documents on the server. As the server administrator you can create a customized text search interface that works with various types of document formats. Sun ONE 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.
Server Extensions
Sun ONE Web Server extensions enable you to extend or replace the function of the server to better suit your business operations. The following server extensions are part of the core Sun ONE Web Server architecture:
Common Gateway Interface (CGI) is a stand-alone application development interface that enables you to create programs that process your client requests dynamically.
Netscape Server Application Programming Interface (NSAPI) is used to implement the functions the server calls when processing a request (Server Application Functions or SAFs), which provide the core and extended functionality of Sun ONE Web Server. It allows the server’s processing of requests to be divided into small steps that may be arranged in a variety of ways for speed and flexible configuration.
Java Servlets and JavaServer Pages extensions enable all servlet and JSP metafunctions, including instantiation, initialization, destruction, access from other components, and configuration management. Servlets and JSPs are reusable Java applications that run on a web server rather than in a web browser.
Runtime Environments
In addition to the various server extensions, Sun ONE Web Server includes a set of runtime environments that support the server extensions. These runtime environments include the following:
Application Services
Finally, the Sun ONE Web Server architecture includes a set of application services for various application-specific functions. These application services include the following:
Configuration FilesYou can configure Sun ONE Web Server using the Administration user interfaces (UI), or by editing configuration files. Most of the configuration files are in the directory in the server_root/https-server_id/config directory. For example, if Sun ONE Web Server is installed on a Windows machine in C:\SunONE\Servers\, the configuration files for the server myserver.com are in:
C:\SunONE\Servers\https-myserver.com\config
The main configuration files are magnus.conf, server.xml, obj.conf, and mime.types, but there are other configuration files as well. For more information about configuration files, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Sun ONE Web Server 6.1 APIsThis section summarizes the various APIs and programming technologies supported by Sun ONE 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 ONE 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:
- 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:
- Modify the content of the server by adding, removing, or modifying resources and directories. To do this, use remote file manipulation.
Server-parsed HTML Tags
Sun ONE 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 "Server-parsed HTML Tags" for more information about defining and using server-parsed tags.
CGI
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 ONE Web Server complies with the version 1.1 CGI specification.
For more information about using CGI with Sun ONE Web Server 6.1, see "Using CGI."
Java Servlets and JavaServer Pages (JSP)
Sun ONE 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, which was developed by Sun Microsystems. Sun ONE 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 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 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 ONE Web Server 6.1, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.
For more information about using JavaServer Pages, see the documentation from Sun at:
http://java.sun.com/products/jsp/index.jsp
NSAPI
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 ONE 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 ONE Web Server handles requests. For more information, see the Sun ONE Web Server 6.1 NSAPI Programmer’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 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, 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 6.1</font></H4>"
Sun ONE 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 ONE Web Server 6.1 Administrator’s Configuration File Reference. For more information about custom SAFs, see the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide.
Note
The file obj.conf is essential for the operation of the server. If it does not exist, the server cannot work, because it has nowhere to look for instructions on how to handle requests.
Note
When defining new SAFs, include the header function nsapi.h (which is in server_root/plugins/include) to have access to all NSAPI functions.
Installing NSAPI Plugins (SAFs)
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:
See the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide for more information about the following topics:
For more information about the predefined SAFs that are included with Sun ONE Web Server, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.
Access Control API
The Access Control API is a C API that allows you to programmatically control who has access to what on Sun ONE Web Server.
Access control lists (ACLs) determine who has what kind of access privileges to which 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.
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 Sun ONE 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 ONE Web Server 6.1 Administrator’s Guide.
With the Access Control API you can 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. For example, you might want to 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.
Registering New Authentication Services
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:
For information about using the Access Control List API, see the Access Control Programmer's Guide (http://docs.sun.com/db/doc/816-5643-10). For information about the syntax for editing ACL files, see Appendix A in the same guide.
For information about changes to the Access Control API in Sun ONE Web Server 6.1, see the comments in the server_root/plugins/include/nsacl/aclapi.h file.
Certificate-Mapping API
The Certificate-Mapping API consists of data structures and functions used to manage certificate mapping.
When a user authenticates to a Sun ONE server by sending a client certificate to the server, 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 file certmap.conf. This file specifies the following:
For more information about certmap.conf, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference Guide.
You can also modify this process programmatically. Sun ONE 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).
API SummaryThe following table lists the APIs available in Sun ONE Web Server 6.1.
Table 1-1 APIs Available in Sun ONE Web Server 6.1
API/Interface/Protocol
Language
Documentation
Interfaces for Generating
Dynamic ContentCustom Server-parsed HTML Tags
C
"Server-parsed HTML Tags" in this guide
Java Servlets
Java
Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications
JavaServer Pages
HTML with additional JSP tags
Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications
CGI (one process per request)
C, C++, Perl, shell, and other languages
The Common Gateway Interface:
http://hoohoo.ncsa.uiuc.edu/cgi/overview.htmlAPIs for Writing Server
PluginsNSAPI (in-process shared object/DLL)
C, C++
Sun ONE Web Server 6.1 NSAPI Programmer’s Guide
Access Control API
C, C++
Access Control Programmer’s Guide
(http://docs.sun.com/db/doc/816-5643-10)
Certificate-Mapping API
C, C++
Certificate-Mapping Programmer’s Guide
(http://developer.netscape.com/docs/manuals/certificate/contents.htm)
Changes from Previous VersionsChanges from previous versions of Sun ONE Web Server are summarized in the following sections:
API Changes Since iPlanet Web Server 3.x
- A new API for defining customized server-parsed tags as NSAPI plugins has been added. For more information, see "Server-parsed HTML Tags."
- Server-side Java applets (HttpApplets) are not supported; use Java servlets instead.
- The Agents API is not supported.
- NSAPI has new features.
API Changes Since iPlanet Web Server 4.0
- Java Servlets 2.2.1 and JavaServer Pages 1.1 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 "Server-parsed HTML Tags."
- NSAPI has new features.
API Changes Since iPlanet Web Server 4.1
- 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.
API Changes Since Sun ONE Web Server 6.0
- Java Servlets 2.3 and JavaServer Pages 1.2 are supported.
- HTTP extensions for the WebDAV protocol in compliance with RFC 2518 are supported.
- NSAPI filters that enable the custom processing of HTTP request and response streams are supported.
- HTTP compression through the use of native HTTP request and response stream filters is supported.
- Legacy servlets (servlets configured through the servlets.properties, contexts.properties, and rules.properties files) are not supported.