Chapter 3
Installing Java and Getting Started: JDK, Netscape, Explorer, HotJava Features

1. Launch your Net connection (if you need to do that) and your Web browser. If you are unsure of how to do this, consult your system administrator, your friends who know how to use computers, the manuals, or a book on using the World Wide Web, such as Que's Special Edition Using the World Wide Web.

2. Point your browser at the JavaSoft JDK download site at

   http://www.javasoft.com/products/jdk/1.1/index.html

3. Scroll down to the popup menu in the middle of the page that says "Select Download Platform" and has the various operating systems the JDK is available for listed in it. Pick your operating system of choice in that popup menu.

4. Click the "Download JDK 1.1" button just below the popup menu.

5. You'll hit a page that has a number of restrictions on the distribution of the JDK. Read each and, if you comply to all the restrictions, click the "Yes" button to go to the download page.

6. The page that now comes up has a list of various sites the JDK is available to download from. If there are options available, use the one closest to your location. Click the link to start the download.

The JDK is a pretty big file, and downloading is going to take a while. How long it takes depends on how fast your connection is, the user load on the FTP server at that particular moment, the network load on the Internet at the time of day you are downloading the file, the beating of a butterfly's wings somewhere on the planet, sunspots, blind luck, and a large number of other factors that are even more difficult to predict. If the file transfer is going too slow for your taste, try connecting at another time. Depending on where you are on the planet, good times to connect will vary, again depending on many of the same factors that control the transfer rate.

Installing a Downloaded JDK

Now that you have the appropriate installer file for your computer somewhere handy on your hard drive, it is time to actually install the software so you can get to work programming. Each platform has its own standard installation procedures, and the 1.1 release of the JDK is pretty good at following them to make installation a simple and straightforward procedure.

Solaris x86 and SPARC Platforms

For Solaris, the JDK 1.1 is normally distributed as a self-extracting shell script (a file with a .sh extension); the name of the file indicates its version.

CAUTION:
Use tar or your standard system backup process to back up any previous releases of the JDK before beginning installation of a new version! You don't want to lose all that work you put into it, and you'll have a copy of the previous release in the event something goes wrong with your new copy.

1. Choose a directory for the installation. These instructions assume an installation location of /USR1/JAVA. If you choose a different base directory, simply replace USR1 with the name of your installation directory. For example, if you choose to install under your home directory, everywhere you see USR1, replace it with ^~ or $HOME.

2. Verify that you have write permissions for the installation directory. Use this command to check the current permissions:

   ls -ld /usr1
   
   The options to the ls command specify a long listing, which includes information about ownership and permission, and also specifies to ls to not list the contents of the directory, which is the default. For more information about the ls command, see your system manuals.
   
   The output of the command should be similar to the following:
   
   drwxr-xr-x root other 512 Feb 18 21:34 /usr
   
   In this case, the directory is owned by root (the system administrator), and neither the group nor the general user community has permission to write to this directory. If you run into this situation, and you are not root, you need the assistance of your system administrator to install in that directory.

3. Move or copy the JDK distribution file to /USR1.

4. Extract the JDK by typing a period, a space, and then the jdk .sh filename (i.e., "jdk1.1-solaris2-sparc.sh").

   > . jdk1.1-solaris2-sparc.sh
   
   This will execute the shell script, which will then automatically uncompress the file you need into the directories that you need them in.

5. Verify that the following subdirectories were created under /USR1:

   java
   java/bin
   java/classes
   java/demo
   java/lib
   java/src

6. Set your PATH environment variable. For the C shell and its derivatives, use:

   setenv PATH $PATH:/usr1/java/bin

   For the Korn shell and its derivatives, use:
   
   PATH= $PATH;/usr1/java/bin
   export PATH

7. Set your CLASSPATH environment variable. For the C shell and its derivatives, use:

   setenv CLASSPATH /usr1/java/lib/classes.zip

For the Korn shell and its derivatives, use:

CLASSPATH = CLASSPATH /usr1/java/lib/classes.zip
export CLASSPATH

