Java CGI HOWTO: Using the Java CGI Classes.

Java CGI HOWTO: Using the Java CGI Classes. Next Previous Contents

5. Using the Java CGI Classes.

There are currently three main classes supported -- CGI, Email and HTML. I am considering adding classes to deal with MIME-formatted input and output -- MIMEin & MIMEout, respectively.

There are also a few support and test classes. CGI_Test, Email_Test and HTML_Test are intended to be used to test your installation. They can also be used as a starting-point for your own Java programs which use this class library. The Text class is the superclass for both the Email and the HTML classes.

5.1 CGI

Class Syntax

public class CGI

Class Description

The CGI class holds the ``CGI Information'' -- Environment variables set by the web server and the name/value sent from a form when its submit action is selected. All information is stored in a Properties class object.

This class is in the ``Orbits.net'' package.

Member Summary

        CGI()         //  Constructor.
        getNames()    //  Get the list of names.
        getValue()    //  Get form value by specifying name.

CGI()

Purpose: Constructs an object which contains the available CGI data.
Syntax: public CGI()
Description: When a CGI object is constructed, all available CGI information is sucked-up into storage local to the new object.

getNames()

Purpose: List the names which are defined to have corresponding values.
Syntax: public Enumeration getKeys ()
Description: Provides the full list of names for which coresponding values are defined.
Returns: An Enumeration of all the names defined.

getValue()

Purpose

Retrieves the value associated with the name specified.

Syntax

public String getValue ( String name )

Description

This method provides the corespondence between the names and values sent from an HTML form.

Parameter

name: The key by which values are selected.

Returns

A String containing the value.

5.2 CGI_Test

This class provides both an example of how to use the CGI class and a test program which can be used to confirm that the Java CGI package is functioning correctly.

Member Summary

        main()      //  Program main().

main()

Purpose

Provide a main() method.

Syntax

public static void main( String argv[] )

Description

This is the entry point for a CGI program which does nothing but return a list of the available name/value pairs and their current values.

Parameter

argv[]: Arguments passed to the program by the java.cgi script. Currently unused.

5.3 Email

Class Syntax

public class Email extends Text

Class Description

Messages are built up with the Text class add*() methods and the e-mail-specific methods added by this class. When complete, the message is sent to its destination.

This class is in the ``Orbits.net'' package.

Member Summary

        Email()      //  Constructor.
        send()       //  Send the e-mail message.
        sendTo()     //  Add a destination for message.
        subject()    //  Set the Subject: for message.

Email()

Purpose: Constructs an object which will contain an email message.
Syntax: public Email()
Description: Sets up an empty message to be completed by the Email methods.
See Also: Text.

send()

Purpose: Send the e-mail message.
Syntax: public void send ()
Description: This formats and sends the message. If no destination address has been set, there is no action taken.

sendTo()

Purpose

Add a destination for this message.

Syntax

public String sendTo ( String address )

Description

Add address to the list of destinations for this method. There is no set limit to the number of destinations an e-mail message may have. I'm sure that if you build up the list large enough, you can exceed the size of the parameter list that the Mail Transport Agent can accept or use up your memory.

Parameter/

address: A destination to send this message to.

subject()

Purpose

Set the subject for this message.

Syntax

public void subject ( String subject )

Description

This method sets the text for the e-mail's Subject: line. If called more than once, the latest subject set is the one that is used.

Parameter

subject: The text of this message's Subject: line.

5.4 Email_Test

This class provides both an example of how to use the Email class and a test program which can be used to confirm that the Java CGI package is functioning correctly.

Member Summary

        main()      //  Program main().

main()

Purpose

Provide a main() method.

Syntax

public static void main( String argv[] )

Description

This is the entry point for a CGI program which returns a list of the available name/value pairs and their current values. It will also send this list to the address specified in the Email variable.

Parameter

argv[]: Arguments passed to the program by the java.cgi script. Currently unused.

5.5 HTML

Class Syntax

public class HTML extends Text

Class Description

Messages are built up with the Text class add*() methods and the HTML-specific methods added by this class. When complete, the message is sent to its destination.

