Javadocs & Jar FileHomepage « Case Study « Javadocs & Jar File
In our first lesson of the section we create documentation for the case study by running the javadoc
tool on the packages we have coded. This will extract the HTML style comments we
have written in the source files and produce a top level folder and subfolders for the packages. We then wrap all our files up neatly in a JAR
file so we can easily distribute them and
to also show usage of the -jar
command.
The javadoc
Tool
Top
The javadoc
tool comes with a lot of options as you can see from the following screenshot. You can explore the various options at your leisure but we will just be using the -d
option to create our documentation.

Running javadoc
Top
As our code is separated into different packages we can create javadocs at the package level.
Change to directory cd c:\_Case_Study\src
Run the javadoc
tool using the -d
option javadoc -d ..\javadoc client model remoteservices services
The following screenshot shows the results of running the javadoc
tool on our source packages and the files and directories created.

This screenshot shows the files and directories created in the javadoc
folder.

Exploring Our API Documentation
Top
Change to directory cd c:\_Case_Study\sysdoc
The following screenshot shows us typing index.html from the command prompt and the resultant HTML displayed in Firefox on my Windows 7 machine. The
documentation produced should be familiar in style as it matches that produced for the offical API documentation. Although using javadoc
has an initial effort by the end of the project
we have a documented API for others to use in the future. Well worth the initial effort and a good practice to get into.

Bundling Our Applications
Top
We can bundle up applications we write for easy distribution and installation using WAR
and JAR
files. WAR is an acronym for Web Archive, is not part of the
Java6 certification and is beyond the scope of these tutorials. JAR is an acronym for Java Archive and is part of the Java6 certification and will also be discussed here.
Creating A Manifest.mf
File
Top
Before we create a JAR
file we will need to create a manifest file. A manifest file is used by the JVM to load the correct class when we come to run our application from a
JAR
. Open your text editor and cut and paste the following lines into it. Name the file Manifest.mf
and save it in the c:\_Case_Study directory.
Manifest-Version: 1.0
Main-Class: client.ManufacturerApplicationStartup
Warning:The text file must end with a new line or carriage return, as the last line which in our example is
Main-Class: client.ManufacturerApplicationStartup
will not be parsed properly if it does not end with a new line or carriage return.
The following screenshot shows the contents of the Manifest.mf
file saved into the c:\_Case_Study directory.

If your saved manifest.mf
file has been suffixed with a .txt
extension as shown in the following screenshot just use the ren
option to rename it correctly.

Creating A JAR
File
Top
The following screenshot shows the jar
command which gives us quite a few options for archiving our applications and classes into a JAR file. The most commonly used options are
c
, v
, f
and m
which can be specified in any order you like. The main thing to remember when using the jar
command options is that the
actual values you enter must correalate with the order in which the options are entered.

When we create our JAR
file we will need to include the location and name of the manifest file we created. The following command typed from within the c:\_Case_Study
directory will create a JAR
file called manufacturer.jar
containing our packaged classes. Make sure you include the period at the end.
jar -cvfm manufacturer.jar Manifest.mf -C classes .
The screenshot below shows the JAR
file named manufacturer.jar
being created using the options specified.

Running Our JAR
File
Top
We can run our JAR
file in the usual way using the java
option and specifying the -jar
command, the name of the JAR
file, followed by any command line arguments.
Because the complete Manufacturer application is packaged within the JAR
file we can run the JAR
file from anywhere on our machine using an absolute path:

Or by just using a relative path from the directory the JAR
file resides in as shown by the following screenshot:

What's Next?
That's it for the case study and as this is the last section of the site, I really hope the lessons helped with your journey into the world of Java.