README file for the tmcm-java-web-site archive              June 2004
----------------------------------------------

The tmcm-java directory in this archive contains Web pages and
applets that are also available on line at:   

            http://math.hws.edu/eck/TMCM/java/

The Web pages include some lab worksheets that were written to
be used with my introductory computer science textbook, The Most
Complex Machine.  They can also be used on their own.  There are
also some information/tutorial pages for each applet.  The
main Web page is index.html, and it includes links to all the
other pages.

If you would like to use any of the material in this archive
for commercial purposes, please contact me for permission.
Contact information is given below.

The applets and information/tutorial pages about them
can be freely used for any non-commercial purpose.

The lab worksheets can be used for any private, non-commercial
purpose, but I ask that they not be used as an official part of
a course unless my textbook is adopted for that course.  (However,
I will consider making exceptions to this.)  Note that this 
restriction applies only to the lab Web pages, not to the
applets.

You are welcome to post the entire, unmodified contents of
this Web site archive on your own Web server.

You are also welcome to create non-commercial Web pages that
use the applets.  If you do this, you might want to create
your own sample input files for the applets.  To do that, you
will probably want to download the stand-alone application
versions of the applets, since the applets can only save
files when they are run as standalone applications.  To
run the applets as stand-alone applications, you need the
"jar files" that are available in the "classes" directory
in this archive.  They can also be downloaded using links
from the web page at

      http://math.hws.edu/TMCM/java/DownloadingAndInfo.html
      
Note that you also need to use the jar files to add the
applets to your own Web pages.
     


USING THE APPLETS ON YOUR OWN WEB PAGES:
---------------------------------------

To use one of the applets on a Web page, that page must have
access to the compiled Java program for that applet.  You can
find these programs in the directory named "classes" in
this archive.  The classes are in ".jar" files.  There is
one jar file for each applet:  DataReps.jar, xComputer.jar,
xLogicCircuits.jar, and so on.  To use one of the applets
on a Web page, you can copy the corresponding jar file into
the same directory as the HTML source file for your Web page.
The HTML source file will have an <applet> tag to load the
applet.  This applet tag must refer to the jar file and to
the applet class.  For example, the applet class for the
xLogicCircuits applet is "tmcm.xLogicCircuitsApplet.class".
An <applet> tag for using this applet has the form:

    <p align=center>
    <applet archive="xLogicCircuits.jar" 
            code="tmcm.xLogicCircuitsApplet.class"
            height=420 width=550>
    </applet>
    </p>

The classes for the other applets are named similarly:
tmcm.DataRepsApplet.class, tmcm.xComputerApplet.class, and
so on.  In addition to these applets, which appear right on
the web page, there are "launcher" versions of the applets.
In the launcher version, only a button appears on the Web
page.  When the user clicks the button, the applet is opened
in a separate window.  The names for the launcher versions
are tmcm.DataRepsLauncher.class, tmcm.xLogicCircuitsLauncher.class
and so on.  For example, to use the launcher version of
xLogicCircuits, you could use the <applet> tag

    <p align=center>
    <applet archive="xLogicCircuits.jar"
            code="tmcm/xLogicCircuitsLauncher.class"
            width=180 height=30>
    </applet>
    </p>

Some of the applets can load sample input files.  Such files
can be created using the "Save" button of one of the applets.
However, this button will generally not be functional when you
are running the applet in a Web browser.  If you want to use
the "Save" button, you must run the corresponding jar file
as a stand-alone application, as discussed below.

To be used by an applet, a sample input file should be in the
same directory as the HTML source file for the Web page that
contains the applet.  The names of the sample input files must
be specified as "params" in the <applet> tag.  For example, the
xLogicCircuits applet can read one sample file.  The file
is specified in a param named "LOAD".  For example, if
you want xLogicCircuits to load a sample file named
"SampleCircuits.txt", use the applet tag:

    <p align=center>
    <applet archive="xLogicCircuits.jar" 
            code="tmcm.xLogicCircuitsApplet.class"
            height=420 width=550>
        <param name = "LOAD" value = "SampleCircuits.txt">
    </applet>
    </p>

