Top Description Fields Constructors Methods
org.tukaani.xz

public Class XZOutputStream

extends FinishableOutputStream
Class Inheritance
Imports
java.io.OutputStream, .IOException, org.tukaani.xz.common.EncoderUtil, .StreamFlags, org.tukaani.xz.check.Check, org.tukaani.xz.index.IndexEncoder
Compresses into the .xz file format.

Examples

Getting an output stream to compress with LZMA2 using the default settings and the default integrity check type (CRC64): 

FileOutputStream outfile = new FileOutputStream("foo.xz");
XZOutputStream outxz = new XZOutputStream(outfile, new LZMA2Options());

Using the preset level 8 for LZMA2 (the default is 6) and SHA-256 instead of CRC64 for integrity checking: 

XZOutputStream outxz = new XZOutputStream(outfile, new LZMA2Options(8),
                                          XZ.CHECK_SHA256);

Using the x86 BCJ filter together with LZMA2 to compress x86 executables and printing the memory usage information before creating the XZOutputStream: 

X86Options x86 = new X86Options();
LZMA2Options lzma2 = new LZMA2Options();
FilterOptions[] options = { x86, lzma2 };
System.out.println("Encoder memory usage: "
                   + FilterOptions.getEncoderMemoryUsage(options)
                   + " KiB");
System.out.println("Decoder memory usage: "
                   + FilterOptions.getDecoderMemoryUsage(options)
                   + " KiB");
XZOutputStream outxz = new XZOutputStream(outfile, options);

Field Summary

Modifier and TypeField and Description
private final ArrayCache
arrayCache

private BlockOutputStream
blockEncoder

private final Check
check

private IOException
exception

private FilterEncoder[]
filters

private boolean
filtersSupportFlushing

True if the current filter chain supports flushing.

private boolean
finished

private final IndexEncoder
index

private OutputStream
out

private final StreamFlags
streamFlags

private final byte[]
tempBuf

Constructor Summary

AccessConstructor and Description
public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions
filter options to use
filterOptions)

Creates a new XZ compressor using one filter and CRC64 as the integrity check.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions
filter options to use
filterOptions, ArrayCache
cache to be used for allocating large arrays
arrayCache)

Creates a new XZ compressor using one filter and CRC64 as the integrity check.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions
filter options to use
filterOptions, int
type of the integrity check, for example XZ.CHECK_CRC32
checkType)

Creates a new XZ compressor using one filter and the specified integrity check type.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions
filter options to use
filterOptions, int
type of the integrity check, for example XZ.CHECK_CRC32
checkType, ArrayCache
cache to be used for allocating large arrays
arrayCache)

Creates a new XZ compressor using one filter and the specified integrity check type.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions[]
array of filter options to use
filterOptions)

Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions[]
array of filter options to use
filterOptions, ArrayCache
cache to be used for allocating large arrays
arrayCache)

Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions[]
array of filter options to use
filterOptions, int
type of the integrity check, for example XZ.CHECK_CRC32
checkType)

Creates a new XZ compressor using 1-4 filters and the specified integrity check type.

public
XZOutputStream(OutputStream
output stream to which the compressed data will be written
out, FilterOptions[]
array of filter options to use
filterOptions, int
type of the integrity check, for example XZ.CHECK_CRC32
checkType, ArrayCache
cache to be used for allocating large arrays
arrayCache)

Creates a new XZ compressor using 1-4 filters and the specified integrity check type.

Method Summary

Modifier and TypeMethod and Description
public void
close()

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Finishes compression and closes the underlying stream.
private void
encodeStreamFlags(byte[] buf, int off)

private void
encodeStreamFooter()

private void
encodeStreamHeader()

public void
endBlock()

Finishes the current XZ Block (but not the whole XZ Stream).

public void
finish()

Overrides org.tukaani.xz.FinishableOutputStream.finish.

Finishes compression without closing the underlying stream.
public void
flush()

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Flushes the encoder and calls out.flush().
public void
updateFilters(FilterOptions
new filter to use
filterOptions)

Updates the filter chain with a single filter.

public void
updateFilters(FilterOptions[]
new filter chain to use
filterOptions)

Updates the filter chain with 1-4 filters.

public void
write(int
the byte.
b)

Implements abstract java.io.OutputStream.write.

Writes one byte to be compressed.
public void
write(byte[]
buffer of bytes to be written
buf, int
start offset in buf
off, int
number of bytes to write
len)

Overrides java.io.OutputStream.write.

Writes an array of bytes to be compressed.

Field Detail

arrayCacheback to summary
private final ArrayCache arrayCache
blockEncoderback to summary
private BlockOutputStream blockEncoder
checkback to summary
private final Check check
exceptionback to summary
private IOException exception
filtersback to summary
private FilterEncoder[] filters
filtersSupportFlushingback to summary
private boolean filtersSupportFlushing

True if the current filter chain supports flushing. If it doesn't support flushing, flush() will use endBlock() as a fallback.

finishedback to summary
private boolean finished
indexback to summary
private final IndexEncoder index
outback to summary
private OutputStream out
streamFlagsback to summary
private final StreamFlags streamFlags
tempBufback to summary
private final byte[] tempBuf

Constructor Detail

XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions filterOptions) throws IOException

Creates a new XZ compressor using one filter and CRC64 as the integrity check. This constructor is equivalent to passing a single-member FilterOptions array to XZOutputStream(OutputStream, FilterOptions[]).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions

filter options to use

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions filterOptions, ArrayCache arrayCache) throws IOException

Creates a new XZ compressor using one filter and CRC64 as the integrity check. This constructor is equivalent to passing a single-member FilterOptions array to XZOutputStream(OutputStream, FilterOptions[], ArrayCache).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions

filter options to use

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
Since
1.7
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions filterOptions, int checkType) throws IOException

Creates a new XZ compressor using one filter and the specified integrity check type. This constructor is equivalent to passing a single-member FilterOptions array to XZOutputStream(OutputStream, FilterOptions[], int).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions

filter options to use

checkType:int

type of the integrity check, for example XZ.CHECK_CRC32

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions filterOptions, int checkType, ArrayCache arrayCache) throws IOException

Creates a new XZ compressor using one filter and the specified integrity check type. This constructor is equivalent to passing a single-member FilterOptions array to XZOutputStream(OutputStream, FilterOptions[], int, ArrayCache).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions

filter options to use

checkType:int

type of the integrity check, for example XZ.CHECK_CRC32

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
Since
1.7
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions[] filterOptions) throws IOException

Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check. This constructor is equivalent XZOutputStream(out, filterOptions, XZ.CHECK_CRC64).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions[]

array of filter options to use

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions[] filterOptions, ArrayCache arrayCache) throws IOException

Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check. This constructor is equivalent XZOutputStream(out, filterOptions, XZ.CHECK_CRC64, arrayCache).

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions[]

array of filter options to use

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
Since
1.7
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions[] filterOptions, int checkType) throws IOException

Creates a new XZ compressor using 1-4 filters and the specified integrity check type.

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions[]

array of filter options to use

checkType:int

type of the integrity check, for example XZ.CHECK_CRC32

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
XZOutputStreamback to summary
public XZOutputStream(OutputStream out, FilterOptions[] filterOptions, int checkType, ArrayCache arrayCache) throws IOException

Creates a new XZ compressor using 1-4 filters and the specified integrity check type.

Parameters
out:OutputStream

output stream to which the compressed data will be written

filterOptions:FilterOptions[]

array of filter options to use

checkType:int

type of the integrity check, for example XZ.CHECK_CRC32

arrayCache:ArrayCache

cache to be used for allocating large arrays

Exceptions
IOException:
may be thrown from out
UnsupportedOptionsException:
invalid filter chain
Since
1.7

Method Detail

closeback to summary
public void close() throws IOException

Overrides java.io.OutputStream.close.

Implements java.io.Closeable.close.