Currently, there is no error checking to confirm that the list-building methods are being used in a correct order, so the programmer must take pains not to violate HTML syntax.

This class is in the ``Orbits.net'' package.

Member Summary

        HTML()                  //  Constructor.
        author()                //  Set the name of the document author.
        definitionList()        //  Start a definition list.
        definitionListTerm()    //  Add a term to a definition list.
        endList()               //  End a list.
        listItem()              //  Add an entry to a list.
        send()                  //  Send the HTML message.
        title()                 //  Set the text for the document title.

HTML()

Purpose: Constructs an object which will contain an HTML message.
Syntax: public HTML()
Description: Sets up an empty message to be completed by the HTML methods.
See Also: Text.

author()

Purpose

Set the name of the document author.

Syntax

public void author ( String author )

Description

Set the name of the document author to author.

Parameter/

author: The text to use as the author of this message.

See Also

title().

definitionList()

Purpose: Start a definition list.
Syntax: public void definitionList ()
Description: Start a definition list. A definition list is a list specialized so that each entry in the list is a term followed by the definition text for that term. The start of a definition list should be followed by the creation of (at least) one term/text pair and a call to the endList() method. Note that, currently, lists cannot be nested.
See Also: definitionListTerm(), endList(), listItem().

definitionListTerm()

Purpose: Add a term to a definition list.
Syntax: public void definitionListTerm ()
Description: Add a term to a definition list. The text for the term part of the current list entry should be appended to the message after this method is called and before a corresponding listItem method is called.
See Also: definitionList(), listItem().

endList()

Purpose: End a list.
Syntax: public void endList ()
Description: End a list. This method closes out a list. Note that, currently, lists cannot be nested.
See Also: definitionList().

listItem()

Purpose

Add an entry to a list.

Syntax

public void listItem ()

public void listItem ( String item )

public boolean listItem ( String term, String item )

Description

Add an entry to a list. If the first form is used, the text for the current list item should be appended to the message after this method is called and before any other list methods are called. In the second and third forms, the item text is specified as a parameter to the method instead of (or in addition to) being appended to the message. The third form is specific to definition lists and provides both the term and the definition of the list entry.

Parameters

item: The text of this list entry.
term: The text of this definition list entry's term part.

See Also

definitionList(), definitionListTerm(), endList().

send()

Purpose: Send the HTML message.
Syntax: public void send ()
Description: Send the HTML message.

title()

Purpose

Set the text for the document title.

Syntax

public void title ( String title )

Description

Set the text for the document title.

Parameter

title: The text of this message's title.

See Also

author().

5.6 HTML_Test

This class provides both an example of how to use the HTML class and a test program which can be used to confirm that the Java CGI package is functioning correctly.

Member Summary

        main()      //  Program main().

main()

Purpose

Provide a main() method.

Syntax

public static void main( String argv[] )

Description

This is the entry point for a CGI program which returns a list of the available name/value pairs in an HTML document, with each name/value pair displayed in a definition list element.

Parameter

argv[]: Arguments passed to the program by the java.cgi script. Currently unused.

5.7 Text

Class Syntax

public abstract class Text

Class Description

This class is the superclass of the Email and HTML classes. Messages are built up with the methods in this class and completed and formatted with the methods in subclasses.

This class is in the ``Orbits.text'' package.

Member Summary

        Text()            //  Constructor.
        add()             //  Add text to this object.
        addLineBreak()    //  Add a line break.
        addParagraph()    //  Add a paragraph break.

add()

Purpose

Add text to this item.

Syntax

public void add ( char addition )

public void add ( String addition )

public void add ( StringBuffer addition )

Description

Add addition to the contents of this text item.

Parameter

addition: Text to be added to the text item.

See Also

addLineBreak(), addParagraph().

addLineBreak()

Purpose: Force a line break at this point in the text.
Syntax: public void addLineBreak ()
Description: Add a line break to the text at the current point.
See Also: add(), addParagraph().

addParagraph()

Purpose: Start a new paragaph.
Syntax: public void add ()
Description: Start a new paragraph at this point in the text flow.
See Also: add(), addLineBreak().

Next Previous Contents