Package org.tukaani.xz

Class SingleXZInputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public class SingleXZInputStream
extends java.io.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 
      Constructor Description
      SingleXZInputStream​(java.io.InputStream in)
      Creates a new XZ decompressor that decompresses exactly one XZ Stream from in without a memory usage limit.
      SingleXZInputStream​(java.io.InputStream in, int memoryLimit)
      Creates a new XZ decompressor that decompresses exactly one XZ Stream from in with an optional memory usage limit.
      SingleXZInputStream​(java.io.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​(java.io.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​(java.io.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​(java.io.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 
      Modifier and Type Method Description
      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().
      java.lang.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, nullInputStream, read, readAllBytes, readNBytes, 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​(java.io.InputStream in)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.IOException - may be thrown by in

      • SingleXZInputStream

        public SingleXZInputStream​(java.io.InputStream in,
                           ArrayCache arrayCache)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.IOException - may be thrown by in
        Since:
        1.7

      • SingleXZInputStream

        public SingleXZInputStream​(java.io.InputStream in,
                           int memoryLimit)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.IOException - may be thrown by in

      • SingleXZInputStream

        public SingleXZInputStream​(java.io.InputStream in,
                           int memoryLimit,
                           ArrayCache arrayCache)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.IOException - may be thrown by in
        Since:
        1.7

      • SingleXZInputStream

        public SingleXZInputStream​(java.io.InputStream in,
                           int memoryLimit,
                           boolean verifyCheck)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.IOException - may be thrown by in
        Since:
        1.6

      • SingleXZInputStream

        public SingleXZInputStream​(java.io.InputStream in,
                           int memoryLimit,
                           boolean verifyCheck,
                           ArrayCache arrayCache)
                    throws java.io.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
        java.io.EOFException - less than 12 bytes of input was available from in
        java.io.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 java.lang.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 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 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
        UnsupportedOptionsException
        MemoryLimitException
        XZIOException - if the stream has been closed
        java.io.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 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 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
        UnsupportedOptionsException
        MemoryLimitException
        XZIOException - if the stream has been closed
        java.io.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.
        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.

        This is equivalent to close(true).

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

      • close

        public void close​(boolean closeInput)
           throws java.io.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:
        java.io.IOException - if thrown by in.close()
        Since:
        1.7