net.java.truevfs.comp.zip

Class ZipFile

java.lang.Object

net.java.truevfs.comp.zip.AbstractZipFile<ZipEntry>

net.java.truevfs.comp.zip.ZipFile

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<ZipEntry>

@ThreadSafe
public class ZipFile
extends AbstractZipFile<ZipEntry>

Replacement for java.util.zip.ZipFile.

Where the constructors of this class accept a charset parameter, this is used to decode comments and entry names in the ZIP file. However, if an entry has bit 11 set in its General Purpose Bit Flag, then this parameter is ignored and "UTF-8" is used for this entry. This is in accordance to Appendix D of PKWARE's ZIP File Format Specification, version 6.3.0 and later.

This class is able to skip a preamble like the one found in self extracting archives.

Note that the entries returned by this class are instances of net.truevfs.kernel.io.zip.ZipEntry instead of java.util.zip.ZipEntry.

Author:

Christian Schlichtherle

See Also:

ZipOutputStream

Field Summary

Fields inherited from class net.java.truevfs.comp.zip.AbstractZipFile

DEFAULT_CHARSET

Constructor Summary

Constructors

Constructor and Description
ZipFile(Path file) Equivalent to ZipFile(file, DEFAULT_CHARSET, true, false)
ZipFile(Path file, Charset charset) Equivalent to ZipFile(file, charset, true, false)
ZipFile(Path file, Charset charset, boolean preambled, boolean postambled) Opens the given file for reading its entries.
ZipFile(SeekableByteChannel channel) Equivalent to ZipFile(rof, DEFAULT_CHARSET, true, false)
ZipFile(SeekableByteChannel channel, Charset charset) Equivalent to ZipFile(rof, charset, true, false)
ZipFile(SeekableByteChannel channel, Charset charset, boolean preambled, boolean postambled) Opens the given SeekableByteChannel for reading its entries.

Method Summary

Modifier and Type	Method and Description
boolean	busy() Returns true if and only if this ZIP file is busy reading one or more entries.
void	close() Closes the file.
Enumeration<? extends ZipEntry>	entries() Enumerates clones of all entries in this ZIP file.
ZipEntry	entry(String name) Returns a clone of the entry for the given name or null if no entry with this name exists in this ZIP file.
ZipCryptoParameters	getCryptoParameters() Returns the parameters for encryption or authentication of entries.
protected InputStream	getInputStream(String name, Boolean check, boolean process) Returns an InputStream for reading the contents of the given entry.
String	getName() Returns the string representation of whatever input source object was used to construct this ZIP file.
InputStream	getPostambleInputStream() Returns an InputStream to load the postamble of this ZIP file.
InputStream	getPreambleInputStream() Returns an InputStream to load the preamble of this ZIP file.
Iterator<ZipEntry>	iterator() Iterates through clones for all entries in this ZIP file.
ZipFile	recoverLostEntries() Recovers any lost entries which have been added to the ZIP file after the (last) End Of Central Directory Record (EOCDR).
void	setCryptoParameters(ZipCryptoParameters cryptoParameters) Sets the parameters for encryption or authentication of entries.

Methods inherited from class net.java.truevfs.comp.zip.AbstractZipFile

getCharset, getCheckedInputStream, getComment, getInputStream, getPostambleLength, getPreambleLength, getRawCharset, length, offsetsConsiderPreamble, size

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

ZipFile

public ZipFile(Path file)
        throws IOException

Equivalent to ZipFile(file, DEFAULT_CHARSET, true, false)

Throws:

IOException

ZipFile

public ZipFile(Path file,
               Charset charset)
        throws IOException

Equivalent to ZipFile(file, charset, true, false)

Throws:

IOException

ZipFile

public ZipFile(Path file,
               Charset charset,
               boolean preambled,
               boolean postambled)
        throws ZipException,
               EOFException,
               IOException

Opens the given file for reading its entries.

Parameters:

file - the file.

charset - the charset to use for decoding entry names and ZIP file comment.

preambled - if this is true, then the ZIP file may have a preamble. Otherwise, the ZIP file must start with either a Local File Header (LFH) signature or an End Of Central Directory (EOCD) Header, causing this constructor to fail if the file is actually a false positive ZIP file, i.e. not compatible to the ZIP File Format Specification. This may be useful to read Self Extracting ZIP files (SFX), which usually contain the application code required for extraction in the preamble.

