com.jcraft.jzlib
Class ZStream

java.lang.Object
  com.jcraft.jzlib.ZStream

public final class ZStream
extends Object

The core compression class: A pair of buffers with some metadata for compression or decompression, and the necessary compression/decompression methods. This corresponds to the z_stream_s data structure (and z_streamp pointer type) in zlib, together with most of the (non-utility) functions defined in zlib.h.

next_in

public byte[] next_in

The input buffer. The library will read from here. This may be updated by the application when providing more data.

next_in_index

public int next_in_index

The index of the next input byte in next_in. This will be updated (incremented) by the library as it is reading data from the buffer. It might be reset by the application when providing more data.

avail_in

public int avail_in

The number of bytes available for reading in next_in. (This must not be more than next_in.length - next_in_index. This must be updated by the application when providing more data. This will be updated (decremented) by the library when reading data from the buffer.

total_in

public long total_in

The total number of bytes read so far. This is updated (incremented) by the library on each call of inflate(int) and deflate(int) (if it reads data) and can be used by the application for statistics purposes. It is not used by the library.

next_out

public byte[] next_out

The output buffer. The library will put output data into this buffer at next_out_index. The application will have to read the output from this buffer.

next_out_index

public int next_out_index

The position of the next output byte in next_out_index. This will be updated (incremented) by the library when producing output. It might be reset by the application after reading the output.

avail_out

public int avail_out

The remaining available space in the output buffer. This will be updated (decremented) by the library when producing output. It might be reset by the application after reading output.

total_out

public long total_out

The total number of bytes produced so far. This is updated (incremented) by the library on each call of inflate(int) and deflate(int) (if it produces data) and can be used by the application for statistics purposes. It is not used by the library.

msg

public String msg

last produced error message, in human readable form (english). null if there was no error.

adler

public long adler

The Adler32 checksum of the uncompressed data read (or decompressed) so far.

If inflate(int) returned Z_NEED_DICT, this field contains the Adler32 checksum of the needed dictionary.

ZStream

public ZStream()

inflateInit

public int inflateInit()

Initializes the stream for decompression (inflating), using the default (maximum) window size and the zlib format.

inflateInit

public int inflateInit(boolean nowrap)

Initializes the stream for decompression (inflating), using the default (maximum) window size.

Parameters:

nowrap - if true, the stream uses the plain deflate format. If false, the stream uses the zlib format (which includes a header and checksum).

inflateInit

public int inflateInit(int w)

Initializes the stream for decompression (inflating), using zlib format.

Parameters:

w - the base two logarithm of the window size (e.g. the size of the history buffer). This should be in the range 8 .. 15, resulting in window sizes between 256 and 32768 bytes. This must be as least as large as the window size used for compressing.

inflateInit

public int inflateInit(int w,
                       boolean nowrap)

Initializes the stream for decompression (inflating).

Parameters:

w - the base two logarithm of the window size (e.g. the size of the history buffer). This should be in the range 8 .. 15, resulting in window sizes between 256 and 32768 bytes. This must be as least as large as the window size used for compressing.

nowrap - if true, the stream uses the plain deflate format. If false, the stream uses the zlib format (which includes a header and checksum).

inflate

public int inflate(int flush)

inflate decompresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.

The detailed semantics are as follows. inflate performs one or both of the following actions:

• Decompress more input from next_in, starting at next_in_index, and update next_in_index and avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), next_in_index is updated and processing will resume at this point for the next call of inflate().
• Provide more output in next_out, starting at next_out_index and update next_out_index and avail_out accordingly. inflate() provides as much output as possible, until there is no more input data or no more space in the output buffer (see below about the flush parameter).

Before the call of inflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating the {code next_*_index} and avail_* values accordingly. The application can consume the uncompressed output when it wants, for example when the output buffer is full (avail_out== 0), or after each call of inflate(). If inflate returns Z_OK and with zero avail_out, it must be called again after making room in the output buffer because there might be more output pending.

If a preset dictionary is needed after this call (see inflateSetDictionary(byte[], int)), inflate sets adler to the adler32 checksum of the dictionary chosen by the compressor and returns Z_NEED_DICT; otherwise it sets adler to the adler32 checksum of all output produced so far (that is, total_out bytes) and returns Z_OK, Z_STREAM_END or an error code as described below. At the end of the stream (for zlib format), inflate() checks that its computed adler32 checksum is equal to that saved by the compressor and returns Z_STREAM_END only if the checksum is correct.