TIP: Rather than set these variables from the command line each time, you probably should add the commands to set the PATH and CLASSPATH variables in your shell resource file--.shrc, .cshrc, .profile, and so on. If you are a system administrator installing the JDK as a network development tool, you may want to add these parameters to the default configuration files.

Windows Installation

You need Windows 95 or Windows NT to run Java. For Windows 3.1, see "Installing IBM's Applet Developer's Kit for Windows 3.1" later in this chapter.

Installing the JDK is a fairly simple procedure, but you should know your way around the Windows and DOS environments. For Windows, the JDK is normally distributed as a self-extracting compressed file; the name of the file indicates its version.

1. Choose a directory for the installation. These instructions assume an installation location of C:\JAVA. If you choose a different base directory, simply append the appropriate path (and change the drive letter, if appropriate). For example, if you want to install to E:\TOOLS\JAVA, replace C: with e:\tools whenever it shows up in the instructions.

   ---

   CAUTION:
   Do not install the JDK over a previous release, especially if the previous release is one of the pre-beta or beta 1 versions! Rename the JAVA directory (for example, to OLDJAVA) using the Explorer in Windows 95 or Windows NT. If the installation fails for any reason, you can restore the previous version directly from OLDJAVA. Otherwise, after the installation is complete, you can move any additional files, such as documentation, from your old installation into your new installation before removing it from your system.

   ---

2. If you plan on installing to a networked drive, make sure you have permission to write to the desired directory.

3. Move or copy the JDK distribution file to C:\.

4. Extract the JDK by running the self-extracting program (double-clicking the icon in Explorer or File Manager works just fine).
5. Verify that the following subdirectories were created on drive C:\.

   
   C:\JAVA
   C:\JAVA\BIN
   C:\JAVA\CLASSES
   C:\JAVA\DEMO
   C:\JAVA\LIB
   
   

   ---

   TIP: For Windows NT 4.0 and later, you can skip steps 6, 7, and 8, and set the CLASSPATH from a properties sheet. You do not need to reboot, but you may have to close any DOS Prompt windows that you had open to use the new variable.

   ---

6. Add C:\JAVA\BIN to your PATH statement in your autoexec.bat file:

   set PATH=c:\windows;c:\dos;...;c:\java\bin

7. Set your CLASSPATH environment variable in your AUTOEXEC.BAT file:

   set CLASSPATH=c:\java\lib\classes.zip

8. Reboot your computer for the environment variables to take effect.

Macintosh Installation

For Macintosh, the JDK is normally distributed as a stuffed, bin-hexed archive (a file with a HQX.SIT extension). The file version is indicated in its name.

CAUTION:
Make sure to archive your current version of the JDK before installing a newer version. You don't want to lose all that work you put into it, and you'll have a copy of the previous release in the event something goes wrong with your new copy.

1. After following the previous instructions for downloading the MacJDK 1.1, you should have an installer titled MacJDK.SEA. Double-click this installer so that it launches into a fairly standard Macintosh installer dialog box.

   ---

   CAUTION:
   The Macintosh allows you to name directories and files in a manner that choke UNIX. Filenames that UNIX can't handle include the naming of directories with slashes (/). This causes problems with the JDK because it uses a mixed UNIX/Mac method of tracking paths when the JDK attempts to locate your files. Thus, a slash in the name of a directory is interpreted as a change of directory.
   
   UNIX also has a few problems with names that include spaces. As of this release, you should follow the UNIX file and directory naming conventions used by the developers. That means you shouldn't use spaces, slashes, asterisks, and most other punctuation characters in your file and directory names. You can, however, use as many periods as you want, and the file name can be as long as you want it (as long as it's less than 32 characters).
   
   For example, the following is a perfectly good Macintosh file name, but will not work under UNIX:
   /../..../Stuff \/\/..java
   
   To work under UNIX and the Mac, the file name should look like this:
   Stuff.java

   ---

2. In the lower-left corner of the installer dialog box in the Install Location area, you can specify where you want to install the JDK. After selecting the appropriate drive and directory, click the Install or hit "return" button to run the installer. It will put all of the Mac JDK in a directory called MACJDK at whatever location you specified in the installer. The default installation location is the root level of your startup disk.

