Integrating FastCGI with Java

Steve Harris
Open Market, Inc.
7 May 1996

Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.
Tel: 617-621-9500 Fax: 617-621-1703 URL: http://www.openmarket.com/

1. Introduction

Java is an object-oriented programming language developed by Sun Microsystems. The Java Depvelopers Kit (JDK), which contains the basic Java class packages, is available from Sun in both source and binary forms at Sun's JavaSoft site. This document assumes that you have some familiarity with the basics of compiling and running Java programs.

There are two kinds of applications built using Java.

Java Applets are graphical components which are run off HTML pages via the <APPLET> HTML extention tag.
Java Applications (Apps) are stand-alone programs that are run by invoking the Java interpreter directly. Like C programs, they have a main() method which the interpreter uses as an entry point.

The initial emphasis on using Java for client side applets should not obscure the fact that Java is a full strength programming language which can be used to develop server side stand alone applications, including CGI and now FastCGI applications.

The remainder of this document explains how to write and run FastCGI Java applications. It also illustrates the conversion of a sample Java CGI program to a FastCGI program.

2. Writing FastCGI applications in Java

Writing a FastCGI application in Java is as simple as writing one in C.

Import the FCGIInterface class.

Perform one-time initialization at the _Accept() routine accepts a new request from the Web server.

Migrating Existing CGI Programs

The application library was designed to make migration of existing CGI programs as simple as possible. Many applications can be converted by adding a loop around the main request processing code and recompiling with the FastCGI application library. FastCGI applications have the following structure, with an initialization section and a request processing loop:

Initialize application;
while(FCGI_Accept() >= 0) {
Process request;
}

To ease migration to FastCGI, executables built with the application library can run as either CGI or FastCGI programs, depending on how they are invoked. The library detects the execution environment and automatically selects FastCGI or regular I/O routines, as appropriate.

After migration, developers can clean up their FastCGI applications for best performance:

Fix any resource leaks. Many CGI programs do not attempt to manage memory or close files, because they assume the world is going to be cleaned up when they exit. (If you don't want to clean up your program, you can just have your process assume that it is leaking memory and exit after processing some fixed number of requests.) Purify from Pure Software is one of a number of excellent tools for finding leaks and other memory use problems.
Fix any problems with retained application state. The application must ensure that any state that it creates in processing one request has no unintended effects on later requests.
Collapse functionality. A common practice with CGI applications is to implement many small programs, with one function per program. CGI encourages this, because smaller programs load faster. With FastCGI, it's better to have related functionality in a single executable, so there are fewer processes to manage and applications can take advantage of sharing cached information across functions.

Applications written in Perl, Tcl, and other scripting languages can be migrated by using a language interpreter built with the application library. FastCGI-integrated Tcl and Perl interpreters for popular Unix platforms are available from Open Market. The interpreters are backward-compatible: They can run standard Tcl and Perl applications.

5. FastCGI in the Open Market WebServer

This section describes the FastCGI support in the following Open Market server products:

Open Market WebServer V2.0
Open Market Secure WebServer V2.0
Open Market Secure WebServer (Global) V2.0

For more information about FastCGI support, see the Open Market WebServer Installation and Configuration Guide.

Server Configuration

FastCGI applications are configured with the server's configuration file. Configuration has two parts.

First, the server administrator defines an application class. For local applications, the application class specifies the details of running the FastCGI application, such as:

The pathname of the application executable.
Any arguments and environment variables to pass to the process at startup.
The number of processes to run.

For remote applications, the class configuration information includes the host and TCP port to connect to. The Web server assumes that the FastCGI application has been started on the remote host. If a request comes in and the server can't connect to the FastCGI TCP port, the server logs an error and returns an error page to the client.

The second configuration step is mapping the application class to a role:

For responder roles, the administrator configures some part of the URL space to be handled by the FastCGI application. For example, all URLs beginning with /rollcall/ might be handled by the employee database application.
For filter roles, the administrator configures a file extension to be handled by a filter application. For example, all files with the .sql extension could be handled by a SQL query lookup filter.
For authorizer roles, the administrator configures an authorizer application in the same manner as other access methods (hostname, username/password, etc.) A request must pass all access control checks (possibly including multiple FastCGI authorizers) before access is allowed.

Basic FastCGI

To simplify migration for existing CGI programs, the WebServer provides a simple way to install new FastCGI programs without having to reconfigure the server. However, this approach doesn't offer all of the performance benefits of FastCGI application classes.

The WebServer treats any file with the extension .fcg as a FastCGI application. When a request corresponds to such a file, the WebServer creates a new FastCGI process to handle the request, and shuts down the process when the request is complete (just as in CGI). In this mode of operation performance is comparable to CGI. Future versions of the WebServer will improve performance by automatically caching processes and re-using them for subsequent requests.

Session Affinity

FastCGI programs can improve performance by caching information in the application process. For applications that require frequent but expensive operations such as validating a username/password in an external database for each request, this technique can significantly improve performance.

To improve the effectiveness of this technique, the WebServer implements session affinity. When session affinity is enabled, the WebServer arranges for all requests in a user session to be handled by the same FastCGI application process. What constitutes a "session" is configurable. The default configuration uses the WebServer's built-in session tracking facility to identify user sessions. However, the server administrator can use any part of the request information for the session affinity mapping: the URL path, the client's hostname, the username, etc.

6. FastCGI Performance Analysis

How fast is FastCGI? The answer depends on the application. This section contains some real FastCGI performance measurements, as well as guidelines for estimating the FastCGI speedup.

FastCGI vs CGI

We measured the relative performance of CGI, FastCGI, and static files on the Open Market WebServer, using a simple application that generates a fixed number of output bytes. The following table shows the measured request processing time for different request types on a typical platform. The times are measured from the client perspective and include client, server, and application processing time.

Static file	21ms + 0.19ms per Kbyte
FastCGI	22ms + 0.28ms per Kbyte
CGI	59ms + 0.37ms per Kbyte

FastCGI performance is comparable to serving static files, and significantly better than CGI (clearly showing the high overhead for process creation). Real applications have an additional time component: process initialization, which should be added to overall request processing time.

Let's use this data to estimate the speedup from migrating a typical database CGI application to FastCGI. Assume the application takes 50ms to initialize the database connection and generates 5K of output data. Request performance can be computed as follows:

CGI	59ms + 50ms + (0.37ms)(5) = 111ms
FastCGI	22ms + (0.28ms)(5) = 23ms

In this example, FastCGI has a 5x performance advantage over CGI, mostly due to savings from not having to create and initialize new processes for each request.

7. Conclusions

Today's Web business applications need a platform that's fast, open, maintainable, straightforward, stable, and secure. FastCGI's design meets these requirements, and provides for a logical extension from proven and widely deployed CGI technology. This allows developers to take advantage of FastCGI's benefits without losing their existing investment in CGI applications.

8. For More Information

For more information about Open Market and our products, visit our Web site at:http://www.openmarket.com/

For more information about the FastCGI protocol and the developer's kit, and the latest information about FastCGI standardization and support in other Web servers, visit the FastCGI project page at:http://www.openmarket.com/fastcgi/

./usr/share/doc/libfcgi0ldbl/fcgi-java.htm0000644000000000000000000005005207436304223017254 0ustar rootroot Integrating FastCGI with Java