How to set up the Sun Java JDK

About this document
This document explains how to set up and, in outline, use the Sun Java Development Kit on a PC running Windows '95, '98 or NT. At the time of writing the latest JDK version was 1.2.2, but this will probably have changed by now. However, it is unlikely that the installation procedure will change very much. I am providing this document because, although installation instructions are supplied with the JDK distribution, they are written in a style that many novice programmers find difficult to follow.
What is the JDK, and do I need it?
The Java Development Kit is a package of software and documentation designed to allow you to compile and execute Java programs. It is available free-of-charge from Sun's JavaSoft Web site, but as the complete package (including documentation) is about 40 Megabytes, expect it to take a long time to download. Alternatively, CD-ROM versions are widely available, and are often supplied free with PC magazines.
Although it is free, the Sun JDK contains everything required to develop professional-quality Java programs. Proprietary Java products are available which are easier to use, but these offer little extra functionality. Moreover, by using the JDK -- which is updated regularly -- you ensure that you are following the very latest standards in Java programming.
The Sun JDK is designed to be used by professional software developers. As such the installation process assumes a level of computing experience that may be beyond that of a person who has only used a computer to run application programs. There is nothing difficult about the installation, but you may be asked to do things that are unfamiliar to you. You will certainly have to modify system configuration files manually, which is unusual with modern software.
What is covered by these instructions?
These instructions describe the procedures for setting up the JDK tools and documentation on the following systems:

IBM-compatible PC running Microsoft Windows NT version 4 or later
IBM-compatible PC running Windows '95, Windows '98, or later
This document also provides brief guidance on how to use the JDK software tools to compile and execute a program, and how to manage the files that you will create during this process.
Installation instructions
The installation has four steps: installing the JDK tools, updating your system's `PATH' variable, testing the compiler, and installing the documentation.
Step 1: run the JDK tools installation program
The installation program is a file called `jdk1_2_2-win.exe'. Find this file using the Windows `Explorer' program. Double-click on its icon to start the process. You will know that it is working when you see the JDK installer `welcome' screen, which looks like this:

When the installer starts, you will be asked to read the licence agreement and confirm that you accept its terms (essentially that you won't sell it to other people). Having done this, the installer will ask what directory you want to install the software in. The default is `c:\jdk1.2.2'
Next you will be asked which optional components to install. A full installation requires about 70 Mb of free disk space. Only the first option `Program Files' (about 24 Mb) is absolutely essential for the production of ordinary Java programs.
If you choose to install any of the optional components, there will be more questions to answer. It's probably best to accept the default response unless you have strong reasons to do otherwise. If you don't understand the questions the installation program is asking, you should certainly accept the default response.
The installer will now copy the selected JDK files to your computer's hard disk. If your computer is more than about 2 years old, it will take long enough for you to have a cup of tea.
When all the files have been copied, the installer will ask if you want to reboot the computer. As you will have to do this later anyway, you should say `no' here, and continue with step 2 below.
Step 2: Update your system's `PATH' variable
I have had reports that on some systems this step seems to be carried out automatically during step 1. Do not be alarmed if the instructions given here appear to have been carried out already.
The Sun JDK is a set of command-line software tools, that is, they are designed to be executed by typing commands, not by the use of menus and icons. The `PATH' variable is what tells the computer where to look for files when you type their names on the command line. To compile a Java program you will type `javac'. This command corresponds to the program `javac.exe' that the JDK installer provides. In order for `javac' to work, your computer must have in its PATH the directory where `javac.exe' is installed. If you installed the Java software according to the instructions in step 1 above, then the directory to add to the PATH will be `C:\jdk1.2.2\bin'.
The procedure for setting the PATH depends on whether you are using Windows NT or Windows 95/98.
Procedure for Windows NT
You may need to log in as `administrator' for this to work.
Start the Windows Control Panel. Select `System'. Select `Environment'. Look for an entry labelled `Path' in the `User Variables' or (if it isn't there) the `System Variables' sections. Add the directory for the Java programs to the right-hand end of the existing PATH. If there is no PATH variable, you should create one in the `User Variables' section. For example, suppose the existing PATH was
c:\winnt;c:\utils
you should change it to
c:\winnt;c:\utils;c:\jdk1.2.2\bin
Note that PATH is not case-sensitive on a Windows system, so capitalization doesn't matter. To finish, click `Set', `OK' or `Apply'. It should not be necessary to reboot the computer for this change to take effect, but we have found it necessary on occasion. Reboot now to be certain.
Procedure for Windows 95/98
Windows 95 and Windows 98 get their PATH setting from the file `autoexec.bat' when they boot. You can edit this file using Windows `Notepad'. Start Notepad, and open the file `c:\autoexec.bat'. Look for the PATH statement. It will say something like
PATH C:\WINDOWS;C:\WINDOWS\COMMAND
or
set PATH=C:\WINDOWS;C:\WINDOWS\COMMAND
You should change it by adding the directory for the Java programs to the right-hand end of the existing PATH.
For example, suppose the existing PATH was
PATH C:\WINDOWS;C:\WINDOWS\COMMAND
change it to
PATH C:\WINDOWS;C:\WINDOWS\COMMAND;C:\jdk1.2.2\bin
If there is no PATH statement (unlikely), you should create one, like this:
PATH C:\jdk1.2.2\bin
As this file is only read when the system boots, you should reboot now.
Step 3: test the installation
The proper test is to enter and run a program, but if the following test works, we can be reasonably sure that everything is OK so far.
Start a command prompt session (look for an icon labelled `DOS prompt' or `command prompt'). At the prompt, type `java'. You should see a message of about 10 lines, explaining how to use the program properly, like this:

If this is the case, it's working. If you get a message like `bad command or file name' then the most likely explanation is that the PATH is not set correctly (see step 2 above).
Step 4: install the documentation package
The documentation is supplied in the form of HTML files, designed to be viewed by a Web browser. There are in total about 5000 files in the package. Yes, that's five thousand. Don't worry, you won't need to read them all.
The documentation is provided by Sun in the form of one large file called `jdk1_2_2-doc.zip'. This file has to be expanded into it 5,000 individual components using an `unzip' program.
Many computers already have suitable software installed. If not, we recommend `WinZip' from Nico Mak Computing. You can download a free evaluation version of this software from their Web site. Do not use a DOS-based unzipper like PKUNZIP. These products usually do not support long filenames.
If you have WinZip or something similar installed, the installation procedure is straightforward. Find the file `jdk1_2_2-doc.zip' and double-click its icon. This will start the unzipper, and you will see something like this:

You should then get the unzipper to extract the individual files. With WinZip this is as simple as clicking the `Extract' button. When asked what directory you want to install to, select
c:\
The unzipper may ask if you want directories to be created, to which you should reply `yes'. Again, you may well have time for a cup of tea at this point.
To view the documentation, open the main index using a Web browser. With Netscape Navigator or Microsoft Internet Explorer you should simply be able to enter the directory name in the URL box at the top of the browser. If you have followed these instuctions, the directory name will be
c:\jdk1.2.2\docs\api\index.html
You can test this by following this link. Don't worry if the information you see doesn't make sense at this stage.
That's it. If you get this far then everything should be working. You can begin writing Java programs!
Removing the JDK software
You may at some point wish to remove the JDK software and documentation. To do this, use the `Add/Remove programs' section of the Windows Control Panel. You should see the relevant entries in the list of installed programs; simply click on `Add/remove' to un-install them.
Using the JDK software tools
The complete JDK installation provides a large number of programs for compiling, running, debugging and managing Java programs. There are three particularly important ones:

javac The Java compiler. Used to translate Java programs into a form that can be executed

java The Java run-time processor. Used to run stand-alone Java applications

appletviewer The Java applet viewer. Used to run Java applets without a Web browser

All these are command-line programs. That is, they have no graphical user interface, and are intended to be executed by typing commands. Altough this seems somewhat old-fashioned, it is a very efficient way of working for people who are familiar with it. Most PC users associate the use of a command prompt with MS-DOS. However, the JDK tools are not MS-DOS programs; indeed there is not even an MS-DOS version of the JDK. The use of command-line tools was a design decision on the part of the Java developers. Moreover, the fact that you are using command-line tools to compile your Java programs does not mean that you cannot create programs with graphical user interfaces; on the contrary, Java provides very sophisticated graphical user interface facilities.
These are the basic steps in entering, compiling and running a Java applet. You will need to do all these at the command prompt (`DOS prompt').
Step 1: create a directory for your new program, and change to that directory
I recommend creating a separate directory for each new program you write. This will make it easier to keep track of your files.
c:\>md program1
c:\>cd program1
c:\program1>

Step 2: create the Java program
I recommend using the Windows `Notepad' program for this. Alternatively you can download one of the many shareware text editors that are available. Do not use a word processor! The files produced by a word processor will not be understood by the Java compiler.
c:\program1>notepad Program1.java

Step 3: compile the Java program
When you have created the program (which may have taken some time) you can attempt to compile it using `javac'. This will only work if the program is free of errors. If the compiler produces error messages, you will have to modify the program and try again.
c:\program1>javac Program1.java

Step 4: create an HTML file to control the applet viewer
Even though we will be using the applet viewer to run Java applets (rather than a Web browser), the applet viewer still requires that the applet be specified in an HTML file as if it were a Web page. This step is described in more detail in the document how to use the applet viewer.
We recommend that you use Windows notepad to produce the HTML file.
c:\program1>notepad Program1.html

Step 5: run the Java applet using the applet viewer
c:\program1>appletviewer Program1.html

You can now test the program. You will probably find that you need to modify it, compile it, and execute it several times (perhaps many times) before you get the result you require. I recommend that you keep your Java program open in `Notepad' all the time you are working on it to save time.