de.schlichtherle.util.zip
Class BasicZipFile

java.lang.Object
  extended by de.schlichtherle.util.zip.BasicZipFile
Direct Known Subclasses:
ZipFile, ZipInputArchive

public class BasicZipFile
extends Object

This class is not intended for public use! The methods in this class are unsynchronized and entries/getEntry(java.lang.String) enumerate/return ZipEntry instances which are shared with this class rather than clones of them. This may be used by subclasses in order to benefit from the slightly better performance.

Since:
TrueZIP 6.4
Version:
TrueZIP 6.7
Author:
Christian Schlichtherle
See Also:
ZipFile

Field Summary
static String DEFAULT_CHARSET
          The default character set used for entry names and comments in ZIP compatible files.
 
Constructor Summary
BasicZipFile(File file)
          Opens the given file for reading its ZIP contents, assuming "UTF-8" charset for file names.
BasicZipFile(File file, String charset)
          Opens the given file for reading its ZIP contents, assuming the specified charset for file names.
BasicZipFile(File file, String charset, boolean preambled, boolean postambled)
          Opens the given file for reading its ZIP contents, assuming the specified charset for file names.
BasicZipFile(ReadOnlyFile rof)
          Opens the given read only file for reading its ZIP contents, assuming "UTF-8" charset for file names.
BasicZipFile(ReadOnlyFile rof, String charset)
          Opens the given read only file for reading its ZIP contents, assuming the specified charset for file names.
BasicZipFile(ReadOnlyFile rof, String charset, boolean preambled, boolean postambled)
          Opens the given read only file for reading its ZIP contents, assuming the specified charset for file names.
BasicZipFile(String name)
          Opens the given file for reading its ZIP contents, assuming "UTF-8" charset for file names.
BasicZipFile(String name, String charset)
          Opens the given file for reading its ZIP contents, assuming the specified charset for file names.
BasicZipFile(String name, String charset, boolean preambled, boolean postambled)
          Opens the given file for reading its ZIP contents, assuming the specified charset for file names.
 
Method Summary
 boolean busy()
          Returns true if and only if some input streams are open to read from this ZIP compatible file.
 void close()
          Closes the file.
protected  ReadOnlyFile createReadOnlyFile(File file)
          A factory method called by the constructor to get a read only file to access the contents of the ZIP file.
protected  ZipEntry createZipEntry(String name)
          A factory method returning a newly created ZipEntry for the given name.
 Enumeration entries()
          Returns an enumeration of the ZIP entries in this ZIP file.
 String getCharset()
          Returns the charset to use for entry names and comments.
 InputStream getCheckedInputStream(String name)
          Equivalent to getInputStream(name, true, true).
 InputStream getCheckedInputStream(ZipEntry entry)
          Equivalent to getInputStream(entry.getName(), true, true) instead.
 String getComment()
          Returns the comment of this ZIP compatible file or null if no comment exists.
 String getEncoding()
          Deprecated. Use getCharset() instead.
 ZipEntry getEntry(String name)
          Returns the ZipEntry for the given name or null if no entry with that name exists.
 InputStream getInputStream(String name)
          Equivalent to getInputStream(name, false, true).
 InputStream getInputStream(String name, boolean inflate)
          Deprecated.  
protected  InputStream getInputStream(String name, boolean check, boolean inflate)
          Returns an InputStream for reading the inflated or deflated data of the given entry.
 InputStream getInputStream(ZipEntry entry)
          Equivalent to getInputStream(entry.getName(), false, true) instead.
 InputStream getInputStream(ZipEntry entry, boolean inflate)
          Deprecated.  
 InputStream getPostambleInputStream()
          Returns an InputStream to read the postamble of this ZIP compatible file.
 long getPostambleLength()
          Returns the length of the postamble of this ZIP compatible file in bytes.
 InputStream getPreambleInputStream()
          Returns an InputStream to read the preamble of this ZIP compatible file.
 long getPreambleLength()
          Returns the length of the preamble of this ZIP compatible file in bytes.
 long length()
          Returns the file length of this ZIP compatible 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.
 int size()
          Returns the number of entries in this ZIP compatible file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_CHARSET

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

See Also:
Constant Field Values
Constructor Detail

BasicZipFile

public BasicZipFile(String name)
             throws NullPointerException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming "UTF-8" charset for file names.

Parameters:
name - name of the file.
Throws:
NullPointerException - If name is null.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(String name,
                    String charset)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
name - name of the file.
charset - the charset to use for file names
Throws:
NullPointerException - If name or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(String name,
                    String charset,
                    boolean preambled,
                    boolean postambled)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
name - name of the file.
charset - the charset to use for file names
preambled - If this is true, then the ZIP compatible file may have a preamble. Otherwise, the ZIP compatible file must start with either a Local File Header (LFH) signature or an End Of Central Directory (EOCD) Header, causing this constructor to fail fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX), which usually contain the application code required for extraction in a preamble. This parameter is true by default.
postambled - If this is true, then the ZIP compatible file may have a postamble of arbitrary length. Otherwise, the ZIP compatible 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 fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX) with large postambles. This parameter is false by default.
Throws:
NullPointerException - If name or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(File file)
             throws NullPointerException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming "UTF-8" charset for file names.

Parameters:
file - The file.
Throws:
NullPointerException - If file is null.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(File file,
                    String charset)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
file - The file.
charset - The charset to use for entry names and comments - must not be null!
Throws:
NullPointerException - If file or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(File file,
                    String charset,
                    boolean preambled,
                    boolean postambled)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
file - The file.
charset - The charset to use for entry names and comments - must not be null!
preambled - If this is true, then the ZIP compatible file may have a preamble. Otherwise, the ZIP compatible file must start with either a Local File Header (LFH) signature or an End Of Central Directory (EOCD) Header, causing this constructor to fail fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX), which usually contain the application code required for extraction in a preamble. This parameter is true by default.
postambled - If this is true, then the ZIP compatible file may have a postamble of arbitrary length. Otherwise, the ZIP compatible 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 fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX) with large postambles. This parameter is false by default.
Throws:
NullPointerException - If file or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(ReadOnlyFile rof)
             throws NullPointerException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given read only file for reading its ZIP contents, assuming "UTF-8" charset for file names.

Parameters:
rof - The read only file. Note that this constructor never closes this file.
Throws:
NullPointerException - If rof is null.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(ReadOnlyFile rof,
                    String charset)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given read only file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
rof - The read only file. Note that this constructor never closes this file.
charset - The charset to use for entry names and comments - must not be null!
Throws:
NullPointerException - If rof or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.

BasicZipFile

public BasicZipFile(ReadOnlyFile rof,
                    String charset,
                    boolean preambled,
                    boolean postambled)
             throws NullPointerException,
                    UnsupportedEncodingException,
                    FileNotFoundException,
                    ZipException,
                    IOException
Opens the given read only file for reading its ZIP contents, assuming the specified charset for file names.

Parameters:
rof - The read only file. Note that this constructor never closes this file.
charset - The charset to use for entry names and comments - must not be null!
preambled - If this is true, then the ZIP compatible file may have a preamble. Otherwise, the ZIP compatible file must start with either a Local File Header (LFH) signature or an End Of Central Directory (EOCD) Header, causing this constructor to fail fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX), which usually contain the application code required for extraction in a preamble. This parameter is true by default.
postambled - If this is true, then the ZIP compatible file may have a postamble of arbitrary length. Otherwise, the ZIP compatible 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 fast if the file is actually a false positive ZIP compatible file, i.e. not compatible to the ZIP File Format Specification. This may be used to read Self Extracting ZIP files (SFX) with large postambles. This parameter is false by default.
Throws:
NullPointerException - If rof or charset is null.
UnsupportedEncodingException - If charset is not supported by this JVM.
FileNotFoundException - If the file cannot get opened for reading.
ZipException - If the file is not ZIP compatible.
IOException - On any other I/O related issue.
Method Detail

createReadOnlyFile

protected ReadOnlyFile createReadOnlyFile(File file)
                                   throws FileNotFoundException,
                                          IOException
A factory method called by the constructor to get a read only file to access the contents of the ZIP file. This method is only used if the constructor isn't called with a read only file as its parameter.

Throws:
FileNotFoundException - If the file cannot get opened for reading.
IOException - On any other I/O related issue.

createZipEntry

protected ZipEntry createZipEntry(String name)
A factory method returning a newly created ZipEntry for the given name.


getComment

public String getComment()
Returns the comment of this ZIP compatible file or null if no comment exists.


busy

public boolean busy()
Returns true if and only if some input streams are open to read from this ZIP compatible file.


getCharset

public String getCharset()
Returns the charset to use for entry names and comments.


getEncoding

public String getEncoding()
Deprecated. Use getCharset() instead.


entries

