Package com.chilkatsoft.chilkat2

Class Bz2

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Bz2
All Implemented Interfaces:
AutoCloseable
public class Bz2 extends ChilkatObject
Chilkat.Bz2 provides BZip2 compression and decompression for files, memory buffers, and BinData. It can create standard .bz2 file images, decompress .bz2 content back to its original bytes, and support abortable long-running operations.

For an extended overview, see Bz2 Class Overview

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

    • Bz2

      public Bz2()
      Creates a new Bz2 object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set this property to true to request cancellation of the compression or decompression operation currently executing on this object. Long-running operations check the request periodically; an operation that finishes quickly may complete before the request is observed.

      A synchronous call can be cancelled by setting this property from another thread. After cancellation is processed, Chilkat resets the property to false. If no operation is running, a previously set value is cleared when the next method begins.

      Cancellation is cooperative: Setting this property requests an abort; it does not guarantee immediate termination. Check the method's return value and LastErrorText to determine the final outcome.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

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

    • getHeartbeatMs

      public int getHeartbeatMs()
      Specifies the interval, in milliseconds, between AbortCheck event callbacks during supported long-running compression and decompression operations. The default is 0, which disables AbortCheck callbacks.

      Set a positive value, such as 200, when the application needs periodic opportunities to request cancellation. The interval is approximate; callbacks occur only while an operation is at a point where progress events can be delivered.

      Cancellation workflow: In an AbortCheck handler, set the callback's abort value to request termination. A synchronous method may also be cancelled from another thread by setting getAbortCurrent() to true.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • compressBd

      public void compressBd​(BinData bd)
      Compresses the current contents of bd in place. On success, the BinData no longer contains the original bytes; it contains the complete standard BZip2 stream that may be saved with a .bz2 extension.

      In-place transformation: Preserve a copy of the original data if it is still needed after this call. A BZip2 stream contains a stream header, one or more compressed blocks with integrity checks, and an end-of-stream marker. It does not contain archive filenames or directory entries.

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

    • compressFile

      public void compressFile​(String inFilename, String toPath)
      Reads the file at inFilename and writes its compressed bytes as a standard BZip2 stream to the file at toPath. The output is conventionally given a .bz2 extension.

      Both arguments must identify files, not directories. They may be absolute or relative paths, for example data/report.txt and data/report.txt.bz2.

      BZip2 is a compressor, not an archive format: A .bz2 file represents one compressed byte stream. It does not store the original filename, directory path, timestamps, permissions, or multiple archive entries. Formats such as .tar.bz2 first combine files in a TAR archive and then compress that TAR stream with BZip2.

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

    • uncompressBd

      public void uncompressBd​(BinData bd)
      Decompresses the BZip2 stream currently contained in bd in place. On success, the BinData is replaced with the original uncompressed bytes.

      Input requirement: bd must contain a complete, valid BZip2 stream, such as the bytes of a .bz2 file or the output of compressBd(BinData). This method operates on binary data and does not perform character-set conversion.

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

    • uncompressFile

      public void uncompressFile​(String inFilename, String toPath)
      Reads the BZip2 stream from the file at inFilename, decompresses it, and writes the original uncompressed bytes to the file at toPath.

      Both arguments must identify files, not directories. Chilkat does not derive the destination name from the .bz2 filename because the BZip2 stream does not contain the original filename.

      Terminology: This method decompresses BZip2 data; it does not “unzip” a ZIP archive. A .bz2 file normally contains a single compressed byte stream rather than a collection of named files.

      Parameters:
      inFilename - the inFilename argument (not null)
      toPath - the toPath 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