Java 1.4 Game Programming (Wordware Game and Graphics Library)

A JAR is an archive that uses the ZIP file format to compress files stored within it. The great thing about using JARs is that it is possible to package up your applications and applets into a single JAR file and execute them directly from the compressed JAR archive. This is an excellent feature where applets are concerned, as the JAR is downloaded, decompressed, and executed from the browser (making the download smaller).

Running an Application from a JAR

Let's first look at how we can create an application that we can execute directly from the JAR archive. We will use a simple console application to output a line of text to the console for this example. The complete code listing for this application can be seen here:

Code Listing 5-5: MyApp.java

public class MyApp { public static void main(String args[]) { System.out.println("\n\nI was executed from the JAR!\n\n"); } }

Once we have our basic application in the file, we need to compile it in the usual way, leaving us with a MyApp.class file. Normally from here we would use the Java interpreter to execute the bytecode contained within the class file, but this time we wish to make it into a JAR archive.

To do this, we need to use the JAR tool, which comes with the Java SDK. The JAR tool is called jar.exe and can be found within the /bin/ directory of the SDK.

Creating an actual JAR is a simple process. However, to make our application execute from the JAR, we also require a manifest file, which simply specifies the name of the main class that should be used when the JAR is executed. In this example we will call the manifest file theManifest.txt and it will only contain a single line of text (followed by a carriage return). The following line should be placed within this file:

Main-Class: MyApp

Now that we have the manifest file and our byte code contained within our MyApp.class file, we can proceed to create our JAR archive, which we will call MyApp.jar. Note that the JAR archive does not need to share the same name as its main class. The command used to create the archive can be seen here:

jar cmf theManifest.txt MyApp.jar MyApp.class

First we have the "jar" executable and we specify cmf as a parameter, where "c" stands for "create," "m" means we wish to modify the manifest, and "f" means we wish to output the archive to a file rather than the standard output (i.e., the screen). Next we specify the name of the file our manifest is stored in, which in this case is theManifest.txt. Then we state the name of the archive that we wish to create (i.e., MyApp.jar), and finally we specify the files and/or directories to include within the archive.

When the command is executed, a file called MyApp.jar should then be visible in the same directory as your source and class file.

Now that we have the executable JAR file, we still need to use the Java interpreter to run it, but since we are using an archive, we need to specify the -jar parameter. The full command can be seen here:

java -jar MyApp.jar

Here is a screen shot of the output that we can expect when we execute the JAR archive that we have created.

Figure 5-2: Running an application from a JAR archive

Running an Applet from a JAR

Executing an applet from a JAR archive is equally as easy as running an application. First we will create a simple applet that we can use to package into a JAR file. Here is the complete code listing for the applet that we are going to archive into a JAR:

Code Listing 5-6: MyApplet.java

import java.awt.*; import javax.swing.*; public class MyApplet extends JApplet { public void init() { setSize(400, 300); } public void start() { } public void paint(Graphics g) { g.drawString("I was executed from a JAR!", 20, 20); } public void stop() { } public void destroy() { } }

Once we compile the applet in the usual way, we can then archive it using the JAR tool, as we did in the previous application example. However, this time we do not require the manifest file, as we will specify the main class in the applet tag in the HTML page that we will look at soon. Here is the command we require to archive our applet into an archive called MyApplet.jar:

jar cf MyApplet.jar MyApplet.class

All that is different here is that we have excluded the m and manifest filename parameters.

So we now have our applet in a JAR archive. We can then display the applet from the JAR in an HTML page by using the <APPLET> tag but this time add an extra parameter called archive in which we will specify the JAR file to load (note that the code parameter is then used to define the main class from within the JAR archive). Here is the complete HTML code listing for displaying the applet from the JAR file:

Code Listing 5-7: view.html

<HTML> <HEAD> <TITLE>Applet JAR Example</TITLE> </HEAD> <BODY> <CENTER><B>Applet JAR Example</B> <BR> <APPLET CODE="MyApplet.class" ARCHIVE="MyApplet.jar" WIDTH=400 HEIGHT=300> </APPLET> </CENTER> </BODY> </HTML>

So when we load the view.html file into a web browser (such as Internet Explorer or Opera), we can see that it will load from the archive and look like this:

Figure 5-3: Running an applet from a JAR archive

Note that we will look at applets in more detail in the chapters to follow.

The following table is a list of parameters that can be supplied to the JAR tool to perform various actions.

The following table is a list of optional parameters that can be used to affect the actions that you specify.

For example, we could extract the archive that we created in the applet example with the following command-line argument:

jar xf MyApplet.jar

The x action indicates that we wish to extract files, and the f option indicates that we wish to do this from the JAR file MyApplet.jar.