飛奔嘅蝸牛

The Java^TM platform contains several classes for use with JAR files. Some of these APIs are:

• The java.util.jar package


• The java.net.JarURLConnection class


• The java.net.URLClassLoader class

To give you an idea of the possibilities that are opened up by these new APIs, this lesson guides you through the inner workings of a sample application called JarRunner.

An Example – The JarRunner Application

JarRunner enables you to run an application that’s bundled in a JAR file by specifying the JAR file’s URL on the command line. For example, if an application called TargetApp were bundled in a JAR file at http://www.xxx.yyy/TargetApp.jar, you could run the application using this command:

java JarRunner http://www.xxx.yyy/TargetApp.jar

In order for JarRunner to work, it must be able to perform the following tasks, all of which are accomplished by using the new APIs:

• Access the remote JAR file and establish a communications link with it.


• Inspect the JAR file’s manifest to see which of the classes in the archive is the main class.


• Load the classes in the JAR file.

The JarRunner application consists of two classes, JarRunner and JarClassLoader. JarRunner delegates most of the JAR-handling tasks to the JarClassLoader class. JarClassLoader extends the java.net.URLClassLoader class. You can browse the source code for the JarRunner and JarClassLoader classes before proceeding with the lesson:

• JarRunner.java


• JarClassLoader.java

This lesson has two parts:

The JarClassLoader Class

This section shows you how JarClassLoader uses some of the new APIs to perform tasks required for the JarRunner application to work.

The JarRunner Class

This section summarizes the JarRunner class that comprises the JarRunner application.

The JarClassLoader class extends java.net.URLClassLoader. As its name implies, URLClassLoader is designed to be used for loading classes and resources that are accessed by searching a set of URLs. The URLs can refer either to directories or to JAR files.

In addition to subclassing URLClassLoader, JarClassLoader also makes use of features in two other new JAR-related APIs, the java.util.jar package and the java.net.JarURLConnection class. In this section, we’ll look in detail at the constructor and two methods of JarClassLoader.

The JarClassLoader Constructor

The constructor takes an instance of java.net.URL as an argument. The URL passed to this constructor will be used elsewhere in JarClassLoader to find the JAR file from which classes are to be loaded.

public JarClassLoader(URL url) {

    super(new URL[] { url });

    this.url = url;

}

The URL object is passed to the constructor of the superclass, URLClassLoader, which takes a URL[] array, rather than a single URL instance, as an argument.

The getMainClassName Method

Once a JarClassLoader object is constructed with the URL of a JAR-bundled application, it’s going to need a way to determine which class in the JAR file is the application’s entry point. That’s the job of the getMainClassName method:

public String getMainClassName() throws IOException {

    URL u = new URL(“jar”, “”, url + “!/”);

    JarURLConnection uc = (JarURLConnection)u.openConnection();

    Attributes attr = uc.getMainAttributes();

    return attr != null

                   ? attr.getValue(Attributes.Name.MAIN_CLASS)

                   : null;

}

You may recall from a previous lesson that a JAR-bundled application’s entry point is specified by the Main-Class header of the JAR file’s manifest. To understand how getMainClassName accesses the Main-Class header value, let’s look at the method in detail, paying special attention to the new JAR-handling features that it uses:

The JarURLConnection class and JAR URLs

The getMainClassName method uses the JAR URL format specified by the java.net.JarURLConnection class. The syntax for the URL of a JAR file is as in this example:

jar:http://www.xxx.yyy/jarfile.jar!/

The terminating !/ separator indicates that the URL refers to an entire JAR file. Anything following the separator refers to specific JAR-file contents, as in this example:

jar:http://www.xxx.yyy/jarfile.jar!/mypackage/myclass.class

The first line in the getMainClassName method is:

URL u = new URL(“jar”, “”, url + “!/”);

This statement constructs a new URL object representing a JAR URL, appending the !/ separator to the URL that was used in creating the JarClassLoader instance.

