### Java Applications

## Installation Guide

The software on this CD requires the Java 2 platform, so your first step should be to verify that is is available on your system. If you do not have Java 2 installed, it can be acquired from http://java.sun.com.

The applications use a class library provided on this CD. You must configure Java to access this library, either from the CD or from a directory on your hard disk into which you install the library. Details are given in the class library documentation.

#### Installing the Full Set of Applications

If you wish to install all the applications on your hard disk, the simplest approach is to create a single directory for them and then copy the following files to that directory:

- All the `.class` files in every subdirectory of the `Apps` directory
- `magnify.gif` from subdirectory `Chap05`
- `equals.gif` and `star.gif` from subdirectory `Chap07`

You will then need to modify your classpath to point to this directory. (This is in addition to the modifications made to the classpath so that Java can locate the class library.) For example, suppose you have installed the applications to the directory `C:\IPTools` on an MS-Windows system. You would then do

      set CLASSPATH=%CLASSPATH%;C:\IPTools

This command could be put into a batch file that you execute after opening a window with the MS-DOS prompt; alternatively, it could be added to your `AUTOEXEC.BAT` file. (This would save you the trouble of having to configure the classpath each time you opened an MS-DOS window.)

A similar approach can be used on UNIX systems. For example, on a machine running the bash shell, you can do

      CLASSPATH=$CLASSPATH\:/home/nick/IPTools
      export CLASSPATH

or similar. (If you don't have the bash shell, consult your shell's documentation for precise details of how to configure environment variables.)

#### Installing Selected GUI-based Applications

For the GUI-based applications, which typically consist of several `.class` files, a different method of installation is supported. For each of these applications, copies of the `.class` files have been packaged as a single JAR (Java Archive) file, located in the same directory as the `.class` files. Certain of the applications have icons loaded from GIF images, and these, too, have been added to the JAR files where necessary. Each JAR file therefore contains all the code and data associated with the application.

For each application packaged as a JAR file, there is a corresponding MS-DOS batch file and bash shell script that you may use to invoke the Java interpreter on the code contained in the JAR file. All you need to do is copy the JAR file somewhere, then copy the batch file or shell script to a directory that is searched for such things. The batch file or shell script will need to be edited so that it can locate the JAR file. (The latter can be installed in the same directory as the batch file / shell script if you wish to keep the two together.)

This approach has the advantage of neatness. It keeps related `.class` files together, avoiding needless clutter in your directories; it also allow you to keep applications separate from one another, if you wish. Finally, it does not require permanent modification of your classpath. (The modifications necessary to run the application are made temporarily, by the batch file or shell script.)

#### Running the Applications

If you have elected to install the `.class` files in a single directory and you have configured your classpath appropriately, running the applications will simply involve specifying the main class name of the application as a command line parameter of the `java` command. Examples include

      java Convert foo.png foo.jpg
      java GreyMapTool dark.png
      java ConvolutionTool bar.png 5 5

If you have installed a GUI application in the form of a JAR file plus a batch file or shell script, then you simply need to type the name of the script, followed by any command line parameters. For example, suppose you have installed `ImageViewer.sh` in `~/bin` as the file `ImageViewer`, and that `ImageViewer.jar` is installed somewhere referenced by that script. Assuming that `~/bin` is in your path and that execute permission has been set for the script, an image can now be displayed with the command

      ImageViewer foo.png