org.at4j.zip
Class ZipFile

java.lang.Object
  extended by org.at4j.zip.ZipFile
All Implemented Interfaces:
Map<AbsoluteLocation,ZipEntry>, Archive<ZipEntry,ZipDirectoryEntry>

public class ZipFile
extends Object
implements Archive<ZipEntry,ZipDirectoryEntry>

A ZipFile is an Archive containing ZipEntry:s loaded from a file. Zip entries may be files, directories or symbolic links. They contain metadata about the file system entity that was used to create the Zip entry. For more information on the metadata, see the ZipEntry documentation.

The Zip file consists of several local files, each containing a local file header and file data (for file entries), as well as a central directory that contains data on all entries in the archive. The metadata for one entry is partly stored in the local file header and partly in its central directory entry.

The Zip file may also contain a text comment.

When the Zip file is opened, a ZipFileParser object is used to interpret its contents. That object's configuration may be tweaked to understand new types of Zip files.

The entries in a Zip archive are positioned in a directory hierarchy. Parent directories of entries may be absent. In that case they are represented by ZipDirectoryEntry objects using default directory settings.

If the file used to create this object is in a locking FileSystem, it is locked for reading by this object until it is close():d.

A ZipFile object should be safe to use concurrently from several parallel threads without any external synchronization.

This implementation does not support Zip file encryption or signatures, Zip archives that span several files or the Zip64 format.

Note on character encoding: It is not specified in either PK-Zip's nor Info-Zip's documentation (see below) which character encoding to use when encoding text data in a Zip file. Windows programs (7-Zip, WinZip) use Codepage 437 to encode file names, and the platform's default charset (often Codepage 1252) for other text information such as entry comments. Unix programs use the platform's default character encoding (often UTF-8) for both file names and other text data.

The Zip file format is specified in PK-Zip's application notes and Info-Zip's application notes.

Since:
1.0
Author:
Karl Gustafsson
See Also:
ZipEntry, ZipFileParser, ZipBuilder

Nested Class Summary
 
Nested classes/interfaces inherited from interface java.util.Map
Map.Entry<K,V>
 
Constructor Summary
ZipFile(RandomlyAccessibleFile f)
          Create a new Zip file archive object that reads data from the supplied file.
ZipFile(RandomlyAccessibleFile f, Charset fileNameEncodingCs, Charset textEncodingCs)
          Create a new Zip file archive object that reads data from the supplied file.
ZipFile(RandomlyAccessibleFile f, Charset fileNameEncodingCs, Charset textEncodingCs, ZipFileParser zfp)
          Create a new Zip file archive object that reads data from the supplied file.
 
Method Summary
protected  void assertNotClosed()
          This method throws an IllegalStateException if the Zip object has been closed.
 void clear()
           
 void close()
          This closes the Zip archive, all open input streams on Zip file entries in the archive, and releases the read lock on the Zip file.
 boolean containsKey(Object key)
          Does the Zip file contain an entry at the specified absolute location?
 boolean containsValue(Object value)
          Does the Zip file contain the specified Zip entry?
 Set<Map.Entry<AbsoluteLocation,ZipEntry>> entrySet()
          Get a read only set containing all Zip entries and their locations in the Zip file.
protected  void finalize()
           
 ZipEntry get(Object key)
          Get the Zip entry at the specified absolute location in the Zip file.
 String getComment()
          Get the Zip file's comment.
 ZipDirectoryEntry getRootEntry()
          Get the Zip file's root entry.
 boolean isEmpty()
          This method always returns false since a Zip file always contains the root entry.
 Set<AbsoluteLocation> keySet()
          Get a read only set containing all absolute locations where there are Zip entries in this Zip file.
 ZipEntry put(AbsoluteLocation key, ZipEntry value)
           
 void putAll(Map<? extends AbsoluteLocation,? extends ZipEntry> m)
           
 ZipEntry remove(Object key)
           
 int size()
          Get the number of Zip entries in this Zip file
 Collection<ZipEntry> values()
          Get a read only collection containing all Zip entries in this Zip file
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Map
equals, hashCode
 

