Package com.chilkatsoft.chilkat2

Class ZipEntry

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.ZipEntry
All Implemented Interfaces:
AutoCloseable
public class ZipEntry extends ChilkatObject
<section class="zipentry-summary">

Inspect, extract, update, and iterate individual entries inside a ZIP archive.

Chilkat.ZipEntry represents a single item associated with a Chilkat.Zip archive. An entry may be a file already stored in an opened ZIP, a referenced filesystem file waiting to be compressed, an in-memory text or binary entry, or a directory entry. It provides access to entry-level metadata, compressed and uncompressed data, timestamps, attributes, CRC values, encryption information, and extraction or replacement operations for that specific ZIP item.

Entry metadata

Inspect filenames, stored ZIP paths, comments, timestamps, CRC values, attributes, sizes, compression method, and compression level.

Entry type and state

Use EntryType to understand whether the entry comes from an existing ZIP, a filesystem reference, memory data, or a directory.

Extract one entry

Extract a selected file entry to disk, inflate its contents into memory, or read the uncompressed data into Chilkat objects.

Read compressed data

Access the raw compressed entry data when an application needs ZIP-level control rather than only the inflated contents.

Replace or append data

Update an entry's contents from strings, byte data, files, or in-memory data sources before writing the ZIP archive.

Iterate archive entries

Walk through entries returned from Chilkat.Zip methods to inspect, filter, extract, or modify ZIP contents one item at a time.

Common pattern: Open or create a Chilkat.Zip object, obtain a ZipEntry using methods such as EntryAt, EntryOf, EntryMatching, or FirstEntry, then inspect metadata, extract contents, update the entry, or continue iterating through the archive. Use Chilkat.Zip for whole-archive operations and ZipEntry for operations on one specific archive item.

For an extended overview, see ZipEntry Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • ZipEntry

      public ZipEntry()
      Creates a new ZipEntry object.

  • Method Details

    • getComment

      public String getComment()
      Gets or sets the comment stored in the ZIP archive for this entry.
      Returns:
      the value of the Comment property

    • setComment

      public void setComment​(String value)
      Sets the Comment property; see getComment().
      Parameters:
      value - the new value (not null)

    • getCompressedLength

      public long getCompressedLength()
      The compressed size of this entry, in bytes.

      For mapped entries (entries already contained within an opened ZIP archive), this property contains the actual compressed size stored within the ZIP.

      For file entries or data entries that have not yet been written to a ZIP archive, compression has not yet occurred. In these cases, this property contains:

      • The current uncompressed data size for data entries.
      • The cached filesystem file size for referenced file entries.

      After the ZIP archive is written, the entries become mapped entries, and this property then reflects the actual compressed size stored in the ZIP archive.

      Returns:
      the value of the CompressedLength property (read-only)

    • getCompressedLength64

      public long getCompressedLength64()
      The compressed size of this entry, in bytes, as a 64-bit integer.

      For mapped entries (entries already contained within an opened ZIP archive), this property contains the actual compressed size stored within the ZIP.

      For file entries or data entries that have not yet been written to a ZIP archive, compression has not yet occurred. In these cases, this property contains:

      • The current uncompressed data size for data entries.
      • The cached filesystem file size for referenced file entries.

      After the ZIP archive is written, the entries become mapped entries, and this property then reflects the actual compressed size stored in the ZIP archive.

      Use this property when sizes may exceed the range of a 32-bit integer.

      Returns:
      the value of the CompressedLength64 property (read-only)

    • getCompressedLengthStr

      public String getCompressedLengthStr()
      The compressed size of this entry as a decimal string.

      For mapped entries (entries already contained within an opened ZIP archive), this property contains the actual compressed size stored within the ZIP.

      For file entries or data entries that have not yet been written to a ZIP archive, compression has not yet occurred. In these cases, this property contains:

      • The current uncompressed data size for data entries.
      • The cached filesystem file size for referenced file entries.

      After the ZIP archive is written, the entries become mapped entries, and this property then reflects the actual compressed size stored in the ZIP archive.

      This property is useful when sizes may exceed the range of a 32-bit integer.

      Returns:
      the value of the CompressedLengthStr property (read-only)

    • getCompressionLevel

      public int getCompressionLevel()
      Gets or sets the compression level for this entry.

      A value of 0 means no compression, and a value of 9 means maximum compression.

      The default value is 6.

      Returns:
      the value of the CompressionLevel property

    • setCompressionLevel

      public void setCompressionLevel​(int value)
      Sets the CompressionLevel property; see getCompressionLevel().
      Parameters:
      value - the new value

    • getCompressionMethod

      public int getCompressionMethod()
      Gets or sets the compression method used for this entry.
      • 0 means no compression.
      • 8 means Deflate compression.

      Deflate is the standard compression algorithm used by common ZIP utilities such as WinZip.

      Returns:
      the value of the CompressionMethod property

    • setCompressionMethod

      public void setCompressionMethod​(int value)
      Sets the CompressionMethod property; see getCompressionMethod().
      Parameters:
      value - the new value

    • getCrc

      public int getCrc()
      The CRC value for this ZIP entry.

      For AES-encrypted entries, the CRC value is 0.

      Returns:
      the value of the Crc property (read-only)

    • getEncryptionKeyLen

      public int getEncryptionKeyLen()
      The AES encryption key length for this entry.

      If this entry is AES encrypted, the value is 128, 192, or 256.

      If this entry is not AES encrypted, the value is 0.

      Returns:
      the value of the EncryptionKeyLen property (read-only)

    • getEntryID

      public int getEntryID()
      A unique identifier assigned to this entry while the ZIP object is instantiated in memory.

      This ID can be used to retrieve the same entry later with Zip.EntryById.

      Returns:
      the value of the EntryID property (read-only)

    • getEntryType

      public int getEntryType()
      Indicates the origin and current state of this ZIP entry.
      • 0 — Mapped Entry: an entry that already exists in an open ZIP file.
      • 1 — File Entry: a file in the local filesystem that has been referenced, but not yet read or compressed.
      • 2 — Data Entry: an entry containing uncompressed data already held in memory.
      • 3 — Null Entry: an entry that no longer exists in the ZIP archive.
      • 4 — New Directory Entry: a directory entry added to the ZIP object.

      When the ZIP archive is written by calling WriteZip or WriteToMemory, entries are transformed into mapped entries. In other words, after writing, they point to compressed data contained in the newly created or rewritten ZIP archive.

      Returns:
      the value of the EntryType property (read-only)

    • getFileDateTimeStr

      public String getFileDateTimeStr()
      Gets or sets the local last-modified date/time for this ZIP entry in RFC 822 string format.

      Example RFC 822 date/time strings:

      Tue, 15 Nov 1994 12:45:26 GMT
      Fri, 05 Jan 2024 18:30:00 -0500

      The timezone may be specified either as a named timezone such as GMT, or as a numeric UTC offset such as -0500.

      Returns:
      the value of the FileDateTimeStr property

    • setFileDateTimeStr

      public void setFileDateTimeStr​(String value)
      Sets the FileDateTimeStr property; see getFileDateTimeStr().
      Parameters:
      value - the new value (not null)

    • getFileName

      public String getFileName()
      Gets or sets the filename, including any relative path, stored for this entry inside the ZIP archive.

      Changing this property changes the path/name that will appear in the ZIP archive. It does not rename a source file in the local filesystem.

      Returns:
      the value of the FileName property

    • setFileName

      public void setFileName​(String value)
      Sets the FileName property; see getFileName().
      Parameters:
      value - the new value (not null)

    • getFileNameHex

      public String getFileNameHex()
      Returns the raw filename bytes found in the ZIP entry, encoded as a hexadecimal string.

      This can be useful for diagnosing filename encoding issues.

      Returns:
      the value of the FileNameHex property (read-only)

    • getHeartbeatMs

      public int getHeartbeatMs()
      The interval in milliseconds between each AbortCheck event callback, which enables an application to abort certain method calls before they complete. By default, HeartbeatMs is set to 0, meaning no AbortCheck event callbacks will trigger.
      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getIsAesEncrypted

      public boolean getIsAesEncrypted()
      Indicates whether this ZIP entry is AES encrypted.

      This property can be true only for entries already contained in a ZIP archive, such as entries obtained after calling OpenZip, OpenBd, or OpenFromMemory.

      If the entry is not AES encrypted, the property is false.

      Returns:
      the value of the IsAesEncrypted property (read-only)

    • getIsDirectory

      public boolean getIsDirectory()
      Indicates whether this ZIP entry is a directory entry.

      The value is true if the entry represents a directory, and false if it represents a file.

      Returns:
      the value of the IsDirectory property (read-only)

    • getTextFlag

      public boolean getTextFlag()
      Gets or sets the text flag in the internal file attributes for this ZIP entry.

      This flag indicates whether the entry contents should be considered text rather than binary data.

      The flag is informational and does not need to be accurate for normal ZIP processing. It is provided for compatibility with applications that may be sensitive to this attribute.

      Returns:
      the value of the TextFlag property

    • setTextFlag

      public void setTextFlag​(boolean value)
      Sets the TextFlag property; see getTextFlag().
      Parameters:
      value - the new value

    • getUncompressedLength

      public long getUncompressedLength()
      The uncompressed size of this entry, in bytes.
      Returns:
      the value of the UncompressedLength property (read-only)

    • getUncompressedLength64

      public long getUncompressedLength64()
      The uncompressed size of this entry, in bytes, as a 64-bit integer.

      Use this property when the uncompressed size may exceed the range of a 32-bit integer.

      Returns:
      the value of the UncompressedLength64 property (read-only)

    • getUncompressedLengthStr

      public String getUncompressedLengthStr()
      The uncompressed size of this ZIP entry as a decimal string.

      This is useful when the uncompressed size may be larger than what can safely be represented by a 32-bit integer.

      Returns:
      the value of the UncompressedLengthStr property (read-only)

    • appendString

      public void appendString​(String strContent, String charset)
      Appends text data to this ZIP entry's file contents.

      The text is converted to bytes using the character encoding specified by charset, such as utf-8, utf-16, or ansi.

      If this entry is already a Data Entry (EntryType = 2), then the encoded bytes are appended directly to the existing uncompressed in-memory data.

      If this entry is not already a Data Entry, then the entry is first converted into a Data Entry before the new text data is appended.

      • If the entry is a mapped entry (EntryType = 0), the compressed ZIP entry data is first inflated into memory. The new text data is then appended, and the entry becomes a Data Entry containing the combined uncompressed data.
      • If the entry is a file entry (EntryType = 1), the referenced filesystem file is first loaded into memory. The new text data is then appended, and the entry becomes a Data Entry containing the combined data.

      After this method is called, the entry contents exist entirely as uncompressed in-memory data associated with the ZipEntry object.

      Parameters:
      strContent - the strContent argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copyToBase64

      public String copyToBase64()
      Returns the compressed data for this ZIP entry as a Base64-encoded string.

      This method can only be used when the entry already contains compressed data, meaning the entry is a mapped entry.

      This is possible for entries from a ZIP archive that has already been opened, or after writing a ZIP archive while it remains open.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copyToHex

      public String copyToHex()
      Returns the compressed data for this ZIP entry as a hexadecimal encoded string.

      This method can only be used when the entry already contains compressed data, meaning the entry is a mapped entry.

      This is possible for entries from a ZIP archive that has already been opened, or after writing a ZIP archive while it remains open.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • extract

      public void extract​(String dirPath)
      Extracts this ZIP entry beneath the specified base directory.

      The entry is extracted according to the relative path stored in the ZIP archive.

      For example, if the entry filename is docs/readme.txt and dirPath is c:/temp/output, the file is extracted to c:/temp/output/docs/readme.txt.

      Use ExtractInto instead if the file should be extracted directly into a specific directory regardless of the path stored in the ZIP archive.

      Parameters:
      dirPath - the dirPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • extractInto

      public void extractInto​(String dirPath)
      Extracts this entry directly into the specified directory, ignoring any path information stored in the ZIP entry.

      For example, if the entry filename is docs/readme.txt and dirPath is c:/temp/output, the file is extracted to c:/temp/output/readme.txt.

      If this entry is a directory entry, nothing is extracted. To create the directory represented by a directory entry, use Extract instead.

      Parameters:
      dirPath - the dirPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getNext

      public boolean getNext()
      Updates this ZipEntry object so that it represents the next entry in the same ZIP archive.

      The next entry may be either a file entry or a directory entry.

      Returns true if the object was advanced to the next entry. Returns false if there are no more entries.

      Returns:
      the result; this method never throws ChilkatException

    • getNextMatch

      public boolean getNextMatch​(String pattern)
      Updates this ZipEntry object so that it represents the next entry in the ZIP archive matching the specified wildcard pattern.

      The wildcard character * matches zero or more characters. Matching is performed against the full stored filename, including any relative path.

      The matching entry may be either a file entry or a directory entry.

      Returns true if a matching entry is found. Returns false if no further matching entry exists.

      Parameters:
      pattern - the pattern argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • replaceString

      public void replaceString​(String strContent, String charset)
      Replaces this ZIP entry's existing contents with new text data.

      The text is converted to bytes using the character encoding specified by charset, such as utf-8 or ansi.

      The resulting bytes become the complete contents of the entry.

      Parameters:
      strContent - the strContent argument (not null)
      charset - the charset argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setDt

      public void setDt​(DateTime dt)
      Sets the last-modified date/time for this ZIP entry.

      The dt argument is a CkDateTime object containing the date/time to store for the entry.

      Parameters:
      dt - the dt argument (not null)

    • unzipToBd

      public void unzipToBd​(BinData binData)
      Unzips this entry directly into a BinData object.

      The uncompressed bytes are written to binData.

      Parameters:
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unzipToSb

      public void unzipToSb​(int lineEndingBehavior, String srcCharset, StringBuilder sb)
      Unzips this entry as text and appends the result to a StringBuilder.

      The srcCharset argument specifies how the uncompressed bytes should be interpreted, such as utf-8, utf-16, or windows-1252.

      The lineEndingBehavior argument controls line-ending conversion:

      • 0 — leave line endings unchanged.
      • 1 — convert all line endings to bare LF.
      • 2 — convert all line endings to CRLF.

      Parameters:
      lineEndingBehavior - the lineEndingBehavior argument
      srcCharset - the srcCharset argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unzipToStream

      public void unzipToStream​(Stream toStream)
      Unzips this entry to a stream.

      If called synchronously, the toStream must have a sink, such as a file or another stream object.

      If called asynchronously, the foreground thread can read from the stream while the unzip operation writes to it.

      Parameters:
      toStream - the toStream argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unzipToString

      public String unzipToString​(int lineEndingBehavior, String srcCharset)
      Inflates this entry and returns the uncompressed data as a string.

      The srcCharset argument specifies how the uncompressed bytes should be interpreted, such as utf-8, utf-16, or windows-1252.

      The lineEndingBehavior argument controls line-ending conversion:

      • 0 — leave line endings unchanged.
      • 1 — convert all line endings to bare LF.
      • 2 — convert all line endings to CRLF.

      Parameters:
      lineEndingBehavior - the lineEndingBehavior argument
      srcCharset - the srcCharset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener