Chapter 24. The java.util.jar Package

The java.util.jar package contains classes for reading and writing Java archive, or JAR, files. A JAR file is nothing more than a ZIP file whose first entry is a specially named manifest file that contains attributes and digital signatures for the ZIP file entries that follow it. Many of the classes in this package are relatively simple extensions of classes from the java.util.zip package. Figure 24-1 shows the class hierarchy of this package.

Figure 24-1. The java.util.jar package

The easiest way to read a JAR file is with the random-access JarFile class. This class allows you to obtain the JarEntry that describes any named file within the JAR archive. It also allows you to obtain an enumeration of all entries in the archive and an InputStream for reading the bytes of a specific JarEntry. Each JarEntry describes a single entry in the archive and allows access to the Attributes and the digital signatures associated with the entry. The JarFile also provides access to the Manifest object for the JAR archive; this object contains Attributes for all entries in the JAR file. Attributes is a mapping of attribute name/value pairs, of course, and the inner class Attributes.Name defines constants for various standard attribute names.

You can also read a JAR file with JarInputStream. This class requires to you read each entry of the file sequentially, however. JarOutputStream allows you to write out a JAR file sequentially. Finally, you can also read an entry within a JAR file and manifest attributes for that entry with a java.net.JarURLConnection object.

Attributes

Java 1.2

java.util.jar

cloneable collection

This class is a java.util.Map that maps the attribute names of a JAR file manifest to arbitrary string values. The JAR manifest format specifies that attribute names can contain only the ASCII characters A to Z (uppercase and lowercase), the digits 0 through 9, and the hyphen and underscore characters. Thus, this class uses Attributes.Name as the type of attribute names, in addition to the more general String class. Although you can create your own Attributes objects, you more commonly obtain Attributes objects from a Manifest.

public class Attributes implements Cloneablejava.util.Map {
//	Public Constructors
	public Attributes ();
	public Attributes (java.util.jar.Attributes attr);
	public Attributes (int size);
//	Inner Classes
	;
//	Public Instance Methods
	public String getValue (Attributes.Name name);
	public String getValue (String name);
	public String putValue (String name, String value);
//	Methods Implementing Map
	public void clear ();
	public boolean containsKey (Object name);
	public boolean containsValue (Object value);
	public java.util.Set entrySet ();
	public boolean equals (Object o);
	public Object get (Object name);
	public int hashCode ();
	public boolean isEmpty ();	default:true
	public java.util.Set keySet ();
	public Object put (Object name, Object value);
	public void putAll (java.util.Map attr);
	public Object remove (Object name);
	public int size ();
	public java.util.Collection values ();
//	Public Methods Overriding Object
	public Object clone ();
//	Protected Instance Fields
	protected java.util.Map map ;
}

Hierarchy: Object-->java.util.jar.Attributes(Cloneable,java.util.Map)

Passed To: java.util.jar.Attributes.Attributes()

Returned By: java.net.JarURLConnection.{getAttributes(), getMainAttributes()}, JarEntry.getAttributes(), Manifest.{getAttributes(), getMainAttributes()}

Attributes.Name

Java 1.2

java.util.jar

This class represents the name of an attribute in an Attributes object. It defines constants for the various standard attribute names used in JAR file manifests. Attribute names can contain only ASCII letters, digits, and the hyphen and underscore characters. Any other Unicode characters are illegal.

public static class Attributes.Name {
//	Public Constructors
	public Name (String name);
//	Public Constants
	public static final Attributes.Name CLASS_PATH ;
	public static final Attributes.Name CONTENT_TYPE ;
1.3	public static final Attributes.Name EXTENSION_INSTALLATION ;
1.3	public static final Attributes.Name EXTENSION_LIST ;
1.3	public static final Attributes.Name EXTENSION_NAME ;
	public static final Attributes.Name IMPLEMENTATION_TITLE ;
1.3	public static final Attributes.Name IMPLEMENTATION_URL ;
	public static final Attributes.Name IMPLEMENTATION_VENDOR ;
1.3	public static final Attributes.Name IMPLEMENTATION_VENDOR_ID ;
	public static final Attributes.Name IMPLEMENTATION_VERSION ;
	public static final Attributes.Name MAIN_CLASS ;
	public static final Attributes.Name MANIFEST_VERSION ;
	public static final Attributes.Name SEALED ;
	public static final Attributes.Name SIGNATURE_VERSION ;
	public static final Attributes.Name SPECIFICATION_TITLE ;
	public static final Attributes.Name SPECIFICATION_VENDOR ;
	public static final Attributes.Name SPECIFICATION_VERSION ;
//	Public Methods Overriding Object
	public boolean equals (Object o);
	public int hashCode ();
	public String toString ();
}

