Top Description Fields Constructors Methods
org.tukaani.xz

public Class SingleXZInputStream

extends InputStream
Class Inheritance
Imports
java.io.InputStream, .DataInputStream, .IOException, .EOFException, org.tukaani.xz.common.DecoderUtil, .StreamFlags, org.tukaani.xz.index.IndexHash, org.tukaani.xz.check.Check
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

Field Summary

Modifier and TypeField and Description
private final ArrayCache
arrayCache

private BlockInputStream
blockDecoder

private final Check
check

private boolean
endReached

private IOException
exception

private InputStream
in

private final IndexHash
indexHash

private final int
memoryLimit

private final StreamFlags
streamHeaderFlags

private final byte[]
tempBuf

private final boolean
verifyCheck

Constructor Summary

AccessConstructor and Description
public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in)

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

public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in, ArrayCache
cache to be used for allocating large arrays
arrayCache)

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

public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in, int
memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit
memoryLimit)

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

public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in, int
memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit
memoryLimit, ArrayCache
cache to be used for allocating large arrays
arrayCache)

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

public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in, int
memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit
memoryLimit, boolean
if true, the integrity checks will be verified; this should almost never be set to false
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.

public
SingleXZInputStream(InputStream
input stream from which XZ-compressed data is read
in, int
memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit
memoryLimit, boolean
if true, the integrity checks will be verified; this should almost never be set to false
verifyCheck, ArrayCache
cache to be used for allocating large arrays
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.

pack-priv
SingleXZInputStream(InputStream in, int memoryLimit, boolean verifyCheck, byte[] streamHeader, ArrayCache arrayCache)

Method Summary

Modifier and TypeMethod and Description
public int

Returns:

the number of uncompressed bytes that can be read without blocking
available()

Overrides java.io.InputStream.available.

Returns the number of uncompressed bytes that can be read without blocking.
public void
close()

Overrides java.io.InputStream.close.

Implements java.io.Closeable.close.

Closes the stream and calls in.close().
public void
close(boolean closeInput)

Closes the stream and optionally calls in.close().

public String

Returns:

the name of the check specified in the XZ Stream Header
getCheckName()

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

public int

Returns:

the Check ID specified in the XZ Stream Header
getCheckType()

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

public int

Returns:

the next decompressed byte, or -1 to indicate the end of the compressed stream
read()

Implements abstract java.io.InputStream.read.

Decompresses the next byte from this input stream.
public int

Returns:

number of bytes read, or -1 to indicate the end of the compressed stream
read(byte[]
target buffer for uncompressed data
buf, int
start offset in buf
off, int
maximum number of uncompressed bytes to read
len)

Overrides java.io.InputStream.read.

Decompresses into an array of bytes.
private static byte[]
readStreamHeader(InputStream in)

Reads the Stream Header into a buffer.

private void
validateStreamFooter()

Inherited from java.io.InputStream:
markmarkSupportednullInputStreamreadreadAllBytesreadNBytesreadNBytesresetskipskipNBytestransferTo

Field Detail

arrayCacheback to summary
private final ArrayCache arrayCache
blockDecoderback to summary
private BlockInputStream blockDecoder
checkback to summary
private final Check check
endReachedback to summary
private boolean endReached
exceptionback to summary
private IOException exception
inback to summary
private InputStream in
indexHashback to summary
private final IndexHash indexHash
memoryLimitback to summary
private final int memoryLimit
streamHeaderFlagsback to summary
private final StreamFlags streamHeaderFlags
tempBufback to summary
private final byte[] tempBuf
verifyCheckback to summary
private final boolean verifyCheck

Constructor Detail

SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

Exceptions
IOException:
may be thrown by in
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
SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown by in
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
Since
1.7
SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

memoryLimit:int

memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit

Exceptions
IOException:
may be thrown by in
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
SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

memoryLimit:int

memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown by in
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
Since
1.7
SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

memoryLimit:int

memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit

verifyCheck:boolean

if true, the integrity checks will be verified; this should almost never be set to false

Exceptions
IOException:
may be thrown by in
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
Since
1.6
SingleXZInputStreamback to summary
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:InputStream

input stream from which XZ-compressed data is read

memoryLimit:int

memory usage limit in kibibytes (KiB) or -1 to impose no memory usage limit

verifyCheck:boolean

if true, the integrity checks will be verified; this should almost never be set to false

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown by in
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
Since
1.7
SingleXZInputStreamback to summary
pack-priv SingleXZInputStream(InputStream in, int memoryLimit, boolean verifyCheck, byte[] streamHeader, ArrayCache arrayCache) throws IOException

Method Detail

availableback to summary
public int available() throws IOException

Overrides java.io.InputStream.available.

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.

Returns:int

the number of uncompressed bytes that can be read without blocking

Exceptions
IOException:

Doc from java.io.InputStream.available.

if an I/O error occurs.

closeback to summary
public void close() throws IOException

Overrides java.io.InputStream.close.

Implements java.io.Closeable.close.

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

This is equivalent to close(true).

Exceptions
IOException:
if thrown by in.close()
closeback to summary
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).

Exceptions
IOException:
if thrown by in.close()
Since
1.7
getCheckNameback to summary
public String getCheckName()

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

Returns:String

the name of the check specified in the XZ Stream Header

getCheckTypeback to summary
public int getCheckType()

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

Returns:int

the Check ID specified in the XZ Stream Header

readback to summary
public int read() throws IOException

Implements abstract java.io.InputStream.read.

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.

Returns:int

the next decompressed byte, or -1 to indicate the end of the compressed stream

Exceptions
IOException:
may be thrown by in
XZIOException:
if the stream has been closed
EOFException:
compressed input is truncated or corrupt
readback to summary
public int read(byte[] buf, int off, int len) throws IOException

Overrides java.io.InputStream.read.

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.
Parameters
buf:byte[]

target buffer for uncompressed data

off:int

start offset in buf

len:int

maximum number of uncompressed bytes to read

Returns:int

number of bytes read, or -1 to indicate the end of the compressed stream

Exceptions
IOException:
may be thrown by in
XZIOException:
if the stream has been closed
EOFException:
compressed input is truncated or corrupt
readStreamHeaderback to summary
private static byte[] readStreamHeader(InputStream in) throws IOException

Reads the Stream Header into a buffer. This is a helper function for the constructors.

validateStreamFooterback to summary
private void validateStreamFooter() throws IOException