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