You now have a working copy of the JDK on your hard drive folder. This includes two essential programs: the Java compiler and the Appletviewer. You are now ready to move onto the next (and much more fun) parts of Java development.

Testing the Java Compiler and JVM

Now you're ready to write a small Java application to test your installation of the JDK.

Creating a New Java Project

Somewhere on your hard drive, create a new directory to store your projects. I call mine PROJECTS and I keep it out of the JDK directory, so that I don't need to move it around whenever I install a new version of the JDK. Inside that directory, create another directory called HELLOWORLD.

Now, using your favorite text editor (such as the NotePad, vi, emacs, SimpleText, or something else), create a file called HelloWorld.java (double-check your capitalization--Java is case- sensitive), and type into it:

public class HelloWorld {

     public static void main(String[] args) {

         System.out.println("Hello, World!");

     }

};

Don't worry about the details of syntax right now; just type that in, save it, and exit your text editor. Make sure it's saved as a standard ASCII text file.

Running a Java Application for UNIX or Windows

If you're on a UNIX or Windows machine, at the command (DOS) prompt, type the following:

javac HelloWorld.java

It should pause for a moment, then return you to your prompt.

Get a directory listing in a DOS window to make sure you have the following files:

>dir
HelloWorld.class     HelloWorld.java

Or, in UNIX, get a directory listing to make sure you have the following files:

>ls
HelloWorld.class     HelloWorld.java

If you get any errors, check the HelloWorld.java code to make sure it looks exactly as it does here.

If you get an error that javac was not found, you didn't set the JAVA/BIN directory in your PATH variable. Go back and check your installation.

Now you're ready to run your first Java program! At your command prompt, type the following:

>java HelloWorld

You should see the following:

Hello, World!

If you did, congratulations. You've run your first Java application, but more importantly, you've correctly and successfully installed the JDK.

If you didn't see "Hello, World!", there is something wrong with your installation. Check to make sure your CLASSPATH variable is set to point at both the current working directory (a period ".") and to the classes.zip file. Check to make sure you typed the name of the file correctly, keeping in mind that Java is case-sensitive. If none of that works, you may need to reinstall the JDK.

Running a Java Application for the Macintosh

The procedure is a bit different for a Macintosh because it doesn't have a command prompt.

1. On your Mac, open your HELLOWORLD folder so that your HelloWorld.java file appears.

2. Then open the MACJDK folder so that the Java compiler icon appears (it should be a little "Duke" with a "C" on his chest). Drag the HelloWorld.java file onto the Java compiler icon. The Java compiler then launches and begins compiling the program. When it's finished, a file called HelloWorld.class should appear in your HELLOWORLD folder.

3. If you received compile time errors, check the HelloWorld.java code to make sure it looks exactly the same as the previous code.

4. Double-click the HelloWorld.class file. The java runner application launches, loads the HelloWorld program, and runs the program. A window titled "stdout" should appear, with the words Hello, World! in them.

If it did, congrats. You've installed the JDK and run your first Java program.

If you didn't see "Hello, World!", there is something wrong with your installation. Check to make sure you are running System 7, that the JDK installed completely, and that the filename and the name of the class generated match, keeping in mind that Java is case-sensitive. If you still can't get it to work, you may need to reinstall the JDK.

NOTE: The authors of the Macintosh Java Runner application have cleverly hidden the Quit command in the Apple menu. Why they did that isn't known. If you want to free up the memory that the Java Runner is taking up after it's finished running your program, choose Apple, Java Runtime, Quit. Not very Mac-like, but at least it's not a command line. Or, to quit, you can just hit command-Q, like any other normal Mac program.

Installing IBMs Applet Developers Kit for Windows 3.1

Why isn't there a Sun JDK for Windows 3.1? Well, there are a number of technical issues that make porting the JDK tools to Windows 3.1 difficult, and with the release of Windows 95, Windows 3.1 was seen as a dying platform, so the decision was made to not directly support it. Some of these issues include the fact that Java needs long file names such as the ".java" and ".class" filenames. The eight-character file name and three-character extension of Window's 3.1 naming system just couldn't fully support Java file names. A more difficult problem to solve, however, is the fact that Java is a multi-threaded language, meaning it can run more than one process at the same time, but Windows 3.1 doesn't support multithreading. In order to support Java in Windows 3.1, several groups undertook projects to port the JDK to 3.1, the most successful of which is IBM's ADK.

With IBM's release of their ADK, Windows 3.1 users now have a way to develop Java applets and applications without upgrading to Windows 95 or NT. It includes a number of programs that help get around the problems previously described, as well as improving upon the tools that come with the JDK.

Downloading the ADK

To get to the main ADK Web page, you first need to launch your Web browser and go to http://www.alphaworks.ibm.com/. This is the main Web page for a number of IBM's projects that are currently under development. To get to the ADK Web page, you'll need to pick the "ADK for Win 3.1" entry in the pop-up menu in the "Select" selection.

To completely install the ADK, and use all of its features, you need three components: The ADK itself, the Windows 32-bit extension Win32s, and the WinG graphics extension.

To download and install the two windows components, ftp to ftp://ftp.microsoft.com/softlib/mslfiles/ and get the following two files:

pw1118.exe
wing10.exe

The WinG extension file name is wing10.exe, and it is about 830k.

The Win32s file name is pw1118.exe, and it is about 2.4 megs. You will need to get and install both of these before installing the ADK.

To install these two system enhancements, make a temporary directory for each of the two, and put the .exe files into them. Use either a DOS prompt, or the Run command in the File menu of the program manager, to execute the .exe files. For example, if you put the wing10.exe file in a directory called "wingtemp" on your C: drive, the DOS prompt command would look like:

C:\wingtemp\>wing10.exe

This decompresses all the files to do the complete install. Each should decompress to a large number of files, with an executable called "setup.exe." After it is done decompressing, execute the setup program, again using either a DOS prompt or the File, Run menu. The setup program will prompt you for some information and then install all of the needed files. After you are done you can delete the temporary directories you put the installer programs in.

When you have WinG and Win32s installed, you can proceed with the installation of the ADK itself. You will first need to read the ADK license agreement at:

http://www.alphaWorks.ibm.com/ADK

At the bottom of the page is a button labeled "I Agree." If you have read the license and agree to its terms, you can click that button and it will take you to the download page where you can download the ADK installer. The actual ADK file is rather large, about 4 megabytes, and will take a while to download, especially over a modem connection.

Once you've gotten the ADK installer, you can then execute it from the Windows program manager File, Run menu. It will ask you for an installation directory (For example: C:\java\), and then it will do its stuff, installing all the files you'll need to get up and running with the ADK.

When the ADK is completely installed, it will create a program group with the items in Table 3.4.

Table 3.4 Files in the ADK Program Group

Configure AppletViewer	This will run the AppletViewer and display a license document.
ADK.WRI	The ADK User Guide, read this for more information on the ADK.
ADK File	A file manager type application that lets you manipulate files with long file names, rather than the Win 3.1 standard 8.3 file names.
ADK Edit	A small editor that integrates the ADK tools into one program, so you can work with Java code without having to switch between a number of other programs.
ADK Console	The guts of the ADK, this is the program that runs all of the Java environment-based tools such as AppletViewer and javac.

To set up the ADK, run the "Configure Appletviewer" program, agree to the license agreement, follow the instructions to configure the AppletViewer, then close the applet.

To test your installation, follow these steps:

1. Launch the "ADK Console" program.

2. Select AppletViewer from the Tools menu.

3. Type "C:\java\demo\Animator\" into the Working Directory Field (or whatever directory you installed the ADK).

4. Type example1.html into the Command Options field.

5. Press OK.

This should launch the Animator applet, and put a dancing Duke on your screen. If it did, then you're all set to develop Java programs on your Windows 3.1 machine. If it didn't, make sure that the path you put into the Working Directory field is actually the path that has the Animator applet and that there is a example1.html file in that directory. If not, you may need to go back through the installation process and try again.