LZMA2InputStream
Date: 2017-02-08

org.tukaani.xz

## Class LZMA2InputStream

- java.lang.Object
- - java.io.InputStream
  - - org.tukaani.xz.LZMA2InputStream

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

      public class LZMA2InputStream
      extends java.io.InputStream

  Decompresses a raw LZMA2 stream (no XZ headers).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DICT_SIZE_MAX` Largest dictionary size supported by this implementation.
    `static int` | `DICT_SIZE_MIN` Smallest valid LZMA2 dictionary size.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `LZMA2InputStream(java.io.InputStream in, int dictSize)` Creates a new input stream that decompresses raw LZMA2 data from `in`.
    `LZMA2InputStream(java.io.InputStream in, int dictSize, byte[] presetDict)` Creates a new LZMA2 decompressor using a preset dictionary.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()` Returns the number of uncompressed bytes that can be read without blocking.
    `void` | `close()` Closes the stream and calls `in.close()`.
    `static int` | `getMemoryUsage(int dictSize)` Gets approximate decompressor memory requirements as kibibytes for the given dictionary size.
    `int` | `read()` Decompresses the next byte from this input stream.
    `int` | `read(byte[] buf, int off, int len)` Decompresses into an array of bytes.

    - ### Methods inherited from class java.io.InputStream

      `mark, markSupported, read, reset, skip`

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

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

- - ### Field Detail

    - #### DICT_SIZE_MIN

          public static final int DICT_SIZE_MIN

      Smallest valid LZMA2 dictionary size.

      Very tiny dictionaries would be a performance problem, so the minimum is 4 KiB.

      See Also:
        Constant Field Values

    - #### DICT_SIZE_MAX

          public static final int DICT_SIZE_MAX

      Largest dictionary size supported by this implementation.

      The LZMA2 algorithm allows dictionaries up to one byte less than 4 GiB. This implementation supports only 16 bytes less than 2 GiB for raw LZMA2 streams, and for .xz files the maximum is 1.5 GiB. This limitation is due to Java using signed 32-bit integers for array indexing. The limitation shouldn't matter much in practice since so huge dictionaries are not normally used.

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### LZMA2InputStream

          public LZMA2InputStream(java.io.InputStream in,
                          int dictSize)

      Creates a new input stream that decompresses raw LZMA2 data from `in`.

      The caller needs to know the dictionary size used when compressing; the dictionary size isn't stored as part of a raw LZMA2 stream.

      Specifying a too small dictionary size will prevent decompressing the stream. Specifying a too big dictionary is waste of memory but decompression will work.

      There is no need to specify a dictionary bigger than the uncompressed size of the data even if a bigger dictionary was used when compressing. If you know the uncompressed size of the data, this might allow saving some memory.

      Parameters:
        `in` - input stream from which LZMA2-compressed data is read
        `dictSize` - LZMA2 dictionary size as bytes, must be in the range [`DICT_SIZE_MIN`, `DICT_SIZE_MAX`]

    - #### LZMA2InputStream

          public LZMA2InputStream(java.io.InputStream in,
                          int dictSize,
                          byte[] presetDict)

      Creates a new LZMA2 decompressor using a preset dictionary.

      This is like `LZMA2InputStream(InputStream, int)` except that the dictionary may be initialized using a preset dictionary. If a preset dictionary was used when compressing the data, the same preset dictionary must be provided when decompressing.

      Parameters:
        `in` - input stream from which LZMA2-compressed data is read
        `dictSize` - LZMA2 dictionary size as bytes, must be in the range [`DICT_SIZE_MIN`, `DICT_SIZE_MAX`]
        `presetDict` - preset dictionary or `null` to use no preset dictionary

  - ### Method Detail

    - #### getMemoryUsage

          public static int getMemoryUsage(int dictSize)

      Gets approximate decompressor memory requirements as kibibytes for the given dictionary size.
      Parameters:
        `dictSize` - LZMA2 dictionary size as bytes, must be in the range [`DICT_SIZE_MIN`, `DICT_SIZE_MAX`]
      Returns:
        approximate memory requirements as kibibytes (KiB)

    - #### read

          public int read()
                   throws java.io.IOException

      Decompresses the next byte from this input stream.

      Reading lots of data with `read()` from this input stream may be inefficient. Wrap it in `java.io.BufferedInputStream` if you need to read lots of data one byte at a time.

      Specified by:
        `read` in class `java.io.InputStream`
      Returns:
        the next decompressed byte, or `-1` to indicate the end of the compressed stream
      Throws:
        `CorruptedInputException`
        `XZIOException` - if the stream has been closed
        `EOFException` - compressed input is truncated or corrupt
        `java.io.IOException` - may be thrown by `in`

    - #### read

          public int read(byte[] buf,
                 int off,
                 int len)
                   throws java.io.IOException

      Decompresses into an array of bytes.

      If `len` is zero, no bytes are read and `0` is returned. Otherwise this will block until `len` bytes have been decompressed, the end of the LZMA2 stream is reached, or an exception is thrown.

      Overrides:
        `read` in class `java.io.InputStream`
      Parameters:
        `buf` - target buffer for uncompressed data
        `off` - start offset in `buf`
        `len` - maximum number of uncompressed bytes to read
      Returns:
        number of bytes read, or `-1` to indicate the end of the compressed stream
      Throws:
        `CorruptedInputException`
        `XZIOException` - if the stream has been closed
        `EOFException` - compressed input is truncated or corrupt
        `java.io.IOException` - may be thrown by `in`

    - #### available

          public int available()
                        throws java.io.IOException

      Returns the number of uncompressed bytes that can be read without blocking. The value is returned with an assumption that the compressed input data will be valid. If the compressed data is corrupt, `CorruptedInputException` may get thrown before the number of bytes claimed to be available have been read from this input stream.

      In LZMA2InputStream, the return value will be non-zero when the decompressor is in the middle of an LZMA2 chunk. The return value will then be the number of uncompressed bytes remaining from that chunk.

      Overrides:
        `available` in class `java.io.InputStream`
      Returns:
        the number of uncompressed bytes that can be read without blocking
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the stream and calls `in.close()`. If the stream was already closed, this does nothing.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.InputStream`
      Throws:
        `java.io.IOException` - if thrown by `in.close()`