Package com.chilkatsoft.chilkat2

Class Gzip

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

Compress, decompress, inspect, and convert GZIP data in files or memory.

Chilkat.Gzip provides GZIP compression and decompression for file-based and in-memory workflows. It can compress and uncompress files, strings, byte arrays, BinData, and encoded data such as Base64 or hex. It also supports .tar.gz extraction, gzip metadata such as original filename, timestamp, and comments, and inspection of GZIP header information without fully expanding the compressed data.

File compression

Compress files to .gz, uncompress .gz files, and write decompressed output directly to disk.

Memory-based data

Work with byte arrays and Chilkat.BinData for applications that need compression or decompression without temporary files.

String workflows

Compress and uncompress strings with explicit charset handling for text data that must round-trip correctly.

Encoded GZIP data

Handle GZIP data represented as Base64, hex, or other supported encoded forms when binary data must be carried as text.

GZIP metadata

Set or inspect metadata such as original filename, modified time, comments, and extra data stored in the GZIP header.

Tar-gzip and XFDL

Extract .tar.gz archives and decode XFDL content that uses gzip-related encodings.

Common pattern: Use Gzip when the data is a single GZIP stream, a .gz file, or a .tar.gz archive. For ZIP archives, use Chilkat.Zip; for raw deflate or zlib-style compression, use Chilkat.Compression.

