WebSite
Server-Side Java(tm) SDK
Anatomy of a Server-Side Java Program
Powered by Java

Robert B. Denny - Version 0.3 (experimental)
Back to overview

This section describes the structure of Java programs that use the WebSite Java SDK framework. If you are unfamiliar with the fundamental concepts of object-oriented programming and/or Java, you should review the article Writing Java Programs at the Sun/Java home site. This is part of the Java Tutorial and it contains an excellent fast-start for non-applet programming and general concepts. Also you may want to get a copy of our book, Java in a Nutshell.

Fast Start

Let's jump right in. Here is a simple WebSite Java program:

    import WebSite.WinCGI.*;
    public class Sample extends CGI {
        public void run() throws Throwable {
            Response.println("<html>\r\n<head>");
            Response.println("<title>Hello</title>\r\n</head>");
            Response.println("<body>\r\n<h1>Hello there!</h1>");
            Response.println("</body>\r\n</html>");
        }
    }

Believe it or not, this is a fully functional CGI program. It sends back an HTML document with a window title and the message Hello there!. Let's look at this in more detail:

import WebSite.WinCGI.*;
This line causes the Java compiler to include the WebSite Java CGI class library in the compilation. You need to do this to use the classes in the CGI framework.

public class Sample extends CGI {
All of your CGI programs must include a class that extends CGI. The CGI class is an abstract class that provides the linkage to the CGI runtime environment in the framework, and defines the run() method, which your class must implement (see the next paragraph).

public void run() throws Throwable {
This is the declaration of your implementation of the run() method. Your CGI program starts here. The abstract definition of run() in the parent CGI class specifies that run() throws the generic exception Throwable. This makes it possible for the code in the framework that calls your run() method to catch any type of exception that may be generated by your program. This is important, because the framework sends error messages back to the browser. A very nice feature as you'll see.

Response.println(...);
These lines transmit data back to the browser. As the method name implies, println() prints a line, that is a string of characters followed by a line terminator. The standard line terminator on the net is CRLF (\r\n in Java). Therefore, if you want to embed line terminators within strings to be sent, use CRLF as the terminator. Remember that println() adds a CRLF to the end of the string passed to it.

There is no need to deal with content-type headers and so forth if you are sending back HTML, because the framework defaults to text/html for response content type. It automatically sends the HTTP header when you first call one of Response's output methods. You can set a different content-type if you want, but you must do so before sending any data. Normally, you can just start sending HTML.

Note that the class name Response is used instead of the name of an instance of Response. The framework's classes work this way, similar to the way the System class works in Java. There is only one response, one request, one client, etc. So there is no need to create objects based on the CGI framework classes. Use the class names themselves. In Java terms, the framework's classes are static.

Processing Form Data

One of WebSite Pro's best features is its built-in form decoder. Combined with the WebSite Java SDK framework, form programming is really easy. Let's look at an example. Here is a form with a few of the common widgets:

  Your name:   
Address:
Is this cool or what?

The HTML source for the form is:

  <form method=POST action="/cgi-win/dummy">
  <pre>  Your name:   <input type=text name="nm" size=20><br>
    Address:     <input type=text name="ad" size=40><br>
    <input type=checkbox name="ck" checked>Is this cool or what?<br>
    <input type=submit value="Press here to do nothing"></pre>
  </form>

Note the field names nm, ad, and ck. Also, note that the form's method is POST. This is vital. Don't use GET based forms. Here is a Java CGI program that will send back the stuff in the form:

import WebSite.WinCGI.*;
public class FormEcho extends CGI {
    public void run() throws Throwable {
        Response.println("Your name is " + Form.getField("nm") + "<br>");
        Response.println("You live at " + Form.getField("ad") + "<br>");
        if(Form.getField("ck") != null)
            Response.println("You think this cool! I agree.");
        else
            Response.println("Are you crazy? This is cool!");
    }
}

Easy, isn't it? No decoding, no hassling with environment variables, INI file lines, and so on. As you may have guessed, the Form object encapsulates the data that was posted from the form. The getField() method of Form retrieves field contents by field name. Fields are assumed to contain text, and getField() returns a Java String object.

Checkboxes are special. If a checkbox is checked, it's name and (text) value appear in the posted form data. If it is not checked, it does not appear in the form at all. That's why the checkbox code above tests for null. The getField() method returns null if the named field does not exist in the posted form data.

OK, You Try it!

You can't learn to drive from a book. So now it's your turn to get a Java CGI program compiled and tested. Cut out the form and Java source above and turn them into an HTML form file and a Java source file. Fix the action argument in the form tag so it points to the class proxy for your Java program. Change the label on the button. Compile the Java program. Create the class proxy and put it into cgi-win. Fetch the form file with your browser, fill out the form, and click the button. Try it! Who cares if it doesn't work the first time?


[email protected]