Netscape's Web Application Interface (WAI) is the next-generation program interface that enables developers to extend a web server. As the Internet penetrates more deeply into the business world, the need to extend web servers and create dynamic content becomes stronger. All serious business web applications need to collect some user information from the browser and generate content according to the information collected. As an example, a web site often needs to authenticate a user through a user name and password and then generate a response according to the outcome of the authentication. WAI and other similar technologies provide a way to perform web services of this type.

In this article we'll first look at how these technologies have evolved and how they compare. Then we'll explore WAI programming through a "Hello World" example written in Java. I'll give some tips on how to move from other technologies to WAI, then take a closer look at how WAI works in conjunction with CORBA, and finally talk a little bit about WAI development in C or C++.

A SURVEY OF THE TECHNOLOGIES

Here we'll take a quick look at CGI and NSAPI before introducing WAI. Then we'll compare the Java support these technologies provide, and end with a summary of their advantages and disadvantages.

Common Gateway Interface (CGI)

The Common Gateway Interface (CGI) provides programmers with a simple interface for extending web servers. Take the aforementioned example of user authentication: The web server takes the user name and password supplied by the user and then starts another process (a CGI process) to perform the actual authentication. The communication between the CGI process and the web server is some type of interprocess communication; on a UNIX system, it's a pipe. Once the CGI process has authenticated the user, it passes the result to the server and exits.

The main advantages of CGI are:

• The protocol is simple. An experienced programmer could understand CGI quite thoroughly in a day or two.
• The CGI program can be written in most languages. Perl is a popular choice, although C and C++ are also used. The initial CGI programs were written in UNIX shell scripts. (Java is a different story, as we'll see in a later section.)

CGI has become the most widely used method of extending web servers. However, it also has a noticeable drawback: its performance doesn't meet the needs of serious web applications, mainly because a CGI process exits after servicing a request, so the processing time for each browser request includes process startup and exit overhead.

The fact that the CGI process exits after each request also prevents it from maintaining any state. This problem has a greater impact if database access is involved. Modern relational databases require users to establish a connection to the database engine before performing any SQL commands. The "connecting" phase also includes database user authentication. The time to establish a connection is often several times more than the time to perform an SQL operation. Since every CGI process is started fresh, each one has to reestablish a database connection, causing more processing overhead.

Netscape Server Application Programming Interface (NSAPI)

Recognizing CGI's performance problems, Netscape introduced the Netscape Server Application Programming Interface (NSAPI). NSAPI allows programmers to "plug" their functions into the server process itself rather than start another process, eliminating the process startup/exit overhead associated with CGI. NSAPI applications run much faster than CGI programs.

Let's again take user authentication as an example. After a programmer has plugged an NSAPI module into the server, the user authentication process goes like this: The server collects the user name and password from the browser; then it starts executing the NSAPI module as if the module were part of the server code. No more processes are invoked, so there's no process startup/exit overhead as in CGI. The server process stays on; therefore, any states (such as database connection) can be maintained.

NSAPI also allows the user to extend web servers in ways CGI can't, such as for publication and access control, custom logging, and user monitoring. But unfortunately, NSAPI is not the cure-all technology that we've been looking for. While dramatically increasing the speed of web server applications, NSAPI introduces some nagging problems that CGI doesn't have:

• Merging the application code into the same process as the web server allows a buggy application to crash the web server. (This is not a problem in CGI because CGI runs in a different process than the web server.) It also makes it hard to debug NSAPI programs.
• NSAPI allows programmers to write plug-in modules only in C or C++.
• NSAPI is difficult to learn. To write serious NSAPI applications, a programmer has to master the internal operations, data structures, and functions of the web server.

Because of these problems, NSAPI hasn't gained the wide popularity that CGI enjoys.

Web Application Interface (WAI)

The Web Application Interface (WAI) is Netscape's second approach to solving CGI's performance problems. The idea is that since most of these problems are introduced by starting a new process for each request, why not keep the process alive? That's exactly what WAI does.

A WAI process is started when the web server is started. This process handles CGI requests just as a CGI process would, only it doesn't exit after a request is processed; instead, it goes back and waits for more requests. As more requests come, the web server passes them to WAI. The server and the WAI process communicate through middleware called CORBA. (For now you can think of CORBA as a communication medium like TCP/IP; a later section will elaborate on CORBA.)

Once again, take the example of user authentication. As a user enters a user name and password, the server collects the information and asks the WAI process to invoke the method that does the authentication. The server also passes all the information that the WAI method needs. The WAI authentication method gets the user name and password, does the authentication, and passes the result back to the server, which in turn passes it to the browser. The WAI method exits, but the WAI process stays on and waits for more requests.

Because the WAI process doesn't go away after each request, we've avoided CGI's cumbersome process startup/exit overhead. We're also able to maintain states for browser requests. For example, we're able to "connect" to a database in the beginning and simply do SQL operations for all successive requests. Some preliminary engineering tests show that WAI is about three times faster than CGI.

WAI solves CGI's performance problems without introducing any of the headaches that are associated with NSAPI. Since WAI processes run outside the server process space, buggy code doesn't crash the web server. In addition, since WAI uses CORBA technology, WAI applications can be written in any language, including Java.

If performance is critical for an application, a programmer can even switch WAI from "out-of-process" mode to "in-process" mode so that the application will get the same performance as an NSAPI module. Of course, by doing that, the application sacrifices robustness and has to be written in C or C++; in this case, programmers should use the out-of-process mode to do debugging, and switch to in-process mode when the code is clean.

By using CORBA, WAI has another advantage over CGI and NSAPI: distributed computing. WAI processes can live either on the same machine as the web server or on a different machine. When machine resources are tight, or when the web server is under heavy load, WAI's distributed nature goes a long way toward maintaining application performance.

How Java Fits In

CGI has always been touted as a language-independent protocol. However, its Java support has been awkward at best. To invoke Java methods for CGI processing, the web server has to invoke the CGI process first, which in turn invokes a Java Virtual Machine (JVM) process. Both processes go away after each request, incurring twice the process startup/exit overhead.

At the same time it introduced NSAPI, Netscape integrated a JVM with the server so that programmers can write Java code to process CGI requests. This Java interface is called server-side Java. Unlike CGI, server-side Java's JVM is invoked at web server startup, and it doesn't exit after each request. Thus server-side Java is much faster than Java methods invoked by a CGI process.

Unfortunately, the integration of the web server and server-side Java JVM brings with it a great inconvenience, because server-side Java's JVM is a Netscape JVM. For various reasons, this JVM hasn't implemented all the latest Java Development Kit (JDK) features yet. For example, at this time the Java Native Interface (JNI) is not supported by the JVM, so quite a few Java Database Connectivity (JDBC) products don't operate properly in server-side Java.

WAI, however, allows a programmer to use any available JVM. The JVM is invoked directly from the command line, so there's no "double overhead" as in CGI.

Another comparable technology to WAI is Netscape's server-side JavaScript. Server-side JavaScript is similar to WAI in that it maintains state. It also provides some rich functionality in session management and database management. Compared to WAI, server-side JavaScript is easier to use to develop and build database connections, but it doesn't provide the performance of in-process WAI and also doesn't have the fine-grained control that WAI offers. The relationship between WAI and server-side JavaScript is similar to the relationship between a general language such as C and a scripting language like Perl.

The Comparison at a Glance

Table 1 summarizes the advantages and disadvantages of the technologies we've looked at so far. (I haven't covered Sun's Servlet API because currently it's not officially supported by Netscape.)

WAI PROGRAMMING

WAI is a bit more complicated than CGI but far simpler than NSAPI. Here I'll give you an idea of what WAI programming in Java is like. Note that you should have installed the WAI patch on your Enterprise Server 3.0 before starting up any WAI applications.

Configuring the Web Server

To run a WAI application -- also called a web application service (WAS) -- you need to configure the web server to initiate WAI and then start the WAI process. To initiate WAI on a server, do the following:

1. Start up the administration server.
2. Click "program" in the upper left part of the screen. In the left frame, you'll see a list under "Programs."
3. Click "WAI Management." You'll see a yes/no choice in the right frame.
4. Click "yes."
5. Click the "Save and Apply" button.

Your server will now be able to communicate with WAI applications. To verify this, type the URL http://hostname/NameService in your browser; you should see a long string starting with "IOR:".

Overview of WAI Classes

Before looking at our WAI programming example, let's review the four classes and interfaces in WAI:

• WAIWebApplicationService. You need to have your main application logic in the Run() method of this class.
• HttpServerRequest. This interface handles all the interaction between the browser and the web server.
• HttpServerContext. This interface provides information about the web server itself, such as its name and port number.
• FormHandler. This class helps you parse the query string containing the user form input, avoiding some headaches that exist in CGI.

A "Hello World" Example

Example 1 is a WAI "Hello World" example written in Java. It's a bit longer than a CGI "Hello World" example, but as I'll explain later, much of it is the same for every application. Once you've written the first one, you can just cut and paste.

import java.io.*;
import java.net.*;

import org.omg.CORBA.*;
import CosNaming.*;
import netscape.WAI.*;

class MyHello extends WAIWebApplicationService
{
   MyHello(java.lang.String name) throws
      CosNaming.NamingContextPackage.CannotProceed,
      CosNaming.NamingContextPackage.InvalidName,
      CosNaming.NamingContextPackage.AlreadyBound,
      org.omg.CORBA.SystemException {
         super (name);
      }

   // This method has to exist, otherwise your code won't compile.
   public java.lang.String getServiceInfo()
   {
      return "Hello World";
   }

   public int Run (HttpServerRequest request)
   {
      ByteArrayOutputStream streamBuf = new ByteArrayOutputStream();
      PrintStream content = new PrintStream(streamBuf);
      content.print("<h3>Hello World!</h3>");
      HttpServerReturnType rc;
      byte[] outbuff = streamBuf.toByteArray();

      try {
          rc = request.setResponseContentLength(outbuff.length);
          request.StartResponse();
      }
      catch (org.omg.CORBA.SystemException e) {
          System.err.println(e);
      }
      catch (java.lang.Exception e) {
          System.err.println(e);
      }

      int write_cnt = request.WriteClient(outbuff);
      return 0;
   }
}

class HelloWorld
{
   public static void main(java.lang.String[] args)
   throws UnknownHostException {
      try {
         // CORBA initialization, the same code for every WAI application
         ORB orb = org.omg.CORBA.ORB.init();
         BOA boa = orb.BOA_init();

         StringBuffer host = new StringBuffer(InetAddress.getLocalHost ().getHostName());
         if (args.length > 0)
             host = new StringBuffer (args[0]);
         try {
            MyHello mh = new MyHello("JavaHello");
            mh.RegisterService(host.toString());
            System.out.println("JavaHello registered");
            boa.impl_is_ready();
         }
         catch (org.omg.CORBA.UserException e) {}
         catch (java.lang.Exception e) {
            System.out.println ("WAS failed to initialize");
            System.err.println(e);
         }
      }
      catch (org.omg.CORBA.SystemException e) {
         System.err.println(e);
      }
      catch (java.lang.Exception e) {
         System.err.println(e);
      }
   }
}

To run the example program:

1. Enable WAI on your web server.
2. Set your CLASSPATH environment variable to include server root/wai/java/nisb.zip and server root/wai/java/WAI.zip.
3. Compile the program.
4. Run the application with the command java HelloWorld hostname:port number.
5. In a browser, enter the URL http://hostname/iiop/JavaHello. You'll see "Hello World!" displayed in the browser window.

Unlike with CGI, where the processes are started by a web server, a programmer needs to manually start the WAI process; the command in step 4 above does the trick. Your WAI process also has to tell the web server that it has started and is waiting for requests. In Example 1, the lines

