BZip2CompressorOutputStream
Date: 2017-02-08

org.apache.commons.compress.compressors.bzip2

## Class BZip2CompressorOutputStream

- java.lang.Object
- - java.io.OutputStream
  - - org.apache.commons.compress.compressors.CompressorOutputStream
    - - org.apache.commons.compress.compressors.bzip2.BZip2CompressorOutputStream

- All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

      public class BZip2CompressorOutputStream
      extends CompressorOutputStream

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BASEBLOCKSIZE`
    `static int` | `G_SIZE`
    `static int` | `MAX_ALPHA_SIZE`
    `static int` | `MAX_BLOCKSIZE` The maximum supported blocksize `== 9`.
    `static int` | `MAX_CODE_LEN`
    `static int` | `MAX_SELECTORS`
    `static int` | `MIN_BLOCKSIZE` The minimum supported blocksize `== 1`.
    `static int` | `N_GROUPS`
    `static int` | `N_ITERS`
    `static int` | `NUM_OVERSHOOT_BYTES`
    `static int` | `RUNA`
    `static int` | `RUNB`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static int` | `chooseBlockSize(long inputLength)` Chooses a blocksize based on the given length of the data to compress.
    `void` | `close()`
    `protected void` | `finalize()` Overriden to warn about an unclosed stream.
    `void` | `finish()`
    `void` | `flush()`
    `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 java.io.OutputStream

      `write`

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

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

- - ### Field Detail

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

          public static final int BASEBLOCKSIZE

      See Also:
        Constant Field Values

    - #### MAX_ALPHA_SIZE

          public static final int MAX_ALPHA_SIZE

      See Also:
        Constant Field Values

    - #### MAX_CODE_LEN

          public static final int MAX_CODE_LEN

      See Also:
        Constant Field Values

    - #### RUNA

          public static final int RUNA

      See Also:
        Constant Field Values

    - #### RUNB

          public static final int RUNB

      See Also:
        Constant Field Values

    - #### N_GROUPS

          public static final int N_GROUPS

      See Also:
        Constant Field Values

    - #### G_SIZE

          public static final int G_SIZE

      See Also:
        Constant Field Values

    - #### N_ITERS

          public static final int N_ITERS

      See Also:
        Constant Field Values

    - #### MAX_SELECTORS

          public static final int MAX_SELECTORS

      See Also:
        Constant Field Values

    - #### NUM_OVERSHOOT_BYTES

          public static final int NUM_OVERSHOOT_BYTES

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### BZip2CompressorOutputStream

          public BZip2CompressorOutputStream(java.io.OutputStream out)
                                      throws java.io.IOException

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

    - #### BZip2CompressorOutputStream

          public BZip2CompressorOutputStream(java.io.OutputStream out,
                                     int blockSize)
                                      throws java.io.IOException

      Constructs a new `BZip2CompressorOutputStream` with specified blocksize.
      Parameters:
        `out` - the destination stream.
        `blockSize` - the blockSize as 100k units.
      Throws:
        `java.io.IOException` - if an I/O error occurs in the specified stream.
        `java.lang.IllegalArgumentException` - if `(blockSize < 1) || (blockSize > 9)`.
        `java.lang.NullPointerException` - if `out == null`.
      See Also:
        `MIN_BLOCKSIZE`, `MAX_BLOCKSIZE`

  - ### Method Detail

    - #### 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.

    - #### write

          public void write(int b)
                     throws java.io.IOException

      Specified by:
        `write` in class `java.io.OutputStream`
      Throws:
        `java.io.IOException`

    - #### finalize

          protected void finalize()
                           throws java.lang.Throwable

      Overriden to warn about an unclosed stream.
      Overrides:
        `finalize` in class `java.lang.Object`
      Throws:
        `java.lang.Throwable`

    - #### finish

          public void finish()
                      throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.OutputStream`
      Throws:
        `java.io.IOException`

    - #### flush

          public void flush()
                     throws java.io.IOException

      Specified by:
        `flush` in interface `java.io.Flushable`
      Overrides:
        `flush` in class `java.io.OutputStream`
      Throws:
        `java.io.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 java.io.IOException

      Overrides:
        `write` in class `java.io.OutputStream`
      Throws:
        `java.io.IOException`