old-www/HOWTO/Java-CGI-HOWTO-5.html

631 lines
16 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE>Java CGI HOWTO: Using the Java CGI Classes.</TITLE>
<LINK HREF="Java-CGI-HOWTO-6.html" REL=next>
<LINK HREF="Java-CGI-HOWTO-4.html" REL=previous>
<LINK HREF="Java-CGI-HOWTO.html#toc5" REL=contents>
</HEAD>
<BODY>
<A HREF="Java-CGI-HOWTO-6.html">Next</A>
<A HREF="Java-CGI-HOWTO-4.html">Previous</A>
<A HREF="Java-CGI-HOWTO.html#toc5">Contents</A>
<HR>
<H2><A NAME="s5">5. Using the Java CGI Classes.</A></H2>
<P>There are currently three main classes supported --
<A HREF="#cgi-class">CGI</A>,
<A HREF="#email-class">Email</A> and
<A HREF="#html-class">HTML</A>.
I am considering adding classes to deal with MIME-formatted input and
output -- MIMEin &amp; MIMEout, respectively.
<P>There are also a few support and test classes.
<A HREF="#cgi-test-class">CGI_Test</A>,
<A HREF="#email-test-class">Email_Test</A> and
<A HREF="#email-test-class">HTML_Test</A> 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
<A HREF="#text-class">Text</A> class is the superclass for both the
<CODE>Email</CODE> and the <CODE>HTML</CODE> classes.
<P>
<P>
<P>
<H2><A NAME="cgi-class"></A> <A NAME="ss5.1">5.1 CGI</A>
</H2>
<P>
<P>
<P>
<P>
<H3>Class Syntax</H3>
<P><CODE>public class CGI</CODE>
<P>
<P>
<P>
<H3>Class Description</H3>
<P>The CGI class holds the ``CGI Information'' -- Environment variables
set by the web server and the name/value sent from a
form when its <B>submit</B> action is selected.
All information is stored in a <CODE>Properties</CODE> class object.
<P>This class is in the ``Orbits.net'' package.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
CGI() // Constructor.
getNames() // Get the list of names.
getValue() // Get form value by specifying name.
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>CGI_Test</CODE>.
<P>
<P>
<P>
<H3>CGI()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Constructs an object which contains the available CGI data.
<DT><B>Syntax</B><DD><P><CODE>public CGI()</CODE>
<DT><B>Description</B><DD><P>When a CGI object is constructed, all available CGI
information is sucked-up into storage local to the new object.
</DL>
<P>
<P>
<P>
<H3>getNames()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>List the names which are defined to have corresponding values.
<DT><B>Syntax</B><DD><P><CODE>public Enumeration getKeys ()</CODE>
<DT><B>Description</B><DD><P>Provides the full list of names for which coresponding
values are defined.
<DT><B>Returns</B><DD><P>An <CODE>Enumeration</CODE> of all the names defined.
</DL>
<P>
<P>
<P>
<H3>getValue()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Retrieves the <B>value</B> associated with the <B>name</B>
specified.
<DT><B>Syntax</B><DD><P><CODE>public String getValue ( String name )</CODE>
<DT><B>Description</B><DD><P>This method provides the corespondence between the
<CODE>names</CODE> and <CODE>values</CODE> sent from an HTML form.
<DT><B>Parameter</B><DD><P>
<DL>
<DT><B>name</B><DD><P>The key by which values are selected.
</DL>
<DT><B>Returns</B><DD><P>A <CODE>String</CODE> containing the value.
</DL>
<P>
<P>
<P>
<H2><A NAME="cgi-test-class"></A> <A NAME="ss5.2">5.2 CGI_Test</A>
</H2>
<P>This class provides both an example of how to use the <CODE>CGI</CODE> class
and a test program which can be used to confirm that the <EM>Java CGI</EM>
package is functioning correctly.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
main() // Program main().
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>CGI</CODE>.
<P>
<P>
<P>
<H3>main()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Provide a <CODE>main()</CODE> method.
<DT><B>Syntax</B><DD><P><CODE>public static void main( String argv[] )</CODE>
<DT><B>Description</B><DD><P>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.
<DT><B>Parameter </B><DD><P>
<DL>
<DT><B>argv[]</B><DD><P>Arguments passed to the program by
the <CODE>java.cgi</CODE> script.
Currently unused.
</DL>
</DL>
<P>
<P>
<P>
<H2><A NAME="email-class"></A> <A NAME="ss5.3">5.3 Email</A>
</H2>
<P>
<P>
<P>
<P>
<H3>Class Syntax</H3>
<P><CODE>public class Email extends Text</CODE>
<P>
<P>
<P>
<H3>Class Description</H3>
<P>Messages are built up with the <CODE>Text</CODE> class <CODE>add*()</CODE> methods
and the e-mail-specific methods added by this class.
When complete, the message is sent to its destination.
<P>This class is in the ``Orbits.net'' package.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
Email() // Constructor.
send() // Send the e-mail message.
sendTo() // Add a destination for message.
subject() // Set the Subject: for message.
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>Email_Test, Text</CODE>.
<P>
<P>
<P>
<H3>Email()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Constructs an object which will contain an email message.
<DT><B>Syntax</B><DD><P><CODE>public Email()</CODE>
<DT><B>Description</B><DD><P>Sets up an empty message to be completed by the Email methods.
<DT><B>See Also</B><DD><P><CODE>Text</CODE>.
</DL>
<P>
<P>
<P>
<H3>send()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Send the e-mail message.
<DT><B>Syntax</B><DD><P><CODE>public void send ()</CODE>
<DT><B>Description</B><DD><P>This formats and sends the message.
If no destination address has been set, there is no action taken.
</DL>
<P>
<P>
<P>
<H3>sendTo()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Add a destination for this message.
<DT><B>Syntax</B><DD><P><CODE>public String sendTo ( String address )</CODE>
<DT><B>Description</B><DD><P>Add <CODE>address</CODE> 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 <EM>Mail Transport
Agent</EM> can accept or use up your memory.
<DT><B>Parameter/</B><DD><P>
<DL>
<DT><B>address</B><DD><P>A destination to send this message to.
</DL>
</DL>
<P>
<P>
<P>
<H3>subject()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Set the subject for this message.
<DT><B>Syntax</B><DD><P><CODE>public void subject ( String subject )</CODE>
<DT><B>Description</B><DD><P>This method sets the text for the e-mail's <CODE>Subject:</CODE>
line.
If called more than once, the latest subject set is the one that is used.
<DT><B>Parameter</B><DD><P>
<DL>
<DT><B>subject</B><DD><P>The text of this message's <CODE>Subject:</CODE> line.
</DL>
</DL>
<P>
<P>
<P>
<H2><A NAME="email-test-class"></A> <A NAME="ss5.4">5.4 Email_Test</A>
</H2>
<P>This class provides both an example of how to use the <CODE>Email</CODE> class
and a test program which can be used to confirm that the <EM>Java CGI</EM>
package is functioning correctly.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
main() // Program main().
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>Email</CODE>.
<P>
<P>
<P>
<H3>main()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Provide a <CODE>main()</CODE> method.
<DT><B>Syntax</B><DD><P><CODE>public static void main( String argv[] )</CODE>
<DT><B>Description</B><DD><P>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 <CODE>Email</CODE>
variable.
<DT><B>Parameter </B><DD><P>
<DL>
<DT><B>argv[]</B><DD><P>Arguments passed to the program by
the <CODE>java.cgi</CODE> script.
Currently unused.
</DL>
</DL>
<P>
<P>
<P>
<H2><A NAME="html-class"></A> <A NAME="ss5.5">5.5 HTML</A>
</H2>
<P>
<P>
<P>
<P>
<H3>Class Syntax</H3>
<P><CODE>public class HTML extends Text</CODE>
<P>
<P>
<P>
<H3>Class Description</H3>
<P>Messages are built up with the <CODE>Text</CODE> class <CODE>add*()</CODE> methods
and the HTML-specific methods added by this class.
When complete, the message is sent to its destination.
<P>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.
<P>This class is in the ``Orbits.net'' package.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
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.
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>HTML_Test, Text</CODE>.
<P>
<P>
<P>
<H3>HTML()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Constructs an object which will contain an HTML message.
<DT><B>Syntax</B><DD><P><CODE>public HTML()</CODE>
<DT><B>Description</B><DD><P>Sets up an empty message to be completed by the HTML methods.
<DT><B>See Also</B><DD><P><CODE>Text</CODE>.
</DL>
<P>
<P>
<P>
<H3>author()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Set the name of the document author.
<DT><B>Syntax</B><DD><P><CODE>public void author ( String author )</CODE>
<DT><B>Description</B><DD><P>Set the name of the document author to <CODE>author</CODE>.
<DT><B>Parameter/</B><DD><P>
<DL>
<DT><B>author</B><DD><P>The text to use as the author of this message.
</DL>
<DT><B>See Also</B><DD><P><CODE>title()</CODE>.
</DL>
<P>
<P>
<P>
<H3>definitionList()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Start a definition list.
<DT><B>Syntax</B><DD><P><CODE>public void definitionList ()</CODE>
<DT><B>Description</B><DD><P>Start a definition list.
A <EM>definition list</EM> is a list specialized so that each entry in
the list is a <EM>term</EM> followed by the definition <EM>text</EM>
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 <CODE>endList()</CODE> method.
<EM>Note that, currently, lists cannot be nested.</EM>
<DT><B>See Also</B><DD><P><CODE>definitionListTerm()</CODE>, <CODE>endList()</CODE>,
<CODE>listItem()</CODE>.
</DL>
<P>
<P>
<P>
<H3>definitionListTerm()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Add a term to a definition list.
<DT><B>Syntax</B><DD><P><CODE>public void definitionListTerm ()</CODE>
<DT><B>Description</B><DD><P>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
<CODE>listItem</CODE> method is called.
<DT><B>See Also</B><DD><P><CODE>definitionList()</CODE>, <CODE>listItem()</CODE>.
</DL>
<P>
<P>
<P>
<H3>endList()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>End a list.
<DT><B>Syntax</B><DD><P><CODE>public void endList ()</CODE>
<DT><B>Description</B><DD><P>End a list.
This method closes out a list.
<EM>Note that, currently, lists cannot be nested.</EM>
<DT><B>See Also</B><DD><P><CODE>definitionList()</CODE>.
</DL>
<P>
<P>
<P>
<H3>listItem()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Add an entry to a list.
<DT><B>Syntax</B><DD><P><CODE>public void listItem ()</CODE>
<DT><B></B><DD><P><CODE>public void listItem ( String item )</CODE>
<DT><B></B><DD><P><CODE>public boolean listItem ( String term, String item )</CODE>
<DT><B>Description</B><DD><P>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 <CODE>item</CODE> 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.
<DT><B>Parameters</B><DD><P>
<DL>
<DT><B>item</B><DD><P>The text of this list entry.
<DT><B>term</B><DD><P>The text of this definition list entry's term part.
</DL>
<DT><B>See Also</B><DD><P><CODE>definitionList()</CODE>, <CODE>definitionListTerm()</CODE>,
<CODE>endList()</CODE>.
</DL>
<P>
<P>
<P>
<H3>send()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Send the HTML message.
<DT><B>Syntax</B><DD><P><CODE>public void send ()</CODE>
<DT><B>Description</B><DD><P>Send the HTML message.
</DL>
<P>
<P>
<P>
<H3>title()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Set the text for the document title.
<DT><B>Syntax</B><DD><P><CODE>public void title ( String title )</CODE>
<DT><B>Description</B><DD><P>Set the text for the document title.
<DT><B>Parameter</B><DD><P>
<DL>
<DT><B>title</B><DD><P>The text of this message's title.
</DL>
<DT><B>See Also</B><DD><P><CODE>author()</CODE>.
</DL>
<P>
<P>
<P>
<H2><A NAME="html-test-class"></A> <A NAME="ss5.6">5.6 HTML_Test</A>
</H2>
<P>This class provides both an example of how to use the <CODE>HTML</CODE> class
and a test program which can be used to confirm that the <EM>Java CGI</EM>
package is functioning correctly.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
main() // Program main().
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>HTML</CODE>.
<P>
<P>
<P>
<H3>main()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Provide a <CODE>main()</CODE> method.
<DT><B>Syntax</B><DD><P><CODE>public static void main( String argv[] )</CODE>
<DT><B>Description</B><DD><P>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.
<DT><B>Parameter </B><DD><P>
<DL>
<DT><B>argv[]</B><DD><P>Arguments passed to the program by
the <CODE>java.cgi</CODE> script.
Currently unused.
</DL>
</DL>
<P>
<P>
<P>
<H2><A NAME="text-class"></A> <A NAME="ss5.7">5.7 Text</A>
</H2>
<P>
<P>
<P>
<P>
<H3>Class Syntax</H3>
<P><CODE>public abstract class Text</CODE>
<P>
<P>
<P>
<H3>Class Description</H3>
<P>This class is the superclass of the <CODE>Email</CODE> and <CODE>HTML</CODE>
classes.
Messages are built up with the methods in this class and completed and
formatted with the methods in subclasses.
<P>This class is in the ``Orbits.text'' package.
<P>
<P>
<P>
<H3>Member Summary</H3>
<P>
<HR>
<PRE>
Text() // Constructor.
add() // Add text to this object.
addLineBreak() // Add a line break.
addParagraph() // Add a paragraph break.
</PRE>
<HR>
<P>
<P>
<P>
<H3>See Also</H3>
<P><CODE>Email</CODE>, <CODE>HTML</CODE>.
<P>
<P>
<P>
<H3>add()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Add text to this item.
<DT><B>Syntax</B><DD><P><CODE>public void add ( char addition )</CODE>
<DT><B></B><DD><P><CODE>public void add ( String addition )</CODE>
<DT><B></B><DD><P><CODE>public void add ( StringBuffer addition )</CODE>
<DT><B>Description</B><DD><P>Add <CODE>addition</CODE> to the contents of this text item.
<DT><B>Parameter</B><DD><P>
<DL>
<DT><B>addition</B><DD><P>Text to be added to the text item.
</DL>
<DT><B>See Also</B><DD><P><CODE>addLineBreak()</CODE>, <CODE>addParagraph()</CODE>.
</DL>
<P>
<P>
<P>
<H3>addLineBreak()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Force a line break at this point in the text.
<DT><B>Syntax</B><DD><P><CODE>public void addLineBreak ()</CODE>
<DT><B>Description</B><DD><P>Add a line break to the text at the current point.
<DT><B>See Also</B><DD><P><CODE>add()</CODE>, <CODE>addParagraph()</CODE>.
</DL>
<P>
<P>
<P>
<H3>addParagraph()</H3>
<P>
<DL>
<DT><B>Purpose</B><DD><P>Start a new paragaph.
<DT><B>Syntax</B><DD><P><CODE>public void add ()</CODE>
<DT><B>Description</B><DD><P>Start a new paragraph at this point in the text flow.
<DT><B>See Also</B><DD><P><CODE>add()</CODE>, <CODE>addLineBreak()</CODE>.
</DL>
<P>
<P>
<P>
<HR>
<A HREF="Java-CGI-HOWTO-6.html">Next</A>
<A HREF="Java-CGI-HOWTO-4.html">Previous</A>
<A HREF="Java-CGI-HOWTO.html#toc5">Contents</A>
</BODY>
</HTML>