For an extended overview, see Gzip Class 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

    • Gzip

      public Gzip()
      Creates a new Gzip object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set this property to true to request that the currently running operation be aborted. This is useful for long-running operations such as large file compression or decompression. Methods that complete quickly are generally not affected.

      If no method is currently running, the property is automatically reset to false when the next method begins. After an abort occurs, it is also reset to false. Both synchronous and asynchronous operations can be aborted. For synchronous calls, another thread must set this property.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getComment

      public String getComment()
      An optional comment to embed in the Gzip file when a Compress* method is called.
      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)

    • getCompressionLevel

      public int getCompressionLevel()
      Controls the compression level used when creating Gzip data. The value can range from 0 to 9.
      • 0 = no compression
      • 9 = maximum compression

      The default value is 6, which is a typical balance between compression size and speed. Higher levels may take significantly more CPU time while producing only slightly smaller output, depending on the data.

      Returns:
      the value of the CompressionLevel property

    • setCompressionLevel

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

    • getFilename

      public String getFilename()
      The filename to embed in the Gzip file when a Compress* method is called. Some Gzip extraction tools use this embedded filename as the default output filename.
      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)

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks. These callbacks allow an application to cancel certain long-running operations before they finish.

      The default value is 0, which means no AbortCheck callbacks are triggered.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • getLastModStr

      public String getLastModStr()
      Specifies the last-modified date/time to embed in the Gzip file when a Compress* method is called.

      The value must be provided as an RFC 822 formatted date/time string.

      Example: 

      Sun, 12 Apr 2026 12:45:26 GMT

      If this property is not set, the current system date/time is used automatically.

      Returns:
      the value of the LastModStr property

    • setLastModStr

      public void setLastModStr​(String value)
      Sets the LastModStr property; see getLastModStr().
      Parameters:
      value - the new value (not null)

    • getUseCurrentDate

      public boolean getUseCurrentDate()
      Controls the last-modified date/time assigned to files created by Uncompress* methods.

      When set to true, the extracted file uses the current date/time instead of the date/time stored in the Gzip data.

      Returns:
      the value of the UseCurrentDate property

    • setUseCurrentDate

      public void setUseCurrentDate​(boolean value)
      Sets the UseCurrentDate property; see getUseCurrentDate().
      Parameters:
      value - the new value

    • compressBd

      public void compressBd​(BinData binDat)
      Compresses the contents of a BinData object in place, replacing the original data with Gzip-compressed data.
      Parameters:
      binDat - the binDat argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • compressFile

      public void compressFile​(String srcPath, String destPath)
      Compresses a file and writes the result as a Gzip file, typically with a .gz extension.
      Parameters:
      srcPath - the srcPath argument (not null)
      destPath - the destPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • compressFile2

      public void compressFile2​(String srcPath, String embeddedFilename, String destPath)
      Compresses a file and writes the result as a Gzip file, while allowing a different filename to be embedded inside the Gzip data.

      The inFilename parameter is the actual file on disk. The srcPath parameter is the filename stored in the Gzip header and may be used by extraction tools as the output filename.

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

    • compressFileBd

      public void compressFileBd​(String filePath, BinData bd)
      Compresses a file and stores the resulting Gzip data in a BinData object.

      The compressed output is held in memory. The maximum compressed size is 4 GB.

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

    • compressSb

      public void compressSb​(StringBuilder sb, String charset, BinData bd)
      Compresses the text contained in a StringBuilder and writes the Gzip-compressed result to a BinData object.

      Before compression, the string is converted to bytes using the specified character set, such as utf-8, iso-8859-1, or shift_JIS.

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

    • compressStringENC

      public String compressStringENC​(String inStr, String charset, String encoding)
      Compresses a string and returns the Gzip-compressed data as an encoded string.

      The input string is first converted to bytes using the specified character set. The compressed binary data is then encoded using the requested encoding, such as base64, hex, url, base32, or quoted-printable.

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

    • compressStringToFile

      public void compressStringToFile​(String inStr, String destCharset, String destPath)
      Compresses a string and writes the resulting Gzip data to a file.

      The string is first converted to bytes using the character set specified by destCharset.

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

    • getGzipInfo

      public void getGzipInfo​(String filePath, JsonObject json)
      Retrieves metadata stored in a Gzip file and returns the information in a JsonObject.

      The metadata is returned using the following JSON structure: 

      {
   "extraData": "AAECAw==",
   "filename": "example.txt",
   "comment": "This is the comment"
 }
      • filename – the original filename embedded in the Gzip file (if present)
      • comment – an optional descriptive comment (if present)
      • extraData – optional additional binary data, returned as a Base64-encoded string

      Any of these fields may be omitted if they were not included when the Gzip file was created.

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

    • getGzipInfoBd

      public void getGzipInfoBd​(BinData bd, JsonObject json)
      Retrieves metadata stored in Gzip data contained within a BinData object and returns the information in a JsonObject.

      The metadata is returned using the same JSON structure: 

      {
   "extraData": "AAECAw==",
   "filename": "example.txt",
   "comment": "This is the comment"
 }
      • filename – the original filename embedded in the Gzip data (if present)
      • comment – an optional descriptive comment (if present)
      • extraData – optional additional binary data, returned as a Base64-encoded string

      Any of these fields may be omitted if they were not included when the Gzip data was created.

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

    • isGzip

      public boolean isGzip​(BinData bd)
      Checks whether the data contained in a BinData object is in Gzip format.

      Returns true if the data is Gzip-formatted, or false otherwise.

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

    • setDt

      public void setDt​(DateTime dt)
      Sets the last-modified date/time to embed in the Gzip file when a Compress* method is called.

      If no date/time is explicitly set, the current system date/time is used.

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

    • setExtraData

      public void setExtraData​(String encodedData, String encoding)
      Sets optional extra binary data to include in the Gzip header when a Compress* method is called.

      The data is passed as an encoded string. Supported encodings include base64, hex, ascii, and many others.

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

    • unTarGz

      public void unTarGz​(String gzPath, String destDir, boolean bNoAbsolute)
      Extracts a .tar.gz archive to a directory.

      The Gzip decompression and TAR extraction are performed in streaming mode. No temporary files are created, and memory usage remains small and constant.

      If bNoAbsolute is true, absolute paths in the TAR archive are not allowed. This helps protect against extracting files to unsafe locations, such as system directories.

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

    • uncompressBd

      public void uncompressBd​(BinData binDat)
      Decompresses Gzip data contained in a BinData object in place, replacing the compressed data with the uncompressed data.
      Parameters:
      binDat - the binDat argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uncompressBdToFile

      public void uncompressBdToFile​(BinData bd, String filePath)
      Decompresses Gzip data stored in a BinData object and writes the result to a file.
      Parameters:
      bd - the bd argument (not null)
      filePath - the filePath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • uncompressFile

      public void uncompressFile​(String srcPath, String destPath)
      Decompresses a Gzip file and writes the result to the specified output path.

      The output filename is provided by the caller. The filename embedded in the Gzip data is not used.

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

    • uncompressFileToString

      public String uncompressFileToString​(String srcPath, String charset)
      Decompresses a Gzip file that contains text and returns the uncompressed text as a string.

      The charset parameter specifies the character encoding of the uncompressed text, such as utf-8, iso-8859-1, windows-1252, shift_JIS, big5, etc.

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

    • uncompressStringENC

      public String uncompressStringENC​(String inStr, String charset, String encoding)
      Decompresses Gzip data provided as an encoded string and returns the uncompressed result as text.

      The input string is first decoded using the specified encoding, such as base64, hex, url, base32, quoted-printable, etc. The decoded Gzip data is then decompressed and converted to text using the specified character set.

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

    • xfdlToXml

      public String xfdlToXml​(String xfldData)
      Converts encoded and compressed XFDL data to a decompressed XML string.

      XFDL data is often stored in an ASCII-safe compressed form, such as asci-gzip or asc-gzip. Despite the name, this does not always mean the data is a standard .gz file. In some XFDL files, the compressed payload uses the raw deflate format rather than the full Gzip file format.

      Chilkat automatically detects the actual encoding and compression format used by the XFDL data. It decodes the ASCII/Base64 representation, determines whether the compressed data is Gzip or deflate, decompresses it correctly, and returns the resulting XML string.

      This allows applications to call XfdlToXml without needing to manually distinguish between XFDL variants such as Base64+Gzip and Base64+Deflate.

      Returns the decoded and decompressed XML string.

      XFDL (Extensible Forms Description Language) is an XML-based format used to define secure, interactive electronic forms—often including digital signatures and integrity protections—commonly used in government and enterprise applications.

      Parameters:
      xfldData - the xfldData 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