RawZipFile (TrueZIP Driver ZIP 7.4.2 API)

java.lang.Object
- de.schlichtherle.truezip.zip.RawZipFile<E>

All Implemented Interfaces:

Closeable, AutoCloseable, Iterable<E>

Direct Known Subclasses:

ZipFile, ZipInputShop
```
@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public abstract class RawZipFile<E extends ZipEntry>
extends Object
implements Iterable<E>, Closeable
```
Provides unsafe (raw) access to a ZIP file using unsynchronized methods and 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:
RawZipOutputStream

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private class`	`RawZipFile.EntryReadOnlyFile` An interval read only file which accounts for itself until it gets closed.
`private static class`	`RawZipFile.SafeBufferedReadOnlyFile` A buffered read only file which is safe for use with a concurrently growing file, e.g. when another thread is appending to it.

Field Summary

Fields
Modifier and Type	Field and Description
`private Charset`	`charset` The charset to use for entry names and comments.
`private byte[]`	`comment` The encoded file comment.
`static Charset`	`DEFAULT_CHARSET` The default character set used for entry names and comments in ZIP files.
`private Map<String,E>`	`entries` Maps entry names to zip entries.
`private long`	`length` The total number of bytes in the ZIP file.
`private static int`	`LFH_FILE_NAME_LENGTH_OFF`
`private OffsetMapper`	`mapper` Maps offsets specified in the ZIP file to real offsets in the file.
`private int`	`open` The number of open resources for reading the entries in this ZIP file.
`private ZipEntryFactory<E>`	`param`
`private long`	`postamble` The number of bytes in the postamble of this ZIP file.
`private long`	`preamble` The number of bytes in the preamble of this ZIP file.
`private ReadOnlyFile`	`rof` The nullable data source.

Constructor Summary

Constructors
Modifier	Constructor and Description
`(package private)`	`RawZipFile(Pool<ReadOnlyFile,IOException> source, ZipFileParameters<E> param)`
`protected`	`RawZipFile(ReadOnlyFile zip, ZipFileParameters<E> param)` Reads the given `zip` file in order to provide random access to its entries.

Method Summary

Methods
Modifier and Type	Method and Description
`(package private) void`	`assertOpen()` Asserts that this ZIP file is still open for reading its entries.
`private void`	`assertZipFileSignature(ReadOnlyFile rof)`
`boolean`	`busy()` Returns `true` if and only if this ZIP file is busy reading one or more entries.
`void`	`close()` Closes the file.
`private String`	`decode(byte[] bytes)`
`private int`	`findCentralDirectory(ReadOnlyFile rof, boolean postambled)` Positions the file pointer at the first Central File Header.
`private static int`	`getBufferSize(ZipEntry entry)`
`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)`.
`InputStream`	`getCheckedInputStream(ZipEntry entry)` Equivalent to `getInputStream(entry.getName(), true, true)` instead.
`String`	`getComment()` Returns the file comment.
`protected abstract ZipCryptoParameters`	`getCryptoParameters()` Returns the parameters for encryption or authentication of entries.
`E`	`getEntry(String name)` Returns the entry for the given name or `null` if no entry with this name exists.
`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`	`getInputStream(ZipEntry entry)` Equivalent to `getInputStream(entry.getName(), null, true)` instead.
`(package private) OffsetMapper`	`getOffsetMapper()`
`InputStream`	`getPostambleInputStream()` Returns an `InputStream` to read 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 read 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.
`(package private) byte[]`	`getRawComment()`
`(package private) Map<String,E>`	`getRawEntries()`
`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.
`private void`	`mountCentralDirectory(ReadOnlyFile rof, int numEntries)` Reads the central directory from the given read only file file and populates the internal tables with ZipEntry instances.
`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.
`void`	`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

- Field Detail
  - charset
```
private Charset charset
```
    The charset to use for entry names and comments.
  - comment
```
@CheckForNull
private byte[] comment
```
    The encoded file comment.
  - 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.
  - entries
```
private Map<String,E extends ZipEntry> entries
```
    Maps entry names to zip entries.
  - length
```
private long length
```
    The total number of bytes in the ZIP file.
  - LFH_FILE_NAME_LENGTH_OFF
```
private static final int LFH_FILE_NAME_LENGTH_OFF
```
    See Also:
    Constant Field Values
  - mapper
```
private OffsetMapper mapper
```
    Maps offsets specified in the ZIP file to real offsets in the file.
  - open
```
private int open
```
    The number of open resources for reading the entries in this ZIP file.
  - param
```
private final ZipEntryFactory<E extends ZipEntry> param
```
  - postamble
```
private long postamble
```
    The number of bytes in the postamble of this ZIP file.
  - preamble
```
private long preamble
```
    The number of bytes in the preamble of this ZIP file.
  - rof
```
@CheckForNull
private ReadOnlyFile rof
```
    The nullable data source.
- Constructor Detail
  - RawZipFile
```
RawZipFile(Pool<ReadOnlyFile,IOException> source,
          ZipFileParameters<E> param)
     throws IOException
```
    Throws:
    
    IOException
  - RawZipFile
```
protected RawZipFile(ReadOnlyFile zip,
          ZipFileParameters<E> param)
              throws IOException
```
    Reads the given zip file in order to provide random access to its entries.
    
    Parameters:
    zip - the ZIP file to be read.
    param - the parameters for reading the ZIP file.
    
    Throws:
    
    ZipException - if the file is not compatible to the ZIP File Format Specification.
    
    IOException - on any other I/O related issue.
    See Also:
    recoverLostEntries()
- Method Detail
  - assertOpen
```
final void assertOpen()
               throws ZipException
```
    Asserts that this ZIP file is still open for reading its entries.
    
    Throws:
    
    ZipException
  - assertZipFileSignature
```
private void assertZipFileSignature(ReadOnlyFile rof)
                             throws IOException
```
    Throws:
    
    IOException
  - busy
```
public boolean busy()
```
    Returns true if and only if this ZIP file is busy reading one or more entries.
  - close
```
public void close()
           throws IOException
```
    Closes the file. This closes any allocate 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.
  - decode
```
private String decode(byte[] bytes)
```
  - findCentralDirectory
```
private int findCentralDirectory(ReadOnlyFile rof,
                       boolean postambled)
                          throws IOException
```
    Positions the file pointer at the first Central File Header. Performs some means to check that this is really a ZIP file.
    As a side effect, the following fields will get initialized:
    - preamble
    - postamble
    The following fields may get updated:
    - comment
    - mapper
    Throws:
    
    ZipException - If the file is not compatible to the ZIP File Format Specification.
    
    IOException - On any other I/O error.
  - getBufferSize
```
private static int getBufferSize(ZipEntry entry)
```
  - 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
```
@Nullable
public final InputStream getCheckedInputStream(String name)
                                        throws IOException
```
    Equivalent to getInputStream(name, true, true).
    
    Throws:
    
    IOException
  - getCheckedInputStream
```
@Nullable
public final InputStream getCheckedInputStream(ZipEntry entry)
                                        throws IOException
```
    Equivalent to getInputStream(entry.getName(), true, true) instead.
    
    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.
    
    Since:
    
    TrueZIP 7.3
  - getEntry
```
public E getEntry(String name)
```
    Returns the entry for the given name or null if no entry with this name exists. Note that the returned entry is shared with this instance. It is illegal to change its state!
    
    Parameters:
    name - the name of the ZIP entry.
  - getInputStream
```
@Nullable
public final InputStream getInputStream(String name)
                                 throws IOException
```
    Equivalent to getInputStream(name, null, true).
    
    Throws:
    
    IOException
  - getInputStream
```
@Nullable
protected InputStream getInputStream(String name,
                                  @CheckForNull
                                  Boolean check,
                                  boolean process)
                              throws 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.
  - getInputStream
```
@Nullable
public final InputStream getInputStream(ZipEntry entry)
                                 throws IOException
```
    Equivalent to getInputStream(entry.getName(), null, true) instead.
    
    Throws:
    
    IOException
  - getOffsetMapper
```
final OffsetMapper getOffsetMapper()
```
  - getPostambleInputStream
```
public InputStream getPostambleInputStream()
                                    throws IOException
```
    Returns an InputStream to read 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 RawZipFile.EntryReadOnlyFile 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 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
```
public InputStream getPreambleInputStream()
                                   throws IOException
```
    Returns an InputStream to read 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 RawZipFile.EntryReadOnlyFile 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 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.
    
    Since:
    
    TrueZIP 7.3
  - getRawComment
```
@CheckForNull
final byte[] getRawComment()
```
  - getRawEntries
```
final Map<String,E> getRawEntries()
```
  - iterator
```
public Iterator<E> iterator()
```
    Returns an iteration of all entries in this ZIP file. Note that the iteration supports element removal and the returned 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.
  - mountCentralDirectory
```
private void mountCentralDirectory(ReadOnlyFile rof,
                         int numEntries)
                            throws IOException
```
    Reads the central directory from the given read only file file and populates the internal tables with ZipEntry instances.
    The ZipEntrys will know all data that can be obtained from the central directory alone, but not the data that requires the local file header or additional data to be read.
    As a side effect, the following fields will get initialized:
    - entries
    The following fields may get updated:
    - preamble
    - charset
    Throws:
    
    ZipException - If the file is not compatible to the ZIP File Format Specification.
    
    IOException - On any other I/O related issue.
  - 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 void 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 soon 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().
    
    Throws:
    
    ZipException - if an invalid entry is found.
    
    IOException - if any other I/O error occurs.
  - size
```
public int size()
```
    Returns the number of entries in this ZIP file.

Class RawZipFile<E extends ZipEntry>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

charset

comment

DEFAULT_CHARSET

entries

length

LFH_FILE_NAME_LENGTH_OFF

mapper

open

param

postamble

preamble

rof

Constructor Detail

RawZipFile

RawZipFile

Method Detail

assertOpen

assertZipFileSignature

busy

close

decode

findCentralDirectory

getBufferSize

getCharset

getCheckedInputStream

getCheckedInputStream

getComment

getCryptoParameters

getEntry

getInputStream

getInputStream

getInputStream

getOffsetMapper

getPostambleInputStream

getPostambleLength

getPreambleInputStream

getPreambleLength

getRawCharset

getRawComment

getRawEntries

iterator

length

mountCentralDirectory

offsetsConsiderPreamble

recoverLostEntries

size