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 Toolgo to top of page 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.

javadoc Options

Running javadocgo to top of page 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.

Run javadoc

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

javadoc Directory

Exploring Our API Documentationgo to top of page 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.

Looking at javadoc

Bundling Our Applicationsgo to top of page 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 Filego to top of page 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 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 file saved into the   c:\_Case_Study directory.

Create file

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

Rename file

Creating A JAR Filego to top of page 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.

jar Options

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 -C classes .

The screenshot below shows the JAR file named manufacturer.jar being created using the options specified.

jar Creation

Running Our JAR Filego to top of page 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:

Run jar 1

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

Run jar 2

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.

go to home page Homepage go to home page Top