Setting Up and Using the Java Developer's Kit By Phil Filner, last revised September 6, 1996 Finally updated for JDK 1.0.2 and Sun's reorganized Java web site This page has been visited times since September 7, 1996 Feedback welcome, especially corrections and clarifications. _________________________________________________________________ What is the Java Developer's Kit ? Sun Microsystems is developing a computer language called Java. It is designed for writing programs to run on the World Wide Web. Sun has made available for downloading, a set of programming tools called the Java Developers Kit (JDK). JDK is available for several systems, including 32-bit versions of Windows: Windows 95 or Windows NT. The current version, JDK 1.0.2, can be downloaded as a self-expanding file, JDK-1_0_2-win32-x86.exe . The file can be downloaded via Sun's java home page or more directly from the JDK 1.0.2 home page. The URL for the download of JDK 1.0.2 is: http://java.sun.com/products/JDK/1.0.2/installation-win32-x86.html A version of the JDK and documentation can also be found on the CD-ROM bundled with "Hooked on Java", by A. van Hoff, S. Shaio, and O. Starbuck, of Sun's java development group, and published by Addison-Wesley. However, if the CD-ROM is not updated, the version will not be current. The book itself is a clear, concise introduction to applets and applet programming. A subset of the Java system is the Application Programming Interface (API). It provides standardized names of access routes to object classes and their methods used in java programs. There have been two iterations of the API, alpha and beta. Programs conforming to the alpha API can be interpreted by the java interpreter in Sun's Hot Java browser. Programs conforming to the newer beta API can be interpreted by the java interpreter in Netscape Navigator 2.0 or later; and in Microsoft Internet Explorer 3.0 . Netscape Navigator can be downloaded from Netscape's home page. Internet Explorer can be downloaded from Microsoft's Internet Explorer home page. This document is written with the assumption that the JDK will be installed on a personal computer running Windows 95. _________________________________________________________________ Pre-download Preparation Before downloading the JDK, it is convenient to make some changes in the DOS/Windows environment in which the JDK programs will run. In any event, these changes should be made before attempting to use JDK programs. Start a text editor, e.g. Windows Word Pad, by selecting Start|Programs|Accessories|WordPad|File|Open| At the bottom of the Open file dialog box, set "Files of Type" to "All Documents". At the top of the dialog box, select the drop-down menu|, and then select Somedrivelabel (C:)| , Then select the file autoexec. Select Open|. Move in the autoexec.bat text to a line below the last line in which the path was defined or modified. Beginning at that line, add the following text: SET PATH=%PATH%;C:\java\bin SET CLASSPATH=.;C:\myjava;C;\java\lib\classes.zip SET HOME=C:\java Then select file|save|, file|exit| _________________________________________________________________ Developing Programs Folder A folder should be set up for storage of progam files during development. The name suggested by Sun for this folder was html, but you can call it whatever you want, myjava, for example. If you choose a name other than myjava, be sure to change the name of the directory in the CLASSPATH environmental variable , accordingly. Like any other folder, you can create it the old DOS way or the new Windows 95 way. The old DOS way Select Start|Programs|MS-DOS Prompt| At the DOS prompt, enter: MD \myjava EXIT The new Windows 95 way Select Start|Explore|. In the All Folders window, open the drop-down menu, or scroll up, until you can see Somedrivelabel (C:). Select Somedrivelabel (C:) Select File|New|Folder| A folder icon labeled "New Folder" will appear at the bottom of the "Contents of Somedrivelabel (C:)" window, with the name highlighted. Press the Delete key to clear the highlighted temporary name. Type myjava Press [Enter] _________________________________________________________________ Environmental Variables Explained Path to java\bin C:\java\bin will contain the executable programs of the JDK. By adding that directory to the path, it becomes possible to execute JDK programs from any directory. CLASSPATH The JDK programs look for user-created .class files in the directories named in the CLASSPATH environmental variable. Java's standard .class files, the ones named in the beta API (Application Programming Interface), are in C:\java\lib\classes.zip . JDK 1.0.2 requires that the directory containing classes.zip be explicitly declared in the CLASSPATH environmental variable. In JDK 1.0, it was appended automatically when JDK programs looked up CLASSPATH. HOME The directory assigned to HOME is used by JDK's appletviewer program, initially to create the folder(=directory) .hotjava, in which appletviewer writes the properties file when an applet is loaded. If an applet has parameter tags in the html file from which the applet is called, the values are written to the properties file, and can be displayed by appletviewer. If for some reason, you do not want the .hotjava folder in c:\java, you can specify some other directory, e.g. C:\, which is specified in Sun's current installation instructions for JDK 1.0.2 . _________________________________________________________________ Download of the JDK Start a graphic browser. Select Open| Enter the URL for Sun's JDK 1.0.2 download page: http://java.sun.com/products/JDK/1.0.2/installation-win32-x86.html . Follow the onscreen instructions to download the self-expanding file, JDK-1_0_2-win32-x86.exe When prompted for the directory in which to store the file on disk, select the root directory, C:\ The file contains about 3.75 Megabytes. At 2 KB/sec, it takes about 30 minutes to download. After the download is complete, exit from your graphic browser. _________________________________________________________________ Expansion of the JDK Select Start|Programs|MS-DOS Prompt| At the DOS prompt, enter cd \ JDK-1_0_2-win32-x86 The expansion will begin and the names of the resulting folders and files will be displayed in the MS-DOS window. _________________________________________________________________ The JDK Java\ Folders The expansion creates a folder, C:\java. The java folder contains the following sub-folders: * bin * demo * include * lib and these files: * copyright * index.html * readme * src.zip Using winzip or pkunzip, the src.zip file may optionally be unzipped into a src folder containing .java files. They contain the source code of standard classes (= java objects) which can be found in compiled, compressed form in classes.zip. Unzipping src.zip results in about 900 KB of .java files. The folder lib contains the file classes.zip which has the compiled versions of the standard classes, but in compressed form. This file should not be unzipped. During compilations, the java compiler, javac, gets compiled code for particular classes, as needed, from the compressed file . Folder Contents JAVA\BIN This folder contains the executable programs of the JDK, all of which are tools for programming in java. There are 2 versions of each program, one optimized and one not optimized. The latter additionally create a table for use with a debugger. The non-optimized ones have names ending in _g . The purposes of the programs, and their settable switches, are described briefly in online documents listed in the JDK tool index. The programs are: appletviewer for viewing applets without the surrounding web page. javac compiler of .java files java interpreter of .class files.-can run class files; also a combination compiler + interpreter of .java files jdb debugger javah header file generator javap disassembler- creates human-readable code from compiled code in .class files Note: the argument for javap is the class name, not the name of the file, i.e. omit .class javadoc builds API documentation, from specially marked comment lines (//* */) javaw ? (did not find online page on it in the JDK documentation) appletviewer_g non-optimized appletviewer javac_g non-optimized javac java_g non-optimized java javah_g non-optimized javah javap_g non-optimized javap javadoc_g non-optimized javadoc jdb_g non-optimized jdb javaw_g non-optimized javaw JAVA\DEMO The Demo folder contains more than 20 folders, each named for an applet, and containing the files defining that applet. There is in each folder at least: appletname.java a source code file appletname.class a compiled code file example1.html an html in which the applet is called. Other files If the applet uses sound or image files, there will be additional files or subfolders containing those files. There may also be additional example html files. JAVA\.HOTJAVA A folder created in the course of the first running of appletviewer. A file called properties is also written by appletviewer, in the folder .hotjava JAVA\INCLUDE C programs frequently use standard portions of source code. These are provided in so-called "header" or "include" files with the extension .h . Each file contains a set of related functions, e.g. math, input/output, graphics, etc. This directory is for include files which interface between C programs and java programs. JAVA\LIB Programs can also use pre-compiled portions of code. In java, these are provided in files with the extension .class. java\lib contains one large compressed file of .class code for many classes. It is read directly by the compiler, javac, as needed during compiles. There are also in java\lib files javai and javai_g (purpose ?), and a text file containing a list of javac properties. JAVA\SRC An optional folder for .java files containing source code of standard java classes. The folder can be created by expanding the file java\src.zip _________________________________________________________________ Sun Documentation : References The documentation within the JDK is very sparse, almost nonexistent. For example, there do not appear to be any help files. There are, however, numerous documents available from Sun's menu of java documentation . Thanks to a third party product, Bill Bercik's Information Portafilter, the most essential of these documents, including the API, are available for onscreen use in the searchable Windows Help format. Another third-party product, a book entitled, "Java in a Nutshell", by David Flanagan, published by O'Reilly & Associates, Inc., is a very useful reference book on java. It has the API indexed in several different ways, thereby addressing one of the most irritating problems in java programming: how do you find the name of the object you need, if you do not already know its name ? Finding java documents at Sun's java web site is vastly improved over the early maze-like environment, which was confusing and frustrating. The information below was assembled to aid navigation of the old maze. It still can be a time-saver. The preferred domain name for Sun's java web site is: http://java.sun.com/ If you add one of these major subdirectories to the URL, you will get to indices of pages at the site: doc/ - some, but by no means all, of the java documentation Overviews/ - mostly non-technical information about the java language and HotJava browser programmer.html - List of html files with technical information on java books/ hooked/ - material related to book "Hooked on Java" Series/ Tutorial/ applet/ - Writing java applets java/ Writing standalone java applications - meatiest part of tutorials getStarted/ - "Hello World" first programs #CORE - Using java classes nutsandbolts/ - line by line analysis of a java program objects/ - a primer javaOO/ - objects structure strings/ - Strings and string buffers cmdLineArgs/ - Setting Program Attributes threads/ - Demo of three threads in an applet running simultaneously exceptions/ -java error handling JDK/ - home page of JDK; be sure to scroll down to documentation list JDK-1.0.2/ -current release of the JDK tools/ - brief instructions for programs in java/bin api/ - see packages.html debugging/ - VERY IMPORTANT: tutorials on debugging applets and applications Pages in html format which you might wish to print out initially include: JDK tools brief introductions to the executable programs in the JDK Programming Tutorials Getting Started: The Hello World Applet Writing Applets Writing Applications Debugging Tutorials Debugging Applets Debugging Applications Application Programming Interface (API) Individual API packages for viewing or printing via browser. They can be viewed and printed via a browser as needed. API as a single zipped 766 KB file for downloading _________________________________________________________________ Sun Online Java Lessons Other information available online from Sun is in the form of Lessons in html pages, which can be read or printed from a browser. At present, these documents barely scratch the surface of what is needed to learn how to write java programs, however. They include: java objects - concepts and overview java "Hello World" first applet tutorial java applet writing tutorial java application writing tutorial java nuts and bolts - a program explained line by line When studying these documents, it helps greatly to have some previous exposure to C and C++ , i.e. to have a concept of the structure of an object-oriented programming language. Studying java then becomes an exercise in learning java's names for concepts already understood. _________________________________________________________________ Non-Sun Sources Online During the past few months, there has been a virtual avalanche of books on java. They range from big fat tomes with lots of words and pictures of applets on screens, but little sample code; to concise little books packed with code. Good luck finding just the right book to meet your needs. There are now several news groups comp.lang.java.somesubtopic . You can try many different applets, and download the source code for any of them, at The Java Boutique. Demos of many more applets are available at Gamelan. However, some will only run under the alpha API in the Hot Java browser, and the source code is not available for downloading for many which can run under the beta API . The number of non-Sun web sites has been growing rapidly during 1996. Many offer lots of useful information about java, and applets. A few sites are listed below. You can find plenty more with almost any web search engine. * Teamjava * Java Central * Club Java * Digital Espresso * Java Land - read the java fairy tales from Oak Ridge ! * Jivin' to the Java Beat - the java world as seen from Canada, spiced with near-poetic java tutorials from India * Java Developer Howdoi - offers java code snippets which solve specific programming problems * Rainer's Java-Seite - a German perspective on the java world _________________________________________________________________ First Use of Appletviewer AppletViewer is a program for extracting applets from .html files and displaying them. It is an alternative tool to a java-capable browser, one which displays only the applet instead of the entire web page. Appletviewer provides other tools of use during applet development, such as listing applet parameters, restarting the applet, cloning it, etc. When appletviewer runs, it writes the parameters extracted from the applet portion of the html, into a properties file, HOME\.hotjava\properties. The properties file can be displayed in a window which can be opened from the window in which the applet is displayed. The first time that appletviewer is run, it looks up the environmental variable HOME, then creates the folder .hotjava in HOME, and writes the first properties file in the folder HOME\.hotjava . The purpose of the HOME environmental variable is to specify the path to the .hotjava folder and properties file. Also, when appletviewer is run the first time after installation of the JDK, after the .hotjava folder and properties file are created, a window containing a copyright statement and license agreement opens. It opens in resizable form rather than the fullscreen form, but the window lacks a scroll bar. As a result, at least on an 800 x 600 display, the "I agree" checkbox at the bottom of the document is not displayed. Select the fullscreen box in the upper right corner of the window frame, and then select the "I agree" box. If this is done, that window will not open in subsequent runs of appletviewer. More important: no applet can be loaded by appletviewer until it is done. _________________________________________________________________ Displaying An Applet Alone Appletviewer can be used to see an applet running. Select Start|Programs|MSDOS Prompt| At the DOS prompt enter cd c:\java\demo\appletname (substitute the name of an applet folder for appletname) appletviewer example1.html Appletviewer finds the information specifying the applet in the example1.html file, and then displays and runs just the applet, ignoring the rest of the .html file. To exit the applet, click in the upper left corner within the applet. A dropdown menu should appear. Select exit| . If the dropdown menu does not appear, press [ctrl-C] to exit the applet. _________________________________________________________________ Displaying An Applet Within A Web Page To see what a demo applet looks like within a web page, start your java-capable browser. It can be online or offline. If you wish to have it in offline mode, allow it to perform at least one dialup before cancelling the connection attempt. In the browser, open c:\java\demo\appletname\example1.html The page and the applet within it should be loaded and displayed. _________________________________________________________________ Test Use of Compiler Select a simple demo applet, i.e. one not using sound or image files. Copy three files in the demo\appletname folder to c:\myjava appletname.java appletname.class example1.html Notes: 1. Replace "appletname" in the above filenames with the name of an actual applet folder in C:\java\demo. 2. The copy operation is most conveniently done using the Windows 95 group-copy method. Use Start|Programs|Explore| to display the contents of the c:\java\demo\appletname folder. Then hold down the [Ctrl] key while right-clicking on the icons of the three files to be copied. Then drag the group of icons to the c:\myjava icon and release the mouse button. Then select "copy here" in the drop-down menu that appears. Assuming the MSDOS window is open, and C:\myjava is the current directory, use appletviewer (see above) to satisfy yourself that the applet copied to c:\myjava works. To do so, at the DOS prompt, enter: appletviewer example1.html Then change the extension of appletname.class so it is no longer .class. For example, enter REN appletname.class appletname.xlass Note: if the rename (ren) command doesn't behave with "long" filenames, either use the dos versions, or rename the file by the Window 95 method: select Start|Explore|; then click on (+) to left of the name of the html folder to display the contents of the html folder; right-click on appletname.class file icon, then select rename| in the pop-up menu ; then edit the highlighted file name and click outside the filename object to save the change. Now try compiling. The current directory should be c:\myjava . At the DOS prompt, enter javac -verbose appletname.java (substituting the filename of the applet for "appletname") If javac works properly, the names of the .class files loaded from classes.zip will be listed in the window as the compile proceeds. If the compile is successful, a new appletname.class file will be created. Note: if you have only 8 MB of RAM in your computer, you are likely to get "Out of memory exiting. Abnormal termination" messages when you attempt to run javac while other programs are running. The best solution is to increase your RAM to at least 16 MB. Considering that the price of RAM has dropped about 75 % in the past six months, this is a very attractive time to upgrade your RAM. You can usually run javac with 8 MB of RAM if you shut down other Windows programs and reboot your computer to initialize RAM. if you installed Windows 95 as an upgrade from Windows 3.x, you may encounter "Out of memory" messages more frequently. The explanation may be that when Windows 95 was installed, a .pif file was written for the MSDOS shell program, in which memory allocations were not set to "auto". To correct this cause of "Out of memory" events, select Start|Programs|MSDOS| Then right-click on the little MSDOS icon in the upper left corner of the window. In the drop-down menu, select Properties|Memory|. Set all of the memory allocation options to "auto". You may also have an MSDOS prompt in the Group Folder Main. Verify that the memory allocation settings for that MSDOS icon are now all "auto". To do so, select Start|Open|Programs|Main|MSDOS|Memory| To see if the new appletname.class file works, again enter at the DOS prompt: appletviewer example1.html The applet should behave the same with the new .class file as the original did. After you are satisfied that the applet works, you can end appletviewer by clicking on the word "applet" in the upper left corner of the applet window. A dropdown menu should appear. Select "Exit" . However, if the applet has not worked properly, or the dropdown menu is not accessible. press {Ctrl-C], which terminates the applet display window and returns the applet command line window to the DOS shell. You are now ready to start using the JDK to create and test new java code. _________________________________________________________________ Editors and the Coding Cycle The JDK does not come with an Integrated Development Environment (IDE). However Sun and a growing list of other companies are offering IDE's for java programming. One shareware product which does the job nicely and is relatively easy to use is the KAWA IDE . Without an IDE, we are obliged to assemble the environment components we need to create/edit java source code, compile it, and see how well it works. Windows 95 includes three text editors which can handle long file names: Windows-based notepad and wordpad, and MSDOS-based edit. While any one of them can be used to create and edit .java and .html files, it is worth considering which makes possible the quickest coding cycle, each composed of edit, compile and run steps. Edit loads most rapidly, and loads an entered filename for editing most quickly. However, Edit is by no means the best of all editors. It still has the inexcusable built-in handicaps for users that Microsoft has never seen fit to remove. For example, edit cannot cut or copy and paste text beginning in the middle of one line and extending to the middle of another line, something other text editors have been able to do for at least 20 years. If multiple lines are involved, edit insists on processing only entire lines. Notepad loads a little more rapidly than Wordpad. When using either Notepad or Wordpad, the quickest way to get into editing is to enter at the Filename prompt, the full path and filename, then select Open| . Suggested Coding Cycle Procedure in the Windows 95 Environment 1. Open a text editor program window and an MSDOS shell window. If you choose to use MSDOS edit, open two MSDOS shell windows by twice selecting Start|Programs|MSDOS| In each, enter the command: cd \myjava 2. Load the file appletname.java in the editor program window. Proceed to create/edit the text of appletname.java . When ready to attempt compiling, select File|Save| 3. At the DOS prompt in the second window, enter the command: javac -verbose appletname.java 4. If the compile is unsuccessful, the errors in appletname.java will be reported by javac. To correct those errors, resume editing in the window in which the editor is still running, and still contains the text of appletname.java 5. If (when) the compile is successful, at the MSDOS prompt in the window in which javac was run, enter the command: appletviewer appletname.html Note: it is assumed that a simple appletname.html was created for testing the applet in appletviewer. 6. If the test in appletviewer revealed runtime flaws in the applet, return to the window in which the editor program is running, to resume editing appletname.java . 7. If (when) the test in appletviewer is successful, and additional features are to be added to the applet, make a copy of the working version of the applet, giving it a modified extension, e.g. appletname.java.ok_1. This can be done with the command: copy appletname.java appletname.java.ok_1 . Then resume editing appletname.java in the window in which the editor program is running. 8. When appletname.java is finished, and a satisfactory appletname.class exists, load appletname.html into java-capable browser in offline mode, using the URL: C:\myjava\appletname.html 9. After a successful loading and running of the applet in your java-capable browser, upload the appletname.class and appletname.html files to a web page directory. Verify that the files are readable by anybody. Then verify that you can load and run the .html file containing the applet, via the Internet. Finally, have someone else do it from a different computer with access to the Internet. Batch Files for Optional Command Line Aliases After you have typed "javac -verbose" and "appletviewer" at the MSDOS prompt several times, you may become interested in the possibility of using much briefer aliases for these commands. While MSDOS does not provide the aliasing capability of Unix shells, the functional equivalents of aliases can be created as batch files. First, let us create jv.bat, so that "jv" becomes an alias for javac -verbose : Select Start|Programs|MSDOS| At the MSDOS prompt, enter: cd \java\bin edit jv.bat In the editing environment, enter these lines: @echo off javac -verbose %1 Select File|Save|, File|Exit| To create av.bat, so "av" becomes an alias for appletviewer, at the MSDOS prompt, enter: cd c:\java\bin : edit av.bat In the editing environment, enter these lines: @echo off appletviewer %1 Select File|Save, File|Exit| To test these batch-file aliases, at the MSDOS prompt, enter: cd \myjava jv appletname.java (Substitute the name of a .java file in c:\myjava for appletname.) After "jv" has been successfully tested, enter: av appletname.html _________________________________________________________________ What Now ? while (success =< 0) { conceive(in_brain); compose(demo.java, any_text_editor) { while(numbugs != 0) { compile(demo.java, javac); run(demo.class, applet_containing.html, appletviewer); debug(jdb); edit(demo.java, any_text_editor); } } rework(in_brain) { while (criticisms != 0) { demo(users, applet_containing.html, demo.class, browser)); getFeedback(user_comments); edit(demo.java,any_text_editor); while(numbugs != 0) { compile(demo.java, javac); run(demo.class, applet_containing.html, appletviewer); debug(jdb); edit(demo.java, any_text_editor); } } } if exists(finished.class, nice_use.html) { market(finished.class, nice_use.html); distribute(finished.class,nice_use.html); success = succe$$_in_USA(income,expenses); } else success < 0; } _________________________________________________________________ Text Version of Menu [What is JDK?]............ .. [Lessons]................. age] [Pre-Downloa.......... ... [83][Non-Sun Sources]... [84][Compiler Test]. [Development Folder].. [Appletviewer First].. [88][Coding Cycle]...... [Variables]................... ].. [91][Applet Alone].......... [92][What Now ?