org.tukaani.xz
Class XZInputStream

java.lang.Object
  extended by java.io.InputStream
      extended by org.tukaani.xz.XZInputStream
All Implemented Interfaces:
Closeable

public class XZInputStream
extends InputStream

Decompresses a .xz file in streamed mode (no seeking).

Use this to decompress regular standalone .xz files. This reads from its input stream until the end of the input or until an error occurs. This supports decompressing concatenated .xz files.

Typical use cases

Getting an input stream to decompress a .xz file:

 InputStream infile = new FileInputStream("foo.xz");
 XZInputStream inxz = new XZInputStream(infile);
 

It's important to keep in mind that decompressor memory usage depends on the settings used to compress the file. The worst-case memory usage of XZInputStream is currently 1.5 GiB. Still, very few files will require more than about 65 MiB because that's how much decompressing a file created with the highest preset level will need, and only a few people use settings other than the predefined presets.

It is possible to specify a memory usage limit for XZInputStream. If decompression requires more memory than the specified limit, MemoryLimitException will be thrown when reading from the stream. For example, the following sets the memory usage limit to 100 MiB:

 InputStream infile = new FileInputStream("foo.xz");
 XZInputStream inxz = new XZInputStream(infile, 100 * 1024);
 

When uncompressed size is known beforehand

If you are decompressing complete files 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. (This advice seems to apply to java.util.zip.GZIPInputStream too.)

See Also:
SingleXZInputStream

Constructor Summary
XZInputStream(InputStream in)
          Creates a new XZ decompressor without a memory usage limit.
XZInputStream(InputStream in, int memoryLimit)
          Creates a new XZ decompressor with an optional memory usage limit.
 
Method Summary
 int available()
          Returns the number of uncompressed bytes that can be read without blocking.
 void close()
          Closes the stream and calls in.close().
 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
 

Constructor Detail

XZInputStream

public XZInputStream(InputStream in)
              throws IOException
Creates a new XZ decompressor 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

XZInputStream

public XZInputStream(InputStream in,
                     int memoryLimit)
              throws IOException
Creates a new XZ decompressor with an optional memory usage limit.

This is identical to XZInputStream(InputStream) except that this takes also 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
Method Detail

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:

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.

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