School of Engineering and Applied Science
Department of Computer Science
CSci 133 -- Algorithms and Data Structures I
http://www.seas.gwu.edu/~csci133/spring05
Prof. Michael B. Feldman
mfeldman@gwu.edu

Lab Exercise #2
for lab meeting Friday, Jan. 28, 2005

Objectives: As we know, Java is very fussy about your directory structure: the compiler expects certain packages and classes to be in certain (sub-)directories and gives compilation errores if it can't find what it needs in the expected places. The purpose of this lab is to give you some experience with Java directory structures and to help you familiarize yourself with the directory structures we'll use in this course.

Once you completed lab 1, you were left with this directory structure:

your top-level directory
csci53
programs53 (a shortcut to Feldman's directory of programs from the Lewis & Loftus book)
csci133
cs1 (currently contains the Keyboard class)
mbf (Feldman's classes, currently contains the Screen class)
programs133 (a shortcut to Feldman's directory of files from the Lewis & Chase book)
jss2 (a subdirectory of reusable classes from Lewis & Chase)
exceptions (an inner directory of exception class files)

Assignment:

Part 1: Setting up the directories.

  1. Create another subdirectory of your own, csci133/jss2, which will contain any reusable classes you copy from Feldman's programs133/jss2 directory, and yet another, programs133/jss2/exceptions, to contain any exceptions you copy.
  2. Copy the application program Bingo.java, from programs133 into your own csci133 directory.
  3. Examine this file; to compile it, you'll have to copy what it imports. Notice that it imports jss2.ArrayBag. So copyArrayBag.java from programs133/jss2 to your csci133/jss2.
  4. Now examine ArrayBag.java; note that it implements the interface BagAdt, and imports from jss2. Copy the necessary files. (It also imports from the standard API's; you always have access to these without copying them.)
  5. Now compile each of the files you've copied, startiing from the lowest directory and moving back to Bingo.java.
  6. Run Bingo.

Part 2: Visiting the Sun website to explore the APIs

Let's go to the Sun website and look at the "official" documentation of a few standard classes we've encountered in the course.

Open a Netscape window and go to http://java.sun.com. At the right side of this page, you'll see a link to J2SE1.4 APIs. Click on this link. You'll see 3 frames: the ones on the left are indexes to the packages and classes; the large window shows the details of a particular package or class.

In the class index, scroll down to Math and click. Now in the large window, scroll down to the method summary; you'll start to see some familiar methods. Try to make some sense of all the stuff at the top of the window; it isn't necessary to really understand it at this point.

Now do the same with Random and String. The objective here is not necessarily to understand all the details of each class and each method, but rather to just familiarize yourself with how Sun documents these things.

Part 3: Using javadoc to document a course-specific class

First let's take a look at how javadoc does its thing. In your ssh window, bring mbf/Screen.java into the editor, and look carefully at the comments for each method. Now in your browser, go to www.seas.gwu.edu/~csci133/documents, and then click on Screen. Compare the javadoc pages with the Java source code.

Now let's try actually using javadoc. Since javadoc generates web documents, you'll have to use your own SEASCF personal website to use it meaningfully. To do this, you're going to
  1. Let's get your website ready. Open an ssh window to hobbes, and a second ssh window to cobweb.seas.gwu.edu. This is the machine SEASCF has allocated to student websites. Use your regular SEASCF userid and password to log in to both computers.
  2. In your cobweb window, list the directory. You'll see a subdirectory called public_html. Move to this directory; it is where your public web documents reside.
  3. In your public_html directory, create a new directory called csci133docs. Type
    mkdir csci133docs

    4. and then move to this new subdirectory.
  4. Now go back to your hobbes window. Move to your csci133 directory, and use vi to add javadoc comments to each of the methods in the jss2/ArrayBag class. Just above the code for each method, add these lines:

    5. /**
    *  write a 1-line description of the method
    */

    The /* and */ comment markers are those of Java's C ancestor. They are legal in Java, but they are used mostly for javadoc annotations. /* followed by an extra * is recognized by javadoc to mean "begin a javadoc annotation". Add similar lines to the other two methods, save the file, and quit the editor.
  5. Now you'll move this file over to cobweb using the ncftp file-transfer client. Let's say your userid is george. Type

    6. ncftp -u george tangle
    and enter your password when prompted. Once you get to cobweb, move to public_html/csci133docs. Then transfer the file by typing
    put jss2/ArrayBag.java
    then quit ncftp
    quit
     
  6. Now you are ready to run javadoc. Go back to your cobweb window and type

    7. javadoc *.java
    and observe the messages. When javadoc is done, you should have a set of html files, as well as one or more subdirectories containing more html files.
  7. Now you need to make these files readable from a browser, by changing the Unix permissions. First look at the existing pemissions: type

    8. ls -l
    you'll see a bunch of codes next to each file name, something like
    -rw-------   1 george user  685 Nov  5 00:04 allclasses-frame.html

    The codes on the left indicate that on the html files, you (the user) have read/write permissions and nobody else has any. On the Java file, others have read access. Now type

    chmod -Rf 755 *

    which means "change the mode (permissions) on all files to "everyone can read and execute and I can also delete". List the directory again; now it looks like
    -rwxr-xr-x   1 george user  685 Nov  5 00:04 allclasses-frame.html

  8. Now you can go back to your Netscape window, and go to your website at

    9. http://student.seas.gwu.edu/~george/csci133docs
    Browse around and see what javadoc put there.
This is all rather involved and a bit tricky; this is mostly because, for security reasons, SEASCF put the web server, cobweb/tangle, on a different computer from the regular server,hobbes. It's a lot easier once you've done it a few times.

Part 4: Using javadoc in the rest of the course, to document your project class files

Now you can use javadoc to document your own classes!

(end of lab)