Package org.tukaani.xz

## Class SingleXZInputStream

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

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

    public class SingleXZInputStream
    extends InputStream

Decompresses exactly one XZ Stream in streamed mode (no seeking). The decompression stops after the first XZ Stream has been decompressed, and the read position in the input stream is left at the first byte after the end of the XZ Stream. This can be useful when XZ data has been stored inside some other file format or protocol.

Unless you know what you are doing, don't use this class to decompress standalone .xz files. For that purpose, use `XZInputStream`.

#### When uncompressed size is known beforehand

If you are decompressing complete XZ streams and your application knows exactly how much uncompressed data there should be, it is good to try reading one more byte by calling `read()` and checking that it returns `-1`. This way the decompressor will parse the file footers and verify the integrity checks, giving the caller more confidence that the uncompressed data is valid.

See Also:
  `XZInputStream`

### Constructor Summary

Constructors
`SingleXZInputStream​(InputStream in)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` without a memory usage limit.
`SingleXZInputStream​(InputStream in, int memoryLimit)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit.
`SingleXZInputStream​(InputStream in, int memoryLimit, boolean verifyCheck)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit and ability to disable verification of integrity checks.
`SingleXZInputStream​(InputStream in, int memoryLimit, boolean verifyCheck, ArrayCache arrayCache)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit and ability to disable verification of integrity checks.
`SingleXZInputStream​(InputStream in, int memoryLimit, ArrayCache arrayCache)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit.
`SingleXZInputStream​(InputStream in, ArrayCache arrayCache)` Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` without a memory usage limit.

### Method Summary

All Methods Instance Methods Concrete Methods
`int` `available()` Returns the number of uncompressed bytes that can be read without blocking.
`void` `close()` Closes the stream and calls `in.close()`.
`void` `close​(boolean closeInput)` Closes the stream and optionally calls `in.close()`.
`String` `getCheckName()` Gets the name of the integrity check used in this XZ Stream.
`int` `getCheckType()` Gets the ID of the integrity check used in this XZ Stream.
`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, readAllBytes, readNBytes, reset, skip, transferTo`

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

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

### Constructor Detail

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` without a memory usage limit.

This constructor reads and parses the XZ Stream Header (12 bytes) from `in`. The header of the first Block is not read until `read` is called.

Parameters:
  `in` - input stream from which XZ-compressed data is read
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in,
                               ArrayCache arrayCache)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` without a memory usage limit.

This is identical to `SingleXZInputStream(InputStream)` except that this also takes the `arrayCache` argument.

Parameters:
  `in` - input stream from which XZ-compressed data is read
  `arrayCache` - cache to be used for allocating large arrays
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`
Since:
  1.7

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in,
                               int memoryLimit)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit.

This is identical to `SingleXZInputStream(InputStream)` except that this also takes the `memoryLimit` argument.

Parameters:
  `in` - input stream from which XZ-compressed data is read
  `memoryLimit` - memory usage limit in kibibytes (KiB) or `-1` to impose no memory usage limit
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in,
                               int memoryLimit,
                               ArrayCache arrayCache)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit.

This is identical to `SingleXZInputStream(InputStream)` except that this also takes the `memoryLimit` and `arrayCache` arguments.

Parameters:
  `in` - input stream from which XZ-compressed data is read
  `memoryLimit` - memory usage limit in kibibytes (KiB) or `-1` to impose no memory usage limit
  `arrayCache` - cache to be used for allocating large arrays
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`
Since:
  1.7

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in,
                               int memoryLimit,
                               boolean verifyCheck)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit and ability to disable verification of integrity checks.

This is identical to `SingleXZInputStream(InputStream,int)` except that this also takes the `verifyCheck` argument.

Note that integrity check verification should almost never be disabled. Possible reasons to disable integrity check verification:

- Trying to recover data from a corrupt .xz file.
- Speeding up decompression. This matters mostly with SHA-256 or with files that have compressed extremely well. It's recommended that integrity checking isn't disabled for performance reasons unless the file integrity is verified externally in some other way.

`verifyCheck` only affects the integrity check of the actual compressed data. The CRC32 fields in the headers are always verified.

Parameters:
  `in` - input stream from which XZ-compressed data is read
  `memoryLimit` - memory usage limit in kibibytes (KiB) or `-1` to impose no memory usage limit
  `verifyCheck` - if `true`, the integrity checks will be verified; this should almost never be set to `false`
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`
Since:
  1.6

