org.at4j.comp.lzma
Class LzmaOutputStream

java.lang.Object
  extended by java.io.OutputStream
      extended by org.at4j.comp.lzma.LzmaOutputStream
All Implemented Interfaces:
Closeable, Flushable

public final class LzmaOutputStream
extends OutputStream

This class provides an OutputStream for encoding data using the Lempel-Ziv-Markov chain algorithm. It uses the LZMA encoder from the LZMA SDK.

The data written by this encoder is has the following structure:

  1. Settings used when encoding (5 bytes). Optional. Enabled by default.
  2. Total size of the data in the stream when uncompressed (8 bytes, little endian). If the uncompressed size is not known, this is set to -1 and the data part will be followed by an end of stream marker. Optional. Enabled by default.
  3. Data
  4. End of stream marker (if the total data size was set to -1).

The API from the LZMA SDK is built around a standalone encoder. To adapt that into the Java streams API, the encoder is launched in a separate execution thread and it is fed data as it is written to the stream. When the stream is closed, the encoder finishes and the encoder thread is shut down.

Errors are propagated up from the encoder to the calling thread. If an error occurs in the encoder, it will be reported to the calling thread the next time that it tries to write to or close the stream.

If the application that uses this stream writes small data chunks to it, it is probably a good idea to wrap it in a BufferedOutputStream to ensure that the LZMA encoder gets bigger chunks of data to work with.

Compressing a file requires a lot of memory since the compression dictionary has to be held in memory. The default size of the dictionary is 2^23 = 8.4 MB. By default, the buffer used to feed data to the encoder has an unlimited size, which may cause the entire written data to be stored in memory if the writing thread is fast and the encoder is slow. A maximum size for the buffer can be set by using a custom data queue depth when creating the compressing stream. See LzmaOutputStreamSettings.setMaxDataQueueSize(int).

Since:
1.0
Author:
Karl Gustafsson
See Also:
LzmaOutputStreamSettings, LzmaInputStream

Constructor Summary
LzmaOutputStream(OutputStream out)
          Create a new LZMA compressing output stream using default compression settings.
LzmaOutputStream(OutputStream out, LzmaOutputStreamSettings settings)
          Create a new LZMA compressing output stream using custom compression settings.
LzmaOutputStream(OutputStream out, LzmaOutputStreamSettings settings, long uncompressedDataSize)
          Create a new LZMA compressing output stream using custom compression settings that compresses data of a known size.
 
Method Summary
 void close()
           
protected  void finalize()
           
 void write(byte[] barr)
           
 void write(byte[] barr, int offset, int len)
           
 void write(int b)
           
 
Methods inherited from class java.io.OutputStream
flush
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

LzmaOutputStream

public LzmaOutputStream(OutputStream out)
Create a new LZMA compressing output stream using default compression settings. The default settings should be good for most compression cases.

This method will set the uncompressed data size to -1 in the compressed stream and will write an end of stream marker after all data.

Parameters:
out - The output stream to write compressed data to.
See Also:
LzmaOutputStream(OutputStream, LzmaOutputStreamSettings)

LzmaOutputStream

public LzmaOutputStream(OutputStream out,
                        LzmaOutputStreamSettings settings)
Create a new LZMA compressing output stream using custom compression settings.

This method will set the uncompressed data size to -1 in the compressed stream and will write an end of stream marker after all data.

Parameters:
out - The output stream to write compressed data to.
settings - Compression settings.
See Also:
LzmaOutputStream(OutputStream), LzmaOutputStream(OutputStream, LzmaOutputStreamSettings, long)

LzmaOutputStream

public LzmaOutputStream(OutputStream out,
                        LzmaOutputStreamSettings settings,
                        long uncompressedDataSize)
                 throws IllegalArgumentException
Create a new LZMA compressing output stream using custom compression settings that compresses data of a known size.

Parameters:
out - The output stream to write compressed data to.
settings - Compression settings.
uncompressedDataSize - The size of the uncompressed data. Set this to -1 (or rather, use any of the other constructors) if the data size is unknown.
Throws:
IllegalArgumentException - If the data size is zero or less than -1.
Method Detail

write

public void write(int b)
           throws IOException
Specified by:
write in class OutputStream
Throws:
IOException

write

public void write(byte[] barr)
           throws IOException
Overrides:
write in class OutputStream
Throws:
IOException

write

public void write(byte[] barr,
                  int offset,
                  int len)
           throws IOException
Overrides:
write in class OutputStream
Throws:
IOException

close

public void close()
           throws IOException
Specified by:
close in interface Closeable
Overrides:
close in class OutputStream
Throws:
IOException

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable