Chapter 25. The java.util.zip Package

The java.util.zip package contains classes for data compression and decompression. It is new as of Java 1.1. Figure 25-1 shows the class hierarchy of the package. The Deflater and Inflater classes perform data compression and decompression. DeflaterOutputStream and InflaterInputStream apply that functionality to byte streams; the subclasses of these streams implement both the GZIP and ZIP compression formats. The Adler32 and CRC32 classes implement the Checksum interface and compute the checksums required for data compression.

Figure 25-1. The java.util.zip package

Adler32

Java 1.1

java.util.zip

PJ1.1(opt)

This class implements the Checksum interface and computes a checksum on a stream of data using the Adler-32 algorithm. This algorithm is significantly faster than the CRC-32 algorithm and is almost as reliable. The CheckedInputStream and CheckedOutputStream classes provide a higher-level interface to computing checksums on streams of data.

public class Adler32 implements Checksum {
//	Public Constructors
	public Adler32 ();
//	Public Instance Methods
	public void update (byte[ ] b);
//	Methods Implementing Checksum
	public long getValue ();	default:1
	public void reset ();
	public void update (int b);
	public void update (byte[ ] b, int off, int len);
}

Hierarchy: Object-->Adler32(Checksum)

CheckedInputStream

Java 1.1

java.util.zip

PJ1.1

This class is a subclass of java.io.FilterInputStream; it allows a stream to be read and a checksum computed on its contents at the same time. This is useful when you want to check the integrity of a stream of data against a published checksum value. To create a CheckedInputStream, you must specify both the stream it should read and a Checksum object, such as CRC32, that implements the particular checksum algorithm you desire. The read() and skip() methods are the same as those of other input streams. As bytes are read, they are incorporated into the checksum that is being computed. The getChecksum() method does not return the checksum value itself, but rather the Checksum object. You must call the getValue() method of this object to obtain the checksum value.

public class CheckedInputStream extends java.io.FilterInputStream {
//	Public Constructors
	public CheckedInputStream (java.io.InputStream in, Checksum cksum);
//	Public Instance Methods
	public Checksum getChecksum ();
//	Public Methods Overriding FilterInputStream
	public int read () throws java.io.IOException;
	public int read (byte[ ] buf, int off, int len) throws java.io.IOException;
	public long skip (long n) throws java.io.IOException;
}

Hierarchy: Object-->java.io.InputStream-->java.io.FilterInputStream-->CheckedInputStream

CheckedOutputStream

Java 1.1

java.util.zip

PJ1.1

This class is a subclass of java.io.FilterOutputStream that allows data to be written to a stream and a checksum computed on that data at the same time. To create a CheckedOutputStream, you must specify both the output stream to write its data to and a Checksum object, such as an instance of Adler32, that implements the particular checksum algorithm you desire. The write() methods are similar to those of other OutputStream classes. The getChecksum() method returns the Checksum object. You must call getValue() on this object in order to obtain the actual checksum value.

public class CheckedOutputStream extends java.io.FilterOutputStream {
//	Public Constructors
	public CheckedOutputStream (java.io.OutputStream out, Checksum cksum);
//	Public Instance Methods
	public Checksum getChecksum ();
//	Public Methods Overriding FilterOutputStream
	public void write (int b) throws java.io.IOException;
	public void write (byte[ ] b, int off, int len) throws java.io.IOException;
}

Hierarchy: Object-->java.io.OutputStream-->java.io.FilterOutputStream-->CheckedOutputStream

Checksum

Java 1.1

java.util.zip

PJ1.1

This interface defines the methods required to compute a checksum on a stream of data. The checksum is computed based on the bytes of data supplied by the update() methods; the current value of the checksum can be obtained at any time with the getValue() method. reset() resets the checksum to its default value; use this method before beginning a new stream of data. The checksum value computed by a Checksum object and returned through the getValue() method must fit into a long value. Therefore, this interface is not suitable for the cryptographic checksum algorithms used in cryptography and security. The classes CheckedInputStream and CheckedOutputStream provide a higher-level API for computing a checksum on a stream of data. See also java.security.MessageDigest.

public interface Checksum {
//	Public Instance Methods
	public abstract long getValue ();
	public abstract void reset ();
	public abstract void update (int b);
	public abstract void update (byte[ ] b, int off, int len);
}

Implementations: Adler32, CRC32

Passed To: CheckedInputStream.CheckedInputStream(), CheckedOutputStream.CheckedOutputStream()

Returned By: CheckedInputStream.getChecksum(), CheckedOutputStream.getChecksum()

CRC32

Java 1.1

java.util.zip

PJ1.1

This class implements the Checksum interface and computes a checksum on a stream of data using the CRC-32 algorithm. The CheckedInputStream and CheckedOutputStream classes provide a higher-level interface to computing checksums on streams of data.

public class CRC32 implements Checksum {
//	Public Constructors
	public CRC32 ();
//	Public Instance Methods
	public void update (byte[ ] b);
//	Methods Implementing Checksum
	public long getValue ();	default:0
	public void reset ();
	public void update (int b);
	public void update (byte[ ] b, int off, int len);
}

Hierarchy: Object-->CRC32(Checksum)

Type Of: GZIPInputStream.crc, GZIPOutputStream.crc

DataFormatException

Java 1.1

java.util.zip

serializable checked PJ1.1

Signals that invalid or corrupt data has been encountered while uncompressing data.

public class DataFormatException extends Exception {
//	Public Constructors
	public DataFormatException ();
	public DataFormatException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->DataFormatException

Thrown By: Inflater.inflate()

Deflater

Java 1.1

java.util.zip

PJ1.1(opt)

This class implements the general ZLIB data-compression algorithm used by the gzip and PKZip compression programs. The constants defined by this class are used to specify the compression strategy and the compression speed/strength tradeoff level to be used. If you set the nowrap argument to the constructor to true, the ZLIB header and checksum data are omitted from the compressed output, which is the format both gzip and PKZip use.

The important methods of this class are setInput(), which specifies input data to be compressed, and deflate(), which compresses the data and returns the compressed output. The remaining methods exist so that Deflater can be used for stream-based compression, as it is in higher-level classes, such as GZIPOutputStream and ZipOutputStream. These stream classes are sufficient in most cases. Most applications do not need to use Deflater directly. The Inflater class uncompresses data compressed with a Deflater object.

public class Deflater {
//	Public Constructors
	public Deflater ();
	public Deflater (int level);
	public Deflater (int level, boolean nowrap);
//	Public Constants
	public static final int BEST_COMPRESSION ;	=9
	public static final int BEST_SPEED ;	=1
	public static final int DEFAULT_COMPRESSION ;	=-1
	public static final int DEFAULT_STRATEGY ;	=0
	public static final int DEFLATED ;	=8
	public static final int FILTERED ;	=1
	public static final int HUFFMAN_ONLY ;	=2
	public static final int NO_COMPRESSION ;	=0
//	Property Accessor Methods (by property name)
	public int getAdler ();	synchronized default:1
	public int getTotalIn ();	synchronized default:0
	public int getTotalOut ();	synchronized default:0
//	Public Instance Methods
	public int deflate (byte[ ] b);
	public int deflate (byte[ ] b, int off, int len);	synchronized
	public void end ();	synchronized
	public void finish ();	synchronized
	public boolean finished ();	synchronized
	public boolean needsInput ();
	public void reset ();	synchronized
	public void setDictionary (byte[ ] b);
	public void setDictionary (byte[ ] b, int off, int len);	synchronized
	public void setInput (byte[ ] b);
	public void setInput (byte[ ] b, int off, int len);	synchronized
	public void setLevel (int level);	synchronized
	public void setStrategy (int strategy);	synchronized
//	Protected Methods Overriding Object
	protected void finalize ();
}

Passed To: DeflaterOutputStream.DeflaterOutputStream()

Type Of: DeflaterOutputStream.def

DeflaterOutputStream

Java 1.1

java.util.zip

PJ1.1(opt)

This class is a subclass of java.io.FilterOutputStream; it filters a stream of data by compressing (deflating) it and then writing the compressed data to another output stream. To create a DeflaterOutputStream, you must specify both the stream it is to write to and a Deflater object to perform the compression. You can set various options on the Deflater object to specify just what type of compression is to be performed. Once a DeflaterOutputStream is created, its write() and close() methods are the same as those of other output streams. The InflaterInputStream class can read data written with a DeflaterOutputStream. A DeflaterOutputStream writes raw compressed data; applications often prefer one of its subclasses, GZIPOutputStream or ZipOutputStream, that wraps the raw compressed data within a standard file format.

public class DeflaterOutputStream extends java.io.FilterOutputStream {
//	Public Constructors
	public DeflaterOutputStream (java.io.OutputStream out);
	public DeflaterOutputStream (java.io.OutputStream out, Deflater def);
	public DeflaterOutputStream (java.io.OutputStream out, Deflater def, int size);
//	Public Instance Methods
	public void finish () throws java.io.IOException;
//	Public Methods Overriding FilterOutputStream
	public void close () throws java.io.IOException;
	public void write (int b) throws java.io.IOException;
	public void write (byte[ ] b, int off, int len) throws java.io.IOException;
//	Protected Instance Methods
	protected void deflate () throws java.io.IOException;
//	Protected Instance Fields
	protected byte[ ] buf ;
	protected Deflater def ;
}

Hierarchy: Object-->java.io.OutputStream-->java.io.FilterOutputStream-->DeflaterOutputStream

Subclasses: GZIPOutputStream, ZipOutputStream

GZIPInputStream

Java 1.1

java.util.zip

PJ1.1

This class is a subclass of InflaterInputStream that reads and uncompresses data compressed in gzip format. To create a GZIPInputStream, simply specify the InputStream to read compressed data from and, optionally, a buffer size for the internal decompression buffer. Once a GZIPInputStream is created, you can use the read() and close() methods as you would with any input stream.

public class GZIPInputStream extends InflaterInputStream {
//	Public Constructors
	public GZIPInputStream (java.io.InputStream in) throws java.io.IOException;
	public GZIPInputStream (java.io.InputStream in, int size) throws java.io.IOException;
//	Public Constants
	public static final int GZIP_MAGIC ;	=35615
//	Public Methods Overriding InflaterInputStream
	public void close () throws java.io.IOException;
	public int read (byte[ ] buf, int off, int len) throws java.io.IOException;
//	Protected Instance Fields
	protected CRC32 crc ;
	protected boolean eos ;
}

Hierarchy: Object-->java.io.InputStream-->java.io.FilterInputStream-->InflaterInputStream-->GZIPInputStream

GZIPOutputStream

Java 1.1

java.util.zip

PJ1.1(opt)

This class is a subclass of DeflaterOutputStream that compresses and writes data using the gzip file format. To create a GZIPOutputStream, specify the OutputStream to write to and, optionally, a size for the internal compression buffer. Once the GZIPOutputStream is created, you can use the write() and close() methods as you would any output stream.

public class GZIPOutputStream extends DeflaterOutputStream {
//	Public Constructors
	public GZIPOutputStream (java.io.OutputStream out) throws java.io.IOException;
	public GZIPOutputStream (java.io.OutputStream out, int size) throws java.io.IOException;
//	Public Methods Overriding DeflaterOutputStream
	public void close () throws java.io.IOException;
	public void finish () throws java.io.IOException;
	public void write (byte[ ] buf, int off, int len) throws java.io.IOException;	synchronized
//	Protected Instance Fields
	protected CRC32 crc ;
}

Hierarchy: Object-->java.io.OutputStream-->java.io.FilterOutputStream-->DeflaterOutputStream-->GZIPOutputStream

Inflater

Java 1.1

java.util.zip

PJ1.1(mod)

This class implements the general ZLIB data-decompression algorithm used by gzip, PKZip, and other data-compression applications. It decompresses or inflates data compressed through the Deflater class. The important methods of this class are setInput(), which specifies input data to be decompressed, and inflate(), which decompresses the input data into an output buffer. A number of other methods exist so that this class can be used for stream-based decompression, as it is in the higher-level classes, such as GZIPInputStream and ZipInputStream. These stream-based classes are sufficient in most cases. Most applications do not need to use Inflater directly.

public class Inflater {
//	Public Constructors
	public Inflater ();
	public Inflater (boolean nowrap);
//	Property Accessor Methods (by property name)
	public int getAdler ();	synchronized default:1
	public int getRemaining ();	synchronized default:0
	public int getTotalIn ();	synchronized default:0
	public int getTotalOut ();	synchronized default:0
//	Public Instance Methods
	public void end ();	synchronized
	public boolean finished ();	synchronized
	public int inflate (byte[ ] b) throws DataFormatException;
	public int inflate (byte[ ] b, int off, int len) throws DataFormatException;	synchronized
	public boolean needsDictionary ();	synchronized
	public boolean needsInput ();	synchronized
	public void reset ();	synchronized
	public void setDictionary (byte[ ] b);
	public void setDictionary (byte[ ] b, int off, int len);	synchronized
	public void setInput (byte[ ] b);
	public void setInput (byte[ ] b, int off, int len);	synchronized
//	Protected Methods Overriding Object
	protected void finalize ();
}

Passed To: InflaterInputStream.InflaterInputStream()

Type Of: InflaterInputStream.inf

InflaterInputStream

Java 1.1

java.util.zip

PJ1.1

This class is a subclass of java.io.FilterInputStream; it reads a specified stream of compressed input data (typically one that was written with DeflaterOutputStream or a subclass) and filters that data by uncompressing (inflating) it. To create an InflaterInputStream, specify both the input stream to read from and an Inflater object to perform the decompression. Once an InflaterInputStream is created, the read() and skip() methods are the same as those of other input streams. The InflaterInputStream uncompresses raw data. Applications often prefer one of its subclasses, GZIPInputStream or ZipInputStream, that work with compressed data written in the standard gzip and PKZip file formats.

public class InflaterInputStream extends java.io.FilterInputStream {
//	Public Constructors
	public InflaterInputStream (java.io.InputStream in);
	public InflaterInputStream (java.io.InputStream in, Inflater inf);
	public InflaterInputStream (java.io.InputStream in, Inflater inf, int size);
//	Public Methods Overriding FilterInputStream
1.2	public int available () throws java.io.IOException;
1.2	public void close () throws java.io.IOException;
	public int read () throws java.io.IOException;
	public int read (byte[ ] b, int off, int len) throws java.io.IOException;
	public long skip (long n) throws java.io.IOException;
//	Protected Instance Methods
	protected void fill () throws java.io.IOException;
//	Protected Instance Fields
	protected byte[ ] buf ;
	protected Inflater inf ;
	protected int len ;
}

Hierarchy: Object-->java.io.InputStream-->java.io.FilterInputStream-->InflaterInputStream

Subclasses: GZIPInputStream, ZipInputStream

ZipEntry

Java 1.1

java.util.zip

cloneable PJ1.1

This class describes a single entry (typically a compressed file) stored within a ZIP file. The various methods get and set various pieces of information about the entry. The ZipEntry class is used by ZipFile and ZipInputStream, which read ZIP files, and by ZipOutputStream, which writes ZIP files.

When you are reading a ZIP file, a ZipEntry object returned by ZipFile or ZipInputStream contains the name, size, modification time, and other information about an entry in the file. When writing a ZIP file, on the other hand, you must create your own ZipEntry objects and initialize them to contain the entry name and other appropriate information before writing the contents of the entry.

public class ZipEntry implements Cloneable {
//	Public Constructors
1.2	public ZipEntry (ZipEntry e);
	public ZipEntry (String name);
//	Public Constants
	public static final int DEFLATED ;	=8
	public static final int STORED ;	=0
//	Property Accessor Methods (by property name)
	public String getComment ();
	public void setComment (String comment);
	public long getCompressedSize ();
1.2	public void setCompressedSize (long csize);
	public long getCrc ();
	public void setCrc (long crc);
	public boolean isDirectory ();
	public byte[ ] getExtra ();
	public void setExtra (byte[ ] extra);
	public int getMethod ();
	public void setMethod (int method);
	public String getName ();
	public long getSize ();
	public void setSize (long size);
	public long getTime ();
	public void setTime (long time);
//	Public Methods Overriding Object
1.2	public Object clone ();
1.2	public int hashCode ();
	public String toString ();
}

Hierarchy: Object-->ZipEntry(Cloneable,ZipConstants)

Subclasses: java.util.jar.JarEntry

Passed To: java.util.jar.JarEntry.JarEntry(), java.util.jar.JarFile.getInputStream(), java.util.jar.JarOutputStream.putNextEntry(), ZipEntry.ZipEntry(), ZipFile.getInputStream(), ZipOutputStream.putNextEntry()

Returned By: java.util.jar.JarFile.getEntry(), java.util.jar.JarInputStream.{createZipEntry(), getNextEntry()}, ZipFile.getEntry(), ZipInputStream.{createZipEntry(), getNextEntry()}

ZipException

Java 1.1

java.util.zip

serializable checked PJ1.1

Signals that an error has occurred in reading or writing a ZIP file.

public class ZipException extends java.io.IOException {
//	Public Constructors
	public ZipException ();
	public ZipException (String s);
}

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

Subclasses: java.util.jar.JarException

Thrown By: ZipFile.ZipFile()

ZipFile

Java 1.1

java.util.zip

PJ1.1(opt)

This class reads the contents of ZIP files. It uses a random-access file internally so that the entries of the ZIP file do not have to be read sequentially, as they do with the ZipInputStream class. A ZipFile object can be created by specifying the ZIP file to be read either as a String filename or as a File object. In Java 1.3, temporary ZIP files can be marked for automatic deletion when they are closed. To take advantage of this feature, pass ZipFile.OPEN_READ|ZipFile.OPEN_DELETE as the mode argument to the ZipFile() constructor.

Once a ZipFile is created, the getEntry() method returns a ZipEntry object for a named entry, and the entries() method returns an Enumeration object that allows you to loop through all the ZipEntry objects for the file. To read the contents of a specific ZipEntry within the ZIP file, pass the ZipEntry to getInputStream(); this returns an InputStream object from which you can read the entry's contents.

public class ZipFile {
//	Public Constructors
	public ZipFile (String name) throws java.io.IOException;
	public ZipFile (java.io.File file) throws ZipExceptionjava.io.IOException;
1.3	public ZipFile (java.io.File file, int mode) throws java.io.IOException;
//	Public Constants
1.3	public static final int OPEN_DELETE ;	=4
1.3	public static final int OPEN_READ ;	=1
//	Public Instance Methods
	public void close () throws java.io.IOException;
	public java.util.Enumeration entries ();
	public ZipEntry getEntry (String name);
	public java.io.InputStream getInputStream (ZipEntry entry) throws java.io.IOException;
	public String getName ();
1.2	public int size ();
}

Hierarchy: Object-->ZipFile(ZipConstants)

Subclasses: java.util.jar.JarFile

ZipInputStream

Java 1.1

java.util.zip

PJ1.1

This class is a subclass of InflaterInputStream that reads the entries of a ZIP file in sequential order. Create a ZipInputStream by specifying the InputStream from which it is to read the contents of the ZIP file. Once the ZipInputStream is created, you can use getNextEntry() to begin reading data from the next entry in the ZIP file. This method must be called before read() is called to begin reading the first entry. getNextEntry() returns a ZipEntry object that describes the entry being read, or null when there are no more entries to be read from the ZIP file.

The read() methods of ZipInputStream read until the end of the current entry and then return -1, indicating that there is no more data to read. To continue with the next entry in the ZIP file, you must call getNextEntry() again. Similarly, the skip() method only skips bytes within the current entry. closeEntry() can be called to skip the remaining data in the current entry, but it is usually easier simply to call getNextEntry() to begin the next entry.

public class ZipInputStream extends InflaterInputStream {
//	Public Constructors
	public ZipInputStream (java.io.InputStream in);
//	Public Instance Methods
	public void closeEntry () throws java.io.IOException;
	public ZipEntry getNextEntry () throws java.io.IOException;
//	Public Methods Overriding InflaterInputStream
1.2	public int available () throws java.io.IOException;
	public void close () throws java.io.IOException;
	public int read (byte[ ] b, int off, int len) throws java.io.IOException;
	public long skip (long n) throws java.io.IOException;
//	Protected Instance Methods
1.2	protected ZipEntry createZipEntry (String name);
}

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

Subclasses: java.util.jar.JarInputStream

ZipOutputStream

Java 1.1

java.util.zip

PJ1.1(opt)

This class is a subclass of DeflaterOutputStream that writes data in ZIP file format to an output stream. Before writing any data to the ZipOutputStream, you must begin an entry within the ZIP file with putNextEntry(). The ZipEntry object passed to this method should specify at least a name for the entry. Once you have begun an entry with putNextEntry(), you can write the contents of that entry with the write() methods. When you reach the end of an entry, you can begin a new one by calling putNextEntry() again, you can close the current entry with closeEntry(), or you can close the stream itself with close().

Before beginning an entry with putNextEntry(), you can set the compression method and level with setMethod() and setLevel(). The constants DEFLATED and STORED are the two legal values for setMethod(). If you use STORED, the entry is stored in the ZIP file without any compression. If you use DEFLATED, you can also specify the compression speed/strength tradeoff by passing a number from 1 to 9 to setLevel(), where 9 gives the strongest and slowest level of compression. You can also use the constants Deflater.BEST_SPEED, Deflater.BEST_COMPRESSION, and Deflater.DEFAULT_COMPRESSION with the setLevel() method.

If you are storing an entry without compression, the ZIP file format requires that you specify, in advance, the entry size and CRC-32 checksum in the ZipEntry object for the entry. An exception is thrown if these values are not specified or specified incorrectly.

public class ZipOutputStream extends DeflaterOutputStream {
//	Public Constructors
	public ZipOutputStream (java.io.OutputStream out);
//	Public Constants
	public static final int DEFLATED ;	=8
	public static final int STORED ;	=0
//	Public Instance Methods
	public void closeEntry () throws java.io.IOException;
	public void putNextEntry (ZipEntry e) throws java.io.IOException;
	public void setComment (String comment);
	public void setLevel (int level);
	public void setMethod (int method);
//	Public Methods Overriding DeflaterOutputStream
	public void close () throws java.io.IOException;
	public void finish () throws java.io.IOException;
	public void write (byte[ ] b, int off, int len) throws java.io.IOException;	synchronized
}

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

Subclasses: java.util.jar.JarOutputStream