The following code fragment demonstrates a trivial compression * and decompression of a string using {@code Deflater} and * {@code Inflater}. * *
* try {
* // Encode a String into bytes
* String inputString = "blahblahblah";
* byte[] input = inputString.getBytes("UTF-8");
*
* // Compress the bytes
* byte[] output = new byte[100];
* Deflater compresser = new Deflater();
* compresser.setInput(input);
* compresser.finish();
* int compressedDataLength = compresser.deflate(output);
* compresser.end();
*
* // Decompress the bytes
* Inflater decompresser = new Inflater();
* decompresser.setInput(output, 0, compressedDataLength);
* byte[] result = new byte[100];
* int resultLength = decompresser.inflate(result);
* decompresser.end();
*
* // Decode the bytes into a String
* String outputString = new String(result, 0, resultLength, "UTF-8");
* } catch(java.io.UnsupportedEncodingException ex) {
* // handle
* } catch (java.util.zip.DataFormatException ex) {
* // handle
* }
* If the compression strategy is changed, the next invocation * of {@code deflate} will compress the input available so far with * the old strategy (and may be flushed); the new strategy will take * effect only after that invocation. * * @param strategy the new compression strategy * @exception IllegalArgumentException if the compression strategy is * invalid */ public void setStrategy(int strategy) { switch (strategy) { case DEFAULT_STRATEGY: case FILTERED: case HUFFMAN_ONLY: break; default: throw new IllegalArgumentException(); } synchronized (zsRef) { if (this.strategy != strategy) { this.strategy = strategy; setParams = true; } } } /** * Sets the compression level to the specified value. * *
If the compression level is changed, the next invocation * of {@code deflate} will compress the input available so far * with the old level (and may be flushed); the new level will * take effect only after that invocation. * * @param level the new compression level (0-9) * @exception IllegalArgumentException if the compression level is invalid */ public void setLevel(int level) { if ((level < 0 || level > 9) && level != DEFAULT_COMPRESSION) { throw new IllegalArgumentException("invalid compression level"); } synchronized (zsRef) { if (this.level != level) { this.level = level; setParams = true; } } } /** * Returns true if the input data buffer is empty and setInput() * should be called in order to provide more input. * @return true if the input data buffer is empty and setInput() * should be called in order to provide more input */ public boolean needsInput() { synchronized (zsRef) { return len <= 0; } } /** * When called, indicates that compression should end with the current * contents of the input buffer. */ public void finish() { synchronized (zsRef) { finish = true; } } /** * Returns true if the end of the compressed data output stream has * been reached. * @return true if the end of the compressed data output stream has * been reached */ public boolean finished() { synchronized (zsRef) { return finished; } } /** * Compresses the input data and fills specified buffer with compressed * data. Returns actual number of bytes of compressed data. A return value * of 0 indicates that {@link #needsInput() needsInput} should be called * in order to determine if more input data is required. * *
This method uses {@link #NO_FLUSH} as its compression flush mode. * An invocation of this method of the form {@code deflater.deflate(b, off, len)} * yields the same result as the invocation of * {@code deflater.deflate(b, off, len, Deflater.NO_FLUSH)}. * * @param b the buffer for the compressed data * @param off the start offset of the data * @param len the maximum number of bytes of compressed data * @return the actual number of bytes of compressed data written to the * output buffer */ public int deflate(byte[] b, int off, int len) { return deflate(b, off, len, NO_FLUSH); } /** * Compresses the input data and fills specified buffer with compressed * data. Returns actual number of bytes of compressed data. A return value * of 0 indicates that {@link #needsInput() needsInput} should be called * in order to determine if more input data is required. * *
This method uses {@link #NO_FLUSH} as its compression flush mode. * An invocation of this method of the form {@code deflater.deflate(b)} * yields the same result as the invocation of * {@code deflater.deflate(b, 0, b.length, Deflater.NO_FLUSH)}. * * @param b the buffer for the compressed data * @return the actual number of bytes of compressed data written to the * output buffer */ public int deflate(byte[] b) { return deflate(b, 0, b.length, NO_FLUSH); } /** * Compresses the input data and fills the specified buffer with compressed * data. Returns actual number of bytes of data compressed. * *
Compression flush mode is one of the following three modes: * *
In the case of {@link #FULL_FLUSH} or {@link #SYNC_FLUSH}, if * the return value is {@code len}, the space available in output * buffer {@code b}, this method should be invoked again with the same * {@code flush} parameter and more output space. Make sure that * {@code len} is greater than 6 to avoid flush marker (5 bytes) being * repeatedly output to the output buffer every time this method is * invoked. * * @param b the buffer for the compressed data * @param off the start offset of the data * @param len the maximum number of bytes of compressed data * @param flush the compression flush mode * @return the actual number of bytes of compressed data written to * the output buffer * * @throws IllegalArgumentException if the flush mode is invalid * @since 1.7 */ public int deflate(byte[] b, int off, int len, int flush) { if (b == null) { throw new NullPointerException(); } if (off < 0 || len < 0 || off > b.length - len) { throw new ArrayIndexOutOfBoundsException(); } synchronized (zsRef) { ensureOpen(); if (flush == NO_FLUSH || flush == SYNC_FLUSH || flush == FULL_FLUSH) { int thisLen = this.len; int n = deflateBytes(zsRef.address(), b, off, len, flush); bytesWritten += n; bytesRead += (thisLen - this.len); return n; } throw new IllegalArgumentException(); } } /** * Returns the ADLER-32 value of the uncompressed data. * @return the ADLER-32 value of the uncompressed data */ public int getAdler() { synchronized (zsRef) { ensureOpen(); return getAdler(zsRef.address()); } } /** * Returns the total number of uncompressed bytes input so far. * *
Since the number of bytes may be greater than * Integer.MAX_VALUE, the {@link #getBytesRead()} method is now * the preferred means of obtaining this information.
* * @return the total number of uncompressed bytes input so far */ public int getTotalIn() { return (int) getBytesRead(); } /** * Returns the total number of uncompressed bytes input so far. * * @return the total (non-negative) number of uncompressed bytes input so far * @since 1.5 */ public long getBytesRead() { synchronized (zsRef) { ensureOpen(); return bytesRead; } } /** * Returns the total number of compressed bytes output so far. * *Since the number of bytes may be greater than * Integer.MAX_VALUE, the {@link #getBytesWritten()} method is now * the preferred means of obtaining this information.
* * @return the total number of compressed bytes output so far */ public int getTotalOut() { return (int) getBytesWritten(); } /** * Returns the total number of compressed bytes output so far. * * @return the total (non-negative) number of compressed bytes output so far * @since 1.5 */ public long getBytesWritten() { synchronized (zsRef) { ensureOpen(); return bytesWritten; } } /** * Resets deflater so that a new set of input data can be processed. * Keeps current compression level and strategy settings. */ public void reset() { synchronized (zsRef) { ensureOpen(); reset(zsRef.address()); finish = false; finished = false; off = len = 0; bytesRead = bytesWritten = 0; } } /** * Closes the compressor and discards any unprocessed input. * * This method should be called when the compressor is no longer * being used. Once this method is called, the behavior of the * Deflater object is undefined. */ public void end() { synchronized (zsRef) { zsRef.clean(); buf = null; } } /** * Closes the compressor when garbage is collected. * * @deprecated The {@code finalize} method has been deprecated and will be * removed. It is implemented as a no-op. Subclasses that override * {@code finalize} in order to perform cleanup should be modified to use * alternative cleanup mechanisms and to remove the overriding {@code finalize} * method. The recommended cleanup for compressor is to explicitly call * {@code end} method when it is no longer in use. If the {@code end} is * not invoked explicitly the resource of the compressor will be released * when the instance becomes unreachable. */ @Deprecated(since="9", forRemoval=true) protected void finalize() {} private void ensureOpen() { assert Thread.holdsLock(zsRef); if (zsRef.address() == 0) throw new NullPointerException("Deflater has been closed"); } private static native void initIDs(); private static native long init(int level, int strategy, boolean nowrap); private static native void setDictionary(long addr, byte[] b, int off, int len); private native int deflateBytes(long addr, byte[] b, int off, int len, int flush); private static native int getAdler(long addr); private static native void reset(long addr); private static native void end(long addr); /** * A reference to the native zlib's z_stream structure. It also * serves as the "cleaner" to clean up the native resource when * the Deflater is ended, closed or cleaned. */ static class DeflaterZStreamRef implements Runnable { private long address; private final Cleanable cleanable; private DeflaterZStreamRef(Deflater owner, long addr) { this.cleanable = (owner != null) ? CleanerFactory.cleaner().register(owner, this) : null; this.address = addr; } long address() { return address; } void clean() { cleanable.clean(); } public synchronized void run() { long addr = address; address = 0; if (addr != 0) { end(addr); } } /* * If {@code Deflater} has been subclassed and the {@code end} method is * overridden, uses {@code finalizer} mechanism for resource cleanup. So * {@code end} method can be called when the {@code Deflater} is unreachable. * This mechanism will be removed when the {@code finalize} method is * removed from {@code Deflater}. */ static DeflaterZStreamRef get(Deflater owner, long addr) { Class clz = owner.getClass(); while (clz != Deflater.class) { try { clz.getDeclaredMethod("end"); return new FinalizableZStreamRef(owner, addr); } catch (NoSuchMethodException nsme) {} clz = clz.getSuperclass(); } return new DeflaterZStreamRef(owner, addr); } private static class FinalizableZStreamRef extends DeflaterZStreamRef { final Deflater owner; FinalizableZStreamRef (Deflater owner, long addr) { super(null, addr); this.owner = owner; } @Override void clean() { run(); } @Override @SuppressWarnings("deprecation") protected void finalize() { owner.end(); } } } }