General

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 File1.java, File2.java, File3.java in a .tar file called VOCA.tar (on Unix),

make sure that your are in the directory where the files are

type:

tar cvf VOCA.tar File1.java File2.java File3.java

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

create a text file called manifest-addition
put a single line there (followed by carriage return):
```
Main-Class: Voca
```
make sure you are in the same directory as all the files you need and the manifest-addition

type:

jar cvmf manifest-addition VOCA.jar  Voca.class  GUI.class  Question.class 
GUI$1.class  GUI$2.class french.gif english.gif

to check what's in the archive, type:
```
jar tvf VOCA.jar
```
to test it, move it to another directory; put default.voc there or any other file in the .voc format; type
```
 
java -jar VOCA.jar 
```
or
```
 
java -jar VOCA.jar other.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");

with

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.