public class

Deflater

extends Object
java.lang.Object
   ↳ java.util.zip.Deflater

Class Overview

This class compresses data using the DEFLATE algorithm (see specification).

It is usually more convenient to use DeflaterOutputStream.

To compress an in-memory byte[] to another in-memory byte[] manually: 

     byte[] originalBytes = ...
     Deflater deflater = new Deflater();
     deflater.setInput(originalBytes);
     deflater.finish();
     ByteArrayOutputStream baos = new ByteArrayOutputStream();
     byte[] buf = new byte[8192];
     while (!deflater.finished()) {
         int byteCount = deflater.deflate(buf);
         baos.write(buf, 0, byteCount);
     }
     deflater.end();
     byte[] compressedBytes = baos.toByteArray();

In situations where you don't have all the input in one array (or have so much input that you want to feed it to the deflater in chunks), it's possible to call setInput repeatedly, but you're much better off using DeflaterOutputStream to handle all this for you. DeflaterOutputStream also helps minimize memory requirements — the sample code above is very expensive.

Summary

Constants
int BEST_COMPRESSION Upper bound for the compression level range.
int BEST_SPEED Lower bound for compression level range.
int DEFAULT_COMPRESSION The default compression level.
int DEFAULT_STRATEGY The default compression strategy.
int DEFLATED The default compression method.
int FILTERED A compression strategy.
int HUFFMAN_ONLY A compression strategy.
int NO_COMPRESSION A compression level.
Public Constructors
Deflater()
Constructs a new Deflater instance using the default compression level.
Deflater(int level)
Constructs a new Deflater instance using compression level level.
Deflater(int level, boolean noHeader)
Constructs a new Deflater instance with a specific compression level.
Public Methods
synchronized int deflate(byte[] buf, int offset, int byteCount)
Deflates data (previously passed to setInput) into a specific region within the supplied buffer.
int deflate(byte[] buf)
Deflates the data (previously passed to setInput) into the supplied buffer.
synchronized void end()
Frees all resources held onto by this deflating algorithm.
synchronized void finish()
Indicates to the Deflater that all uncompressed input has been provided to it.
synchronized boolean finished()
Returns true if finish has been called and all data provided by setInput has been successfully compressed and consumed by deflate.
synchronized int getAdler()
Returns the Adler32 checksum of the uncompressed data read so far.
synchronized long getBytesRead()
Returns the total number of bytes read by the Deflater.
synchronized long getBytesWritten()
Returns a the total number of bytes written by this Deflater.
synchronized int getTotalIn()
Returns the total number of bytes of input read by this Deflater.
synchronized int getTotalOut()
Returns the total number of bytes written to the output buffer by this Deflater.
synchronized boolean needsInput()
Returns true if setInput must be called before deflation can continue.
synchronized void reset()
Resets the Deflater to accept new input without affecting any previously made settings for the compression strategy or level.
synchronized void setDictionary(byte[] buf, int offset, int byteCount)
Sets the dictionary to be used for compression by this Deflater.
void setDictionary(byte[] dictionary)
Sets the dictionary to be used for compression by this Deflater.
synchronized void setInput(byte[] buf, int offset, int byteCount)
Sets the input buffer the Deflater will use to extract uncompressed bytes for later compression.
void setInput(byte[] buf)
Sets the input buffer the Deflater will use to extract uncompressed bytes for later compression.
synchronized void setLevel(int level)
Sets the compression level to be used when compressing data.
synchronized void setStrategy(int strategy)
Sets the compression strategy to be used.
Protected Methods
void finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int BEST_COMPRESSION

Since: API Level 1

Upper bound for the compression level range.

Constant Value: 9 (0x00000009)

public static final int BEST_SPEED

Since: API Level 1

Lower bound for compression level range.

Constant Value: 1 (0x00000001)

public static final int DEFAULT_COMPRESSION

Since: API Level 1

The default compression level.

Constant Value: -1 (0xffffffff)

public static final int DEFAULT_STRATEGY

Since: API Level 1

The default compression strategy.

Constant Value: 0 (0x00000000)

public static final int DEFLATED

Since: API Level 1

The default compression method.

Constant Value: 8 (0x00000008)

public static final int FILTERED

Since: API Level 1

A compression strategy.

Constant Value: 1 (0x00000001)

public static final int HUFFMAN_ONLY

Since: API Level 1

A compression strategy.

Constant Value: 2 (0x00000002)

public static final int NO_COMPRESSION

Since: API Level 1

A compression level.

Constant Value: 0 (0x00000000)

Public Constructors

