Class XZOutputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    public class XZOutputStream
    extends FinishableOutputStream
    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);
     
    • Constructor Summary

      Constructors 
      Constructor Description
      XZOutputStream​(java.io.OutputStream out, FilterOptions filterOptions)
      Creates a new XZ compressor using one filter and CRC64 as the integrity check.
      XZOutputStream​(java.io.OutputStream out, FilterOptions[] filterOptions)
      Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check.
      XZOutputStream​(java.io.OutputStream out, FilterOptions[] filterOptions, int checkType)
      Creates a new XZ compressor using 1-4 filters and the specified integrity check type.
      XZOutputStream​(java.io.OutputStream out, FilterOptions[] filterOptions, int checkType, ArrayCache arrayCache)
      Creates a new XZ compressor using 1-4 filters and the specified integrity check type.
      XZOutputStream​(java.io.OutputStream out, FilterOptions[] filterOptions, ArrayCache arrayCache)
      Creates a new XZ compressor using 1-4 filters and CRC64 as the integrity check.
      XZOutputStream​(java.io.OutputStream out, FilterOptions filterOptions, int checkType)
      Creates a new XZ compressor using one filter and the specified integrity check type.
      XZOutputStream​(java.io.OutputStream out, FilterOptions filterOptions, int checkType, ArrayCache arrayCache)
      Creates a new XZ compressor using one filter and the specified integrity check type.
      XZOutputStream​(java.io.OutputStream out, FilterOptions filterOptions, ArrayCache arrayCache)
      Creates a new XZ compressor using one filter and CRC64 as the integrity check.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Finishes compression and closes the underlying stream.
      void endBlock()
      Finishes the current XZ Block (but not the whole XZ Stream).
      void finish()
      Finishes compression without closing the underlying stream.
      void flush()
      Flushes the encoder and calls out.flush().
      void updateFilters​(FilterOptions filterOptions)
      Updates the filter chain with a single filter.
      void updateFilters​(FilterOptions[] filterOptions)
      Updates the filter chain with 1-4 filters.
      void write​(byte[] buf, int off, int len)
      Writes an array of bytes to be compressed.
      void write​(int b)
      Writes one byte to be compressed.
      • Methods inherited from class java.io.OutputStream

        nullOutputStream, write
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions filterOptions)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - filter options to use
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions filterOptions,
                              ArrayCache arrayCache)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - filter options to use
        arrayCache - cache to be used for allocating large arrays
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
        Since:
        1.7
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions filterOptions,
                              int checkType)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - filter options to use
        checkType - type of the integrity check, for example XZ.CHECK_CRC32
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions filterOptions,
                              int checkType,
                              ArrayCache arrayCache)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - filter options to use
        checkType - type of the integrity check, for example XZ.CHECK_CRC32
        arrayCache - cache to be used for allocating large arrays
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
        Since:
        1.7
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions[] filterOptions)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - array of filter options to use
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions[] filterOptions,
                              ArrayCache arrayCache)
                       throws java.io.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 - output stream to which the compressed data will be written
        filterOptions - array of filter options to use
        arrayCache - cache to be used for allocating large arrays
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
        Since:
        1.7
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions[] filterOptions,
                              int checkType)
                       throws java.io.IOException
        Creates a new XZ compressor using 1-4 filters and the specified integrity check type.
        Parameters:
        out - output stream to which the compressed data will be written
        filterOptions - array of filter options to use
        checkType - type of the integrity check, for example XZ.CHECK_CRC32
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
      • XZOutputStream

        public XZOutputStream​(java.io.OutputStream out,
                              FilterOptions[] filterOptions,
                              int checkType,
                              ArrayCache arrayCache)
                       throws java.io.IOException
        Creates a new XZ compressor using 1-4 filters and the specified integrity check type.
        Parameters:
        out - output stream to which the compressed data will be written
        filterOptions - array of filter options to use
        checkType - type of the integrity check, for example XZ.CHECK_CRC32
        arrayCache - cache to be used for allocating large arrays
        Throws:
        UnsupportedOptionsException - invalid filter chain
        java.io.IOException - may be thrown from out
        Since:
        1.7
    • Method Detail

      • updateFilters

        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 - new filter to use
        Throws:
        UnsupportedOptionsException - unsupported filter chain, or trying to change the filter chain in the middle of a Block
        XZIOException
      • updateFilters

        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 - new filter chain to use
        Throws:
        UnsupportedOptionsException - unsupported filter chain, or trying to change the filter chain in the middle of a Block
        XZIOException
      • write

        public void write​(int b)
                   throws java.io.IOException
        Writes one byte to be compressed.
        Specified by:
        write in class java.io.OutputStream
        Throws:
        XZIOException - XZ Stream has grown too big
        XZIOException - finish() or close() was already called
        java.io.IOException - may be thrown by the underlying output stream
      • write

        public void write​(byte[] buf,
                          int off,
                          int len)
                   throws java.io.IOException
        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.
        Overrides:
        write in class java.io.OutputStream
        Parameters:
        buf - buffer of bytes to be written
        off - start offset in buf
        len - number of bytes to write
        Throws:
        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
        XZIOException - finish() or close() was already called and len > 0
        java.io.IOException - may be thrown by the underlying output stream
      • endBlock

        public void endBlock()
                      throws java.io.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).

        Throws:
        XZIOException - XZ Stream has grown too big
        XZIOException - stream finished or closed
        java.io.IOException - may be thrown by the underlying output stream
      • flush

        public void flush()
                   throws java.io.IOException
        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.

        Specified by:
        flush in interface java.io.Flushable
        Overrides:
        flush in class java.io.OutputStream
        Throws:
        XZIOException - XZ Stream has grown too big
        XZIOException - stream finished or closed
        java.io.IOException - may be thrown by the underlying output stream
      • finish

        public void finish()
                    throws java.io.IOException
        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.

        Overrides:
        finish in class FinishableOutputStream
        Throws:
        XZIOException - XZ Stream has grown too big
        java.io.IOException - may be thrown by the underlying output stream
      • close

        public void close()
                   throws java.io.IOException
        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.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        XZIOException - XZ Stream has grown too big
        java.io.IOException - may be thrown by the underlying output stream