postambled - if this is true, then the ZIP file may have a postamble of arbitrary length. Otherwise, the ZIP file must not have a postamble which exceeds 64KB size, including the End Of Central Directory record (i.e. including the ZIP file comment), causing this constructor to fail if the file is actually a false positive ZIP file, i.e. not compatible to the ZIP File Format Specification. This may be useful to read Self Extracting ZIP files (SFX) with large postambles.

Throws:

ZipException - if the file data is not compatible with the ZIP File Format Specification.

EOFException - on unexpected end-of-file.

IOException - on any I/O error.

See Also:

recoverLostEntries()

ZipFile

public ZipFile(SeekableByteChannel channel)
        throws IOException

Equivalent to ZipFile(rof, DEFAULT_CHARSET, true, false)

Throws:

IOException

ZipFile

public ZipFile(SeekableByteChannel channel,
               Charset charset)
        throws IOException

Equivalent to ZipFile(rof, charset, true, false)

Throws:

IOException

ZipFile

public ZipFile(SeekableByteChannel channel,
               Charset charset,
               boolean preambled,
               boolean postambled)
        throws ZipException,
               EOFException,
               IOException

Opens the given SeekableByteChannel for reading its entries.

Parameters:

channel - the channel to read.

charset - the charset to use for decoding entry names and ZIP file comment.

preambled - if this is true, then the ZIP file may have a preamble. Otherwise, the ZIP file must start with either a Local File Header (LFH) signature or an End Of Central Directory (EOCD) Header, causing this constructor to fail if the file is actually a false positive ZIP file, i.e. not compatible to the ZIP File Format Specification. This may be useful to read Self Extracting ZIP files (SFX), which usually contain the application code required for extraction in the preamble.

postambled - if this is true, then the ZIP file may have a postamble of arbitrary length. Otherwise, the ZIP file must not have a postamble which exceeds 64KB size, including the End Of Central Directory record (i.e. including the ZIP file comment), causing this constructor to fail if the file is actually a false positive ZIP file, i.e. not compatible to the ZIP File Format Specification. This may be useful to read Self Extracting ZIP files (SFX) with large postambles.

Throws:

ZipException - if the channel data is not compatible with the ZIP File Format Specification.

EOFException - on unexpected end-of-file.

IOException - on any I/O error.

See Also:

recoverLostEntries()

Method Detail

busy

public boolean busy()

Description copied from class: AbstractZipFile

Returns true if and only if this ZIP file is busy reading one or more entries.

Overrides:

busy in class AbstractZipFile<ZipEntry>

close

public void close()
           throws IOException

Description copied from class: AbstractZipFile

Closes the file. This closes any allocated input streams reading from this ZIP file.

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Overrides:

close in class AbstractZipFile<ZipEntry>

Throws:

IOException - if an error occurs closing the file.

entries

public Enumeration<? extends ZipEntry> entries()

Enumerates clones of all entries in this ZIP file.

See Also:

iterator()

entry

public ZipEntry entry(String name)

Returns a clone of the entry for the given name or null if no entry with this name exists in this ZIP file.

Overrides:

entry in class AbstractZipFile<ZipEntry>

Parameters:

name - the name of the ZIP entry.

Returns:

A clone of the entry for the given name or null if no entry with this name exists in this ZIP file.

getCryptoParameters

@Nullable
public ZipCryptoParameters getCryptoParameters()

Description copied from class: AbstractZipFile

Returns the parameters for encryption or authentication of entries. Returns The parameters for encryption or authentication of entries.

Specified by:

getCryptoParameters in class AbstractZipFile<ZipEntry>

getInputStream

protected InputStream getInputStream(String name,
                                     Boolean check,
                                     boolean process)
                              throws IOException

Description copied from class: AbstractZipFile

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

If the AbstractZipFile.close() method is called on this instance, all input streams returned by this method are closed, too.

Overrides:

getInputStream in class AbstractZipFile<ZipEntry>

Parameters:

name - The name of the entry to get the stream for.

check - Whether or not the entry content gets checked/authenticated. If the parameter process is false, then this parameter is ignored. Otherwise, if this parameter is null, then it is set to the ZipEntry.isEncrypted() property of the given entry. Finally, if this parameter is true, then the following additional check is performed for the entry:

• If the entry is encrypted, then the Message Authentication Code (MAC) value gets computed and checked. If this check fails, then a ZipAuthenticationException gets thrown from this method (pre-check).
• If the entry is not encrypted, then the CRC-32 value gets computed and checked. First, the local file header is checked to hold the same CRC-32 value than the central directory record. Second, the CRC-32 value is computed and checked. If this check fails, then a Crc32Exception gets thrown when InputStream.close() is called on the returned entry stream (post-check).

process - Whether or not the entry contents should get processed, e.g. inflated. This should be set to false if and only if the application is going to copy entries from an input ZIP file to an output ZIP file.

Returns:

A stream to read the entry data from or null if the entry does not exist.

Throws:

ZipAuthenticationException - If the entry is encrypted and checking the MAC fails.

ZipException - If this file is not compatible to the ZIP File Format Specification.

IOException - If the entry cannot get read from this ZipFile.

getName

public String getName()

Returns the string representation of whatever input source object was used to construct this ZIP file. For String and Path objects, this is a path name.

getPostambleInputStream

public InputStream getPostambleInputStream()
                                    throws IOException

Description copied from class: AbstractZipFile

Returns an InputStream to load the postamble of this ZIP file.

Note that the returned stream is a lightweight stream, i.e. there is no external resource such as a SeekableByteChannel allocated for it. Instead, all streams returned by this method share the underlying SeekableByteChannel of this ZipFile. This allows to close this object (and hence the underlying SeekableByteChannel) without cooperation of the returned streams, which is important if the client application wants to work on the underlying file again (e.g. update or delete it).

Overrides:

getPostambleInputStream in class AbstractZipFile<ZipEntry>

Throws:

ZipException - If this ZIP file has been closed.

IOException

getPreambleInputStream

public InputStream getPreambleInputStream()
                                   throws IOException

Description copied from class: AbstractZipFile

Returns an InputStream to load the preamble of this ZIP file.

Note that the returned stream is a lightweight stream, i.e. there is no external resource such as a SeekableByteChannel allocated for it. Instead, all streams returned by this method share the underlying SeekableByteChannel of this ZipFile. This allows to close this object (and hence the underlying SeekableByteChannel) without cooperation of the returned streams, which is important if the client application wants to work on the underlying file again (e.g. update or delete it).

Overrides:

getPreambleInputStream in class AbstractZipFile<ZipEntry>

Throws:

ZipException - If this ZIP file has been closed.

IOException

iterator

public Iterator<ZipEntry> iterator()

Iterates through clones for all entries in this ZIP file. The iteration does not support element removal.

Specified by:

iterator in interface Iterable<ZipEntry>

Overrides:

iterator in class AbstractZipFile<ZipEntry>

recoverLostEntries

public ZipFile recoverLostEntries()
                           throws IOException

Recovers any lost entries which have been added to the ZIP file after the (last) End Of Central Directory Record (EOCDR). This method should be called immediately after the constructor. It requires a fully initialized object, hence it's not part of the constructor. For example, to recover encrypted entries, it may require crypto parameters.

This method starts parsing entries at the start of the postamble and continues until it hits EOF or any non-entry data. As a side effect, it will not only add any found entries to its internal map, but will also cut the start of the postamble accordingly.

Note that it's very likely that this method terminates with an exception unless the postamble is empty or contains only valid ZIP entries. Therefore it may be a good idea to log or silently ignore any exception thrown by this method. If an exception is thrown, you can check and recover the remaining postamble for post-mortem analysis by calling AbstractZipFile.getPostambleLength() and AbstractZipFile.getPostambleInputStream().

Note that this method is not thread-safe!

Overrides:

recoverLostEntries in class AbstractZipFile<ZipEntry>

Returns:

this

Throws:

ZipException - if an invalid entry is found.

EOFException - on unexpected end-of-file.

IOException - on any I/O error.

setCryptoParameters

public void setCryptoParameters(@CheckForNull
                                ZipCryptoParameters cryptoParameters)

Sets the parameters for encryption or authentication of entries.

Parameters:

cryptoParameters - the parameters for encryption or authentication of entries.