public Deflater ()

Since: API Level 1

Constructs a new Deflater instance using the default compression level. The strategy can be specified with setStrategy(int). A header is added to the output by default; use Deflater(int, boolean) if you need to omit the header.

public Deflater (int level)

Since: API Level 1

Constructs a new Deflater instance using compression level level. The strategy can be specified with setStrategy(int). A header is added to the output by default; use Deflater(int, boolean) if you need to omit the header.

Parameters
level the compression level in the range between 0 and 9.

public Deflater (int level, boolean noHeader)

Since: API Level 1

Constructs a new Deflater instance with a specific compression level. If noHeader is true, no ZLIB header is added to the output. In a ZIP archive every entry (compressed file) comes with such a header. The strategy can be specified using setStrategy(int).

Parameters
level the compression level in the range between 0 and 9.
noHeader true indicates that no ZLIB header should be written.

Public Methods

public synchronized int deflate (byte[] buf, int offset, int byteCount)

Since: API Level 1

Deflates data (previously passed to setInput) into a specific region within the supplied buffer.

Returns
  • the number of bytes of compressed data written to buf.

public int deflate (byte[] buf)

Since: API Level 1

Deflates the data (previously passed to setInput) into the supplied buffer.

Returns
  • number of bytes of compressed data written to buf.

public synchronized void end ()

Since: API Level 1

Frees all resources held onto by this deflating algorithm. Any unused input or output is discarded. This method should be called explicitly in order to free native resources as soon as possible. After end() is called, other methods will typically throw IllegalStateException.

public synchronized void finish ()

Since: API Level 1

Indicates to the Deflater that all uncompressed input has been provided to it.

See Also

public synchronized boolean finished ()

Since: API Level 1

Returns true if finish has been called and all data provided by setInput has been successfully compressed and consumed by deflate.

public synchronized int getAdler ()

Since: API Level 1

Returns the Adler32 checksum of the uncompressed data read so far.

public synchronized long getBytesRead ()

Since: API Level 1

Returns the total number of bytes read by the Deflater. This method is the same as getTotalIn() except that it returns a long value instead of an integer.

public synchronized long getBytesWritten ()

Since: API Level 1

Returns a the total number of bytes written by this Deflater. This method is the same as getTotalOut except it returns a long value instead of an integer.

public synchronized int getTotalIn ()

Since: API Level 1

Returns the total number of bytes of input read by this Deflater. This method is limited to 32 bits; use getBytesRead() instead.

public synchronized int getTotalOut ()

Since: API Level 1

Returns the total number of bytes written to the output buffer by this Deflater. The method is limited to 32 bits; use getBytesWritten() instead.

public synchronized boolean needsInput ()

Since: API Level 1

Returns true if setInput must be called before deflation can continue. If all uncompressed data has been provided to the Deflater, finish() must be called to ensure the compressed data is output.

public synchronized void reset ()

Since: API Level 1

Resets the Deflater to accept new input without affecting any previously made settings for the compression strategy or level. This operation must be called after finished() returns true if the Deflater is to be reused.

public synchronized void setDictionary (byte[] buf, int offset, int byteCount)

Since: API Level 1

Sets the dictionary to be used for compression by this Deflater. This method can only be called if this Deflater supports the writing of ZLIB headers. This is the default, but can be overridden using Deflater(int, boolean).

public void setDictionary (byte[] dictionary)

Since: API Level 1

Sets the dictionary to be used for compression by this Deflater. This method can only be called if this Deflater supports the writing of ZLIB headers. This is the default, but can be overridden using Deflater(int, boolean).

public synchronized void setInput (byte[] buf, int offset, int byteCount)

Since: API Level 1

Sets the input buffer the Deflater will use to extract uncompressed bytes for later compression.

public void setInput (byte[] buf)

Since: API Level 1

Sets the input buffer the Deflater will use to extract uncompressed bytes for later compression.

public synchronized void setLevel (int level)

Since: API Level 1

Sets the compression level to be used when compressing data. The compression level must be a value between 0 and 9. This value must be set prior to calling setInput.

Throws
IllegalArgumentException If the compression level is invalid.

public synchronized void setStrategy (int strategy)

Since: API Level 1

Sets the compression strategy to be used. The strategy must be one of FILTERED, HUFFMAN_ONLY or DEFAULT_STRATEGY. This value must be set prior to calling setInput.

Throws
IllegalArgumentException If the strategy specified is not one of FILTERED, HUFFMAN_ONLY or DEFAULT_STRATEGY.

Protected Methods

protected void finalize ()

Since: API Level 1

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.