The java.net.JarURLConnection class

This class represents a communications link between an application and a JAR file. It has methods for accessing the JAR file’s manifest. The second line of getMainClassName is:

JarURLConnection uc = (JarURLConnection)u.openConnection();

In this statement, URL instance created in the first line opens a URLConnection. The URLConnection instance is then cast to JarURLConnection so it can take advantage of JarURLConnection‘s JAR-handling features.

Fetching Manifest Attributes: java.util.jar.Attributes

With a JarURLConnection open to a JAR file, you can access the header information in the JAR file’s manifest by using the getMainAttributes method of JarURLConnection. This method returns an instance of java.util.jar.Attributes, a class that maps header names in JAR-file manifests with their associated string values. The third line in getMainClassName creates an Attributes object:

Attributes attr = uc.getMainAttributes();

To get the value of the manifest’s Main-Class header, the fourth line of getMainClassName invokes the Attributes.getValue method:

return attr != null

               ? attr.getValue(Attributes.Name.MAIN_CLASS)

               : null;

The method’s argument, Attributes.Name.MAIN_CLASS, specifies that it’s the value of the Main-Class header that you want. (The Attributes.Name class also provides static fields such as MANIFEST_VERSION, CLASS_PATH, and SEALED for specifying other standard manifest headers.)

The invokeClass Method

We’ve seen how JarURLClassLoader can identify the main class in a JAR-bundled application. The last method to consider, JarURLClassLoader.invokeClass, enables that main class to be invoked to launch the JAR-bundled application:

public void invokeClass(String name, String[] args)

    throws ClassNotFoundException,

           NoSuchMethodException,

           InvocationTargetException

{

    Class c = loadClass(name);

    Method m = c.getMethod(“main”, new Class[] { args.getClass() });

    m.setAccessible(true);

    int mods = m.getModifiers();

    if (m.getReturnType() != void.class || !Modifier.isStatic(mods) ||

        !Modifier.isPublic(mods)) {

        throw new NoSuchMethodException(“main”);

    }

    try {

        m.invoke(null, new Object[] { args });

    } catch (IllegalAccessException e) {

        // This should not happen, as we have disabled access checks

    }

}

The invokeClass method takes two arguments: the name of the application’s entry-point class and an array of string arguments to pass to the entry-point class’s main method. First, the main class is loaded:

Class c = loadClass(name);

The loadClass method is inherited from java.lang.ClassLoader.

Once the main class is loaded, the reflection API of the java.lang.reflect package is used to pass the arguments to the class and launch it. You can refer to the tutorial on The Reflection API for a review of reflection.

Now that you’ve learned how to create JAR files, how do you actually run the code that you’ve packaged? Consider these three scenarios:

• Your JAR file contains an applet that is to be run inside a browser.


• Your JAR file contains an application that is to be invoked from the command line.


• Your JAR file contains code that you want to use as an extension.

This section will cover the first two situations. A separate trail in the tutorial on the extension mechanism covers the use of JAR files as extensions.

Applets Packaged in JAR Files

To invoke any applet from an HTML file for running inside a browser, you need to use the APPLET tag. For more information, see the Applets lesson. If the applet is bundled as a JAR file, the only thing you need to do differently is to use the ARCHIVE parameter to specify the relative path to the JAR file.

As an example, let’s use (again!) the TicTacToe demo applet that ships with the Java^TM Development Kit. The APPLET tag in the HTML file that calls the demo looks like this:

<applet code=TicTacToe.class

        width=120 height=120>

</applet>

If the TicTacToe demo were packaged in a JAR file named TicTacToe.jar, you could modify the APPLET tag with the simple addition of an ARCHIVE parameter:

<applet code=TicTacToe.class

        archive=”TicTacToe.jar”

        width=120 height=120>

</applet>

The ARCHIVE parameter specifies the relative path to the JAR file that contains TicTacToe.class. This example assumes that the JAR file and the HTML file are in the same directory. If they’re not, you would need to include the JAR file’s relative path in the ARCHIVE parameter’s value. For example, if the JAR file was one directory below the HTML file in a directory called applets, the APPLET tag would look like this:

<applet code=TicTacToe.class

        archive=”applets/TicTacToe.jar”

        width=120 height=120>

</applet>

JAR Files as Applications

You can run JAR-packaged applications with the Java interpreter. The basic command is:

java -jar jar-file

The -jar flag tells the interpreter that the application is packaged in the JAR file format. You can only specify one JAR file, which must contain all the application-specific code.

Before you execute this command make sure the runtime environment has an information of which class within the JAR file is the application’s entry point.

To indicate which class is the application’s entry point, you must add a Main-Class header to the JAR file’s manifest. The header takes the form:

Main-Class: classname

The header’s value, classname, is the name of the class that’s the application’s entry point.

For more information, see the Setting an Application’s Entry Point section.

When the Main-Class is set in the manifest file, you can run the application from the command line:

java -jar app.jar

The Jar tool provides a u option which you can use to update the contents of an existing JAR file by modifying its manifest or by adding files.

The basic command for adding files has this format:

jar uf jar-file input-file(s)

In this command:

• The u option indicates that you want to update an existing JAR file.


• The f option indicates that the JAR file to update is specified on the command line.


• jar-file is the existing JAR file that’s to be updated.


• input-file(s) is a space-deliminated list of one or more files that you want to add to the Jar file.

Any files already in the archive having the same pathname as a file being added will be overwritten.

When creating a new JAR file, you can optionally use the -C option to indicate a change of directory. For more information, see the Creating a JAR File section.

Examples

Recall that TicTacToe.jar has these contents:

META-INF/MANIFEST.MF

TicTacToe.class

audio/

audio/beep.au

audio/ding.au

audio/return.au

audio/yahoo1.au

audio/yahoo2.au

images/

images/cross.gif

images/not.gif

Suppose that you want to add the file images/new.gif to the JAR file. You could accomplish that by issuing this command from the parent directory of the images directory:

jar uf TicTacToe.jar images/new.gif

The revised JAR file would have this table of contents:

META-INF/MANIFEST.MF

TicTacToe.class

audio/

audio/beep.au

audio/ding.au

audio/return.au

audio/yahoo1.au

audio/yahoo2.au

images/

images/cross.gif

images/not.gif

images/new.gif

You can use the -C option to “change directories” during execution of the command. For example:

jar uf TicTacToe.jar -C images new.gif

This command would change to the images directory before adding new.gif to the JAR file. The images directory would not be included in the pathname of new.gif when it’s added to the archive, resulting in a table of contents that looks like this:

META-INF/MANIFEST.MF

TicTacToe.class

audio/

audio/beep.au

audio/ding.au

audio/return.au

audio/yahoo1.au

audio/yahoo2.au

images/

images/cross.gif

images/not.gif

new.gif

The basic command to use for extracting the contents of a JAR file is:

jar xf jar-file [archived-file(s)]

Let’s look at the options and arguments in this command:

• The x option indicates that you want to extract files from the JAR archive.


• The f options indicates that the JAR file from which files are to be extracted is specified on the command line, rather than through stdin.


• The jar-file argument is the filename (or path and filename) of the JAR file from which to extract files.


• archived-file(s) is an optional argument consisting of a space-separated list of the files to be extracted from the archive. If this argument is not present, the Jar tool will extract all the files in the archive.

As usual, the order in which the x and f options appear in the command doesn’t matter, but there must not be a space between them.

When extracting files, the Jar tool makes copies of the desired files and writes them to the current directory, reproducing the directory structure that the files have in the archive. The original JAR file remains unchanged.

---

Caution: When it extracts files, the Jar tool will overwrite any existing files having the same pathname as the extracted files.