Passed To: java.util.jar.Attributes.getValue()

Type Of: Too many fields to list.

JarEntry

Java 1.2

java.util.jar

cloneable

This class extends java.util.zip.ZipEntry; it represents a single file in a JAR archive and the manifest attributes and digital signatures associated with that file. JarEntry objects can be read from a JAR file with JarFile or JarInputStream, and they can be written to a JAR file with JarOutputStream. Use getAttributes() to obtain the Attributes for the entry. Use getCertificates() to obtain a java.security.cert.Certificate array that contains the certificate chains for all digital signatures associated with the file.

public class JarEntry extends java.util.zip.ZipEntry {
//	Public Constructors
	public JarEntry (JarEntry je);
	public JarEntry (String name);
	public JarEntry (java.util.zip.ZipEntry ze);
//	Public Instance Methods
	public java.util.jar.Attributes getAttributes () throws java.io.IOException;
	public java.security.cert.Certificate[ ] getCertificates ();
}

Hierarchy: Object-->java.util.zip.ZipEntry(Cloneable,java.util.zip.ZipConstants)-->JarEntry

Passed To: JarEntry.JarEntry()

Returned By: java.net.JarURLConnection.getJarEntry(), JarFile.getJarEntry(), JarInputStream.getNextJarEntry()

JarException

Java 1.2

java.util.jar

serializable checked

Signals an error while reading or writing a JAR file.