#### SingleXZInputStream

    public SingleXZInputStream​(InputStream in,
                               int memoryLimit,
                               boolean verifyCheck,
                               ArrayCache arrayCache)
                        throws IOException

Creates a new XZ decompressor that decompresses exactly one XZ Stream from `in` with an optional memory usage limit and ability to disable verification of integrity checks.

This is identical to `SingleXZInputStream(InputStream,int,boolean)` except that this also takes the `arrayCache` argument.

Parameters:
  `in` - input stream from which XZ-compressed data is read
  `memoryLimit` - memory usage limit in kibibytes (KiB) or `-1` to impose no memory usage limit
  `verifyCheck` - if `true`, the integrity checks will be verified; this should almost never be set to `false`
  `arrayCache` - cache to be used for allocating large arrays
Throws:
  `XZFormatException` - input is not in the XZ format
  `CorruptedInputException` - XZ header CRC32 doesn't match
  `UnsupportedOptionsException` - XZ header is valid but specifies options not supported by this implementation
  `EOFException` - less than 12 bytes of input was available from `in`
  `IOException` - may be thrown by `in`
Since:
  1.7

### Method Detail

#### getCheckType

    public int getCheckType()

Gets the ID of the integrity check used in this XZ Stream.

Returns:
  the Check ID specified in the XZ Stream Header

#### getCheckName

    public String getCheckName()

Gets the name of the integrity check used in this XZ Stream.

Returns:
  the name of the check specified in the XZ Stream Header

#### read

    public int read()
             throws 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 `BufferedInputStream` if you need to read lots of data one byte at a time.

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

#### read

    public int read​(byte[] buf,
                    int off,
                    int len)
             throws IOException

Decompresses into an array of bytes.

If `len` is zero, no bytes are read and `0` is returned. Otherwise this will try to decompress `len` bytes of uncompressed data. Less than `len` bytes may be read only in the following situations:

- The end of the compressed data was reached successfully.
- An error is detected after at least one but less `len` bytes have already been successfully decompressed. The next call with non-zero `len` will immediately throw the pending exception.
- An exception is thrown.

Overrides:
  `read` in class `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`
  `UnsupportedOptionsException`
  `MemoryLimitException`
  `XZIOException` - if the stream has been closed
  `EOFException` - compressed input is truncated or corrupt
  `IOException` - may be thrown by `in`

#### available

    public int available()
                  throws 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.

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

#### close

    public void close()
               throws IOException

Closes the stream and calls `in.close()`. If the stream was already closed, this does nothing.

This is equivalent to `close(true)`.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Overrides:
  `close` in class `InputStream`
Throws:
  `IOException` - if thrown by `in.close()`

#### close

    public void close​(boolean closeInput)
               throws IOException

Closes the stream and optionally calls `in.close()`. If the stream was already closed, this does nothing. If `close(false)` has been called, a further call of `close(true)` does nothing (it doesn't call `in.close()`).

If you don't want to close the underlying `InputStream`, there is usually no need to worry about closing this stream either; it's fine to do nothing and let the garbage collector handle it. However, if you are using `ArrayCache`, `close(false)` can be useful to put the allocated arrays back to the cache without closing the underlying `InputStream`.

Note that if you successfully reach the end of the stream (`read` returns `-1`), the arrays are automatically put back to the cache by that `read` call. In this situation `close(false)` is redundant (but harmless).

Throws:
  `IOException` - if thrown by `in.close()`
Since:
  1.7