---

An Example

Let’s extract some files from the TicTacToe JAR file we’ve been using in previous sections. Recall that the contents of TicTacToe.jar are:

META-INF/MANIFEST.MF

TicTacToe.class

audio/

audio/beep.au

audio/ding.au

audio/return.au

audio/yahoo1.au

audio/yahoo2.au

images/

images/cross.gif

images/not.gif

Suppose you want to extract the TicTacToe class file and the cross.gif image file. To do so, you can use this command:

jar xf TicTacToe.jar TicTacToe.class images/cross.gif

This command does two things:

• It places a copy of TicTacToe.class in the current directory.


• It creates the directory images, if it doesn’t already exist, and places a copy of cross.gif within it.

The original TicTacToe JAR file remains unchanged.

As many files as desired can be extracted from the JAR file in the same way. When the command doesn’t specify which files to extract, the Jar tool extracts all files in the archive. For example, you can extract all the files in the TicTacToe archive by using this command:

jar xf TicTacToe.jar

The basic format of the command for creating a JAR file is:

jar cf jar-file input-file(s)

The options and arguments used in this command are:

• The c option indicates that you want to create a JAR file.


• The f option indicates that you want the output to go to a file rather than to stdout.


• jar-file is the name that you want the resulting JAR file to have. You can use any filename for a JAR file. By convention, JAR filenames are given a .jar extension, though this is not required.


• The input-file(s) argument is a space-separated list of one or more files that you want to include in your JAR file. The input-file(s) argument can contain the wildcard * symbol. If any of the “input-files” are directories, the contents of those directories are added to the JAR archive recursively.

The c and f options can appear in either order, but there must not be any space between them.

This command will generate a compressed JAR file and place it in the current directory. The command will also generate a default manifest file for the JAR archive.

---

Note: The metadata in the JAR file, such as the entry names, comments, and contents of the manifest, must be encoded in UTF8.

---

You can add any of these additional options to the cf options of the basic command:

jar command options

Option	Description
v	Produces verbose output on stdout while the JAR file is being built. The verbose output tells you the name of each file as it’s added to the JAR file.
0 (zero)	Indicates that you don’t want the JAR file to be compressed.
M	Indicates that the default manifest file should not be produced.
m	Used to include manifest information from an existing manifest file. The format for using this option is: jar cmf existing-manifest jar-file input-file(s) See Modifying a Manifest File for more information about his option. Warning: The manifest must end with a new line or carriage return. The last line will not be parsed properly if it does not end with a new line or carriage return.
-C	To change directories during execution of the command. See below for an example.

---

Note:  When you create a JAR file, the time of creation is stored in the JAR file. Therefore, even if the contents of the JAR file do not change, when you create a JAR file multiple times, the resulting files are not exactly identical. You should be aware of this when you are using JAR files in a build environment. It is recommended that you use versioning information in the manifest file, rather than creation time, to control versions of a JAR file. See the Setting Package Version Information section.

---

An Example

Let us look at an example. A simple TicTacToe applet. You can see the source code of this Applet at TicTacToe.java. This demo contains a bytecode class file, audio files, and images having this structure:

TicTacToe folder Hierarchy

The audio and images subdirectories contain sound files and GIF images used by the applet.

You can obtain all these files from jar/examples directory when you download the entire Tutorial online. To package this demo into a single JAR file named TicTacToe.jar, you would run this command from inside the TicTacToe directory:

jar cvf TicTacToe.jar TicTacToe.class audio images

The audio and images arguments represent directories, so the Jar tool will recursively place them and their contents in the JAR file. The generated JAR file TicTacToe.jar will be placed in the current directory. Because the command used the v option for verbose output, you would see something similar to this output when you run the command:

adding: TicTacToe.class (in=3825) (out=2222) (deflated 41%)

adding: audio/ (in=0) (out=0) (stored 0%)

