com.mucommander.file.impl.zip.provider
Class ZipFile

java.lang.Object
  com.mucommander.file.impl.zip.provider.ZipFile

All Implemented Interfaces:

ZipConstants

public class ZipFile
extends java.lang.Object
implements ZipConstants

This class is a replacement for java.util.ZipFile with some extra functionalities:

• Ability to add or remove entries 'on-the-fly', i.e. without rewriting the whole archive.
• Advanced encoding support for filenames and comments. UTF-8 is used for parsing entries that explicitely declare using UTF-8 (as per Zip specs). For entries that do not use UTF-8, the encoding is auto-detected (best effort). Alternatively, the encoding used for parsing entries can be specified if it is known in advance. For new entries added with addEntry(ZipEntry), UTF-8 is always used and declared as such in the Zip headers.
• Loads the internal/external file attributes and extra fields instead of ignoring them

This class doesn't extend java.util.zip.ZipFile as it would have to reimplement all methods anyway. Like java.util.ZipFile, it supports compressed (DEFLATED) and uncompressed (STORED) entries.

Random read access is required to instanciate a ZipFile and retrieve its entries. Furthermore, random write access is required for methods that modify the Zip file.

The method signatures mimic the ones of java.util.zip.ZipFile with a few exceptions:

• There is no getName method.
• There is no close method: underlying input and output streams are opened and closed automatically as they are needed.
• entries has been renamed to getEntries().
• size has been renamed to getNbEntries().

--------------------------------------------------------------------------------------------------------------

This class is based off the org.apache.tools.zip package of the Apache Ant project. The Ant code has been modified under the terms of the Apache License which you can find in the bundled muCommander license file. It was forked at version 1.7.0 of Ant.

Author:

Apache Ant, Maxence Bernard

Field Summary

Fields inherited from interface com.mucommander.file.impl.zip.provider.ZipConstants

CFH_SIG, DD_SIG, DEFAULT_DEFLATER_BUFFER_SIZE, DEFAULT_DEFLATER_COMPRESSION, DEFLATED, EOCD_SIG, LFH_SIG, STORED, UTF_8, WRITE_BUFFER_SIZE

Constructor Summary

ZipFile(AbstractFile f)
Opens the given Zip file and parses information about the entries it contains.

Method Summary

java.io.OutputStream	addEntry(ZipEntry entry) Appends the given entry to the end of this zip file and returns an OutputStream that allows to write the contents of the entry.
void	defragment() Removes free space fragments from this zip file, thus reducing the size of the zip file.
void	deleteEntry(ZipEntry ze) Deletes the given entry from this zip file.
java.lang.String	getDefaultEncoding() Returns the default encoding to use for parsing filenames and comments.
java.util.Enumeration	getEntries() Returns all entries as an enumeration of ZipEntry instances.
ZipEntry	getEntry(java.lang.String name) Returns a named entry or null if no entry by that name exists.
java.io.InputStream	getInputStream(ZipEntry ze) Returns an InputStream for reading the contents of the given entry.
int	getNbEntries() Returns the number of entries contained by this Zip file.
void	setDefaultEncoding(java.lang.String defaultEncoding) Sets the default encoding to use for parsing filenames and comments.
void	updateEntry(ZipEntry entry) Updates the date and permissions of the entry designated by the given ZipEntry object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ZipFile

public ZipFile(AbstractFile f)
        throws java.io.IOException,
               java.util.zip.ZipException

Opens the given Zip file and parses information about the entries it contains.

The given AbstractFile must have random read access. If not, an IOException will be thrown.

Parameters:

f - the archive file

Throws:

java.io.IOException - if a RandomAccessInputStream could not retrieved, or if an error occurred while reading the Zip file.

java.util.zip.ZipException - if this file is not a valid Zip file

Method Detail

getDefaultEncoding

public java.lang.String getDefaultEncoding()

Returns the default encoding to use for parsing filenames and comments. This value is not used for Zip entries that explicitely declare using UTF-8 (in the general purpose bit flag).

By default, this method returns null to indicate that automatic encoding detection is used. Although it is not 100% accurate, encoding detection is the preferred approach, unless the encoding is known in advance which is rather uncommon.

Note that this value only affects entries parsing. Written entries are systematically encoded in UTF-8 and declared as such in the general purpose bit flag so that proper zip unpackers know what encoding to expect.

Returns:

the default encoding to use for parsing filenames and comments

setDefaultEncoding

public void setDefaultEncoding(java.lang.String defaultEncoding)

Sets the default encoding to use for parsing filenames and comments. This value is not used for Zip entries that explicitely declare using UTF-8 (in the general purpose bit flag).

By default, the encoding is null to indicate that automatic encoding detection is used. Although it is not 100% accurate, encoding detection is the preferred approach, unless the encoding is known in advance which is rather uncommon.

Note that this value only affects entries parsing. Written entries are systematically encoded in UTF-8 and declared as such in the general purpose bit flag so that proper zip unpackers know what encoding to expect.

Parameters:

defaultEncoding - the default encoding to use for parsing filenames and comments

getEntries

public java.util.Enumeration getEntries()

Returns all entries as an enumeration of ZipEntry instances.

Returns:

Returns all entries as an enumeration of ZipEntry instances.

getNbEntries

public int getNbEntries()

Returns the number of entries contained by this Zip file.

Returns:

the number of entries contained by this Zip file

getEntry

public ZipEntry getEntry(java.lang.String name)

Returns a named entry or null if no entry by that name exists.

Parameters:

name - name of the entry.

Returns:

the ZipEntry corresponding to the given name or null if not present.

getInputStream

public java.io.InputStream getInputStream(ZipEntry ze)
                                   throws java.io.IOException,
                                          java.util.zip.ZipException

Returns an InputStream for reading the contents of the given entry.

Parameters:

ze - the entry to get the stream for.

Returns:

a stream to read the entry from.

Throws:

java.io.IOException - if unable to create an input stream from the zipenty

java.util.zip.ZipException - if the zipentry has an unsupported compression method

deleteEntry

public void deleteEntry(ZipEntry ze)
                 throws java.io.IOException,
                        java.util.zip.ZipException

Deletes the given entry from this zip file. For performance reasons, this method removes the central file header and zero out the local file header and data so that the entry cannot be retrieved, but it does not reclaim the freed space and produces fragmentation. In other words, the resulting zip file will not be smaller after the entry has been deleted and will contain an area of unused space. The defragment() method can be called to reclaim the free space.

There is one case where this method reclaims the free space: when the specified entry is the last one in the zip file. In this case, the resulting zip file will be smaller.

Note that 'fragmented' zip files are perfectly valid zip files, any zip parser should be able to cope with such files.

The underlying AbstractFile must have random write access. If not, an IOException will be thrown.

Parameters:

ze - the ZipEntry to delete

Throws:

java.io.IOException - if the underlying AbstractFile does not have random write access or if an I/O error occurred

java.util.zip.ZipException - if the specified ZipEntry cannot be found in this zip file

addEntry

public java.io.OutputStream addEntry(ZipEntry entry)
                              throws java.io.IOException

Appends the given entry to the end of this zip file and returns an OutputStream that allows to write the contents of the entry. The returned OutputStream must always be closed for the zip file to be properly modified. Not doing will leave this zip file in a inconsistent, corrupted state.

The underlying AbstractFile must have random write access. If not, an IOException will be thrown.

Parameters:

entry - the entry to add to this zip file

Returns:

an OutputStream to write the contents of the entry

Throws:

java.io.IOException - if the underlying AbstractFile does not have random write access or if an I/O error occurred

updateEntry

public void updateEntry(ZipEntry entry)
                 throws java.io.IOException

Updates the date and permissions of the entry designated by the given ZipEntry object. The specified entry must exist in this Zip file.

The underlying AbstractFile must have random write access. If not, an IOException will be thrown.

Parameters:

entry - the entry to update

Throws:

java.io.IOException - if the underlying AbstractFile does not have random write access or if an I/O error occurred

defragment

public void defragment()
                throws java.io.IOException

Removes free space fragments from this zip file, thus reducing the size of the zip file. If this zip file does not contain any free space fragments, the zip file is not modified.

Fragmentation occurs when deleting entries with deleteEntry(ZipEntry). When deleting several entries, this method should be called once after all entries have deleted.

The underlying AbstractFile must have random write access. If not, an IOException will be thrown.

Throws:

java.io.IOException - if the underlying AbstractFile does not have random write access or if an I/O error occurred