public Enumeration entries()
Returns an enumeration of the ZIP entries in this ZIP file. Note that the enumerated entries are shared with this class. It is illegal to change their state!


getEntry

public ZipEntry getEntry(String name)
Returns the ZipEntry for the given name or null if no entry with that name exists. Note that the returned entry is shared with this class. It is illegal to change its state!

Parameters:
name - Name of the ZIP entry.

size

public int size()
Returns the number of entries in this ZIP compatible file.


length

public long length()
            throws IOException
Returns the file length of this ZIP compatible file in bytes.

Throws:
IOException

getPreambleLength

public long getPreambleLength()
Returns the length of the preamble of this ZIP compatible file in bytes.

Returns:
A positive value or zero to indicate that this ZIP compatible file does not have a preamble.
Since:
TrueZIP 5.1

getPreambleInputStream

public InputStream getPreambleInputStream()
                                   throws IOException
Returns an InputStream to read the preamble of this ZIP compatible file.

Note that the returned stream is a lightweight stream, i.e. there is no external resource such as a ReadOnlyFile allocated for it. Instead, all streams returned by this method share the underlying ReadOnlyFile of this ZipFile. This allows to close this object (and hence the underlying ReadOnlyFile) without cooperation of the returned streams, which is important if the 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
Since:
TrueZIP 5.1

getPostambleLength

public long getPostambleLength()
Returns the length of the postamble of this ZIP compatible file in bytes.

Returns:
A positive value or zero to indicate that this ZIP compatible file does not have an postamble.
Since:
TrueZIP 5.1

getPostambleInputStream

public InputStream getPostambleInputStream()
                                    throws IOException
Returns an InputStream to read the postamble of this ZIP compatible file.

Note that the returned stream is a lightweight stream, i.e. there is no external resource such as a ReadOnlyFile allocated for it. Instead, all streams returned by this method share the underlying ReadOnlyFile of this ZipFile. This allows to close this object (and hence the underlying ReadOnlyFile) without cooperation of the returned streams, which is important if the 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
Since:
TrueZIP 5.1

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.


getInputStream

public final InputStream getInputStream(String name)
                                 throws IOException
Equivalent to getInputStream(name, false, true).

Throws:
IOException

getInputStream

public final InputStream getInputStream(ZipEntry entry)
                                 throws IOException
Equivalent to getInputStream(entry.getName(), false, true) instead.

Throws:
IOException

getCheckedInputStream

public final InputStream getCheckedInputStream(String name)
                                        throws IOException
Equivalent to getInputStream(name, true, true).

Throws:
IOException

getCheckedInputStream

public final InputStream getCheckedInputStream(ZipEntry entry)
                                        throws IOException
Equivalent to getInputStream(entry.getName(), true, true) instead.

Throws:
IOException

getInputStream

public InputStream getInputStream(String name,
                                  boolean inflate)
                           throws IOException
Deprecated. 

Throws:
IOException

getInputStream

public final InputStream getInputStream(ZipEntry entry,
                                        boolean inflate)
                                 throws IOException
Deprecated. 

Throws:
IOException

getInputStream

protected InputStream getInputStream(String name,
                                     boolean check,
                                     boolean inflate)
                              throws IOException
Returns an InputStream for reading the inflated or deflated data 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 - may not be null!
check - Whether or not the entry's CRC-32 value is checked. If and only if this parameter is true, two additional checks are performed for the ZIP entry:
  1. All entry headers are checked to have consistent declarations of the CRC-32 value for the inflated entry data.
  2. When calling InputStream.close() on the returned entry stream, the CRC-32 value computed from the inflated entry data is checked against the declared CRC-32 values. This is independent from the inflate parameter.
If any of these checks fail, a CRC32Exception is thrown.

This parameter should be false for most applications, and is the default for the sibling of this class in java.util.zip.ZipFile.

inflate - Whether or not the entry data should be inflated. If false, the entry data is not inflated, even if the entry data is deflated. This parameter should be true for most applications.
Returns:
A stream to read the entry data from or null if the entry does not exist.
Throws:
NullPointerException - If name is null.
CRC32Exception - If the declared CRC-32 values of the inflated entry data are inconsistent across the entry headers.
ZipException - If this file is not compatible to the ZIP File Format Specification.
IOException - If the entry cannot get read from this ZipFile.
Since:
TrueZIP 6.4

close

public void close()
           throws IOException
Closes the file. This closes any open input streams reading from this ZIP file.

Throws:
IOException - if an error occurs closing the file.