Package com.chilkatsoft.chilkat2

Class Compression

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

Compress and decompress bytes, text, files, and streams with a flexible API.

Chilkat.Compression provides a general-purpose API for compressing and decompressing data in memory, files, and streams. It supports multiple algorithms, text charset conversion, encoded output, chunked processing, and streaming operations for large data.

Multiple algorithms

Supports deflate, zlib, bzip2, and lzw.

Flexible data types

Work with byte arrays, strings, BinData, StringBuilder, files, and streams.

Chunked processing

Process data incrementally with FirstChunk and LastChunk for chunk-aware methods.

Encoded output

Return compressed bytes as text using encodings such as base64, hex, and others.

Streaming support

Compress or decompress large files and streams with stable memory usage.

Compression + encryption

Combine compression and encryption in file workflows with integrated methods.

Tip: For text compression, explicitly set Charset = "utf-8" unless another encoding is required. For encoded compressed data, set EncodingMode to the desired output format.

For an extended overview, see Compression Class Overview. See also Binary Encodings for supported encoded output formats.

</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

    • Compression

      public Compression()
      Creates a new Compression object.

  • Method Details

    • getAlgorithm

      public String getAlgorithm()
      Specifies the compression algorithm to use. Supported values are deflate, zlib, gzip, bzip2, and lzw.

      The zlib option is the deflate algorithm with a zlib header.

      The gzip option (starting in v11.7.0) is the deflate algorithm in the gzip format (RFC 1952): a gzip header, the deflate data, and a trailer with the CRC-32 and size of the uncompressed data. When decompressing in one call, the CRC-32 and size are checked. Before v11.7.0, gzip was not recognized and was treated as deflate.

      Note: ppmd is deprecated and should not be used. It was only available on 32-bit systems and specifically used the J variant. New applications should use one of the supported algorithms listed above.

      Returns:
      the value of the Algorithm property

    • setAlgorithm

      public void setAlgorithm​(String value)
      Sets the Algorithm property; see getAlgorithm().
      Parameters:
      value - the new value (not null)

    • getCharset

      public String getCharset()
      Specifies the character encoding used when converting text to bytes before compression, and bytes back to text after decompression.

      The current default is the computer’s ANSI charset, such as Windows-1252 on many Western Windows systems. However, most modern applications should explicitly set this property to utf-8.

      Recommendation: Set Charset = "utf-8" unless you specifically need compatibility with another encoding.

      Returns:
      the value of the Charset property

    • setCharset

      public void setCharset​(String value)
      Sets the Charset property; see getCharset().
      Parameters:
      value - the new value (not null)

    • getDeflateLevel

      public int getDeflateLevel()
      Sets the compression level used by the deflate and zlib algorithms.
      • 0 means no compression.
      • 9 means maximum compression.
      • The default value is 6.

      Higher values may produce smaller output but can require more processing time.

      Returns:
      the value of the DeflateLevel property

    • setDeflateLevel

      public void setDeflateLevel​(int value)
      Sets the DeflateLevel property; see getDeflateLevel().
      Parameters:
      value - the new value

    • getEncodingMode

      public String getEncodingMode()
      Specifies the text encoding used by methods whose names end in ENC, such as CompressBytesENC and DecompressStringENC.

      Compression methods ending in ENC return compressed binary data as an encoded string. Decompression methods ending in ENC expect the input string to use this same encoding.

      Valid values include:

      • base64
      • hex
      • url
      • quoted-printable

      Returns:
      the value of the EncodingMode property

    • setEncodingMode

      public void setEncodingMode​(String value)
      Sets the EncodingMode property; see getEncodingMode().
      Parameters:
      value - the new value (not null)

    • getFirstChunk

      public boolean getFirstChunk()
      Indicates that the next chunk-aware compression or decompression call is the first chunk in a sequence.

      The default value is true.

      When both FirstChunk and LastChunk are true, the method call is treated as a complete, single-call compression or decompression operation.

      Returns:
      the value of the FirstChunk property

    • setFirstChunk

      public void setFirstChunk​(boolean value)
      Sets the FirstChunk property; see getFirstChunk().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks.

      This allows an application to periodically check whether a long-running operation should be aborted.

      The default value is 0, which disables AbortCheck callbacks.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • getLastChunk

      public boolean getLastChunk()
      Indicates that the next chunk-aware compression or decompression call is the final chunk in a sequence.

      The default value is true.

      When both FirstChunk and LastChunk are true, the input is treated as the complete data set and processed in a single call.

      Returns:
      the value of the LastChunk property

    • setLastChunk

      public void setLastChunk​(boolean value)
      Sets the LastChunk property; see getLastChunk().
      Parameters:
      value - the new value

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a way to enable specialized or uncommon behavior. This property normally remains empty.

      It may be set to a comma-separated list of keywords.

      Supported option:

      • Crypt2CompressHdr — Duplicates the compression/decompression header behavior used by the deprecated and removed Crypt2 compression functions.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • compressBd

      public void compressBd​(BinData bd)
      Compresses the data contained in a BinData object.

      The BinData object is modified to contain the compressed result.

      This method is not FirstChunk / LastChunk aware.

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

    • compressBd2

      public void compressBd2​(BinData bdIn, BinData bdOut)
      Compresses the data in one BinData object and appends the compressed output to another BinData object.

      The input BinData is not modified.

      This method is FirstChunk / LastChunk aware.

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

    • compressEncryptFile

      public void compressEncryptFile​(JsonObject cryptParams, String srcPath, String destPath)
      Compresses and encrypts a file, writing the result to a destination file.

      The compression and encryption are performed internally in streaming mode, so files of any size can be processed without loading the entire file into memory.

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

    • compressFile

      public void compressFile​(String srcPath, String destPath)
      Compresses a source file and writes the compressed data to a destination file.

      The file is processed internally in streaming mode, allowing files of any size to be compressed with stable memory usage.

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

    • compressSb

      public void compressSb​(StringBuilder sb, BinData binData)
      Compresses the text contained in a StringBuilder and appends the compressed bytes to a BinData object.

      Text is converted to bytes according to the Charset property.

      This method is FirstChunk / LastChunk aware.

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

    • compressStream

      public void compressStream​(Stream strm)
      Compresses data from a stream source and writes the compressed data to the stream sink.

      The operation is performed in streaming mode, making it suitable for very large or even continuous streams while maintaining stable memory usage.

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

    • compressStringENC

      public String compressStringENC​(String str)
      Compresses a string and returns the compressed result as an encoded string.

      The string is first converted to bytes using Charset, then compressed, and finally encoded according to EncodingMode.

      This method is not FirstChunk / LastChunk aware.

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

    • decompressBd

      public void decompressBd​(BinData bd)
      Decompresses the compressed data contained in a BinData object.

      The BinData object is modified to contain the decompressed result.

      This method is not FirstChunk / LastChunk aware.

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

    • decompressBd2

      public void decompressBd2​(BinData bdIn, BinData bdOut)
      Decompresses the data in one BinData object and appends the decompressed output to another BinData object.

      The input BinData is not modified.

      This method is FirstChunk / LastChunk aware.

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

    • decompressFile

      public void decompressFile​(String srcPath, String destPath)
      Decompresses a source file and writes the decompressed data to a destination file.

      The file is processed internally in streaming mode, allowing files of any size to be decompressed without loading the entire file into memory.

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

    • decompressSb

      public void decompressSb​(BinData binData, StringBuilder sb)
      Decompresses compressed data from a BinData object and appends the resulting text to a StringBuilder.

      The decompressed bytes are converted to text using the Charset property.

      This method is FirstChunk / LastChunk aware.

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

    • decompressStream

      public void decompressStream​(Stream strm)
      Decompresses data from a stream source and writes the decompressed data to the stream sink.

      The operation is performed in streaming mode, making it suitable for very large or continuous streams while maintaining stable memory usage.

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

    • decompressStringENC

      public String decompressStringENC​(String encodedCompressedData)
      Decompresses compressed data supplied as an encoded string and returns the resulting text.

      The input string is decoded according to EncodingMode, then decompressed. The resulting bytes are converted to text using Charset.

      This method is not FirstChunk / LastChunk aware.

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

    • decryptDecompressFile

      public void decryptDecompressFile​(JsonObject cryptParams, String srcPath, String destPath)
      Decrypts and decompresses a file, writing the restored data to a destination file.

      This is the reverse operation of CompressEncryptFile.

      Parameters:
      cryptParams - the cryptParams argument (not null)
      srcPath - the srcPath argument (not null)
      destPath - the destPath argument (not 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