public class JarException extends java.util.zip.ZipException {
//	Public Constructors
	public JarException ();
	public JarException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->java.io.IOException-->java.util.zip.ZipException-->JarException

JarFile

Java 1.2

java.util.jar

This class represents a JAR file and allows the manifest, file list, and individual files to be read from the JAR file. It extends java.util.zip.ZipFile, and its use is similar to that of its superclass. Create a JarFile by specifying a filename or File object. If you do not want JarFile to attempt to verify any digital signatures contained in the JarFile, pass an optional boolean argument of false to the JarFile() constructor. In Java 1.3, temporary JAR files can be automatically deleted when they are closed. To take advantage of this feature, pass ZipFile.OPEN_READ|ZipFile.OPEN_DELETE as the mode argument to the JarFile() constructor.

Once you have created a JarFile object, obtain the JAR Manifest with getManifest(). Obtain an enumeration of the java.util.zip.ZipEntry objects in the file with entries(). Get the JarEntry for a specified file in the JAR file with getJarEntry(). To read the contents of a specific entry in the JAR file, obtain the JarEntry or ZipEntry object that represents that entry, pass it to getInputStream(), and then read until the end of that stream. JarFile does not support the creation of new JAR files or the modification of existing files.

public class JarFile extends java.util.zip.ZipFile {
//	Public Constructors
	public JarFile (java.io.File file) throws java.io.IOException;
	public JarFile (String name) throws java.io.IOException;
	public JarFile (java.io.File file, boolean verify) throws java.io.IOException;
	public JarFile (String name, boolean verify) throws java.io.IOException;
1.3	public JarFile (java.io.File file, boolean verify, int mode) throws java.io.IOException;
//	Public Constants
	public static final String MANIFEST_NAME ;	="META-INF/MANIFEST.MF"
//	Public Instance Methods
	public JarEntry getJarEntry (String name);
	public Manifest getManifest () throws java.io.IOException;
//	Public Methods Overriding ZipFile
	public java.util.Enumeration entries ();
	public java.util.zip.ZipEntry getEntry (String name);
	public java.io.InputStream getInputStream (java.util.zip.ZipEntry ze) throws java.io.IOException;	synchronized
}

Hierarchy: Object-->java.util.zip.ZipFile(java.util.zip.ZipConstants)-->JarFile

Returned By: java.net.JarURLConnection.getJarFile()

JarInputStream

Java 1.2

java.util.jar

This class allows a JAR file to be read from an input stream. It extends java.util.ZipInputStream and is used much like that class is used. To create a JarInputStream, simply specify the InputStream from which to read. If you do not want the JarInputStream to attempt to verify any digital signatures contained in the JAR file, pass false as the second argument to the JarInputStream() constructor. The JarInputStream() constructor first reads the JAR manifest entry, if one exists. The manifest must be the first entry in the JAR file. getManifest() returns the Manifest object for the JAR file.

Once you have created a JarInputStream, call getNextJarEntry() or getNextEntry() to obtain the JarEntry or java.util.zip.ZipEntry object that describes the next entry in the JAR file. Then, call a read() method (including the inherited versions) to read the contents of that entry. When the stream reaches the end of file, call getNextJarEntry() again to start reading the next entry in the file. When all entries have been read from the JAR file, getNextJarEntry() and getNextEntry() return null.

public class JarInputStream extends java.util.zip.ZipInputStream {
//	Public Constructors
	public JarInputStream (java.io.InputStream in) throws java.io.IOException;
	public JarInputStream (java.io.InputStream in, boolean verify) throws java.io.IOException;
//	Public Instance Methods
	public Manifest getManifest ();
	public JarEntry getNextJarEntry () throws java.io.IOException;
//	Public Methods Overriding ZipInputStream
	public java.util.zip.ZipEntry getNextEntry () throws java.io.IOException;
	public int read (byte[ ] b, int off, int len) throws java.io.IOException;
//	Protected Methods Overriding ZipInputStream
	protected java.util.zip.ZipEntry createZipEntry (String name);
}

Hierarchy: Object-->java.io.InputStream-->java.io.FilterInputStream-->java.util.zip.InflaterInputStream-->java.util.zip.ZipInputStream(java.util.zip.ZipConstants)-->JarInputStream

JarOutputStream

Java 1.2

java.util.jar

This class can write a JAR file to an arbitrary OutputStream. JarOutputStream extends java.util.zip.ZipOutputStream and is used much like that class is used. Create a JarOutputStream by specifying the stream to write to and, optionally, the Manifest object for the JAR file. The JarOutputStream() constructor starts by writing the contents of the Manifest object into an appropriate JAR file entry. It is the programmer's responsibility to ensure that the contents of the JAR entries written subsequently match those specified in the Manifest object. This class provides no explicit support for attaching digital signatures to entries in the JAR file.

After creating a JarOutputStream, call putNextEntry() to specify the JarEntry or java.util.zip.ZipEntry to be written to the stream. Then, call any of the inherited write() methods to write the contents of the entry to the stream. When that entry is finished, call putNextEntry() again to begin writing the next entry. When you have written all JAR file entries in this way, call close(). Before writing any entry, you may call the inherited setMethod() and setLevel() methods to specify how the entry should be compressed. See java.util.zip.ZipOutputStream.

public class JarOutputStream extends java.util.zip.ZipOutputStream {
//	Public Constructors
	public JarOutputStream (java.io.OutputStream out) throws java.io.IOException;
	public JarOutputStream (java.io.OutputStream out, Manifest man) throws java.io.IOException;
//	Public Methods Overriding ZipOutputStream
	public void putNextEntry (java.util.zip.ZipEntry ze) throws java.io.IOException;
}

Hierarchy: Object-->java.io.OutputStream-->java.io.FilterOutputStream-->java.util.zip.DeflaterOutputStream-->java.util.zip.ZipOutputStream(java.util.zip.ZipConstants)-->JarOutputStream

Manifest

Java 1.2

java.util.jar

cloneable

This class represents the manifest entry of a JAR file. getMainAttributes() returns an Attributes object that represents the manifest attributes that apply to the entire JAR file. getAttributes() returns an Attributes object that represents the manifest attributes specified for a single file in the JAR file. getEntries() returns a java.util.Map that maps the names of entries in the JAR file to the Attributes objects associated with those entries. getEntries() returns the Map object used internally by the Manifest. You can edit the contents of the Manifest by adding, deleting, or editing entries in the Map. read() reads manifest entries from an input stream, merging them into the current set of entries. write() writes the Manifest out to the specified output stream.

public class Manifest implements Cloneable {
//	Public Constructors
	public Manifest ();
	public Manifest (Manifest man);
	public Manifest (java.io.InputStream is) throws java.io.IOException;
//	Public Instance Methods
	public void clear ();
	public java.util.jar.Attributes getAttributes (String name);
	public java.util.Map getEntries ();	default:HashMap
	public java.util.jar.Attributes getMainAttributes ();
	public void read (java.io.InputStream is) throws java.io.IOException;
	public void write (java.io.OutputStream out) throws java.io.IOException;
//	Public Methods Overriding Object
	public Object clone ();
	public boolean equals (Object o);
	public int hashCode ();
}

Hierarchy: Object-->Manifest(Cloneable)

Passed To: java.net.URLClassLoader.definePackage(), JarOutputStream.JarOutputStream(), Manifest.Manifest()

Returned By: java.net.JarURLConnection.getManifest(), JarFile.getManifest(), JarInputStream.getManifest()