Comp 212 Lab 3: JavaDoc, Package, JAR, 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.
• Java Archive (jar) utility to compress files for distribution and execution of java applications.
• Some exercises on the immutable list structure to help prepare for homework 02.

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

Click here to download a single jar file (listSource.jar) containing sample Java code into your own directory.  It includes Java source code for a version of lists discussed in the past few lectures.  Extract the files from the jar file using the command:

jar xf listSource.jar

Section III below will provide a more detailed discussion of the JDK's JAR utility.

Use Emacs to look at both the code and the comments, which follow the Javadoc conventions.  The following is a very short summary of the Javadoc conventions.

• Comments are enclosed in between /** and */ and must immediately precede the java constructs (e.g. class, field, method) that are to be commented.
• Each method should have a comment that describes the purpose of the method.
• Each method should have a comment for each parameter,  if any.  The comment for a parameter has the form:
  • @param parameter-name some-description
•  Each function method should have a comment for the returned object.  The comment for the returned object has the form:
  • @return some-description
• Each method should have a comment for each exception thrown, if any.  The comment for an exception has the form:
  • @exception exception-type some-description

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.

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. TestLength.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 TestLength.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 TestLength.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 TestLength class is not part of the list package. One way to resolve this problem by making TestLength 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 TestLength.java. You should get no error.  Try to run TestLength now.

JAR (Java ARchive) files are special files that contain Java applications.  They generally contain either compiled Java code or Java source code; when properly designed, they also allow Java applications to be easily distributed and executed.

Despite the fancy name (and its resemblance to the tar extension used by the Unix tape archive command), JAR files are actually zip files in disguise.  Zip is a popular file compression format developed by PKWare.  This means you can also create and modify JAR files with your favorite zip compression tool. JAR files are intended to be created with the jar utility from the JDK, however.

More detailed information on JAR files is available on the Sun web site: http://java.sun.com/docs/books/tutorial/jar/

Extracting JAR files

Since JAR files are just zip files, you should be able to use your favorite zip compression tool (the command unzip works under Unix) to decompress them.  You can also use the jar command with the following syntax (the 'x' means to extract and the 'f' means to use the given JAR file):

jar xf jarfile.jar

Creating source code JAR files

To create a simple, non-executable JAR file use the following command:

jar cfv jarfile.jar list of files to-put-in-jar-file

The 'c' means create a JAR file, the 'f' means to save the JAR file to a file rather than printing it to stdout, and the 'v' means to be more verbose, particularly if an error occurs.  The following is a more concrete example.

jar cfv listSource.jar AList.java EmptyList.java NEList.java

The above command will create a jar file called listSource.jar, compress AList.java, EmptyList.java, NEList.java, and add the compressed filed to listSource.jar.

Passing filenames on the Unix command line and JAR creation examples

When creating JAR files, the last arguments on the command line are the files to include in the JAR file.  Unix is very powerful and allows many tricks in passing the filenames.  One way to give it filenames is to simply give it wildcards like this:

jar -cfv hw02.jar *.java docs/*.html docs/*.png

That command will create a simple source code JAR file named hw02.jar containing all *.java files in the current directory and all *.png and *.html files in the docs/ subdirectory.  This assumes that you told StructureBuilder to generate documentation in the docs/ subdirectory, of course.

Simply putting a '.' (a period) in place of the file listing tells jar to include the current directory and all subdirectories:

jar cfv hw02.jar .

Creating executable JAR files

Creating an executable JAR file that allows the application to be run with the java -jar command is slightly more difficult.

First, make a file called "manifest" with the following contents:

Main-Class: classDirectory/ClassName

This identifies the main class of your Java application - in other words, the one with the main() method. The "classDirectory/" part is optional and is only required if the main class is in a subdirectory.  The "ClassName" part must not include the .class extension.

Next, run the jar command with the following syntax:

jar cfvm filename.jar manifest files-to-put-in-jar-file

The 'm' means to use the manifest file stored in the file with the name of the parameter after the filename.jar file parameter (in this case, "manifest").  The files that you put in should be the compiled .class files.

All the compiled .class files must be included for this to work properly.

This is the type of JAR file you are most likely to create when sharing your Java application with friends. The resulting JAR file can be run with the java -jar command listed below.

Using JAR files

In order to run a compiled Java application packaged in a JAR file, simply use the following syntax:

java -jar jarfile.jar

If you have JDK properly set up on a Windows machine, you should be able to run the JAR files by simply double-clicking on them.

IV. 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.