Connecting Java to CGI

(Also, for this case decodeURLString( ) returns a string instead of a char*.) You don't need to define a copy-constructor, operator=, or destructor because the compiler does that for you, and does it correctly. But even if it sometimes works automatically, C++ programmers must still know the details of copy-construction and assignment.

The remainder of the Pair class consists of the two methods decodeURLString( ) and a helper method translateHex( ), which is used by decodeURLString( ). (Note that translateHex( ) does not guard against bad user input such as "%1H.") After allocating adequate storage (which must be released by the destructor), decodeURLString( ) moves through and replaces each '+' with a space and each hex code (beginning with a '%') with the appropriate character.

CGI_vector parses and holds an entire CGI GET command. It is inherited from the STL vector, which is instantiated to hold Pairs. Inheritance in C++ is denoted by using a colon at the point you'd say extends in Java. In addition, inheritance defaults to private so you'll almost always need to use the public keyword as was done here. You can also see that CGI_vector has a copy-constructor and an operator=, but they're both declared as private. This is to prevent the compiler from synthesizing the two functions (which it will do if you don't declare them yourself), but it also prevents the client programmer from passing a CGI_vector by value or from using assignment.

CGI_vector's job is to take the QUERY_STRING and parse it into name-value pairs, which it will do with the aid of Pair. First it copies the string into locally-allocated memory and keeps track of the starting address with the constant pointer start. (This is later used in the destructor to release the memory.) Then it uses its method nextPair( ) to parse the string into raw name-value pairs, delimited by '=' and '&' signs. These are handed by nextPair( ) to the Pair constructor so nextPair( ) can return the Pair object, which is then added to the vector with push_back( ). When nextPair( ) runs out of QUERY_STRING, it returns zero.

Now that the basic tools are defined, they can easily be used in a CGI program, like this:

The alreadyInList( ) function is almost identical to the previous version, except that it assumes all email names are inside '<>'.

When you use the GET approach (which is normally done in the HTML METHOD tag of the FORM directive, but which is controlled here by the way the data is sent), the Web server grabs everything after the '?' and puts in into the environment variable QUERY_STRING. So to read that information you have to get the value of QUERY_STRING, which you do using the standard C library function getenv( ). In main( ), notice how simple the act of parsing the QUERY_STRING is: you just hand it to the constructor for the CGI_vector object called query and all the work is done for you. From then on you can pull out the names and values from query as if it were an array. (This is because the operator[] is overloaded in vector.) You can see how this works in the debug code, which is surrounded by the preprocessor directives #if defined(DEBUG) and #endif(DEBUG).

Now it's important to understand something about CGI. A CGI program is handed its input in one of two ways: through QUERY_STRING during a GET (as in this case) or through standard input during a POST. But a CGI program sends its output through standard output, typically using printf( ) in a C program. Where does this output go? Back to the Web server, which decides what to do with it. The server makes this decision based on the content-type header, which means that if the content-type header isn't the first thing it sees, it won't know what to do with the data. Thus, it's essential that you start the output of all CGI programs with the content-type header.

In this case, we want the server to feed all the information directly back to the client program (which is our applet, waiting for its reply). The information should be unchanged, so the content-type is text/plain. Once the server sees this, it will echo all strings right back to the client. So each of the strings you see, three for error conditions and one for a successful add, will end up back at the applet.

Adding the email name uses the same code. In the case of the CGI script, however, there isn't an infinite loop - the program just responds and then terminates. Each time a CGI request comes in, the program is started in response to that request, and then it shuts down. Thus there is no possibility of CPU hogging, and the only performance issue concerns starting the program up and opening the file, which are dwarfed by the overhead of the Web server as it handles the CGI request.

One of the advantages of this design is that, now that Pair and CGI_vector are defined, most of the work is done for you so you can easily create your own CGI program simply by modifying main( ). Eventually, servlet servers will probably be ubiquitous, but in the meantime C++ is still handy for creating fast CGI programs.

What about POST?

Using a GET is fine for many applications. However, GET passes its data to the CGI program through an environment variable, and some Web servers can run out of environment space with long GET strings (you should start worrying at about 200 characters). CGI provides a solution for this: POST. With POST, the data is encoded and concatenated the same way as a GET, but POST uses standard input to pass the encoded query string to the CGI program. All you have to do is determine the length of the query string, and this length is stored in the environment variable CONTENT_LENGTH. Once you know the length, you can allocate storage and read the precise number of bytes from standard input.

The Pair and CGI_vector from CGITools.h can be used as is for a CGI program that handles POSTs. The following listing shows how simple it is to write such a CGI program. In this example, "pure" C++ will be used so the stdio.h library will be dropped in favor of iostreams. With iostreams, two predefined objects are available: cin, which connects to standard input, and cout, which connects to standard output. There are several ways to read from cin and write to cout, but the following program take the common approach of using '<<' to send information to cout, and the use of a member function (in this case, read( )) to read from cin.

The getenv( ) function returns a pointer to a character string representing the content length. If this pointer is zero, the CONTENT_LENGTH environment variable has not been set, so something is wrong. Otherwise, the character string must be converted to an integer using the ANSI C library function atoi( ). The length is used with new to allocate enough storage to hold the query string (plus its null terminator), and then read( ) is called for cin. The read( ) function takes a pointer to the destination buffer and the number of bytes to read. The query_str is then null-terminated to indicate the end of the character string.

At this point, the query string is no different from a GET query string, so it is handed to the constructor for CGI_vector. The different fields in the vector are then available just as in the previous example.

To test this program, you must compile it in the cgi-bin directory of your host Web server. Then you can perform a simple test by writing an HTML page like this:

When you fill this out and submit it, you'll get back a simple text page containing the parsed results, so you can see that the CGI program works correctly.

Of course, it's a little more interesting to submit the data using an applet. Submitting POST data is a different process, however. After you invoke the CGI program in the usual way, you must make a direct connection to the server so you can feed it the query string. The server then turns around and feeds the query string to the CGI program via standard input.

To make a direct connection to the server, you must take the URL you've created and call openConnection( ) to produce a URLConnection. Then, because a URLConnection doesn't usually allow you to send data to it, you must call the magic function setDoOutput(true) along with setDoInput(true) and setAllowUserInteraction(false). Finally, you can call getOutputStream( ) to produce an OutputStream, which you wrap inside a DataOutputStream so you can talk to it conveniently. Here's an applet that does just that, after collecting data from its various fields:

Once the information is sent to the server, you can call getInputStream( ) and wrap the return value in a DataInputStream so that you can read the results. One thing you'll notice is that the results are displayed as lines of text in a TextArea. Why not simply use getAppletContext().showDocument(u)? Well, this is one of those mysteries. The code above works fine, but if you try to use showDocument( ) instead, everything stops working - almost. That is, showDocument( ) does work, but what you get back from POSTtest is "Zero CONTENT_LENGTH." So somehow, showDocument( ) prevents the POST query from being passed on to the CGI program. It's difficult to know whether this is a bug that will be fixed, or some lack of understanding on my part (the books I looked at were equally abstruse). In any event, if you can stand to limit yourself to looking at the text that comes back from the CGI program, the above applet works fine.