Appendix B: Installing PtPlot & Java Developer’s Kit Packages

The first step in setting up PtPlotis to download the latest version and then uncompress it.¹ The plotting package we call PtPlot is part of a larger Java project called Ptolemy [PtPlot], all free for downloading. After you have properly unzipped or untarred the PtPlot package, a directory such as ptplot5.6 should be created. The number 5.6 here is the version number of the PtPlot package that we are now using; there may be a newer version when you do your download. For our examples we have renamed the directory in which PtPlot resides as simply ptplot, with no version number attached.On Unix, we assume that your ptplot directory will be ˜/java_packages/ptplot, where the ˜ indicates your home directory. On Windows, we assume that your ptplot directory will be C:ptplot. ² Advanced users may prefer to keep the version number in the directory name or use a different organizational system. However, if this is the first time that you have installed a Java package, we recommend that you use the same directory names that we have.

Now that we have placed the Pt Plot package in its own directory, we need to tell Java where to find it. As a matter of convention, the Java compiler javac and the Java interpreter java assume that the value of a variable named CLASSPATH contains the information on where packages such as PtPlot are stored. This type of variable that controls the environment in which programs run is called an environment variable. Because the programs in the packages having already been compiled into class files, the variable that directs Java to the classes is called CLASSPATH. To get PtPlot to work under Java, you need to modify the CLASSPATH variable to include the location where PtPlot is stored.

Windows 95: Open the autoexec.bat file (usually C: autoexec.bat) in a text editor such as Notepad. At the end of the file, add the line

Save the autoexec.bat file and restart your computer.

Windows 98/ME: Click Start and then Rununder that. Key in the command name msconfig and press Enter.The _{System Configuration Utility} should appear.Select the tab Autoexec.bat and look for a line that says SET CLASSPATH. If you cannot find that line, click New and enter SET CLASSPATH = C:ptplot. If the SET CLASSPATH line already exists, select it, choose Edit, add a semicolon ; to the end of the line, and then add C:ptplot after the semicolon. The semicolon is a separator that tells Java that it should look in more than one location for class files. Make sure that the checkbox next to the CLASSPATH line is checked and then click OK. Answer Yes when Windows asks you whether you want to restart the computer.

Windows NT/2000/XP: Open the Control Panel (Start, Settings, Control Panel in NT/2000, or Start,Control Panel in XP). Open the System icon (you may need to switch to the Classic View in Windows XP). Under the System Properties window, select the Advanced tab and choose Environment Variables. Two lists should be shown. One contains environment variables just for you, and one contains environment variables for all users on the system. On your personal environment variable list, look for CLASSPATH. If you cannot find the CLASS-PATH variable, click New and enter CLASSPATH for the variable name and C:ptplot for the value. If the CLASSPATH variable already exists, select it, choose Edit, add a semicolon ; to the end of the current value, and then add C:ptplot after the semicolon. The semicolon is a separator that tells Java that it should look in more than one location for class files. Click OK until you get back to the Control Panel and then restart your machine.

Unix: We assume that you do not have system authority for your computer and so will install PtPlot in your home directory. We suggest that you make a subdirectory called java_packages in your home directory and install PtPlot there:

If the ~ is used to represent your home directory, this assumes that you will be installing the PtPlot package in the ˜/java_packages/ptplot/ directory.

Your CLASSPATH variable that needs updating is contained in the initiation (init) file .cshrc in your home directory. Because this file name begins with a. It is usually hidden from view. Beware: It is easy to mess up your .cshrc file and end up in a quagmire where you cannot enter commands. For this reason we suggest that you first create a backup copy of your .cshrc file in case anything goes wrong:

Next, open the .cshrc file in a text editor. Because this file may contain some very long lines that must be kept intact, if your text editor has an automatic word wrap feature, make sure it is turned off. Next look for a line that starts with setenv CLASSPATH. If you cannot find that line, add setenv CLASSPATH ˜/java_packages/ptplot on its own line at the end of your .cshrc file. If the setenv CLASSPATH line already exists, add a colon: to the end of the existing line and then add ˜/java_packages/ptplot after the colon. The colon is a separator that tells Java that it should look in more than one location for class files. Save your .cshrc file and then close and reopen all the shells that you have open (or log off and then back on).

Once you have the CLASSPATH variable set, you should make sure that it is working. To check, go to a command prompt in a shell and enter

The complete value for the CLASSPATH variable should be printed to the screen, for example:

/home/jan/java/classes:/home/jan:/home/jan/mpi:/usr/local/mpiJava/ lib/classes:/home/jan/java_packages:/home/jab/java_packages/ptplot:

If your changes do not take, carefully follow the directions again, and if you still have problems, ask for help.

At this point you are ready to try out PtPlot. Get the file EasyPtPlot.java containing a sample plot program from the CD (available online: http://press.princeton.edu/landau_survey/) and enter

If the PtPlot package was installed correctly, you should get a nice graph on your screen. If this does not work, ask for help.

B.1 Installing Java Developer’s Kit

Sun Microsystem’s Java Web site [SunJ] contains the latest (free) version of Java Developer’sKit(JDK)(JavaSEorJava2,presently JDK6.3). Though most operating systems have all that is needed to run Java programs, you need the developer’s kit to compile Java programs from a source file. The actual JDK tools occupy about 7 MB, with its (optional) documentation occupying more than 10 times as much space (the documentation is in HTML). This means that you may want to install only the tools if space is an issue.

On Windows computers, JDK is usually placed in C:Program FilesJavajdk1.5in, while on Unix it is placed in /usr/local/jdk1.5. Once installed, you will need to update the PATH and the CLASSPATH environment variables so that the shell knows where to find the Java compiler and classes you make. This is essentially the same procedure we used to include the PtPlot classes in CLASSPATH. Under Windows go to the System Control Panel and then select the Environment tab. Then add ;C:jdk1.5in (or whatever file JDK was installed in) to the PATH variable. Likewise, CLASSPATH needs to be added, for example,

> set CLASSPATH=C:…

Finally, reboot Windows for the changes to take effect, or log off and on under Unix.

TABLE B.1
Some of Java’s Packages and the Classes They Contain

B.2 Using Classes and Packages

Most of the programs we give as examples contain a single class in a file with a .java or .class extension. That class contains a main method and possibly some other methods. Just as we encourage you to modify old programs rather than write all programs from scratch, so we encourage you to include in your new programs methods that you and others have already written and debugged. Java contains a large number of libraries consisting of collections of methods for various purposes, and you should think of these libraries as toolboxes from which you can extract individual tools needed for your programs. In fact, the object-oriented approach of Java is specifically designed to make the reuse of components easier and safer.

B.2.1 Including Packages

A collection of related methods is called a class, and a broader collection, a library (such as the Math library). In strict Java naming convention, each method would be in a class file, and the libraries would be called packages. In general, there are two types of packages: the standard Java packages that constitute the Java language, and user-defined packages that extend standard Java. The PtPlot package is an example of a user-defined package. Some of the standard Java packages are given in Table B.1.

Because these Java packages contain hundreds or thousands of classes, some organization is necessary to keep track of what each method does. Java does this with a hierarchical directory structure in which there are parent packages containing subpackages, with the subpackages containing more subpackages or various classes. To make the name of each class unique, it is preceded by the names of the package and subpackages that contain this class. As an example, consider the command

System.out.println

that we use to print a line of output on the screen. Here System is the name of the class (classes begin with capital letters) containing many of Java’s methods. When we give the combination System.out, we are referring to an object representing the standard output stream. The final println that is affixed to System.out is the name of the method that prints lines.

To summarize, the convention is to have the names of classes capitalized, while the names of packages and methods are lowercase. This is relevant because the System.out.println command is in the java.lang package, and so the proper full name of the command is actually

java.lang.System.out.println

which contains the package name as well. Because java.lang is the most basic package, the Java compiler automatically looks there to find the methods we invoke. This means we can, fortunately, omit the java.lang prefix. Technically, java is the main package and lang is a subpackage, but it is easier to just say java.lang is the package. We must admit that we sometimes find Java’s naming conventions overwhelming. Nevertheless, we will use them when importing packages and using methods from other classes, so some familiarity is helpful.

The classes from a package are included with the import command. It may be given in one of two forms:

The import command tells the compiler to look in the package packageName for methods that it might not find otherwise. However, for the importation to work, the compiler must know where the package of classes and their methods are stored on your particular computer. In other words, the compiler needs to know the path to follow through the local disk memory to get to the directory or folder where the classes are stored. For this purpose each computer system, be it Windows, Unix, or Mac OS, has an environmental variable named CLASSPATH that contains the explicit path to where the classes are stored on that particular computer. As we show in Appendix B on installing PtPlot, you need to modify this variable before your program can import the package.

Even though what follows is more advanced programming than we do in this book, for completeness we indicate how you can create your own packages. This is done by placing several classes in the same .java file and then including a package command at the beginning of the file:

Your package may be a collection of methods without any main method, for instance, mathematical subroutines that are called from a lltheprogramsyouwrite.However, there must be one main method someplace if the program is to run since execution always begins in a main method. Likewise, the main method must be a public class.

1 If you have never done this before, you may want to do it with a friend who has. In Windows, you use WinZip to unzip files. In Unix, try double-clicking on an icon of the file, or decompress it from within a shell with gunzip and tar -xvf.

2 If you use the Windows automatic installer and you want to follow our examples verbatim, you should install to C:ptplot rather than C:ptolemyptplot5.6.