net.java.truevfs.comp.zip

Class AbstractZipFile<E extends ZipEntry>

java.lang.Object

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

Type Parameters:

E - the type of the ZIP entries.

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<E>

Direct Known Subclasses:

ZipFile, ZipInputService

@NotThreadSafe
 @CleanupObligation
public abstract class AbstractZipFile<E extends ZipEntry>
extends Object
implements Closeable, Iterable<E>

Provides unsafe (raw) access to a ZIP file using shared ZipEntry instances.

Warning: This class is not intended for public use - its API may change at will without prior notification!

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 Flags, 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.

Author:

Christian Schlichtherle

See Also:

AbstractZipOutputStream

Field Summary

Fields

Modifier and Type	Field and Description
static Charset	DEFAULT_CHARSET The default character set used for entry names and comments in ZIP files.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractZipFile(net.java.truecommons.io.Source source, ZipFileParameters<E> param) Reads the given zip file in order to provide random access to 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.
E	entry(String name) Returns the entry for the given name or null if no entry with this name exists in this ZIP file.
String	getCharset() Returns the name of the character set which is effectively used for decoding entry names and the file comment.
InputStream	getCheckedInputStream(String name) Equivalent to getInputStream(name, true, true).
String	getComment() Returns the file comment.
protected abstract ZipCryptoParameters	getCryptoParameters() Returns the parameters for encryption or authentication of entries.
InputStream	getInputStream(String name) Equivalent to getInputStream(name, null, true).
protected InputStream	getInputStream(String name, Boolean check, boolean process) Returns an InputStream for reading the contents of the given entry.
InputStream	getPostambleInputStream() Returns an InputStream to load the postamble of this ZIP file.
long	getPostambleLength() Returns the size of the postamble of this ZIP file in bytes.
InputStream	getPreambleInputStream() Returns an InputStream to load the preamble of this ZIP file.
long	getPreambleLength() Returns the size of the preamble of this ZIP file in bytes.
Charset	getRawCharset() Returns the character set which is effectively used for decoding entry names and the file comment.
Iterator<E>	iterator() Returns an iteration of all entries in this ZIP file.
long	length() Returns the file length of this ZIP file in bytes.
boolean	offsetsConsiderPreamble() Returns true if and only if the offsets in this ZIP file are relative to the start of the file, rather than the first Local File Header.
AbstractZipFile<E>	recoverLostEntries() Recovers any lost entries which have been added to the ZIP file after the (last) End Of Central Directory Record (EOCDR).
int	size() Returns the number of entries in this ZIP file.

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

Field Detail

DEFAULT_CHARSET

public static final Charset DEFAULT_CHARSET

The default character set used for entry names and comments in ZIP files. This is "UTF-8" for compatibility with Sun's JDK implementation. Note that you should use "IBM437" for ordinary ZIP files instead.

Constructor Detail

AbstractZipFile

@CreatesObligation
protected AbstractZipFile(net.java.truecommons.io.Source source,
                                             ZipFileParameters<E> param)
                                      throws ZipException,
                                             EOFException,
                                             IOException

Reads the given zip file in order to provide random access to its entries.

Parameters:

source - the source for reading the ZIP file from.

param - the parameters for reading the ZIP file.

Throws:

ZipException - if the source data is not compatible to 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()

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

close

@DischargesObligation
public void close()
                                 throws IOException

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

Throws:

IOException - if an error occurs closing the file.

entry

public E entry(String name)

Returns the entry for the given name or null if no entry with this name exists in this ZIP file. Note that the returned entry is shared with this instance - it is an error to change its state!

Parameters:

name - the name of the ZIP entry.

Returns:

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

getCharset

public String getCharset()

Returns the name of the character set which is effectively used for decoding entry names and the file comment. Depending on the ZIP file contents, this may differ from the character set provided to the constructor.

getCheckedInputStream

@CreatesObligation
 @Nullable
public final InputStream getCheckedInputStream(String name)
                                                                      throws IOException

Equivalent to getInputStream(name, true, true).

Throws:

IOException

getComment

@Nullable
public String getComment()

Returns the file comment.

Returns:

The file comment.

getCryptoParameters

@CheckForNull
protected abstract ZipCryptoParameters getCryptoParameters()

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

getInputStream

@CreatesObligation
 @Nullable
public final InputStream getInputStream(String name)
                                                               throws IOException

Equivalent to getInputStream(name, null, true).

Throws:

IOException

getInputStream

@CreatesObligation
 @Nullable
protected InputStream getInputStream(String name,
                                                                   @CheckForNull
                                                                   Boolean check,
                                                                   boolean process)
                                                            throws ZipException,
                                                                   IOException

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

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

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.

getPostambleInputStream

@CreatesObligation
public InputStream getPostambleInputStream()
                                                       throws IOException

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).

Throws:

ZipException - If this ZIP file has been closed.

IOException

getPostambleLength

public long getPostambleLength()

Returns the size of the postamble of this ZIP file in bytes.

Returns:

A positive value or zero to indicate that this ZIP file does not have a postamble.

getPreambleInputStream

@CreatesObligation
public InputStream getPreambleInputStream()
                                                      throws IOException

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).

Throws:

ZipException - If this ZIP file has been closed.

IOException

getPreambleLength

public long getPreambleLength()

Returns the size of the preamble of this ZIP file in bytes.

Returns:

A positive value or zero to indicate that this ZIP file does not have a preamble.

getRawCharset

public Charset getRawCharset()

Returns the character set which is effectively used for decoding entry names and the file comment. Depending on the ZIP file contents, this may differ from the character set provided to the constructor.

iterator

public Iterator<E> iterator()

Returns an iteration of all entries in this ZIP file. Note that the iterated entries are shared with this instance. It is illegal to change their state!

Specified by:

iterator in interface Iterable<E extends ZipEntry>

length

public long length()

Returns the file length of this ZIP file in bytes.

offsetsConsiderPreamble

public boolean offsetsConsiderPreamble()

Returns true if and only if the offsets in this ZIP file are relative to the start of the file, rather than the first Local File Header.

This method is intended for very special purposes only.

recoverLostEntries

public AbstractZipFile<E> recoverLostEntries()
                                      throws ZipException,
                                             EOFException,
                                             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 getPostambleLength() and getPostambleInputStream().

Returns:

this

Throws:

ZipException - if an invalid entry is found.

EOFException - on unexpected end-of-file.

IOException - on any I/O error.

size

public int size()

Returns the number of entries in this ZIP file.