Finishes compression and closes the underlying stream. The underlying stream out is closed even if finishing fails. If both finishing and closing fail, the exception thrown by finish() is thrown and the exception from the failed out.close() is lost.

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
XZ Stream has grown too big
encodeStreamFlagsback to summary
private void encodeStreamFlags(byte[] buf, int off)
encodeStreamFooterback to summary
private void encodeStreamFooter() throws IOException
encodeStreamHeaderback to summary
private void encodeStreamHeader() throws IOException
endBlockback to summary
public void endBlock() throws IOException

Finishes the current XZ Block (but not the whole XZ Stream). This doesn't flush the stream so it's possible that not all data will be decompressible from the output stream when this function returns. Call also flush() if flushing is wanted in addition to finishing the current XZ Block.

If there is no unfinished Block open, this function will do nothing. (No empty XZ Block will be created.)

This function can be useful, for example, to create random-accessible .xz files.

Starting a new XZ Block means that the encoder state is reset. Doing this very often will increase the size of the compressed file a lot (more than plain flush() would do).

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
  • XZ Stream has grown too big
  • stream finished or closed
finishback to summary
public void finish() throws IOException

Overrides org.tukaani.xz.FinishableOutputStream.finish.

Finishes compression without closing the underlying stream. No more data can be written to this stream after finishing (calling write with an empty buffer is OK).

Repeated calls to finish() do nothing unless an exception was thrown by this stream earlier. In that case the same exception is thrown again.

After finishing, the stream may be closed normally with close(). If the stream will be closed anyway, there usually is no need to call finish() separately.

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
XZ Stream has grown too big
flushback to summary
public void flush() throws IOException

Overrides java.io.OutputStream.flush.

Implements java.io.Flushable.flush.

Flushes the encoder and calls out.flush(). All buffered pending data will then be decompressible from the output stream.

Calling this function very often may increase the compressed file size a lot. The filter chain options may affect the size increase too. For example, with LZMA2 the HC4 match finder has smaller penalty with flushing than BT4.

Some filters don't support flushing. If the filter chain has such a filter, flush() will call endBlock() before flushing.

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
  • XZ Stream has grown too big
  • stream finished or closed
updateFiltersback to summary
public void updateFilters(FilterOptions filterOptions) throws XZIOException

Updates the filter chain with a single filter. This is equivalent to passing a single-member FilterOptions array to updateFilters(FilterOptions[]).

Parameters
filterOptions:FilterOptions

new filter to use

Exceptions
UnsupportedOptionsException:
unsupported filter chain, or trying to change the filter chain in the middle of a Block
updateFiltersback to summary
public void updateFilters(FilterOptions[] filterOptions) throws XZIOException

Updates the filter chain with 1-4 filters.

Currently this cannot be used to update e.g. LZMA2 options in the middle of a XZ Block. Use endBlock() to finish the current XZ Block before calling this function. The new filter chain will then be used for the next XZ Block.

Parameters
filterOptions:FilterOptions[]

new filter chain to use

Exceptions
UnsupportedOptionsException:
unsupported filter chain, or trying to change the filter chain in the middle of a Block
writeback to summary
public void write(int b) throws IOException

Implements abstract java.io.OutputStream.write.

Writes one byte to be compressed.

Parameters
b:int

Doc from java.io.OutputStream.write.

the byte.

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
  • XZ Stream has grown too big
  • finish() or close() was already called
writeback to summary
public void write(byte[] buf, int off, int len) throws IOException

Overrides java.io.OutputStream.write.

Writes an array of bytes to be compressed. The compressors tend to do internal buffering and thus the written data won't be readable from the compressed output immediately. Use flush() to force everything written so far to be written to the underlaying output stream, but be aware that flushing reduces compression ratio.

Parameters
buf:byte[]

buffer of bytes to be written

off:int

start offset in buf

len:int

number of bytes to write

Exceptions
IOException:
may be thrown by the underlying output stream
XZIOException:
  • XZ Stream has grown too big: total file size about 8 EiB or the Index field exceeds 16 GiB; you shouldn't reach these sizes in practice
  • finish() or close() was already called and len > 0