The param name, "LOAD", must be given in uppercase letters, as
shown.  Param names are case-sensitive.  You can also use an
input file with the launcher version of the applet:

    <p align=center>
    <applet archive="xLogicCircuits.jar"
            code="tmcm.xLogicCircuitsLauncher.class"
            width=180 height=30>
       <param name="LOAD" value="SampleCircuits.txt">
    </applet>
    </p>
    
The xComputer, xTuringMachine, xTurtle, and xModels applets can
load several sample files.  The files must be specified using
the param names "URL", "URL1", "URL2", and so on.  You have to
be careful to use the right names, without any omissions.
(If there is no URL2, for example, the applet won't even check for
URL3.)  For example, to use four sample input files with the
launcher version of the xComputer applet, you could use the
following tag on your web page.

    <applet archive="xComputer.jar"
            code="tmcm.xComputerLauncher.class"
            width=150 height=30>
       <param name="URL" value="SimpleCounter.txt">
       <param name="URL1" value="MultiplyByAdding.txt">
       <param name="URL2" value="ThreeNPlusOne.txt">
       <param name="URL3" value="ListSum.txt">
    </applet>


The preceding tags assume that the jar files and sample input
files are in the same directory with the HTML source file of
the Web page.  It's possible to put them in other directories.
If the jar file is not in the directory with the HTML file, then
you must specify a codebase in the applet tag.  The codebase
in an <applet> tag is the directory that contains the compiled
Java code for the applet.  It is specified relative to the
directory that contains the Web page.  For example:

    <p align=center>
    <applet codebase="../classes/" archive="xLogicCircuits.jar"
            code="tmcm.xLogicCircuitsLauncher.class"
            width=180 height=30>
       <param name="LOAD" value="SampleCircuit.txt">
    </applet>
    </p>

Here, the codebase directory is found by going up to the directory
that contains the Web page (specified as "../") and then looking
in that directory for a directory named "classes/".  (I've found
that the "/" at the end of the directory name is necessary, at least
for some browsers.)

It's a good idea to have just one copy of a .jar file, even if you
are going to use the applet on several Web pages.  Then, if the
user visits several of those pages, the Web browser will only have
to download one jar file.  That's why I put all the jar files
in one "classes" directory on my own site.

You can also have sample input files in a different directory
from the Web page.  Just include the directory name in the
name of the input file.  For example, "samples/SampleCircuits.txt"
or "../models/FirstModel.txt".  The name should be given relative
to the directory that contains the Web page.


RUNNING JAR FILES AS STAND-ALONE APPLICATIONS:
---------------------------------------------

The jar files DataReps.jar, xLogicCircuits.jar, etc. can be run
as stand-alone applications, outside a Web browser.  How to do
this will depend on which version of Java you are using on
your computer and how it has been configured.

You might be able to run an executable jar file simply by
double-clicking on it.  (This will be true under Windows if
you have installed a recent version of Java from Sun Microsystems,
using the default settings.  It is also true under MacOS X.)

If you are using Java in Internet Explorer on Windows, and if
you have not installed another version of java, then you can
use the "jview" command in a command window to run Java
applications.  To run xLogicCircuits as a standalone application,
use the command:

       jview  -cp  xLogicCircuits.jar  tmcm.xLogicCircuitsFrame

Here, "-cp xLogicCircuits.jar" specifies that the program is
in the jar file named xLogicCircuits.jar, and "tmcm.xLogicCircuitsFrame"
is the name of the Java class that defines the program.
For the other jar files, the commands are similar, such as
"jview -cp DataReps.jar tmcm.DataRepsFrame".

If the "java" command is defined on your system, you can try
commands of the form

       java  -jar  xLogicCircuits.jar
       
       java  -cp  xLogicCircuits.jar  tmcm.xLogicCircuitsFrame
       
For very old versions of the java command, you might have to
specify the location of the built-in java classes.  For example,
if Java 1.1 is installed in /usr/lib/java under Linux, the 
command would be of the form

  java  -classpath  xModels.jar:/usr/lib/java/lib/classes.zip  tmcm.xModelsFrame


----------------------------------------------
David Eck
Department of Mathematics and Computer Science
Hobart and William Smith Colleges
Geneva, NY   14456    USA
Email:  eck@hws.edu
WWW:    http://math.hws.edu/eck/