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:
    Closeable, Flushable

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

    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 close the 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(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 < 1) || (blockSize > 9)`.
        `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 IOException

      Specified by:
        `write` in class `OutputStream`
      Throws:
        `IOException`

    - #### finalize

          protected void finalize()
                           throws Throwable

      Overriden to close the stream.
      Overrides:
        `finalize` in class `Object`
      Throws:
        `Throwable`

    - #### finish

          public void finish()
                      throws IOException

      Throws:
        `IOException`

    - #### close

          public void close()
                     throws IOException

      Specified by:
        `close` in interface `Closeable`
      Overrides:
        `close` in class `OutputStream`
      Throws:
        `IOException`

    - #### flush

          public void flush()
                     throws IOException

      Specified by:
        `flush` in interface `Flushable`
      Overrides:
        `flush` in class `OutputStream`
      Throws:
        `IOException`

    - #### getBlockSize

          public final int getBlockSize()

      Returns the blocksize parameter specified at construction time.

    - #### write

          public void write(byte[] buf,
                   int offs,
                   int len)
                     throws IOException

      Overrides:
        `write` in class `OutputStream`
      Throws:
        `IOException`

Copyright © 2014 The Apache Software Foundation. All rights reserved.