Package org.apache.commons.compress.compressors.bzip2

# Class BZip2CompressorOutputStream

java.lang.Object
java.io.OutputStream
java.io.FilterOutputStream
org.apache.commons.compress.CompressFilterOutputStream<OutputStream>
org.apache.commons.compress.compressors.CompressorOutputStream<OutputStream>
org.apache.commons.compress.compressors.bzip2.BZip2CompressorOutputStream

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`

public class BZip2CompressorOutputStream extends CompressorOutputStream<OutputStream>
An output stream that compresses into the BZip2 format into another stream.

The compression requires large amounts of memory. Thus you should call the `close()` method as soon as possible, to force `BZip2CompressorOutputStream` to release the allocated memory.

You can shrink the amount of allocated memory and maybe raise the compression speed by choosing a lower blocksize, which in turn may cause a lower compression ratio. You can avoid unnecessary memory allocation by avoiding using a blocksize which is bigger than the size of the input.

You can compute the memory usage for compressing by the following formula:

     <code>400k + (9 * blocksize)</code>.

To get the memory required for decompression by `BZip2CompressorInputStream` use

     <code>65k + (5 * blocksize)</code>.

Memory usage by blocksize
Memory usage by blocksize
Blocksize | Compression memory usage | Decompression memory usage
--- | --- | ---
100k | 1300k | 565k
200k | 2200k | 1065k
300k | 3100k | 1565k
400k | 4000k | 2065k
500k | 4900k | 2565k
600k | 5800k | 3065k
700k | 6700k | 3565k
800k | 7600k | 4065k
900k | 8500k | 4565k

For decompression `BZip2CompressorInputStream` allocates less memory if the bzipped input is smaller than one block.

Instances of this class are not threadsafe.

TODO: Update to BZip2 1.0.1

This class is not thread-safe

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `BASEBLOCKSIZE`
  Constant 100000.
  `static final int`
  `G_SIZE`
  Constant 50.
  `static final int`
  `MAX_ALPHA_SIZE`
  Constant 258.
  `static final int`
  `MAX_BLOCKSIZE`
  The maximum supported blocksize `== 9`.
  `static final int`
  `MAX_CODE_LEN`
  Constant 23.
  `static final int`
  `MAX_SELECTORS`
  Constant 18002.
  `static final int`
  `MIN_BLOCKSIZE`
  The minimum supported blocksize `== 1`.
  `static final int`
  `N_GROUPS`
  Constant 6.
  `static final int`
  `N_ITERS`
  Constant 4.
  `static final int`
  `NUM_OVERSHOOT_BYTES`
  Constant 20.
  `static final int`
  `RUNA`
  Constant 0.
  `static final int`
  `RUNB`
  Constant 1.

  ### Fields inherited from class java.io.FilterOutputStream

  `out`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `BZip2CompressorOutputStream(OutputStream out)`
  Constructs a new `BZip2CompressorOutputStream` with a blocksize of 900k.
  `BZip2CompressorOutputStream(OutputStream out, int blockSize)`
  Constructs a new `BZip2CompressorOutputStream` with specified blocksize.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `chooseBlockSize(long inputLength)`
  Chooses a blocksize based on the given length of the data to compress.
  `void`
  `close()`
  `void`
  `finish()`
  Finishes the addition of entries to this stream, without closing it.
  `void`
  `flush()`
  `final int`
  `getBlockSize()`
  Returns the blocksize parameter specified at construction time.
  `void`
  `write(byte[] buf, int offs, int len)`
  `void`
  `write(int b)`

  ### Methods inherited from class org.apache.commons.compress.CompressFilterOutputStream

  `checkOpen, isClosed, isFinished, out, write, write, writeUsAscii, writeUsAsciiRaw, writeUtf8`

  ### Methods inherited from class java.io.FilterOutputStream

  `write`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MIN_BLOCKSIZE

    public static final int MIN_BLOCKSIZE
    The minimum supported blocksize `== 1`.
    See Also:
      - Constant Field Values

  - ### MAX_BLOCKSIZE

    public static final int MAX_BLOCKSIZE
    The maximum supported blocksize `== 9`.
    See Also:
      - Constant Field Values

  - ### BASEBLOCKSIZE

    static final int BASEBLOCKSIZE
    Constant 100000.
    See Also:
      - Constant Field Values

  - ### MAX_ALPHA_SIZE

    static final int MAX_ALPHA_SIZE
    Constant 258.
    See Also:
      - Constant Field Values

  - ### MAX_CODE_LEN

    static final int MAX_CODE_LEN
    Constant 23.
    See Also:
      - Constant Field Values

  - ### RUNA

    static final int RUNA
    Constant 0.
    See Also:
      - Constant Field Values

  - ### RUNB

    static final int RUNB
    Constant 1.
    See Also:
      - Constant Field Values

  - ### N_GROUPS

    static final int N_GROUPS
    Constant 6.
    See Also:
      - Constant Field Values

  - ### G_SIZE

    static final int G_SIZE
    Constant 50.
    See Also:
      - Constant Field Values

  - ### N_ITERS

    static final int N_ITERS
    Constant 4.
    See Also:
      - Constant Field Values

  - ### MAX_SELECTORS

    static final int MAX_SELECTORS
    Constant 18002.
    See Also:
      - Constant Field Values

  - ### NUM_OVERSHOOT_BYTES

    static final int NUM_OVERSHOOT_BYTES
    Constant 20.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### BZip2CompressorOutputStream

    public BZip2CompressorOutputStream(OutputStream out) throws IOException
    Constructs a new `BZip2CompressorOutputStream` with a blocksize of 900k.
    Parameters:
      `out` - the destination stream.
    Throws:
      `IOException` - if an I/O error occurs in the specified stream.
      `NullPointerException` - if `out == null`.

  - ### BZip2CompressorOutputStream

    public BZip2CompressorOutputStream(OutputStream out, int blockSize) throws IOException
    Constructs a new `BZip2CompressorOutputStream` with specified blocksize.
    Parameters:
      `out` - the destination stream.
      `blockSize` - the blockSize as 100k units.
    Throws:
      `IOException` - if an I/O error occurs in the specified stream.
      `IllegalArgumentException` - if `(blockSize &lt; 1) || (blockSize &gt; 9)`.
      `NullPointerException` - if `out == null`.
    See Also:
      - `MIN_BLOCKSIZE`
      - `MAX_BLOCKSIZE`

- ## Method Details

  - ### chooseBlockSize

    public static int chooseBlockSize(long inputLength)
    Chooses a blocksize based on the given length of the data to compress.
    Parameters:
      `inputLength` - The length of the data which will be compressed by `BZip2CompressorOutputStream`.
    Returns:
      The blocksize, between `MIN_BLOCKSIZE` and `MAX_BLOCKSIZE` both inclusive. For a negative `inputLength` this method returns `MAX_BLOCKSIZE` always.

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `CompressFilterOutputStream<OutputStream>`
    Throws:
      `IOException`

  - ### finish

    public void finish() throws IOException
    Description copied from class: `CompressFilterOutputStream`
    Finishes the addition of entries to this stream, without closing it. Additional data can be written, if the format supports it.
    Overrides:
      `finish` in class `CompressFilterOutputStream<OutputStream>`
    Throws:
      `IOException` - Maybe thrown by subclasses if the user forgets to close the entry.

  - ### flush

    public void flush() throws IOException
    Specified by:
      `flush` in interface `Flushable`
    Overrides:
      `flush` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### getBlockSize

    public final int getBlockSize()
    Returns the blocksize parameter specified at construction time.
    Returns:
      the blocksize parameter specified at construction time

  - ### write

    public void write(byte[] buf, int offs, int len) throws IOException
    Overrides:
      `write` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### write

    public void write(int b) throws IOException
    Overrides:
      `write` in class `FilterOutputStream`
    Throws:
      `IOException`