This tutorial covers:
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.
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.
Exercises:
javadoc *.java
.
javadoc -private *.java
.
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.
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:
Add the package scheme;
declaration to the top of IList.java
.
You need to create a subdirectory called scheme
and
move IList.java
into it.
Now compile using
javac scheme/IList.javaNote 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.
Add the package
scheme
;
declaration to the top of
IEmptyList.java, INEList.java,
EmptyList.java
, NEList.java
and ListOps.java
,
and move them into the scheme
subdirectory.
Do not make TestListOps.java
and TestList.java
part of
the package. TestListOps.java
and TestList.java
do not have a package name, and are 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 TestList.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 TestListOps.java
and TestList.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 TestList
class is not part of
the scheme
package.
One way to resolve this problem by making TestList
part of
the scheme
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 TestListOps.java
and TestList.java
. You should
get no error. Try to run TestListOps.java
and TestList.java
now.
In the following exercises, assume NEList contains Integer objects only. Integer is called the wrapper class for int. You will need to use its intValue() method and its constructor Integer(int i). The detailed documentation for Integer can be found at: http://java.sun.com/j2se/1.4/docs/api/java/lang/Integer.html.
Add the following methods to IList
and its
appropriate subclasses as specified.
IList
.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/
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
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.
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 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.
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.
Prepared by D. X. Nguyen and Eric Rechlin last revised 01/27/03