Comp 212 Lab 3: JavaDoc, Package, Immutable Lists

Introduction

This tutorial covers:

• Java documentation style and JavaDoc, a tool for generating documentation in html format,
• Java Packages for the purpose of grouping related classes and hiding classes that clients should not have access to.
• Some exercises on the immutable list structure.

I. Java Documentation Style

The Java Development Kit (JDK) comes with a tool called JavaDoc.  This tool will generate documentation for Java source code with comments written in accordance with the Java documentation style.   The following links show more examples.  You do need to spend time outside of the lab to study them.

• javadoc
• Writing doc comments
• Comments Conventions

Copy this tutorial directory (~comp212/public_html/01-fall/labs/03/ or click here to download a single zipped file containing all the Java code) into your own directory. It includes Java source code for a version of lists. Use Emacs to look at both the code and the comments, which follow the Javadoc conventions.

Exercises:

1. Run the javadoc utility on the Java code by executing the command
       javadoc *.java.   
   Many html files will be generated.  Use a browser to view them.  Does the documentation include descriptions of the private fields and methods?
   Now execute the command
       javadoc -private *.java. 
   What is the difference?
   

2. Now try simply
   javadoc
   Like many UNIX commands, running the program without specifying any options will provide a brief description of its possible usage. Take a brief look at the explanation of the flags. In particular, note the -d flag for putting the documentation into a separate directory.

3.  

II. Package

A Java package is a grouping of classes similar to the notion of a directory is a grouping of files. Packages are used to help avoid name clashes and to hide particular pieces of code from the clients. A package has a name, such as utility or java.lang.util. In general, a package name is a series of strings of alphanumeric characters (starting with an alphabetic character) and separated by periods. To make a java class part of a particular package, say scheme, you must add the declaration package scheme; to the very top of the class source file.

Also, you will need to put the file in the directory structure that mirrors the package name. For example, the java classes that belong to the package scheme should be in a directory also named scheme. If you don't do this, it will still compile, but it won't run correctly.

Exercises:

1. Add the package scheme; declaration to the top of AList.java. You need to create a subdirectory called scheme and move AList.java into it.

   Now compile using

        javac scheme/AList.java
        

   Note that you should always compile from your project's main directory. If you compile from within a package subdirectory, it doesn't find all the supporting definitions.

   We can't run anything yet, because that's just a piece of the whole program.

2. Add the package scheme; declaration to the top of EmptyList.java and NEList.java, and move them into the scheme subdirectory. Do not make ListClient.java part of the package. ListClient.java does not have a package name, and it thus said to be in the no-name (or default) package.  

   Also, remove the public access from the EmptyList and NEList classes. By default, a class is "package-private", i.e., it is known within the package, but not from outside. If you try to compile ListClient.java now, you will get an error message. Try it to see what happens.

   You need to add the statement import scheme.*; to the top of ListClient.java to indicate to the compiler that you are using all the public classes in that package. Try to compile it again.

   You should see a few error messages saying that you can't use EmptyList.java and NEList.java because these classes are not public. This is because the ListClient class is not part of the list package. One way to resolve this problem by making ListClient part of the list package. A class of a package can access all the classes (public or "package-private") in the package. However this is not a good solution in general because a client may be using many classes from different packages, but not class can be part of more than one package. A better solution is to use a "factory".  We will discuss factories in another lab.  For now, just make EmptyList.java and NEList.java public again, and recompile ListClient.java. You should get no error.  Try to run ListClient now.

III. List Exercises

In the following exercises, assume NEList contains Integer objects only.  (Recall Integer is the wrapper class for int as discussed in class.)  Add the following methods to AList and its appropriate subclasses as specified.

1. public int sum(): compute and return the sum of the Integer elements in this AList.
2. public boolean containsAllNonNegative(): returns true if all the Integer elements in this AList are non-negative (>= 0), false otherwise.
3. public int nonNegCount(): computes and returns the number of non-negative Integer elements in this AList.
4. public boolean hasMostlyNonNeg(): returns true if this AListcontains more non-negative (>= 0) Integer elements than negative (< 0) ones, false otherwise.