Constructor Detail

ZipFile

public ZipFile(RandomlyAccessibleFile f)
        throws ZipFileParseException,
               WrappedIOException
Create a new Zip file archive object that reads data from the supplied file. File names and other text information in the Zip file is interpreted using the platform's default charset. The Zip file contents is parsed using a standard ZipFileParser with the default settings.

If the file is in a locking FileSystem, it is locked for reading by this method. The read lock is released when this object is close():d. If this method returns with an error, the file is not locked.

See the note on character encodings in the class documentation above.

Parameters:
f - The Zip file.
Throws:
WrappedIOException - On I/O errors.
ZipFileParseException - If the Zip file cannot be parsed for some other reason than an I/O error.
See Also:
ZipFile(RandomlyAccessibleFile, Charset, Charset), ZipFile(RandomlyAccessibleFile, Charset, Charset, ZipFileParser)

ZipFile

public ZipFile(RandomlyAccessibleFile f,
               Charset fileNameEncodingCs,
               Charset textEncodingCs)
        throws ZipFileParseException,
               WrappedIOException
Create a new Zip file archive object that reads data from the supplied file. File names and other text information in the Zip file is interpreted using the supplied charsets. The Zip file contents is parsed using a standard ZipFileParser with the default settings.

If the file is in a locking FileSystem, it is locked for reading by this method. The read lock is released when this object is close():d. If this method returns with an error, the file is not locked.

See the note on character encodings in the class documentation above.

Parameters:
f - The Zip file.
fileNameEncodingCs - The charset to use for interpreting file names in the Zip file.
textEncodingCs - The charset to use for interpreting text information (other than file names) in the Zip file.
Throws:
WrappedIOException - On I/O errors.
ZipFileParseException - If the Zip file cannot be parsed for some other reason than an I/O error.
See Also:
ZipFile(RandomlyAccessibleFile), ZipFile(RandomlyAccessibleFile, Charset, Charset, ZipFileParser)

ZipFile

public ZipFile(RandomlyAccessibleFile f,
               Charset fileNameEncodingCs,
               Charset textEncodingCs,
               ZipFileParser zfp)
        throws ZipFileParseException,
               WrappedIOException
Create a new Zip file archive object that reads data from the supplied file. File names and other text information in the Zip file is interpreted using the supplied charsets. The Zip file contents is parsed using the supplied ZipFileParser.

If the file is in a locking FileSystem, it is locked for reading by this method. The read lock is released when this object is close():d. If this method returns with an error, the file is not locked.

See the note on character encodings in the class documentation above.

Parameters:
f - The Zip file.
fileNameEncodingCs - The charset to use for interpreting file names in the Zip file.
textEncodingCs - The charset to use for interpreting text information (other than file names) in the Zip file.
zfp - The Zip file parser.
Throws:
WrappedIOException - On I/O errors.
ZipFileParseException - If the Zip file cannot be parsed for some other reason than an I/O error.
See Also:
ZipFile(RandomlyAccessibleFile), ZipFile(RandomlyAccessibleFile, Charset, Charset)
Method Detail

assertNotClosed

protected void assertNotClosed()
                        throws IllegalStateException
This method throws an IllegalStateException if the Zip object has been closed.

Throws:
IllegalStateException - If the Zip object has been closed.

getRootEntry

public ZipDirectoryEntry getRootEntry()
                               throws IllegalStateException
Get the Zip file's root entry. The root entry has the location / in the Zip archive.

Specified by:
getRootEntry in interface Archive<ZipEntry,ZipDirectoryEntry>
Returns:
The Zip file's root entry.
Throws:
IllegalStateException - If the Zip object has been closed.

getComment

public String getComment()
                  throws IllegalStateException
Get the Zip file's comment.

Returns:
The Zip file's comment. If the comment is not set, this method returns an empty string.
Throws:
IllegalStateException - If the Zip object has been closed.

clear

public void clear()
           throws UnsupportedOperationException
