If your web server does not support servlets then there are third-party server add-ons. Live Software offers a product called JRun. JRun is a set of classes and native code that can extend your web server to support servlets. This product can be used to add Java servlet functionality to Microsoft's IIS and Netscape's web servers. Visit Live Software's web site for more details: www.livesoftware.com. It is also a good idea to check with your web server vendor for servlet support and release dates.

Sun's Java Web Server At A Glance
You can start developing Java servlets today by downloading the Java Web Server from Sun Microsystems. The current platforms supported are Sun Solaris 2.x and Windows 95/NT. Also, the Java Development Kit (JDK) 1.1.2 or greater is required.

At the time of this writing, the final release of Java Web Server version 1.0.3 was available at Sun Microsystem's web site: http://jserv.javasoft.com

The download contains simple instructions for installing and running the web Server. You can confirm that it is properly installed and running by loading the default web page at http://localhost:8080/. By default, the web server is listening on port 8080 as opposed to port 80. The web server's home page has a number of useful links to developer and administrator documentation.

The Java Web Server has an administration tool that is written as a Java applet. You can administer the web server by opening http://localhost:9090. The default user name is admin and the default password is admin. Once logged in, you will see the Administrator applet as shown in figure 2.

The Administrator applet can be used to perform a number of operations such as add servlets, set up security parameters and set up servlet aliases. There are numerous other operations available and they are fully documented in the Administrator documentation. You will use the Administrator applet frequently during servlet development.

Servlet API Overview
The Java Servlet API is composed of two main packages: javax.servlet and javax.servlet.http.The javax.servlet package has a collection of classes and interfaces for writing servlets that are protocol independent. The servlet can communicate with the client using a custom protocol. Tables 1 and 2 show the most useful classes. A complete list of classes and interfaces can be found in the online documentation available with the Java Web Server.

You can use the javax.servlet.http package to communicate with HTTP specific client requests.

Basic Servlet Code Example
The time has come to view actual Java code for a servlet. Basically, all you have to do is extend from a servlet class. You have a choice here of extending from the abstract classes' GenericServlet or HttpServlet. You can use the GenericServlet class for basic server-side processing. As a web developer, migrating CGI scripts to Java, you will most likely use the HttpServlet class. The HttpServlet class provides protocol support for HTTP 1.0. Listing 1 is a code skeleton for a basic HttpServlet.First, the packages, javax.servlet and javax.servlet.http, are imported. Next, the class TestWebServlet is declared as public and extends from HttpServlet. The main entry point for your servlet is through the service() method. You will do the majority of your processing in this method. When your servlet is called by a client program, the service() method is invoked. The two parameters, HttpServletRequest and HttpServletResponse, contain client request and response information. These parameters will be used for communicating with the client.

The first parameter, an HttpServletRequest object, contains information specific to this client's request. In traditional CGI programming, this information could be read from the standard input stream (stdin). However, using the Java Servlet API you will access this information using an HttpServletRequest object. You can query this object to find out the client's host machine name and IP address. You also have the ability to find out the HTTP method used by the client to request information (i.e., GET, HEAD, POST, PUT). The most valuable method available in this HttpServletRequest object is the getParameter() method. This method allows you to provide the parameter name, the name of a form field for instance, and then the parameter value is returned. Here is an example of calling the getParameter method:

String userName = request.getParameter("Name");

The second parameter, an HttpServlet- Response object, is your vehicle for passing data back to the client. Basically, this works similarly to traditional CGI programming. However, instead of writing your information to the standard output stream (stdout) you will use the output stream provided by the client. To get the client output stream, simply call the getOutputStream() method on the HttpServletResponse object. With this output stream, you can construct a PrintStream for sending back your response. Here is an example of constructing a PrintStream:

PrintWriter out = new PrintWriter
(response.getOutputStream());

Now you have seen the basic framework for an HttpServlet. You are probably very eager to write, compile and run your first servlet. Well, you are in luck because now we will discuss the steps of servlet development.

I. Regional Settings
Some PowerBuilder features, such as DataWindow query mode and the Date() function, use the [shortdate] format defined in the regional settings control panel (see Figure 1).

The first step you should take toward Y2K compliance is to adopt a standard [shortdate] format that includes a four-digit year. You can't simply circumvent the control panel by explicitly specifying formats on all dates because PowerBuilder uses [shortdate] in date formats that you can't override. Also, hard-coding mm/dd or dd/mm may cause problems for users from other countries, where different standards for the relative order of month and day may apply. Even if you only deploy locally, users may still have changed their control panel settings. If you use [date] as the format for your edit masks, you ensure that your interface and the operating system settings align properly ([date] resolves to [shortdate]). By checking the registry, you can verify in code that the [shortdate] format includes a four-digit year. See Listing 1 for an example of how to do so.

Initial values that you set in controls or columns are subject to the [shortdate] settings, as are string/date conversions without explicit formats. When you use a string to assign a date value without providing an explicit format, PowerBuilder uses [shortdate] to interpret the date. PowerBuilder also assigns default formats when you place data fields on a window or DataWindow. Columns and computed fields that default to [general] ultimately resolve to [shortdate], but date edit masks start with mm/dd/yy and must be manually set to show century information. Using the PowerBuilder repository to store default column formats in the database is a good practice, but avoid relying entirely on the repository to set your column formats. See Listing 2 for examples of the impact [shortdate] can have on your code. You can remove some of the risk of this dependence on a system setting by using graphical calendars for user data entry. Alternatively, in PowerBuilder 6.0, if you check the Use Format box on the Edit tab of a column's property sheet, you can use a format for display and an edit mask for editing (see Figures 2 and 3).

II. Ambiguous Century
The most publicized category of Y2K risk comprises dates without clearly indicated century information. In PowerBuilder, since the date and datetime datatypes always carry century information, century problems arise from date/string conversions that lack adequate formatting or validation or when a date's component parts (year, month, day) are manipulated or stored as strings or integers. Remember that implicit or explicit string conversion takes place whenever your application gets a date from a file or a user interface.

Code that assumes a given century is extremely common. The most obvious example pastes a century in front of a two-digit year, as in Listing 3. You'll often find examples like this one at the tail end of extensive string manipulation of a date. Ironically, a desire to avoid century problems often motivates such code.

User interfaces that allow only two-digit year entries can discard century information. For example, if you retrieve the date 1945-12-16 into a column with a "mm/dd/yy" edit mask, PowerBuilder will initially retain the underlying date value. When a user edits the column, perhaps changing the year to "46," the column display will change by one year ("12/16/46") but the underlying value will follow the windowing rules and change to 2046-12-16. You could lose more than just century information by careless use of edit masks - any hidden part of the date will be set to a default value if the visible part is modified. See Listing 4 for an example of this risk.

Century ambiguity cuts in both directions. Reports that display two-digit years may not be clear to users, even if your application has century information in the underlying - but invisible - date values. Similarly, if you display date validation messages that don't include century information, users may find the messages confusing or meaningless. See Listing 5 for an example. Another output issue involves sorting. Without century information, dates in string format may not sort correctly (0 will sort before 9). Unless date strings are formatted YYYY-MM-DD, an alphanumeric sort will not order them chronologically.

Also, make note of the getServletInfo() method. This method is available in the HttpServlet class and we're simply overriding it. This is a developer-friendly method that can provide information on the servlet such as the author's name, date, revision and a shameless plug for the corporate web site.

Step 2: Compile the servlet
Make sure you have the classpath set to server_root/lib/classes.jar. To compile, issue the following command:

$ javac -d server_root/servlets
EchoEnvironmentServlet.java

This will create the class file EchoEnvironmentServlet.class and automatically store it in the server_root/servlets sub-directory.

Step 3: Add the servlet
Remember, you have to add the servlet to the web server.

Servlet Name = EchoEnviro
Servlet Class = EchoEnvironmentServlet

Once entered, click the "Add" button in the bottom of the center pane. Close the window.

Step 4: Test the Servlet
You can check if your servlet was properly added to the web server by invoking the servlet. To invoke your environment variables servlet, use the following URL:

http://localhost:8080/servlet/EchoEnviro

Your servlet should return a web page that lists the different environment variables. Also, as a bonus, this servlet displays the MIME-type header information.

As you can see, accessing environment variables in a Java servlet is very straight-forward. So now you can easily write a Java servlet that can identify the web browser being used by the client.

Reading The Form Data
With the knowledge you've gained so far about Java servlets, you now have the skills to process HTML form data. Forms can be used to gather user information for an order request, class registration or magazine subscription request. In this section, you will develop an HTML form and also a Java servlet to process a magazine subscription.

Step 1: Develop the HTML Form
First, we have to develop the HTML form. This form is your traditional magazine subscription form. Figure 4 is a screen shot of the form.

Listing 4, MagazineForm.html provides the complete HTML code for the form. CAUTION: Form POSTing Buglet

I was migrating an enterprise CGI application to Java servlets when I ran into a bug while using the POST method to pass form data. This bug appears when using the Java Web Server 1.0.3 on the Windows 95 platform. If your form tries to POST data then you will get the following error:

A network error occurred while receiving data. Network Error: Connection reset by peer.

Since my project deadline was fast approaching, I used a simple work-around. Instead of using the POST method, I used the GET method in the HTML form.

Step 2: Develop the Magazine Form Servlet
The magazine form servlet (see Figure 4) will read information from the client's submission. Once the form fields are accessed, a confirmation HTML page is returned to the user.

1. Write the servlet code
Listing 5, EchoMagazineServlet.java, provides the complete code for the Java servlet.

Notice that in this example we are overriding the life cycle method, init(). In this method we call the constructor of the superclass. However, the item of interest here is the initialization of the integer variable, counter. The counter is used to display the number of subscription forms submitted. The counter variable illustrates the fact that only one instance of the servlet is created. During repeated calls to the service() method, the counter is incremented.

As usual, we process the client request in the service() method. The counter variable is incremented in the first couple of lines in the service() method. Then, the basic HTML header tags are added to the replyPage string. A line of text is added to display the subscriber count by accessing the counter variable. Next, the form data is accessed by calling the getParameter() method with the name of the HTML form field. The servlet information is added at the bottom of the page by calling the getServletInfo() method. Finally, the servlet responds to the client by returning the constructed HTML page. 2. Compile the servlet code

$ javac -d server_root/servlets
EchoMagazineServlet.java

3. Add the servlet to the web server
Refer to the "add servlet" steps presented earlier in this article. Use the following information for Servlet Name and Servlet Class fields.

Servlet Name = EchoMagazineForm
Servlet Class = EchoMagazineServlet

4. Test the servlet
Using your Web browser, open the html page, MagazineForm.html. Enter some sample user data and press the "Subscribe" button. A confirmation message should be returned to the web browser.

This example uses a basic, practical approach for accessing form data. There are a number of useful methods available in the HttpServletRequest class. If you are building a dynamic and robust servlet for reading forms then you can call the getParameterNames() routine to get a list of parameter names. The list of parameter names corresponds to the names of the HTML form input fields. The parameter list is actually returned as an Enumeration object.

The following is a simple code fragment that uses the getParameterNames() method:

Enumeration e = request.getParameterNames();
String name, value;

while (e.hasMoreElements()) {
name = (String) e.nextElement();
value = request.getParameter(name);

replyPage += "

" + name + ": " + value;
}

Also, if your servlet needs to read files on the web server then you can use the HttpServletRequest.getRealPath() method. This method is useful because you can provide the relative web file path and the absolute file path is returned. Once you have the absolute path then you can easily create a FileInputStream or FileOutputStream.

If you want to redirect the web browser to a new web page then you can use the HttpServletResponse.sendRedirect() method and provide a URL string. Also, you can gracefully recover from exceptions by sending an error page. In this situation, call the HttpServletResponse.sendError() and provide the error code and error string.

As you can see, the Servlet API provides a great deal of support for communicating with the web client.

Conclusion
Java servlets give you the capability to develop complex server-side applications. Servlets leverage Java's object-oriented features to build reusable and modular components. You can easily create servlets to replace CGI applications, access databases and communicate with remote computers.

The new beta release of the Servlet API provides support for cookies and session management. The API also features HTML page compilation with embedded Java code and HTML templates.

You can use the information in this article to migrate your existing CGI applications to Java servlets. If you want a server-side application that is reusable, maintainable and efficient then you should make the migration!

In the next article, you will learn how to build a data-aware servlet using JDBC.

References
Article Listings:
http://www.j-nine.com/pubs/jdj
Java Servlet API: http://jserv.javasoft.com
Live Software, Jrun 2.0: http://www.livesoftware.com
This article is based on Java Web Server 1.0.3 final. Some details may have changed by the time you read this.