adding: audio/beep.au (in=4032) (out=3572) (deflated 11%)

adding: audio/ding.au (in=2566) (out=2055) (deflated 19%)

adding: audio/return.au (in=6558) (out=4401) (deflated 32%)

adding: audio/yahoo1.au (in=7834) (out=6985) (deflated 10%)

adding: audio/yahoo2.au (in=7463) (out=4607) (deflated 38%)

adding: images/ (in=0) (out=0) (stored 0%)

adding: images/cross.gif (in=157) (out=160) (deflated -1%)

adding: images/not.gif (in=158) (out=161) (deflated -1%)

You can see from this output that the JAR file TicTacToe.jar is compressed. The Jar tool compresses files by default. You can turn off the compression feature by using the 0 (zero) option, so that the command would look like:

jar cvf0 TicTacToe.jar TicTacToe.class audio images

You might want to avoid compression, for example, to increase the speed with which a JAR file could be loaded by a browser. Uncompressed JAR files can generally be loaded more quickly than compressed files because the need to decompress the files during loading is eliminated. However, there is a tradeoff in that download time over a network may be longer for larger, uncompressed files.

The Jar tool will accept arguments that use the wildcard * symbol. As long as there weren’t any unwanted files in the TicTacToe directory, you could have used this alternative command to construct the JAR file:

jar cvf TicTacToe.jar *

Though the verbose output doesn’t indicate it, the Jar tool automatically adds a manifest file to the JAR archive with path name META-INF/MANIFEST.MF. See the Working with Manifest Files: The Basics section for information about manifest files.

In the above example, the files in the archive retained their relative path names and directory structure. The Jar tool provides the -C option that you can use to create a JAR file in which the relative paths of the archived files are not preserved. It’s modeled after TAR’s -C option.

As an example, suppose you wanted to put audio files and gif images used by the TicTacToe demo into a JAR file, and that you wanted all the files to be on the top level, with no directory hierarchy. You could accomplish that by issuing this command from the parent directory of the images and audio directories:

jar cf ImageAudio.jar -C images . -C audio .

The -C images part of this command directs the Jar tool to go to the images directory, and the . following -C images directs the Jar tool to archive all the contents of that directory. The -C audio . part of the command then does the same with the audio directory. The resulting JAR file would have this table of contents:

META-INF/MANIFEST.MF

cross.gif

not.gif

beep.au

ding.au

return.au

yahoo1.au

yahoo2.au

By contrast, suppose that you used a command that did not employ the -C option:

jar cf ImageAudio.jar images audio

The resulting JAR file would have this table of contents:

META-INF/MANIFEST.MF

images/cross.gif

images/not.gif

audio/beep.au

audio/ding.au

audio/return.au

audio/yahoo1.au

audio/yahoo2.au

JAR files support a wide range of functionality, including electronic signing, version control, package sealing, and others. What gives a JAR file this versatility? The answer is the JAR file’s manifest.

The manifest is a special file that can contain information about the files packaged in a JAR file. By tailoring this “meta” information that the manifest contains, you enable the JAR file to serve a variety of purposes.

This lesson will explain the contents of the manifest file and show you how to work with it, with examples for the basic features:

Understanding the Default Manifest

When you create a JAR file, a default manifest is created automatically. This section describes the default manifest.

Modifying a Manifest File

This section shows you the basic method of modifying a manifest file. The later sections demonstrate specific modifications you may want to make.

Setting an Application’s Entry Point

This section describes how to use the Main-Class header in the manifest file to set an application’s entry point.

Adding Classes to the JAR File’s Classpath

This section describes how to use the Class-Path header in the manifest file to add classes in other JAR files to the classpath when running an applet or application.

Setting Package Version Information

This section describes how to use the package version headers in the manifest file.

Sealing Packages within a JAR File

This section describes how to seal packages within a JAR file by modifying the manifest file.