This readme file goes into some simple instructions on how the
JavaCGIBridge actually gets used.  There are really only two places the
code needs to be modified to have a Java applet talk to a Perl/CGI script:
the Perl script itself and the Java applet itself.

The examples in this archive all rely on the JavaCGIBridge as the focal
point for change.

1) Changes to the Perl Script.

Generally, all you need to do is modify the Perl script to return data in
a way that is conducive to allowing the JavaCGIBridge class to parse the
data into a form that is easily teased apart by a Java programmer.

By default, JavaCGIBridge relies on finding certain "separators" to figure
out where the data starts and ends and where the individual records and
fields within that data start and end.

The "start of data" separator is an HTML comment followed by a newline
with the following text:

<!--start of data-->

The "end of data" separator is an HTML comment followed by a newline with 
the following text:

<!--end of data-->

Each record is delimited by a newline:

[newline]

Each field inside a record is delimited by a pipe:

|

ALL fields must end with this separator except the last field in a
record. 

That's it.  That's all you have to modify in your Perl code.

Design Suggestions:

To keep your CGI/Perl script working as a normal HTML forms interface
while you convert over to a Java applet front-end, make the Perl code also
look for a form variable called "javacgibridge" equal to "on" in order to
print out the data with the separators described above. Otherwise, print
the same old HTML you always displayed in your Perl script.

The JavaCGIBridge is NOT just for CGI scripts.  You can also use it to
read HTML URLs (or active server pages, or other browser capable data).
A common thing I like to do is do away with PARAMs in the HTML file and
use a separate setup information stored in a SETUP HTML file.  However, I
get tired of type | all the time for a setup file, so I generally make
the field delimiter "=" and the record delimiter equal to a newline (\n)
for setup files.

This allows an HTML setup file to look like

<!--start of data-->
cgiURL=../test.cgi
backgroundColor=white
foregroundColor=black
<!--end of data-->

Instead of

<!--start of data-->
cgiURL|../test.cgi
backgroundColor|white
foregroundColor|black
<!--end of data-->

The JavaCGIBridge has setXXXXXSeparator methods to allow the Java applet
programmer to set the field and record delimiters to simply "=" and "\n"
respectively (setFieldSeparator, setRecordSeparator).

==============================================

2) Changes to the Java applet.

To call a CGI Script, you need to set up three basic things:

a) The URL

b) The JavaCGIBridge

c) The Form variables (optional)

---

You set up the URL using the java.net.URL class that comes with the Java
JDK.  If you are calling a CGI script in a directory relative to the Java
Applet, you will generally create a URL using getCodeBase() method of the
applet like

URL u = new URL(getCodeBase(), "../divide_by_two.cgi");

If you are calling a CGI script with an absolute reference, you could use

URL u = new URL("http://www.yourdomain.com/cgi-bin/divide.cgi");

Documentation on the URL class and possible constructors are contained in
the Java JDK documentation.

Note: When a URL is instantiated, it needs to be done in a TRY/CATCH
Exception block in order to catch the MalformedURLException.

---

The JavaCGIBridge is easy to set up. Simply instantiate it. An optional
next step is to set up different separators (described above) or change
the timeout value of the JavaCGIBridge object.

Example:

JavaCGIBridge jcb = new JavaCGIBridge();

jcb.setFieldSeparator("="); // optional
jcb.setRecordSeparator("\n"); // optional

// The following tells the JavaCGIBridge to only wait 5000
// milliseconds (5 seconds) before throwing a
// JavaCGIBridgeTimeOutException when attempting to grab data
// from a URL.  Note: The default is 10 seconds.

jcb.setThreadJavaCGIBridgeTimeOut(5000); 

---

If you are calling a URL that expects form variables, then you need to set
these up before calling the CGI script.

This is done by creating a variable of type Hashtable and populating it
with form variables using the addFormValue method on the JavaCGIBridge
object.

Example:

Hashtable formVar = new Hashtable();
jcb.addFormValue(formVar,"firstname", "gunther");
jcb.addFormValue(formVar,"lastname", "birznieks");
jcb.addFormValue(formVar,"javacgibridge", "on");

Note, if a variable like firstname already has a value, then the
JavaCGIBridge appends the values together as elemetns of a Vector.
These are sent as separate form variables when the CGI is actually called
later on.

---

Finally, call the JavaCGIBridge using either getRawData or
getParsedData methods.  The getRawData returns a byte array containing the
raw HTML.  getParsedData returns a Vector of Vectors -- or basically a
Vector of returned Records whose fields have been seperated into elements
of Vectors themselves.

Note: The call to these methods needs to be encapsulated in a TRY/CATCH
block to see whether a JavaCGIBridgeTimeOutException occured.  Remember,
the internet is a slow beast sometimes.  Even if you test your applet on a
fast LAN, your users may be loading your applet around the world and
experience problems accessing the CGI scripts from your web site.

The JavaCGIBridgeTimeOutException is thrown when it takes too long (10
seconds by default) to POST and retrieve data back from the URL.

Example Code:

// Where u is of type URL and formVar is the Hashtable we
// setup previously.
//
// If we are passing form variables
Vector v = jcb.getParsedData(u, formVar);
// If we are not passing form variables
Vector v = jcb.getParsedData(u);

Design Note: If you are reading a setup file with the JavaCGIBridge
using the variable=value settings, then you probably don't want to
go through the trouble of teasing the values out of the Vector of Vectors
that is returned. Thus, JavaCGIBridge has a helper function that 
transformed the first and second elements of each Vector into a Hashtable
entry (Variable=value pair).

Example code:

// Assume we need to get the data
Vector v = jcb.getParsedData(u, formVar);

// convert the data to Hashtable form described above
Hashtable setupVars = jcb.getKeyValuePairs(v);

// use it...
setBackgroundColor((String)setupVars.get("backgroundColor"));

---

Putting this all together, here is some sample code to get a setup file
that is one directory above our class. Note that in the provided examples,
I place all the Java code in a Java subdirectory so that it does not
clutter up the HTML and CGI stuff.  Thus, to read the setup file, I direct
the applet to read from the codebase plus one level up...

eg URL u = new URL(getCodeBase, "../divide.cgi");

Here is a full code example:

    private void getSetupFile() {
        JavaCGIBridge jcb = new JavaCGIBridge();
        // Since we are reading a setup file, we just want
        // to make it into a variable=value format instead of the   
        // | seperator that is the default. This makes the  
        // setup file easier to read at the risk of making sure a
        // particular variable does not have an equal symbol in its
        // value.
        jcb.setFieldSeparator("=");
            
        Vector returnedDataSet = null;
        Hashtable keyValuePairs = null;
        
        try {
            URL u = new URL(getCodeBase(), "../example1_setup.html");
            
            returnedDataSet = jcb.getParsedData(u);
        
            // We call the function below since the vectors that
            // are returned contain setup information in the form of
            // the first field being a key (variable) and the second
            // field being a value to the key
 
            keyValuePairs = jcb.getKeyValuePairs(returnedDataSet);
 
        } catch (MalformedURLException e) {
            System.out.println("Malformed URL Exception:" + e);
        } catch (JavaCGIBridgeTimeOutException e) {
            System.out.println("JavaCGIBridge Timed Out:" + e);
        }
        
        cgiURL = (String)keyValuePairs.get("cgiURL");
            
    } // end of getSetupFile