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
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
option to create our documentation.
As our code is separated into different packages we can create javadocs at the package level.
Change to directory cd c:\_Case_Study\src
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
Exploring Our API Documentation
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
We can bundle up applications we write for easy distribution and installation using
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.
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
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.
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
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.
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:
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.