'; zhtm += ''; zhtm += '

' + pPage + ''; zhtm += '
'; window.popUpWin.document.write(zhtm); window.popUpWin.document.close(); // Johnny Jackson 4/28/98 } //--> Java 1.2 Unleashed -- Ch 48 -- Programming Other Servers

Java 1.2 Unleashed

Previous chapterNext chapterContents

- 48 -

Programming Other Servers

In the previous chapter, you learned how to use the Servlet API to write servlets that run on the Java Web server. The Servlet API is supported by a wide range of Web servers, including the popular Apache Web server, the Netscape Enterprise and FastTrack servers, and the Microsoft Internet Information Server. Support for these servers is provided with the Java Server Development Kit (JSDK), which is available from JavaSoft's Web site.

In this chapter, you'll take a look at server-side programming using Java. You'll learn about the Common Gateway Interface (CGI) and learn why the CGI is not conducive to server-side Java programming. You'll explore some of the server-side Java workarounds developed by Netscape and Microsoft for use with their servers. You'll then learn how to install the JSDK to support servlet programming on popular servers other than Java Web server. Finally, you'll be introduced to the servletrunner tool of JDK 1.2 and learn how to use it to run and test your servlets. When you finish this chapter, you'll have a better understanding of the Java server-side programming options that are available to you.

Java and the Common Gateway Interface

The Common Gateway Interface was adopted early on as a standard for interfacing external programs to Web servers. The CGI allows these external programs, referred to as CGI programs or CGI scripts, to be written in such a way that they are not dependent on the particular Web server being used. The CGI specification describes a standard interface for a Web server to send browser requests to the CGI program and for the CGI program to return response data to the browser, via the Web server. These interfaces are summarized as follows.

NOTE: A variation of the CGI, known as WinCGI, has been popularized by some early Windows-based Web servers.

Web Server to CGI Program Communication

Web servers communicate with CGI programs using environment variables, command-line arguments, and the standard input stream. These three communication methods are used as follows:

java ProgramName v1 v2 v3

CGI Program to Web Server Communication

Although there are three ways that information is provided to a CGI program, there is only one way that the CGI program returns information to the Web server (and on to the browser). CGI program output is simply written to the standard output stream. Java programs use the methods of the java.io package to write data to an output stream.

There are some additions to the CGI, such as the use of non-parsed header programs, but these additions are not significant for Java programming.


Variable Description
AUTH_TYPE The authentication scheme used with the request
CONTENT_LENGTH The length of standard input in bytes
CONTENT_TYPE The MIME type of the standard input
GATEWAY_INTERFACE The version of the CGI in use by the server
PATH_INFO Extra path information added to the URL of the CGI program
PATH_TRANSLATED The full path name of the CGI program
QUERY_STRING The query string appended to the request URL
REMOTE_ADDR The IP address of the requestor
REMOTE_HOST The host name of the requestor
REMOTE_IDENT The verified host name of the requestor
REMOTE_USER The name of the user making the request
REQUEST_METHOD The HTTP method used to make the request
SCRIPT_NAME The name of the CGI program
SERVER_NAME The host name of the server
SERVER_PORT The TCP port used by the Web server
SERVER_PROTOCOL The protocol used to submit the request
SERVER_SOFTWARE The name and version of the Web server software

Most CGI programs are written in scripting languages. Perl and UNIX shell languages are the most popular scripting languages. CGI programs can also be written in compiled languages, such as C and C++. Some Windows-based CGI programs are written in Visual Basic, Delphi, and other Windows-specific programming languages.

Java is not a good programming language for writing CGI programs, for two reasons: It doesn't support environment variables well, and the loading of the Java interpreter adds quite a bit of overhead to CGI processing.

Java's inability to read environment variables is an API problem. The pre-JDK 1.0 API was used to support the getenv() method of the System class for obtaining access to environment variables. However, this method has been deprecated and is no longer supported. Instead, the preferred solution is to use the getProperties() and getProperty() methods of the System class to access environmental properties of the Java program. When the Java interpreter is loaded and executed by a Web server, the server sets the CGI-standard environment variables in the interpreter's environment. However, the Java interpreter does not pass these variables on to the Java program as properties. This fundamental flaw makes Java incompatible with the CGI.

Even if Java programs could read the environment variables of the Java interpreter, the overhead of loading the Java interpreter for every Java CGI program is prohibitive. This is not a showstopper as far as Java CGI programming is concerned, but it is a serious limiting factor.

Because Java is a popular programming language and many people want to develop server-side programs in Java, there have been a number of approaches to making Java suited for server-side programming. The Servlet API is an optimal approach to server-side Java programming and will eventually become the standard. The following sections cover some of the other approaches to server-side Java programming. Then, we'll show how to use the JSDK to implement the Servlet API on popular Web servers.

NOTE: Additional information on the Common Gateway Interface can be obtained at the URL http://hoohoo.ncsa.uiuc.edu/cgi/interface.html.

Server-Side Java Programming with Netscape Servers

Netscape and Microsoft, being major Web server vendors, have created their own solutions to Java Web server programming. However, neither of these solutions is as elegant as the Servlet API. We'll discuss Netscape's approach in this section and Microsoft's in the next.

NOTE: Netscape's Enterprise and FastTrack servers and Microsoft's Internet Information Server provide separate support for the Servlet API, in addition to the standard Java support identified in this section and next.

Netscape solved the processing overhead problem of loading the Java interpreter with each CGI request by building the Java interpreter inside its FastTrack and Enterprise Web servers. The Java interpreter is loaded and started with the Web server and remains in memory throughout the server's operation. Server-side Java programs (referred to as server-side applets by Netscape) are placed in a special applets directory and installed with the Web server. The server is also configured to map specific URLs to the server-side applets.

NOTE: Netscape servers support servlets in a separate servlets directory. Servlets support the Servlet API. Server-side applets are Netscape's equivalent to servlets.

When a browser requests the URL of an applet, the server invokes the applet and passes the request information to the applet via special classes defined in the netscape. server.applet package. These classes are as follows:

Developing server applets using the netscape.server.applet package is a snap. You simply subclass HttpApplet with your applet and override its run() method to implement the applet's processing. Use the various methods of HttpApplet to access request information, and the getOutputStream() method of HttpApplet to obtain a stream that you can use to send response information back to the browser. The netscape.server.applet package is the next best thing to the Servlet API for server-side Java programming.

Netscape is gradually phasing out its server-side applet support in favor of the standard Servlet API of JDK 1.2. The netscape.server.applet package has been deprecated as of Enterprise Server 3.5.1.

Server-Side Java Programming with Microsoft Servers

Microsoft's Internet Information Server (IIS) provides the capability to develop server-side programs in Java. This capability is buried inside of its Active Server Pages (ASP) scripting environment, however.

ASP is an environment for developing dynamic Web applications, primarily using VBScript and JScript (Microsoft's clone of JavaScript). ASP was developed as a substitute for the CGI and supports the embedding of scripts within HTML files. The Web server executes these scripts when browsers request the HTML files. The results of the scripts' execution are embedded in the files before they are sent to the browsers.

Scripts may use objects to access request information provided by Web browsers and to send response information back to the browsers. The five primary objects supported by ASP are as follows:

The preceding objects are referred to as built-in objects. You use the properties and methods of these objects in scripts in much the same way you would use a Java object's variables and methods.

ActiveX server components are server-side components (think of them as server-side JavaBeans) that can be used by scripts. These components can be used to provide interfaces with databases, legacy applications, or just about anything that you would use a CGI program for. You can create server-side components using a variety of languages, one of which is Java.

To build an ActiveX server component using Java, you use the object interfaces that are provided in the asp package. These interfaces are as follows:

The ASP approach to Web applications wasn't exactly developed with Java in mind. You can develop ActiveX server components in Java, but you're probably better off using the ASP scripting languages. If you have the urge to develop server-side programs in Java on IIS, by all means use the Servlet API and the Java Servlet Development Kit.

The Java Servlet Development Kit

Given the diverging approaches taken by Netscape and Microsoft to support server-side Java programming, JavaSoft developed the Servlet API to provide a standard approach to supporting server-side Java. In addition, JavaSoft developed the JSDK as a means of ensuring that "Write Once, Run Everywhere" holds true for the Web server as well as the Web browser. The JSDK provides the servletrunner tool for supporting the development and testing of servlets as well as code that enables servlets to run on Apache, Netscape, and Microsoft Web servers. The following subsections discuss how to install the JSDK to run servlets on these Web servers.

Installing the JSDK with the Apache Web Server

The Apache freeware Web server is the world's most popular Web server. More Apache Web servers are deployed on the Web than Netscape and Microsoft Web servers combined. The Apache server is available in both source and binary distributions from the Apache Web site at http://www.apache.org. Although Apache was designed to take advantage of features of the Linux and UNIX operating systems, it is also available for Windows 98, 95, and NT platforms. However, the JSDK only supports Linux and UNIX implementations of Apache.

In order to use the Servlet API with the Apache Web server, you must download a source code distribution, version 1.1.3 or later. The JSDK provides the Apache servlet module, mod_servlet.c, which you must compile into the Apache server. You do this by copying mod_servlet.c to the src directory of the Apache distribution, editing the Apache Configuration file to include the following line, and compiling the Web server.

Module servlet_module    mod_servlet.o

After compiling Apache, you'll also need to edit the srm.conf file used to configure the server and add the following lines:

<Location /servlet>
 SetHandler servlet-handler

These lines configure the server to use the servlet module with client requests of the servlet directory. Additional configuration commands may be added to the srm.conf file to tailor the execution of the servlet module. These commands are covered in the servlet module's installation instructions.

This installation approach takes advantage of Apache's support for custom modules. The Java-Apache Project (http://java.apache.org/) is developing an external servlet engine for supporting the Servlet API that can be used with all Apache implementations. The overall goals of the project are to promote, plan, and develop server-side Java software for the Apache Web server.

Installing the JSDK with Netscape Servers

Next to Java Web Server, the Netscape family of Web server products provides the most platform-independent Web server solution. Netscape servers run on all major operating system platforms, from low-end Windows platforms to high-end UNIX servers. The JSDK provides support for the Servlet API on both Enterprise and FastTrack servers (versions 2.0 and higher). This support consists of class files that must be unzipped in the plugins\java\local-classes directory of the server's home directory.

Once the class files are put in place, you must configure your server to run Java. This is accomplished via the server administration interface. After turning Java on, you also need to edit your server's obj.conf file to map URLs containing /servlet to the directory where your servlets are stored. Then add the following lines to the bottom of this file:

<Object name="servlet">
Service fn="java-run" class="sun/servlet/netscape/NSRunner" 
vpath="/servlet" initfile="<nshome>/https-<hostname>/config/ servlets.properties"

Make sure to apply these changes and restart your server so that the changes take effect.

NOTE: Version 2.x and 3.0 Netscape servers use a JVM that supports JDK 1.02 but not higher JDK versions. This means that your servlets are limited in the classes that they may use.

Installing the JSDK with Microsoft Servers

Installation of the JSDK for versions 2.0 through 4.0 of Microsoft Internet Information Server is a breeze. Simply run the jsdk-iis.exe program that is distributed with the JSDK. This program copies the necessary files into your Web server's directory structure and makes changes, as required, to your system registry. After running the installation, make sure that you reboot your server so that all changes go into effect.

Using the Servlet API

After installing the JSDK support for your Web server, you can take advantage of the "Write Once, Run Anywhere" feature of the Servlet API. This means that you can develop and test your servlets on one Web server (for example, Java Web Server) and then run them on a different production Web server (such as Apache). This greatly enhances the portability and reusability of your servlets. The standardization provided by the Servlet API will allow the development of a market for platform-independent server-side programs. It is reasonable to expect that servlets and server-side Java beans will be available as commercial products in the same manner as applet-side classes and beans.

Using servletrunner

One of the most useful tools for developing and testing server-side programs is the servletrunner tool that is included with the JSDK 1.2. This tool provides a configurable, multithreaded environment that can be used to test multiple concurrent servlets. The servletrunner is configured to run a list of named servlets with a predefined set of initialization arguments. Configuration of servletrunner is accomplished using a properties file. The servlet.properties file is the default file used by servletrunner, but other files may be substituted using the -s command-line option.

The properties file consists of property statements of the form propertyName = propertyValue, where each statement is on a single logical line. A single logical line may be extended over multiple physical lines by using a backslash (\) as a line continuation character.

Property names are used to name a servlet and identify its initialization arguments. Properties of the form


are used to assign a name to a servlet. For example, the following statement gives the name time to the TimeServlet of Chapter 47, "Sun's Java Web Server":


In some cases, you may want to specify initialization parameters for a servlet. Consider the MessageServlet of Listing 48.1. It uses an initialization argument to determine which message it should display. This initialization argument is named message, and its value is read by the getInitParameter() method. The properties file for this servlet is as follows:

 message=This is the message of the day.

These statements are provided in the message.properties file on the book's CD. The first statement names MessageServlet as message. The second statement (continued over two lines) specifies the value of the message argument as This is the message of the day.

NOTE: Make sure that the servlet.jar file is in your CLASSPATH before compiling any of the servlet examples.

Compile MessageServlet.java in the ch48 directory. Make sure that you copy the message.properties file from the CD. Then run servletrunner from the ch48 directory using the following command:

servletrunner -s message.properties

The above command runs servletrunner using the message.properties file. The default TCP port of servletrunner is 8080. You can view the results of the servlet with your Web browser at http://your.host.com:8080/servlet/message. Figure 48.1 shows the result when I run it on my computer, athome.jaworski.com, and view it with my Web browser. Make sure that your TCP/IP software is up and running before starting servletrunner.

FIGURE 48.1. Viewing the results of the MessageServlet.

LISTING 48.1. THE MessageServlet SOURCE CODE.

import javax.servlet.*;
import java.util.*;
import java.io.*;
public class MessageServlet extends GenericServlet  {
 public String getServletInfo() {
  return "Message Servlet";
 public void service(ServletRequest request, ServletResponse response)
  throws ServletException, IOException {
  PrintStream outputStream = new PrintStream(response.getOutputStream());

Using servletrunner to Test HTML Form Handling

You can use servletrunner to debug the servlets that you use to handle HTML forms. Listing 48.2 presents the FormTestServlet, which is a scaled-down version of the EchoRequest servlet of Chapter 47. Compile FormTestServlet.java in the ch48 directory and copy formtest.properties from the CD. The formtest.properties file contains the single property statement:


This statement simply names the FormTestServlet as formtest. Listing 48.3 provides an HTML form that submits the results of the form to the FormTestServlet. You must edit the ACTION attribute of the FORM tag to replace athome.jaworski.com with your host name.

Run servletrunner from within the ch48 directory using the following command:

servletrunner -s formtest.properties

Open formtest.htm with your Web browser, edit the form's data, and click the Submit button. Figure 48.2 shows the results of submitting the form.

FIGURE 48.2. The results generated by the FormTestServlet.

LISTING 48.2. THE FormTestServlet SOURCE CODE.

import javax.servlet.*;
import java.util.*;
import java.io.*;
public class FormTestServlet extends GenericServlet  {
 public String getServletInfo() {
  return "Form Test Servlet";
 public void service(ServletRequest request, ServletResponse response)
  throws ServletException, IOException {
  PrintStream outputStream = new PrintStream(response.getOutputStream());
  outputStream.println("The request parameters are as follows:");
  Enumeration params = request.getParameterNames();
  if(params != null) {
    String param = (String) params.nextElement();
    String[] values = request.getParameterValues(param);
    outputStream.print(param+" = ");
    for(int i=0;i<values.length;++i) 
     outputStream.print(values[i]+" ");

LISTING 48.3. THE formtest.htm FILE.

<TITLE>Testing a form with FormTestServlet</TITLE>
<FORM ACTION="http://athome.jaworski.com:8080/servlet/formtest">
Enter text: <INPUT NAME="textField" TYPE="TEXT" SIZE="30"><P>
Check this out: <INPUT NAME="checkbox" TYPE="CHECKBOX"><P>
Select me: <SELECT NAME="mySelection">
<OPTION>Number one
<OPTION>Number two
<OPTION>Number three

The servletrunner Command-Line Options

The servletrunner program supports a number of command-line options:

Experiment with these options (especially the -p option) to tailor servletrunner's execution to your needs.


In this chapter, you took a look at server-side programming using Java. You learned about the Common Gateway Interface (CGI) and learned why the CGI is not conducive to server-side Java programming. You also explored some of the server-side Java workarounds developed by Netscape and Microsoft for use on their servers. You then learned how to install the JSDK with Apache, Netscape, and Microsoft Web servers. Finally, you were introduced to the servletrunner tool and learned how to use it to run and test your servlets. In the next chapter, you'll learn how Java is used with push technologies, such as Marimba's Castanet.

Previous chapterNext chapterContents

© Copyright, Macmillan Computer Publishing. All rights reserved.