MyHello mh = new MyHello("JavaHello");
mh.RegisterService(host.toString());

in the main method of the class accomplish this. Once the WAI process has registered with the server, the server calls WAI methods directly through CORBA's remote procedure call (RPC) mechanism. The server always calls the Run() method of the WAIWebApplicationService class; the essence of WAI programming is simply implementing the Run() method.

WAIWebApplicationService has three methods besides the constructor:

• The RegisterService() method registers your WAI application with the server. It's implemented by Netscape already; all you need to do is call it from your main program.
• The getServiceInfo() method, which you implement, has only one line: return a string describing your application.
• The Run() method is called by the server when the server notices a client request. Your main application logic is here.

A WAI application contains at least two classes: a class that extends WAIWebApplicationService and the main class of your application. The latter class is responsible for registering the WAI service with the web server.

In Example 1, the class named MyHello extends WAIWebApplicationService. MyHello has to implement getServiceInfo() and Run() methods in order to compile, because those two methods are declared as abstract methods.

When the server calls the Run() method, it passes an object that knows how to interact with the browser: the request object. In our example, the lines

ByteArrayOutputStream streamBuf = new ByteArrayOutputStream();
PrintStream content = new PrintStream(streamBuf);
content.print("<h3>Hello World!</h3>");
HttpServerReturnType rc;
byte[] outbuff = streamBuf.toByteArray();

put the "Hello World" string into an byte array. Then the statement

rc = request.setResponseContentLength(outbuff.length);

tells the server to set the right content length (part of the HTTP header), and

request.StartResponse();

signals the end of the HTTP header. Finally, the server pushes the content to the browser with

int write_cnt = request.WriteClient(outbuff);

As you can see, there are only about ten lines of code that matter. You can cut and paste the rest of the code for every WAI application.

Describing the classes and methods of WAI in detail is beyond the scope of this article. For more details, you can check out the WAI programming guide. In addition, looking at the sample programs distributed with the Enterprise Server (in the server root/wai/examples directory) will be helpful in learning more about WAI. These programs include:

• WASP (Web Application Server Prototype). Both C++ and Java examples are provided that can be run in-process or out-of-process for C++ and out-of-process for Java.
• CIIOP, a simple "Hello World" example that demonstrates how to use the C-based API to program WAI.
• forms, a C++ (in-process) example and a Java example of a class for handling form data.

FROM CGI TO WAI

Here I'll give you an idea of how you can do things in WAI that you normally do in CGI. We'll look at the three aspects of CGI programming that deal with the web server:

• The characteristics of the browser and the server are sent to the CGI process through environment variables.
• The user input is sent to the CGI process either through the QUERY_STRING environment variable or through standard input.
• The CGI output is sent to the server through standard output.

Environment Variables

There are two types of environment variables: those related to the browser and client input, and those related to the web server. The former are obtained by calling methods of HttpServerRequest, and the latter by calling methods of HttpServerContext. The sample program WASP.java that's distributed with the Enterprise Server shows how you can obtain the value of each environment variable. For example, if you want to know the value of REQUEST_METHOD, you do the following:

request.getRequestInfo("REQUEST_METHOD", environment)

where environment is a StringHolder in CORBA.

The Query String

The user form input is passed to a CGI program either through the QUERY_STRING environment variable or through standard input. Regardless of the method, the programmer is responsible for parsing the input, which is in the form of name-value pairs. WAI provides a very convenient class -- FormHandler -- that receives the user input and parses the name-value pairs into a hash table. Here's a code segment from the sample program forms/TestDriver.java that's distributed with the Enterprise Server:

netscape.WAI.FormHandler frmHndlr = new FormHandler(request)

