public Class LZMA2Options

Overrides java.lang.Object.clone.

Doc from java.lang.Object.clone.

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

x.clone() != x

x.clone().getClass() == x.getClass()

x.clone().equals(x)

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

Returns:Object

a clone of this instance.

Implements abstract org.tukaani.xz.FilterOptions.getDecoderMemoryUsage.

Gets how much memory the LZMA2 decoder will need to decompress the data that was encoded with these options and stored in a .xz file.

The returned value may bigger than the value returned by a direct call to LZMA2InputStream#getMemoryUsage(int) if the dictionary size is not 2^n or 2^n + 2^(n-1) bytes. This is because the .xz headers store the dictionary size in such a format and other values are rounded up to the next such value. Such rounding is harmess except it might waste some memory if an unsual dictionary size is used.

If you use raw LZMA2 streams and unusual dictioanary size, call LZMA2InputStream#getMemoryUsage directly to get raw decoder memory requirements.

Gets the match finder search depth limit.

Gets the dictionary size in bytes.

Implements abstract org.tukaani.xz.FilterOptions.getEncoderMemoryUsage.

Doc from org.tukaani.xz.FilterOptions.getEncoderMemoryUsage.

Gets how much memory the encoder will need with these options.

Implements abstract org.tukaani.xz.FilterOptions.getInputStream.

Doc from org.tukaani.xz.FilterOptions.getInputStream.

Gets a raw (no XZ headers) decoder input stream using these options and the given ArrayCache.

Gets the number of literal context bits.

Gets the number of literal position bits.

Gets the match finder type.

Gets the compression mode.

Gets the nice length of matches.

Implements abstract org.tukaani.xz.FilterOptions.getOutputStream.

Doc from org.tukaani.xz.FilterOptions.getOutputStream.

Gets a raw (no XZ headers) encoder output stream using these options and the given ArrayCache. Raw streams are an advanced feature. In most cases you want to store the compressed data in the .xz container format instead of using a raw stream. To use this filter in a .xz file, pass this object to XZOutputStream.

Gets the number of position bits.

Gets the preset dictionary.

Sets the match finder search depth limit.

The default is a special value of 0 which indicates that the depth limit should be automatically calculated by the selected match finder from the nice length of matches.

Reasonable depth limit for Hash Chain match finders is 4-100 and 16-1000 for Binary Tree match finders. Using very high values can make the compressor extremely slow with some files. Avoid settings higher than 1000 unless you are prepared to interrupt the compression in case it is taking far too long.

Exceptions

UnsupportedOptionsException:

depthLimit is invalid

Sets the dictionary size in bytes.

The dictionary (or history buffer) holds the most recently seen uncompressed data. Bigger dictionary usually means better compression. However, using a dictioanary bigger than the size of the uncompressed data is waste of memory.

Any value in the range [DICT_SIZE_MIN, DICT_SIZE_MAX] is valid, but sizes of 2^n and 2^n + 2^(n-1) bytes are somewhat recommended.

Exceptions

UnsupportedOptionsException:

dictSize is not supported

Sets the number of literal context bits.

All bytes that cannot be encoded as matches are encoded as literals. That is, literals are simply 8-bit bytes that are encoded one at a time.

The literal coding makes an assumption that the highest lc bits of the previous uncompressed byte correlate with the next byte. For example, in typical English text, an upper-case letter is often followed by a lower-case letter, and a lower-case letter is usually followed by another lower-case letter. In the US-ASCII character set, the highest three bits are 010 for upper-case letters and 011 for lower-case letters. When lc is at least 3, the literal coding can take advantage of this property in the uncompressed data.

The default value (3) is usually good. If you want maximum compression, try setLc(4). Sometimes it helps a little, and sometimes it makes compression worse. If it makes it worse, test for example setLc(2) too.

Exceptions

UnsupportedOptionsException:

lc is invalid, or the sum of lc and lp exceed LC_LP_MAX

Sets the number of literal context bits and literal position bits.

The sum of lc and lp is limited to 4. Trying to exceed it will throw an exception. This function lets you change both at the same time.

Exceptions

UnsupportedOptionsException:

lc and lp are invalid

Sets the number of literal position bits.

This affets what kind of alignment in the uncompressed data is assumed when encoding literals. See setPb for more information about alignment.

Exceptions

UnsupportedOptionsException:

lp is invalid, or the sum of lc and lp exceed LC_LP_MAX

Sets the match finder type.

Match finder has a major effect on compression speed, memory usage, and compression ratio. Usually Hash Chain match finders are faster than Binary Tree match finders. The default depends on the preset: 0-3 use MF_HC4 and 4-9 use MF_BT4.

Exceptions

UnsupportedOptionsException:

mf is not supported

Sets the compression mode.

This specifies the method to analyze the data produced by a match finder. The default is MODE_FAST for presets 0-3 and MODE_NORMAL for presets 4-9.

Usually MODE_FAST is used with Hash Chain match finders and MODE_NORMAL with Binary Tree match finders. This is also what the presets do.

The special mode MODE_UNCOMPRESSED doesn't try to compress the data at all (and doesn't use a match finder) and will simply wrap it in uncompressed LZMA2 chunks.

Exceptions

UnsupportedOptionsException:

mode is not supported

Sets the nice length of matches. Once a match of at least niceLen bytes is found, the algorithm stops looking for better matches. Higher values tend to give better compression at the expense of speed. The default depends on the preset.

Exceptions

UnsupportedOptionsException:

niceLen is invalid

Sets the number of position bits.

This affects what kind of alignment in the uncompressed data is assumed in general. The default (2) means four-byte alignment (2^pb = 2^2 = 4), which is often a good choice when there's no better guess.

When the alignment is known, setting the number of position bits accordingly may reduce the file size a little. For example with text files having one-byte alignment (US-ASCII, ISO-8859-*, UTF-8), using setPb(0) can improve compression slightly. For UTF-16 text, setPb(1) is a good choice. If the alignment is an odd number like 3 bytes, setPb(0) might be the best choice.

Even though the assumed alignment can be adjusted with setPb and setLp, LZMA2 still slightly favors 16-byte alignment. It might be worth taking into account when designing file formats that are likely to be often compressed with LZMA2.

Exceptions

UnsupportedOptionsException:

pb is invalid

Sets the compression options to the given preset.

The presets 0-3 are fast presets with medium compression. The presets 4-6 are fairly slow presets with high compression. The default preset (PRESET_DEFAULT) is 6.

The presets 7-9 are like the preset 6 but use bigger dictionaries and have higher compressor and decompressor memory requirements. Unless the uncompressed size of the file exceeds 8 MiB, 16 MiB, or 32 MiB, it is waste of memory to use the presets 7, 8, or 9, respectively.

Exceptions

UnsupportedOptionsException:

preset is not supported

Sets a preset dictionary. Use null to disable the use of a preset dictionary. By default there is no preset dictionary.

The .xz format doesn't support a preset dictionary for now. Do not set a preset dictionary unless you use raw LZMA2.

Preset dictionary can be useful when compressing many similar, relatively small chunks of data independently from each other. A preset dictionary should contain typical strings that occur in the files being compressed. The most probable strings should be near the end of the preset dictionary. The preset dictionary used for compression is also needed for decompression.