Herding Cats

Imagine trying to distribute an application, uncompressed, to end users: "Now downloading file 2 of 768 ". This is what my friends from Texas call herding cats. It is obviously easier to deal with one file than many files, so typically packaging involves taking the many files in your application and putting them into one or two manageable files that can then be FTP'd or copied across the network or burned onto a DVD for sale in stores.

Making One File: Packaging into a JAR

If you have used Microsoft's Visual Studio, you know that it is very easy to make a program you write into an executable file. In Java, you don't make .exe files as you do in Visual Studio. Instead, you make a JAR file, which can be executed on a system that has a Java Runtime installed. It can be a bit of a drag, more of a drag in my view than it should be for a language this mature. But there is always a trade-off between convenience and control. In the long run, it is nice to have the control; so, okay, I will stop whining about it and thank Sun for their prescience. Now let's see how to do it using the JAR tool.

Packaging Using the JAR Tool

A JAR file is a file compressed with the same algorithm used to compress Zip files. JAR stands for Java ARchive. You create a JAR file using the jar command. If you are on Windows, go to this directory: <JAVA_HOME>/bin/. This is where the tools in the SDK live, and therefore where you find the jar program.

GOT JAVA EXECUTABLES?

If you don't care about being a Java "purist" and know that all of your users are on a Windows environment, you can compile your program to native code, bundling your application as an .exe file, executable only in a Windows environment. Although the JDK does not ship with any native compilers, some IDEs allow you to do this (JBuilder for example). There are also a few free programs out there that, as you might imagine, work to greater or lesser degrees. However, as JoJo the Internet Guy says, this is not a five-star idea. You obviously lose portability, perhaps even some functionality, and there are alternatives. For example, you could write a batch file or shell script to make things a little less punishing for your users. We'll see how to do this in a moment. But if you must have things your way, here are some starting places:

JBuilder

http://www.xlsoft.com/en/products/jet/

http://www.excelsior-usa.com/jet.html

If you type jar at the console, the program will display usage options. Here, we will create a JAR file in the C:\apps directory called BlogApp.jar. It will contain all of the files with a .class extension in the target directory.

In running the command, the c is for "create," the v for "verbose" (which means, "tell us what you're doing in detail as you do it"), and f means that you will specify the resulting file name . Run the following command to create the JAR:

 C:\>jar cvf BlogApp.jar blogger added manifest adding: blogger/(in = 0) (out= 0)(stored 0%) adding: blogger/BloggerFrame.class(in = 1017) (out=564) (deflated 44%) adding: blogger/BloggerFrame.class(in = 864) (out=479) (deflated 44%) adding: blogger/BloggerFrame.class(in = 828) (out=458) (deflated 44%) adding: blogger/BloggerFrame.class(in = 741) (out=401) (deflated 45%) adding: blogger/BloggerFrame.class(in = 3801) (out=1945) (deflated 48%) adding: blogger/BloggerKeys.class(in = 670) (out=422) (deflated 37%) adding: blogger/blogs/(in = 0) (out= 0)(stored 0%) adding: blogger/blogs/blog.html(in = 52) (out= 42) (deflated 19%) adding: blogger/StartApp.class(in = 884) (out= 520) (deflated 41%) C:\>

Executing the command, as the output shows, creates a new file in the current directory called blogger.jar. Class files are compressed as added, and a manifest is created. A manifest is a text file that specifies meta data about your application. It must be in a directory called META-INF and the file itself must be called MANIFEST.MF (both the file and the directory are all uppercase). The chief purpose of the manifest file is to point the runtime to the location of the class file containing the main method so it can start the program.

Adding the Manifest

The JAR tool can create a manifest for you if none exists. But then it will not contain some necessary information, such as the class containing the main method. You will need to then extract the JAR, add the information to the manifest, and recompress the JAR. Might as well just create the manifest right off the bat.

Navigate into the JAR and open the META-INF directory and then the MANIFEST.MF file. This is a plain text file in which you can specify things that you want the application to know at runtime. Although the JAR tool created this folder and this file, it did not pick out for us the class with the main method, which it will need to know in order to start the application automatically. So, we will just write our own manifest in a plain ASCII text file. Do this:

Make sure that your classes are compiled in the appropriate structure (that is, in their packages).
Write a plain text file called manifest.mf. In this file, type the following: Main-Class: package.otherpackage.MainClass. Do not include the .class extension. Your text here will be used as an entry in the real MANIFEST.MF file produced by the JAR tool.
Navigate to the working directory one level above the first-level package in your app.
Run the jar command like so: jar -cvmf MANIFEST.MF MyApp.jardirectory/subdirectory, where subdirectory contains your class files.

This will create a JAR file called MyApp.jar in the current working directory:

 jar -cmf MANIFEST.MF MyApp.jar     net/javagarage/test/StartApp

Note that there are many different subtle ways to manipulate JAR file creation. Check out the usage information if you need more control.