if (frmHndlr.IsValid()) {
   frmHndlr.GetQueryString();
   frmHndlr.ParseQueryString();
   Hashtable h = frmHndlr.GetHashTable(); 
   ...

Now you can query the hash table for any names you're interested in.

Writing Back to the Browser

There are two parts to the CGI response to the client: the HTTP header and the HTTP body. You can use the various methods of HttpServerRequest to set the right HTTP headers. For example, RespondRedirect() will redirect a client to a specified URL, and setResponseContentType() will set the desired content type. Once you've set all the HTTP headers, you call StartResponse() to signal the end of the headers (the equivalent of printf("\n\n") in a CGI program).

After you've sent the HTTP headers (including the content length), you send the desired content to the browser by calling HttpServerRequest.WriteClient(outbuff), where outbuff is a byte array. Example 1 in the previous section shows how this is done.

FROM SERVER-SIDE JAVA TO WAI

If you've already written programs using Netscape's server-side Java API, transitioning to WAI is almost a cakewalk. The four classes of WAI roughly correspond to the four classes of server-side Java (see Table 2).

Table 3 lists the most often used server-side Java methods and their WAI counterparts.

Compared to server-side Java, it's easier to do cookie manipulation in WAI, with HttpServerRequest.getCookie() and HttpServerRequest.setCookie().

NSAPI VS. WAI

As difficult as NSAPI programming is, people still program in NSAPI because it offers great flexibility in customizing a web server. For example, you can insert your own environment variable into a CGI process with an NSAPI module. You can also create access control for each of your directories or URLs.

There is always a tradeoff between having a good programming environment and having maximum programming flexibility. Sometimes it's good practice to sacrifice some flexibility for a more user-friendly environment, and that's why Netscape is moving from NSAPI to WAI. To offer programmers maximum flexibility in customizing a web server with NSAPI, Netscape has exposed the inner workings of its servers to the outside world and has allowed external modules to be linked with the server itself. The result is that NSAPI modules are hard to debug and are known to crash web servers. Another unfortunate consequence is that knowledge about the web server's inner workings is a necessity in NSAPI programming.

WAI has fixed these problems by insulating the server from the outside world with a CORBA layer, with the tradeoff that WAI can do only a portion of what people do with NSAPI. But Netscape has done a careful study of how NSAPI is used in the field, and has found that most people use it to customize user authentication and to speed up applications with NSAPI service functions.

In Enterprise Server 3.0, the custom authentication part of NSAPI is replaced by Netscape's Access Control API, and the performance enhancement part of NSAPI is replaced by WAI. Of course there are always people who will want to customize the web server in different ways, and NSAPI will be there for that reason.

This article doesn't include any guidance on moving from NSAPI to WAI because there is no one-to-one relationship between the two.

UNDER THE HOOD: WAI AND CORBA

CORBA (which stands for Common Object Request Broker Architecture) is a kind of middleware that facilitates communication between software applications. The relationship between CORBA and applications is analogous to the relationship between a hardware bus and the boards plugged into it, or between a phone line and the phones plugged into it (the analogy I'll use here). WAI applications and the web server are like phones on the phone line -- CORBA.

When you enable WAI on your web server, the server will register itself with CORBA, like plugging itself into the phone line. In addition, the server will create a name service that acts like a phone line people can use to inquire about phone numbers (like a 555-1212 number in the U.S., except it's free). In CORBA terminology, the "phone number" is called an interoperable object reference (IOR). You can take a look at the name service's IOR by accessing the URL http://hostname/NameService.

When you start up a WAI application, it also registers itself with the name service, by calling the method RegisterService(). This method tells the web server that there's a WAI "phone" on the line, ready to receive calls.

When a user enters http://hostname/iiop/WAIService in the browser, the web server knows it's trying to access a WAI service, since the URL starts with "iiop." It then looks for the IOR (phone number) of WAIService, with the help of the name service. With the IOR in hand, the server "calls" the WAI application and tells it to start the Run() method.

Remember that when we introduced the classes of WAI -- WAIWebApplicationService, HttpServerRequest, HttpServerContext, and FormHandler -- we said that the middle two are actually interfaces while the other two are classes? The difference is that when you call a method of a class, you're executing the method in your own process, but when you call a method of one of the interfaces, you're actually "calling" the server and telling it to execute the method and return the result.

When a WAI application calls the HttpServerContext.getPort() method, for example, it calls the server and tells the server to execute the method and return the port number. Every time a WAI application requests information from the web server, it goes on to the network and does a remote procedure call, whereas in CGI the server passes all the information to the CGI process in one shot. This is a tradeoff between performance and flexibility.

A WORD ON C AND C++ DEVELOPMENT

The classes mentioned in this article also apply to C and C++ development, although in the case of C you're provided with equivalent function calls. You'll need to include some libraries in compiling and linking WAI programs. The makefiles included with the sample programs show how that's done. Netscape supports only the native C and C++ compilers provided by the system vendors; GNU compilers are not supported. For your convenience, Example 2 shows a "Hello World" WAI application in C++.

#include <sys/types.h>
#include "ONESrvPI.hpp"
#include "corba.h"

extern "C" int sleep(int);

const char *instanceName="HelloWorld";

// Declare a WAS class deriving from the Netscape base class.
class HelloWorld: public WAIWebApplicationService
{
public:
   HelloWorld(const char *object_name = (const char *)NULL, int argc=0, char **argv=0);
   long Run(WAIServerRequest_ptr session);
   char *getServiceInfo();
};

HelloWorld::HelloWorld(const char *object_name, int argc, char **argv):
WAIWebApplicationService(object_name, argc, argv)
{ }

long HelloWorld::Run(WAIServerRequest_ptr session)
{

   int buflen = strlen(buffer);
   session->setResponseContentLength(buflen);
   session->StartResponse();
   session->WriteClient((const unsigned char *)buffer, buflen);
   return 0;
}

char *HelloWorld::getServiceInfo(void)
{
   return StringDup("HelloWorld version 1.0");
}
 
int main(int argc, char **argv)
{
   WAIBool    rv;
   HelloWorld *anObject;

   if (argc !=2) {
      cout << "usage: HelloWorld hostname:port number\n";
      exit(1);
   }

   anObject = new HelloWorld("HelloWorld");
   rv = anObject->RegisterService(argv[1]);
   if (rv == WAI_FALSE) {
       printf("Failed to Register with %s\n", "webdev:8080");
   }
   else {
      while(1) sleep(1000);
   }

   return 0;
}

As you can see, a C++ program is very similar to a Java program. This type of language independence is achieved through the wonderful abilities of CORBA.

THE WAI TO GO

To be fair, Netscape isn't the first company that has implemented a persistent process to handle CGI requests. FastCGI, for example, has already achieved some degree of success in improving CGI performance with the same technique. The difference between WAI and FastCGI is that WAI uses CORBA as a communication medium whereas FastCGI is built directly on top of TCP/IP.

Because of CORBA's language-independent nature, Java support is built within the protocol, whereas FastCGI still has to invoke a Java process for each request.

In building a distributed application such as WAI or FastCGI, there are many inherent issues, such as security and load balancing. Currently both WAI and FastCGI face such problems. However, as CORBA improves over time, WAI can use CORBA's functionality and provide users with a better environment, whereas for applications built directly on top of TCP/IP, all new functionality has to be written from scratch.

In other words, WAI has achieved impressive improvement over CGI without introducing major new problems, and it will evolve to be an even better interface as CORBA improves. Future programming interfaces will be along the lines of WAI -- clearly the way to go!

Many thanks to Mike Lee for his valuable comments and suggestions, without which this article would not be complete; to Tass Sperring, Christie Badeaux, and Robert Husted for scrutinizing the original drafts; and to Caroline Rose for her wonderful editing.

Junhe Liu is a technology consultant at Netscape Communications. He works with Netscape partners in integrating their products into the Netscape ONE platform. His interests include Go, racquetball, and of course, Java.

(2.98)

---

Related Readings:

• Frequently Asked Questions: Find the answers to your questions on Internet technologies.
• Documentation: A library of technical information.
• Developer Central: Collections of developer resources organized by Internet technology areas.

Any sample code included above is provided for your use on an "AS IS" basis, under the Netscape License Agreement - Terms of Use