inflate() will decompress and check either zlib-wrapped or plain deflate data, depending on the inflateInit method used (and its nowrap parameter).

Parameters:

flush - one of Z_NO_FLUSH, Z_SYNC_FLUSH, and Z_FINISH.

Z_NO_FLUSH is the usual value for non-interactive usage.

Z_SYNC_FLUSH requests that inflate() flush as much output as possible to the output buffer.

inflate() should normally be called until it returns Z_STREAM_END or an error. However if all decompression is to be performed in a single step (a single call of inflate), the parameter flush should be set to Z_FINISH. In this case all pending input is processed and all pending output is flushed; avail_out must be large enough to hold all the uncompressed data. (The size of the uncompressed data may have been saved by the compressor for this purpose.) The next operation on this stream must be inflateEnd() to deallocate the decompression state. The use of Z_FINISH is never required, but can be used to inform inflate that a faster approach may be used for the single inflate() call.

In this implementation, inflate() always flushes as much output as possible to the output buffer, and always uses the faster approach on the first call. So the only effect of the flush parameter in this implementation is on the return value of inflate(), as noted below.

Returns:

• Z_OK if some progress has been made (more input processed or more output produced),
• Z_STREAM_END if the end of the compressed data has been reached and all uncompressed output has been produced (and for the zlib format, the checksum matches),
• Z_NEED_DICT if a preset dictionary is needed at this point,
• Z_DATA_ERROR if the input data was corrupted (input stream not conforming to the zlib format or incorrect check value),
• Z_STREAM_ERROR if the stream structure was inconsistent (for example if next_in or next_out was null),
• Z_BUF_ERROR if no progress is possible or if there was not enough room in the output buffer when Z_FINISH is used.

Note that Z_BUF_ERROR is not fatal, and inflate() can be called again with more input and more output space to continue decompressing. If Z_DATA_ERROR is returned, the application may then call inflateSync() to look for a good compression block if a partial recovery of the data is desired.

inflateEnd

public int inflateEnd()

All dynamically allocated data structures for this stream are freed. This function discards any unprocessed input and does not flush any pending output.

Returns:

Z_OK if success, Z_STREAM_ERROR if the stream state was inconsistent. In the error case, msg may be set.

inflateSync

public int inflateSync()

Skips invalid compressed data until a full flush point (see above the description of deflate(int) with Z_FULL_FLUSH) can be found, or until all available input is skipped. No output is provided.

In the success case, the application may save the current current value of total_in which indicates where valid compressed data was found. In the error case, the application may repeatedly call inflateSync(), providing more input each time, until success or end of the input data.

Returns:

Z_OK if a full flush point has been found, Z_BUF_ERROR if no more input was provided, Z_DATA_ERROR if no flush point has been found, or Z_STREAM_ERROR if the stream structure was inconsistent.

inflateSetDictionary

public int inflateSetDictionary(byte[] dictionary,
                                int dictLength)

Initializes the decompression dictionary from the given uncompressed byte sequence.

This function must be called immediately after a call of inflate(int), if that call returned Z_NEED_DICT. The dictionary chosen by the compressor can be determined from the adler32 value returned by that call of inflate. The compressor and decompressor must use exactly the same dictionary (see deflateSetDictionary(byte[], int)).

For raw inflate (i.e. decompressing plain deflate data without a zlib header), this function can be called immediately after inflateInit() and before any call of inflate(int) to set the dictionary. The application must insure that the dictionary that was used for compression is provided.

inflateSetDictionary does not perform any decompression: this will be done by subsequent calls of inflate(int).

Parameters:

dictionary - an array containing uncompressed data to use as the dictionary for future inflate(int) calls.

dictLength - the length of the data in the array.

Returns:

Z_OK if success, Z_STREAM_ERROR if a parameter is invalid (such as null dictionary) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the expected one (incorrect adler32 value).

deflateInit

public int deflateInit(int level)

initializes the stream for deflation in zlib format, using the given compression level and the maximum lookback window size.

Parameters:

level - the deflation level. This should be Z_NO_COMPRESSION, Z_DEFAULT_COMPRESSION or a value between Z_BEST_SPEED (1) and Z_BEST_COMPRESSION (9) (both inclusive).

deflateInit

public int deflateInit(int level,
                       boolean nowrap)

initializes the stream for deflation, using the given compression level and the maximum lookback window size.

Parameters:

level - the deflation level. This should be Z_NO_COMPRESSION, Z_DEFAULT_COMPRESSION or a value between Z_BEST_SPEED (1) and Z_BEST_COMPRESSION (9) (both inclusive).

nowrap - if true, the stream uses the plain deflate format. If false, the stream uses the zlib format (which includes a header and checksum).

deflateInit

public int deflateInit(int level,
                       int bits)

initializes the stream for deflation in zlib format, using the given compression level and lookback window size.

Parameters:

level - the deflation level. This should be Z_NO_COMPRESSION, Z_DEFAULT_COMPRESSION or a value between Z_BEST_SPEED (1) and Z_BEST_COMPRESSION (9) (both inclusive).

bits - the base two logarithm of the window size (e.g. the size of the history buffer). This should be in the range 8 .. 15, resulting in window sizes between 256 and 32768 bytes. Larger values result in better compression with more memory usage.

deflateInit

public int deflateInit(int level,
                       int bits,
                       boolean nowrap)

Initializes the stream for deflation, using the given compression level and given lookback window size.

Parameters:

level - the deflation level. This should be Z_NO_COMPRESSION, Z_DEFAULT_COMPRESSION or a value between Z_BEST_SPEED (1) and Z_BEST_COMPRESSION (9) (both inclusive).

bits - the base two logarithm of the window size (e.g. the size of the history buffer). This should be in the range 8 .. 15, resulting in window sizes between 256 and 32768 bytes. Larger values result in better compression with more memory usage.

nowrap - if true, the stream uses the plain deflate format. If false, the stream uses the zlib format (which includes a header and checksum).

deflate

public int deflate(int flush)

deflate compresses as much data as possible, and stops when the input buffer becomes empty or the output buffer becomes full. It may introduce some output latency (reading input without producing any output) except when forced to flush.

The detailed semantics are as follows. deflate performs one or both of the following actions:

• Compress more input from next_in, starting at next_in_index, and update next_in_index and avail_in accordingly. If not all input can be processed (because there is not enough room in the output buffer), next_in_index and avail_in are updated and processing will resume at this point for the next call of deflate().
• Provide more output in next_out, starting at next_out_index and update next_out_index and avail_out accordingly. This action is forced if the parameter flush is non zero (i.e. not Z_NO_FLUSH). Forcing flush frequently degrades the compression ratio, so this parameter should be set only when necessary (in interactive applications). Some output may be provided even if flush is not set.

Before the call of deflate(), the application should ensure that at least one of the actions is possible, by providing more input and/or consuming more output, and updating avail_in or avail_out accordingly; avail_out should never be zero before the call. The application can consume the compressed output when it wants, for example when the output buffer is full (avail_out== 0), or after each call of deflate(). If deflate returns Z_OK and with zero avail_out, it must be called again after making room in the output buffer because there might be more output pending.

Parameters:

flush - whether and how to flush output.

Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to decide how much data to accumulate before producing output, in order to maximize compression.

If the parameter flush is set to Z_SYNC_FLUSH, all pending output is flushed to the output buffer and the output is aligned on a byte boundary, so that the decompressor can get all input data available so far. (In particular avail_in is zero after the call if enough output space has been provided before the call.) Flushing may degrade compression for some compression algorithms and so it should be used only when necessary. This completes the current deflate block and follows it with an empty stored block that is three bits plus filler bits to the next byte, followed by four bytes (00 00 ff ff).

If flush is set to Z_PARTIAL_FLUSH, all pending output is flushed to the output buffer, but the output is not aligned to a byte boundary. All of the input data so far will be available to the decompressor, as for Z_SYNC_FLUSH. This completes the current deflate block and follows it with an empty fixed codes block that is 10 bits long. This assures that enough bytes are output in order for the decompressor to finish the block before the empty fixed code block.

If flush is set to Z_FULL_FLUSH, all output is flushed as with Z_SYNC_FLUSH, and the compression state is reset so that decompression can restart from this point if previous compressed data has been damaged or if random access is desired. Using Z_FULL_FLUSH too often can seriously degrade compression. On the decompression side, such reset points can be found with inflateSync().

If deflate returns with avail_out== 0, this function must be called again with the same value of the flush parameter and more output space (updated avail_out), until the flush is complete (deflate returns with non-zero avail_out). In the case of a Z_FULL_FLUSH or Z_SYNC_FLUSH, make sure that avail_out is greater than six to avoid repeated flush markers due to avail_out== 0 on return.

