mirror of https://github.com/tLDP/LDP
995 lines
26 KiB
Plaintext
995 lines
26 KiB
Plaintext
<!doctype linuxdoc system>
|
|
|
|
<article>
|
|
|
|
<title>Java CGI HOWTO
|
|
<author>by David H. Silber
|
|
<tt><htmlurl url="mailto:javacgi-document@orbits.com"
|
|
name="javacgi-document@orbits.com"></tt>
|
|
<date>v0.5, 1 December 1998
|
|
<abstract>
|
|
This HOWTO document explains how to set up your server to allow CGI programs
|
|
written in Java and how to use Java to write CGI programs.
|
|
|
|
Although HOWTO documents are targetted towards use with the Linux operating
|
|
system, this particular one is not dependant on the particular version of
|
|
unix used.
|
|
</abstract>
|
|
|
|
<toc>
|
|
|
|
|
|
|
|
<sect>Introduction
|
|
<p>
|
|
Because of the way that Java is designed the programmer does not have
|
|
easy access to the system's environment variables.
|
|
Because of the way that the Java Development Kit (JDK) is set up,
|
|
it is necessary to use multiple tokens to invoke a program,
|
|
which does not mesh very well with the standard HTML forms/CGI
|
|
manner of operations.
|
|
There are ways around these limitations, and I have implemented one of
|
|
them.
|
|
Read further for details.
|
|
|
|
Since I wrote the previous paragraph in 1996, there have been many
|
|
changes in the Java technology.
|
|
It is likely that a better solution to running server-side Java programs
|
|
is now available -- perhaps you should take a look at servlets.
|
|
|
|
|
|
|
|
<sect1>Prior Knowledge
|
|
<p>
|
|
I am assuming that you have a general knowledge of HTML and CGI concepts
|
|
and at least a minimal knowledge of your HTTP server.
|
|
You should also know how to program in Java, or a lot of this will not make
|
|
sense.
|
|
|
|
|
|
|
|
<sect1>This Document
|
|
<p>
|
|
The latest version of this document can be read at
|
|
<htmlurl url="http://www.orbits.com/software/Java_CGI.html"
|
|
name="http://www.orbits.com/software/Java_CGI.html">.
|
|
|
|
|
|
|
|
<sect1>The Package
|
|
<p>
|
|
The latest version of the package described here can be accessed via
|
|
anonymous FTP at
|
|
<htmlurl url="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz"
|
|
name="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz">.
|
|
The package distribution includes SGML source for this document.
|
|
|
|
The package is distributed under the terms of the GNU Library General
|
|
Public License. This document can be distributed under the terms of the
|
|
Linux HOWTO copyright notice.
|
|
|
|
If you use this software, please make some reference to
|
|
<htmlurl url="http://www.orbits.com/software/Java_CGI.html"
|
|
name="http://www.orbits.com/software/Java_CGI.html">, so that others
|
|
will be able to find the Java CGI classes.
|
|
|
|
I have run out of time to maintain and support this package, so this
|
|
will probably be its final release.
|
|
If anyone out there is sufficiently enamoured of this software that
|
|
they wish to take over the maintenace of it, please contact me at
|
|
<tt><htmlurl url="mailto:javacgi-document@orbits.com"
|
|
name="javacgi-document@orbits.com"></tt>.
|
|
|
|
|
|
|
|
<sect1>The Mailing List
|
|
<label id="mailing-list">
|
|
<p>
|
|
I have created a majordomo list to allow people to help each-other work
|
|
through their mutual problems in installing and using this software.
|
|
Send a message to
|
|
<tt><htmlurl url="mailto:javacgi-request@orbits.com"
|
|
name="javacgi-request@orbits.com"></tt>,
|
|
containing the word <em>subscribe</em>.
|
|
|
|
|
|
|
|
<sect>Setting Up Your Server to Run Java CGI Programs (With Explanations)
|
|
<label id="install-long">
|
|
<p>
|
|
This section will lead you through installing my <em>Java CGI</em> package
|
|
with copious explanations so that you know what the effects of your
|
|
actions will be.
|
|
If you just want to install the programs and don't care about the
|
|
whys & wherefores, skip to <ref id="install-short"
|
|
name="Setting Up Your Server to Run Java CGI Programs (The Short Form)">.
|
|
|
|
|
|
|
|
<sect1>System Requirements
|
|
<p>
|
|
This software should work on any unix-like web server that has the Java
|
|
Development Kit installed.
|
|
I am using it on a <em>Debian Linux</em> system running
|
|
<em>apache</em> as the HTTP daemon.
|
|
If you find that it does not run on your server, please contact the
|
|
mailing list.
|
|
See <ref id="mailing-list" name="The Mailing List"> for details.
|
|
|
|
Unfortunatly, the Java run-time interpreter seems to be something of a
|
|
memory hog -- you may want to throw another few megabytes of RAM onto
|
|
your server if you will be using Java CGI programs a lot.
|
|
|
|
|
|
|
|
<sect1>Java CGI Add-On Software
|
|
<p>
|
|
The software that I wrote to aid in this is called <em>Java CGI</em>.
|
|
You can get it from
|
|
<htmlurl url="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz"
|
|
name="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz">.
|
|
(The version number may have changed.)
|
|
|
|
|
|
|
|
<sect1>Unpacking the Source
|
|
<p>
|
|
Find a convenient directory to unpack this package into.
|
|
(If you don't already have a standard place to put packages,
|
|
I suggest that you use <tt>/usr/local/src</tt>.)
|
|
Unpack the distribution with this command:
|
|
<verb>
|
|
gzip -dc java_cgi-0.5.tgz | tar -xvf -
|
|
</verb>
|
|
This will create a directory called <tt>java_cgi-0.5</tt>.
|
|
In there you will find the files referenced in the rest of this document.
|
|
(If the version number has changed, use the instructions from within
|
|
that distribution from this point on.)
|
|
|
|
|
|
|
|
<sect1>Decide On Your Local Path Policies
|
|
<label id="make-programs">
|
|
<p>
|
|
You need to decide where you want your Java CGI
|
|
programs to live. Generally, you will want to put them in a directory in
|
|
parallel with your <tt>cgi-bin</tt> directory. My <em>apache</em>
|
|
server came configured to use <tt>/var/www/cgi-bin</tt> as the
|
|
<tt>cgi-bin</tt> directory, so I use <tt>/var/www/javacgi</tt> as the
|
|
directory to put Java CGI programs in. You probably do not want to
|
|
put your Java CGI programs into one of the existing
|
|
<tt>CLASSPATH</tt> directories.
|
|
Edit the Makefile to reflect your system configuration.
|
|
Make sure that you are logged in as the root user and run <tt>make install</tt>.
|
|
This will compile the Java programs, modify the <tt>java.cgi</tt> script
|
|
to fit in with your system and install the programs in the appropriate
|
|
places.
|
|
If you want the HTML version of this documentation and an HTML test document
|
|
in addition, run <tt>make all</tt> instead.
|
|
|
|
|
|
|
|
<sect1>Testing your installation.
|
|
<label id="install-test">
|
|
<p>
|
|
Installed from the distribution are HTML documents called
|
|
<tt>javacgitest.html</tt>, <tt>javaemailtest.html</tt> and
|
|
<tt>javahtmltest.html</tt>.
|
|
If you installed <tt>all</tt> in the previous section, it will be in the
|
|
directory you specified for WEBDIR in the <tt>Makefile</tt>.
|
|
If you didn't, you can run <tt>make test</tt> to build them from
|
|
<tt>javacgitest.html-dist</tt>, <tt>javaemailtest.html-dist</tt> and
|
|
<tt>javahtmltest.html-dist</tt>.
|
|
|
|
When you are sure that your installation is working correctly, you may
|
|
wish to remove <tt>CGI_Test.class</tt>, <tt>Email_Test.class</tt> and
|
|
<tt>HTML_Test.class</tt> from
|
|
your JAVACGI directory and <tt>javacgitest.html</tt>,
|
|
<tt>javaemailtest.html</tt> and <tt>javahtmltest.html</tt>
|
|
from your WEBDIR directory as they show the
|
|
user information that is normally only available to the server.
|
|
|
|
|
|
|
|
<sect>Setting Up Your Server to Run Java CGI Programs (The Short Form)
|
|
<label id="install-short">
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
Get the <em>Java CGI</em> package from
|
|
<htmlurl url="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz"
|
|
name="ftp://ftp.orbits.com/pub/software/java_cgi-0.5.tgz">.
|
|
(The version number may have changed.)
|
|
</item>
|
|
<item>
|
|
Unpack the distribution with this command:
|
|
<verb>
|
|
gzip -dc java_cgi-0.5.tgz | tar -xvf -
|
|
</verb>
|
|
(If the version number has changed, use the instructions from within
|
|
that distribution from this point on.)
|
|
</item>
|
|
<item>
|
|
Edit the <tt>Makefile</tt> you will find in the newly created directory
|
|
<tt>java_cgi-0.5</tt> as appropriate to your system.
|
|
</item>
|
|
<item>
|
|
As root, run <tt>make install</tt>.
|
|
This will compile the Java programs, apply your system-specific information
|
|
and install the various files.
|
|
If you want the HTML version of this documentation and an HTML test document,
|
|
run <tt>make all</tt> instead.
|
|
</item>
|
|
<item>
|
|
You should be ready to go.
|
|
</item>
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect>Executing a Java CGI Program
|
|
<p>
|
|
|
|
|
|
|
|
<sect1>Obstacles to Running Java Programs Under the CGI Model
|
|
<p>
|
|
There are two main problems in running a Java program from a web server:
|
|
|
|
|
|
|
|
<sect2>You can't run Java programs like ordinary executables.
|
|
<p>
|
|
You need to run the Java run-time interpreter and provide the initial
|
|
class (program to run) on the command-line.
|
|
With an HTML form, there is no provision for sending a command-line
|
|
to the web server.
|
|
|
|
|
|
|
|
<sect2>Java does not have general access to the environment.
|
|
<p>
|
|
Every environment variable that will be needed by the Java program
|
|
must be explicitly passed in.
|
|
There is no method similar to the <bf>C</bf> <tt>getenv()</tt> function.
|
|
|
|
|
|
|
|
<sect1>Overcoming Problems in Running Java CGI Programs
|
|
<p>
|
|
To deal with these obstacles, I wrote a shell CGI program that provides
|
|
the information needed by the Java interpreter.
|
|
|
|
|
|
|
|
<sect2>The java.cgi script.
|
|
<p>
|
|
This shell script manages the interaction between the HTTP daemon and the
|
|
Java CGI program that you wish to use.
|
|
It extracts the name of the program that you want to run from the
|
|
server-provided data.
|
|
It collects all of the environment data into a temporary file.
|
|
Then, it runs the Java run-time interpreter with the name of the file of
|
|
environment information and the program name added to the command-line.
|
|
|
|
The <tt>java.cgi</tt> script was configured and installed in
|
|
<ref id="make-programs" name="Decide On Your Local Path Policies">.
|
|
|
|
|
|
|
|
<sect2>Invoking java.cgi from an HTML form.
|
|
<p>
|
|
My forms that use Java CGI programs specify a form action as follows:
|
|
<verb>
|
|
<form action="/cgi-bin/java.cgi/CGI_Test" method="POST">
|
|
</verb>
|
|
Where <tt>/cgi-bin/</tt> is your local CGI binary directory,
|
|
<tt>java.cgi</tt> is the Java front-end that allows us to run Java programs
|
|
over the web
|
|
and <tt>CGI_Test</tt> is an example of the name of the Java program to run.
|
|
|
|
|
|
|
|
<sect>Using the Java CGI Classes.
|
|
<p>
|
|
There are currently three main classes supported --
|
|
<ref id="cgi-class" name=CGI>,
|
|
<ref id="email-class" name=Email> and
|
|
<ref id="html-class" name=HTML>.
|
|
I am considering adding classes to deal with MIME-formatted input and
|
|
output -- MIMEin & MIMEout, respectively.
|
|
<p>
|
|
There are also a few support and test classes.
|
|
<ref id="cgi-test-class" name="CGI_Test">,
|
|
<ref id="email-test-class" name="Email_Test"> and
|
|
<ref id="email-test-class" name="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 <ref id="text-class" name=Text> class is the superclass for both the
|
|
<tt>Email</tt> and the <tt>HTML</tt> classes.
|
|
|
|
|
|
|
|
<sect1>CGI<label id="cgi-class">
|
|
<p>
|
|
|
|
|
|
|
|
<sect2>Class Syntax
|
|
<p>
|
|
<tt>public class CGI</tt>
|
|
|
|
|
|
|
|
<sect2>Class Description
|
|
<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 <bf>submit</bf> action is selected.
|
|
All information is stored in a <tt>Properties</tt> class object.
|
|
|
|
This class is in the ``Orbits.net'' package.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
CGI() // Constructor.
|
|
getNames() // Get the list of names.
|
|
getValue() // Get form value by specifying name.
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>CGI_Test</tt>.
|
|
|
|
|
|
|
|
<sect2>CGI()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Constructs an object which contains the available CGI data.
|
|
<tag/Syntax/ <tt>public CGI()</tt>
|
|
<tag/Description/ When a CGI object is constructed, all available CGI
|
|
information is sucked-up into storage local to the new object.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>getNames()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ List the names which are defined to have corresponding values.
|
|
<tag/Syntax/ <tt>public Enumeration getKeys ()</tt>
|
|
<tag/Description/ Provides the full list of names for which coresponding
|
|
values are defined.
|
|
<tag/Returns/ An <tt>Enumeration</tt> of all the names defined.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>getValue()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Retrieves the <bf>value</bf> associated with the <bf>name</bf>
|
|
specified.
|
|
<tag/Syntax/ <tt>public String getValue ( String name )</tt>
|
|
<tag/Description/ This method provides the corespondence between the
|
|
<tt>names</tt> and <tt>values</tt> sent from an HTML form.
|
|
<tag>Parameter
|
|
<descrip>
|
|
<tag/name/ The key by which values are selected.
|
|
</descrip>
|
|
<tag/Returns/ A <tt>String</tt> containing the value.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>CGI_Test<label id="cgi-test-class">
|
|
<p>
|
|
This class provides both an example of how to use the <tt>CGI</tt> class
|
|
and a test program which can be used to confirm that the <em>Java CGI</em>
|
|
package is functioning correctly.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
main() // Program main().
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>CGI</tt>.
|
|
|
|
|
|
|
|
<sect2>main()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Provide a <tt>main()</tt> method.
|
|
<tag/Syntax/ <tt>public static void main( String argv[] )</tt>
|
|
<tag/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.
|
|
<tag>Parameter
|
|
<descrip>
|
|
<tag/argv[]/ Arguments passed to the program by
|
|
the <tt>java.cgi</tt> script.
|
|
Currently unused.
|
|
</descrip>
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>Email<label id="email-class">
|
|
<p>
|
|
|
|
|
|
|
|
<sect2>Class Syntax
|
|
<p>
|
|
<tt>public class Email extends Text</tt>
|
|
|
|
|
|
|
|
<sect2>Class Description
|
|
<p>
|
|
Messages are built up with the <tt>Text</tt> class <tt>add*()</tt> 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.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
Email() // Constructor.
|
|
send() // Send the e-mail message.
|
|
sendTo() // Add a destination for message.
|
|
subject() // Set the Subject: for message.
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>Email_Test, Text</tt>.
|
|
|
|
|
|
|
|
<sect2>Email()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Constructs an object which will contain an email message.
|
|
<tag/Syntax/ <tt>public Email()</tt>
|
|
<tag/Description/ Sets up an empty message to be completed by the Email methods.
|
|
<tag/See Also/ <tt>Text</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>send()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Send the e-mail message.
|
|
<tag/Syntax/ <tt>public void send ()</tt>
|
|
<tag/Description/ This formats and sends the message.
|
|
If no destination address has been set, there is no action taken.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>sendTo()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Add a destination for this message.
|
|
<tag/Syntax/ <tt>public String sendTo ( String address )</tt>
|
|
<tag/Description/ Add <tt>address</tt> 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.
|
|
<tag>Parameter/
|
|
<descrip>
|
|
<tag/address/ A destination to send this message to.
|
|
</descrip>
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>subject()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Set the subject for this message.
|
|
<tag/Syntax/ <tt>public void subject ( String subject )</tt>
|
|
<tag/Description/ This method sets the text for the e-mail's <tt>Subject:</tt>
|
|
line.
|
|
If called more than once, the latest subject set is the one that is used.
|
|
<tag/Parameter/
|
|
<descrip>
|
|
<tag/subject/ The text of this message's <tt>Subject:</tt> line.
|
|
</descrip>
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>Email_Test<label id="email-test-class">
|
|
<p>
|
|
This class provides both an example of how to use the <tt>Email</tt> class
|
|
and a test program which can be used to confirm that the <em>Java CGI</em>
|
|
package is functioning correctly.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
main() // Program main().
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>Email</tt>.
|
|
|
|
|
|
|
|
<sect2>main()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Provide a <tt>main()</tt> method.
|
|
<tag/Syntax/ <tt>public static void main( String argv[] )</tt>
|
|
<tag/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 <tt>Email</tt>
|
|
variable.
|
|
<tag>Parameter
|
|
<descrip>
|
|
<tag/argv[]/ Arguments passed to the program by
|
|
the <tt>java.cgi</tt> script.
|
|
Currently unused.
|
|
</descrip>
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>HTML<label id="html-class">
|
|
<p>
|
|
|
|
|
|
|
|
<sect2>Class Syntax
|
|
<p>
|
|
<tt>public class HTML extends Text</tt>
|
|
|
|
|
|
|
|
<sect2>Class Description
|
|
<p>
|
|
Messages are built up with the <tt>Text</tt> class <tt>add*()</tt> 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.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
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.
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>HTML_Test, Text</tt>.
|
|
|
|
|
|
|
|
<sect2>HTML()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Constructs an object which will contain an HTML message.
|
|
<tag/Syntax/ <tt>public HTML()</tt>
|
|
<tag/Description/ Sets up an empty message to be completed by the HTML methods.
|
|
<tag/See Also/ <tt>Text</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>author()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Set the name of the document author.
|
|
<tag/Syntax/ <tt>public void author ( String author )</tt>
|
|
<tag/Description/ Set the name of the document author to <tt>author</tt>.
|
|
<tag>Parameter/
|
|
<descrip>
|
|
<tag/author/ The text to use as the author of this message.
|
|
</descrip>
|
|
<tag/See Also/ <tt>title()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>definitionList()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Start a definition list.
|
|
<tag/Syntax/ <tt>public void definitionList ()</tt>
|
|
<tag/Description/ 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 <tt>endList()</tt> method.
|
|
<em>Note that, currently, lists cannot be nested.</em>
|
|
<tag/See Also/ <tt>definitionListTerm()</tt>, <tt>endList()</tt>,
|
|
<tt>listItem()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>definitionListTerm()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Add a term to a definition list.
|
|
<tag/Syntax/ <tt>public void definitionListTerm ()</tt>
|
|
<tag/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
|
|
<tt>listItem</tt> method is called.
|
|
<tag/See Also/ <tt>definitionList()</tt>, <tt>listItem()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>endList()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ End a list.
|
|
<tag/Syntax/ <tt>public void endList ()</tt>
|
|
<tag/Description/ End a list.
|
|
This method closes out a list.
|
|
<em>Note that, currently, lists cannot be nested.</em>
|
|
<tag/See Also/ <tt>definitionList()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>listItem()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Add an entry to a list.
|
|
<tag/Syntax/ <tt>public void listItem ()</tt>
|
|
<tag// <tt>public void listItem ( String item )</tt>
|
|
<tag// <tt>public boolean listItem ( String term, String item )</tt>
|
|
<tag/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 <tt>item</tt> 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.
|
|
<tag/Parameters/
|
|
<descrip>
|
|
<tag/item/ The text of this list entry.
|
|
<tag/term/ The text of this definition list entry's term part.
|
|
</descrip>
|
|
<tag/See Also/ <tt>definitionList()</tt>, <tt>definitionListTerm()</tt>,
|
|
<tt>endList()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>send()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Send the HTML message.
|
|
<tag/Syntax/ <tt>public void send ()</tt>
|
|
<tag/Description/ Send the HTML message.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>title()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Set the text for the document title.
|
|
<tag/Syntax/ <tt>public void title ( String title )</tt>
|
|
<tag/Description/ Set the text for the document title.
|
|
<tag/Parameter/
|
|
<descrip>
|
|
<tag/title/ The text of this message's title.
|
|
</descrip>
|
|
<tag/See Also/ <tt>author()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>HTML_Test<label id="html-test-class">
|
|
<p>
|
|
This class provides both an example of how to use the <tt>HTML</tt> class
|
|
and a test program which can be used to confirm that the <em>Java CGI</em>
|
|
package is functioning correctly.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
main() // Program main().
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>HTML</tt>.
|
|
|
|
|
|
|
|
<sect2>main()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Provide a <tt>main()</tt> method.
|
|
<tag/Syntax/ <tt>public static void main( String argv[] )</tt>
|
|
<tag/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.
|
|
<tag>Parameter
|
|
<descrip>
|
|
<tag/argv[]/ Arguments passed to the program by
|
|
the <tt>java.cgi</tt> script.
|
|
Currently unused.
|
|
</descrip>
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect1>Text<label id="text-class">
|
|
<p>
|
|
|
|
|
|
|
|
<sect2>Class Syntax
|
|
<p>
|
|
<tt>public abstract class Text</tt>
|
|
|
|
|
|
|
|
<sect2>Class Description
|
|
<p>
|
|
This class is the superclass of the <tt>Email</tt> and <tt>HTML</tt>
|
|
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.
|
|
|
|
|
|
|
|
<sect2>Member Summary
|
|
<p>
|
|
<code>
|
|
Text() // Constructor.
|
|
add() // Add text to this object.
|
|
addLineBreak() // Add a line break.
|
|
addParagraph() // Add a paragraph break.
|
|
</code>
|
|
|
|
|
|
|
|
<sect2>See Also
|
|
<p>
|
|
<tt>Email</tt>, <tt>HTML</tt>.
|
|
|
|
|
|
|
|
<sect2>add()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Add text to this item.
|
|
<tag/Syntax/ <tt>public void add ( char addition )</tt>
|
|
<tag// <tt>public void add ( String addition )</tt>
|
|
<tag// <tt>public void add ( StringBuffer addition )</tt>
|
|
<tag/Description/ Add <tt>addition</tt> to the contents of this text item.
|
|
<tag/Parameter/
|
|
<descrip>
|
|
<tag/addition/ Text to be added to the text item.
|
|
</descrip>
|
|
<tag/See Also/ <tt>addLineBreak()</tt>, <tt>addParagraph()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>addLineBreak()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Force a line break at this point in the text.
|
|
<tag/Syntax/ <tt>public void addLineBreak ()</tt>
|
|
<tag/Description/ Add a line break to the text at the current point.
|
|
<tag/See Also/ <tt>add()</tt>, <tt>addParagraph()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect2>addParagraph()
|
|
<p>
|
|
<descrip>
|
|
<tag/Purpose/ Start a new paragaph.
|
|
<tag/Syntax/ <tt>public void add ()</tt>
|
|
<tag/Description/ Start a new paragraph at this point in the text flow.
|
|
<tag/See Also/ <tt>add()</tt>, <tt>addLineBreak()</tt>.
|
|
</descrip>
|
|
|
|
|
|
|
|
<sect>Future Plans
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
Add to the Email class:
|
|
<descrip>
|
|
<tag/Email( int capacity )/ Used when we know how much space the message
|
|
will need to have allocated.
|
|
<tag/sendTo( String [] address )/ Add a list of primary destinations to
|
|
the e-mail message.
|
|
<tag/sendCc( String address )/ Add a Carbon-Copy destination to the
|
|
e-mail message.
|
|
<tag/sendCc( String [] address )/ Add a list of Carbon-Copy
|
|
destinations to the e-mail message.
|
|
<tag/sendBcc( String address )/ Add a Blind Carbon-Copy destination to
|
|
the e-mail message.
|
|
<tag/sendBcc( String [] address )/ Add a list of Blind Carbon-Copy
|
|
destinations to the e-mail message.
|
|
</descrip>
|
|
</item>
|
|
<item>
|
|
Add to the HTML class:
|
|
<descrip>
|
|
<tag/HTML( int capacity )/ Used when we know how much space the message
|
|
will need to have allocated.
|
|
<tag/public void unorderedList()/ Start an unordered list.
|
|
<tag/public void orderedList()/ Start an ordered list.
|
|
<tag/public void directoryList()/ Start a directory list.
|
|
<tag/public void menuList()/ Start a menu list.
|
|
<tag/void anchor( String anchorName )/ Specify an anchor.
|
|
<tag/void link( String url, String text )/ Specify a link.
|
|
<tag/void applet( String url, String altText )/ Specify an applet link.
|
|
</descrip>
|
|
</item>
|
|
<item>
|
|
Allow HTML lists to be nested.
|
|
</item>
|
|
<item>
|
|
Add error checking code to enforce correct ordering of HTML list
|
|
formatting codes.
|
|
</item>
|
|
<item>
|
|
The location of the file of environment data should be configurable
|
|
from the <tt>Makefile</tt>.
|
|
</item>
|
|
<item>
|
|
Get rid of the spurious empty name/value pair that appears in the list when we
|
|
are dealing with the GET method of data transfer.
|
|
</item>
|
|
<item>
|
|
Consider having CGI implement the java.util.Enumeration interface to
|
|
successively provide variable names.
|
|
</item>
|
|
<item>
|
|
Add a <tt>Test</tt> class, which would use every method in this package.
|
|
</item>
|
|
<item>
|
|
Document how <tt>CGI_Test</tt>, <tt>Email_Test</tt> and
|
|
<tt>HTML_Test</tt> build on each other to provide incremental tests for
|
|
debugging purposes.
|
|
</item>
|
|
<item>
|
|
Document how Test uses every feature available in this package.
|
|
</item>
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect>Changes
|
|
<p>
|
|
|
|
|
|
|
|
<sect1>Changes from 0.4 to 0.5
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
Changed documentation and comments to reflect the final nature of this
|
|
release.
|
|
</item>
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect1>Changes from 0.3 to 0.4
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
Fleshed out the HTML class to provide minimal functionality.
|
|
</item>
|
|
<item>
|
|
Wrote the HTML_Test class and javahtmltest.html-dist.
|
|
</item>
|
|
<item>
|
|
Added the HTML methods to deal with a definition list.
|
|
</item>
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect1>Changes from 0.2 to 0.3
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
Added the Text and Email classes.
|
|
HTML was also added, but it is merely a stub at this point.
|
|
</item>
|
|
<item>
|
|
Put the various classes into packages.
|
|
The main classes are in <tt>Orbits.net.*</tt>, the support class
|
|
<tt>Text</tt> is in <tt>Orbits.text.Text</tt>.
|
|
</item>
|
|
<item>
|
|
Changed <tt>CGItest</tt> to <tt>CGI_Test</tt>.
|
|
</item>
|
|
<item>
|
|
Added the <tt>Email_Test</tt> class.
|
|
</item>
|
|
</itemize>
|
|
|
|
|
|
|
|
<sect1>Changes from 0.1 to 0.2
|
|
<p>
|
|
<itemize>
|
|
<item>
|
|
The environment variables are put into a temportary file instead of being
|
|
crammed into the Java inperpreter command-line.
|
|
The <tt>CGI</tt> class and <tt>java.cgi</tt> had to be modified.
|
|
</item>
|
|
<item>
|
|
The <tt>javacgitest.html</tt> document is made part of the distribution.
|
|
</item>
|
|
<item>
|
|
The text files which are modified by <tt>make</tt> upon installation are
|
|
provided with names that end with <em>-dist</em>.
|
|
</item>
|
|
</itemize>
|
|
|
|
</article>
|