jar files are used to bundle all files needed to run an application into one archive file. This has lots of advantages which are explained, for example, in the Java tutorial on jar files.

I asked you to produce a .jar file for the Voca exercise just so that there was only one file VOCA.jar for the CourseMaster to load and we knew that your program should run if we type

java -jar VOCA.jar ourTestingFile.voc
leaving you completely free to write as many class files as you want and also use additional resource files like images and sounds.

We also asked you to put all your source files in another archive VOCA.tar so that the markers could actually see your code.

If your program does not use any resource files (e.g. images) you only need to read sections on making tar files and jar files. If you use resource files, read the section on accessing resources within jar files as well. Finally, if you are interested in putting applets in a jar, read the section on applets.

Making .tar files

To put files called,, in a .tar file called VOCA.tar (on Unix), To see what's in your tar file, type:
tar tvf VOCA.tar 
To unpack the tar file, type:
tar xvf VOCA.tar
For more in-depth information, type (on Unix):
man tar

Making .jar files

Suppose (just an example!) that after you compiled your program, the following .class files have been generated: Voca.class, GUI.class, Question.class, GUI$1.class, GUI$2.class (the latter two are anonymous classes corresponding to some event listeners). All those class files are needed to run your program, so they all should go in VOCA.jar. In addition, suppose that you use two image files french.gif and english.gif. Finally, suppose that the main() method is in the Voca class. To make an archive VOCA.jar which will be runnable by typing
java -jar VOCA.jar ourTestingFile.voc
If you did not use images or other resource files, you should be fine now. If you did, read on.

Accessing files inside a .jar file

If you used a standard simple way of loading an image file into the program, e.g.
ImageIcon fr = new ImageIcon("french.gif");
the image is not loaded any more. The same holds for reading from default.voc if you bundled it in the VOCA.jar: the file is not found. Unfortunately you need to change your program.

Sounds and images

You need to replace
ImageIcon fr = new ImageIcon("french.gif");
URL url = MyClass.class.getResource("french.gif"); 
ImageIcon icon = new ImageIcon(url);
where MyClass is the class which needs to load the resource (e.g. Voca, or GUI). Same for .au files.

For more in-depth information, read about the Class class and getResource() method in Java 1.3 API.

Warning: apparently there are problems with using this method in applets packaged as a jar file. Some versions of Netscape consider it a security violation. There is also a bug (again reported for Applets) in accessing resource files placed in subdirectories rather than on the top level (e.g. if you do

jar cvmf manifest-addition VOCA.jar classes/ images/
with all your class files in the classes/ directory and all images in the images/ directory.)

Opening a stream to a file

To open a stream to a file inside the same .jar archive, again it is not enough to provide the file name. You need to use getResourceAsStream() method of the Class class, for example
InputStream in = Voca.class.getResourceAsStream("default.voc");
BufferedReader br = new BufferedReader(new InputStreamReader(in));

Note: apparently Netscape is happy with applets opening a file in the .jar archive using getResourceAsStream() rather than getResource().

Applets in a jar

To put an applet and all its auxiliary files in a jar file, you do the same things as for an application, only you don't need to bother about adding the Main-Class declaration to the manifest. To put the applet on a web page, use
<APPLET CODE="MyClass.class" ARCHIVE="MyJar.jar" WIDTH=500 HEIGHT=500> </APPLET>
Beware of the problems mentioned in italics in the
previous section.