If the parameter flush is set to Z_FINISH, pending input is processed, pending output is flushed and deflate returns with Z_STREAM_END if there was enough output space; if deflate returns with Z_OK, this function must be called again with Z_FINISH and more output space (updated avail_out) but no more input data, until it returns with Z_STREAM_END or an error. After deflate has returned Z_STREAM_END, the only possible operation on the stream is deflateEnd().

Z_FINISH can be used immediately after deflateInit(int) if all the compression is to be done in a single step. In this case, avail_out must be large enough to compress everything. If deflate does not return Z_STREAM_END, then it must be called again as described above.

Returns:

• Z_OK if some progress has been made (more input processed or more output produced),
• Z_STREAM_END if all input has been consumed and all output has been produced (only when flush is set to Z_FINISH),
• Z_STREAM_ERROR if the stream state was inconsistent (for example if next_in or next_out was null),
• Z_BUF_ERROR if no progress is possible (for example avail_in or avail_out was zero).

Note that Z_BUF_ERROR is not fatal, and deflate() can be called again with more input and more output space to continue compressing.

deflateEnd

public int deflateEnd()

All dynamically allocated data structures for this stream are freed. This function discards any unprocessed input and does not flush any pending output.

Returns:

Z_OK if success, Z_STREAM_ERROR if the stream state was inconsistent, Z_DATA_ERROR if the stream was freed prematurely (some input or output was discarded). In the error case, msg may be set.

deflateParams

public int deflateParams(int level,
                         int strategy)

Dynamically update the compression level and compression strategy.

This can be used to switch between compression and straight copy of the input data, or to switch to a different kind of input data requiring a different strategy. If the compression level is changed, the input available so far is compressed with the old level (and may be flushed); the new level will take effect only at the next call of deflate().

Before the call of deflateParams, the stream state must be set as for a call of deflate(int), since the currently available input may have to be compressed and flushed. In particular, avail_out must be non-zero.

Parameters:

level - the deflation level. This should be Z_NO_COMPRESSION, Z_DEFAULT_COMPRESSION or a value between Z_BEST_SPEED (1) and Z_BEST_COMPRESSION (9) (both inclusive).

strategy - one of Z_DEFAULT_STRATEGY, Z_FILTERED and Z_HUFFMAN_ONLY. (See the description of these constants for details on each.)

Returns:

Z_OK if success, Z_STREAM_ERROR if the source stream state was inconsistent or if a parameter was invalid, Z_BUF_ERROR if avail_out was zero.

deflateSetDictionary

public int deflateSetDictionary(byte[] dictionary,
                                int dictLength)

Initializes the compression dictionary from the given byte sequence, without producing any compressed output.

This function must be called immediately after deflateInit(int), before any call of deflate(int). The compressor and decompressor must use exactly the same dictionary (see inflateSetDictionary(byte[], int)).

The dictionary should consist of strings (byte sequences) that are likely to be encountered later in the data to be compressed, with the most commonly used strings preferably put towards the end of the dictionary. Using a dictionary is most useful when the data to be compressed is short and can be predicted with good accuracy; the data can then be compressed better than with the default empty dictionary.

Depending on the size of the compression data structures selected by deflateInit(int), a part of the dictionary may in effect be discarded, for example if the dictionary is larger than the window size used in deflateInit(int). Thus the strings most likely to be useful should be put at the end of the dictionary, not at the front. In addition, the current implementation of deflate will use at most the window size minus 262 bytes of the provided dictionary.

Upon return of this function, adler is set to the adler32 value of the dictionary; the decompressor may later use this value to determine which dictionary has been used by the compressor. (The adler32 value applies to the whole dictionary even if only a subset of the dictionary is actually used by the compressor.) If a raw deflate was requested (i.e. deflateInit(int,boolean) was invoked with nowrap == true, then the adler32 value is not computed and adler is not set.

deflateSetDictionary does not perform any compression: this will be done by deflate().

Parameters:

dictionary - an array containing the dictionary (from the start).

dictLength - the length of the dictionary. (This should be at most dictionary.length.

Returns:

Z_OK if success, or Z_STREAM_ERROR if a parameter is invalid (such as a null dictionary) or the stream state is inconsistent (for example if deflate(int) has already been called for this stream).

free

public void free()

Frees most memory used by this object. Calling this is normally not necessary in Java, simply ceasing to refer to this object should be enough.