Specified by:
clear in interface Map<AbsoluteLocation,ZipEntry>
Throws:
UnsupportedOperationException - Always.

containsKey

public boolean containsKey(Object key)
                    throws IllegalStateException
Does the Zip file contain an entry at the specified absolute location?

Specified by:
containsKey in interface Map<AbsoluteLocation,ZipEntry>
Parameters:
key - The AbsoluteLocation.
Returns:
true if the Zip file contains an entry at the specified absolute location.
Throws:
IllegalStateException - If the Zip object has been closed.

containsValue

public boolean containsValue(Object value)
                      throws IllegalStateException
Does the Zip file contain the specified Zip entry?

Specified by:
containsValue in interface Map<AbsoluteLocation,ZipEntry>
Parameters:
value - A ZipEntry.
Returns:
true if the Zip file contains the specified Zip entry.
Throws:
IllegalStateException - If the Zip object has been closed.

entrySet

public Set<Map.Entry<AbsoluteLocation,ZipEntry>> entrySet()
                                                   throws IllegalStateException
Get a read only set containing all Zip entries and their locations in the Zip file.

Specified by:
entrySet in interface Map<AbsoluteLocation,ZipEntry>
Returns:
A read only set containing all Zip entries and their locations in the Zip file.
Throws:
IllegalStateException - If the Zip object has been closed.

get

public ZipEntry get(Object key)
             throws IllegalStateException
Get the Zip entry at the specified absolute location in the Zip file.

Specified by:
get in interface Map<AbsoluteLocation,ZipEntry>
Parameters:
key - An AbsoluteLocation.
Returns:
The ZipEntry at the specified location, or null if there is no Zip entry at the location.
Throws:
IllegalStateException - If the Zip object has been closed.

isEmpty

public boolean isEmpty()
                throws IllegalStateException
This method always returns false since a Zip file always contains the root entry.

Specified by:
isEmpty in interface Map<AbsoluteLocation,ZipEntry>
Returns:
false, always.
Throws:
IllegalStateException - If the Zip object has been closed.

keySet

public Set<AbsoluteLocation> keySet()
                             throws IllegalStateException
Get a read only set containing all absolute locations where there are Zip entries in this Zip file.

Specified by:
keySet in interface Map<AbsoluteLocation,ZipEntry>
Returns:
A read only set containing all absolute locations where there are Zip entries in this Zip file.
Throws:
IllegalStateException - If the Zip object has been closed.

put

public ZipEntry put(AbsoluteLocation key,
                    ZipEntry value)
             throws UnsupportedOperationException
Specified by:
put in interface Map<AbsoluteLocation,ZipEntry>
Throws:
UnsupportedOperationException - Always.

putAll

public void putAll(Map<? extends AbsoluteLocation,? extends ZipEntry> m)
            throws UnsupportedOperationException
Specified by:
putAll in interface Map<AbsoluteLocation,ZipEntry>
Throws:
UnsupportedOperationException - Always.

remove

public ZipEntry remove(Object key)
                throws UnsupportedOperationException
Specified by:
remove in interface Map<AbsoluteLocation,ZipEntry>
Throws:
UnsupportedOperationException - Always.

size

public int size()
         throws IllegalStateException
Get the number of Zip entries in this Zip file

Specified by:
size in interface Map<AbsoluteLocation,ZipEntry>
Returns:
The number of Zip entries in this Zip file.
Throws:
IllegalStateException - If the Zip object has been closed.

values

public Collection<ZipEntry> values()
                            throws IllegalStateException
Get a read only collection containing all Zip entries in this Zip file

Specified by:
values in interface Map<AbsoluteLocation,ZipEntry>
Returns:
A read only collection containing all Zip entries in this Zip file.
Throws:
IllegalStateException - If the Zip object has been closed.

close

public void close()
This closes the Zip archive, all open input streams on Zip file entries in the archive, and releases the read lock on the Zip file.

It is safe to call this method several times on the same object.

Specified by:
close in interface Archive<ZipEntry,ZipDirectoryEntry>

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable