1 /*
2 * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util.zip;
27
28 /**
29 * This class provides support for general purpose compression using the
30 * popular ZLIB compression library. The ZLIB compression library was
31 * initially developed as part of the PNG graphics standard and is not
32 * protected by patents. It is fully described in the specifications at
33 * the <a href="package-summary.html#package_description">java.util.zip
34 * package description</a>.
35 *
36 * <p>The following code fragment demonstrates a trivial compression
37 * and decompression of a string using <tt>Deflater</tt> and
38 * <tt>Inflater</tt>.
39 *
40 * <blockquote><pre>
41 * try {
42 * // Encode a String into bytes
43 * String inputString = "blahblahblah";
44 * byte[] input = inputString.getBytes("UTF-8");
45 *
46 * // Compress the bytes
47 * byte[] output = new byte[100];
48 * Deflater compresser = new Deflater();
49 * compresser.setInput(input);
50 * compresser.finish();
51 * int compressedDataLength = compresser.deflate(output);
52 * compresser.end();
53 *
54 * // Decompress the bytes
55 * Inflater decompresser = new Inflater();
56 * decompresser.setInput(output, 0, compressedDataLength);
57 * byte[] result = new byte[100];
58 * int resultLength = decompresser.inflate(result);
59 * decompresser.end();
60 *
61 * // Decode the bytes into a String
62 * String outputString = new String(result, 0, resultLength, "UTF-8");
63 * } catch(java.io.UnsupportedEncodingException ex) {
64 * // handle
65 * } catch (java.util.zip.DataFormatException ex) {
66 * // handle
67 * }
68 * </pre></blockquote>
69 *
70 * @see Inflater
71 * @author David Connelly
72 */
73 public
74 class Deflater {
75
76 private final ZStreamRef zsRef;
77 private byte[] buf = new byte[0];
78 private int off, len;
79 private int level, strategy;
80 private boolean setParams;
81 private boolean finish, finished;
82 private long bytesRead;
83 private long bytesWritten;
84
85 /**
86 * Compression method for the deflate algorithm (the only one currently
87 * supported).
88 */
89 public static final int DEFLATED = 8;
90
91 /**
92 * Compression level for no compression.
93 */
94 public static final int NO_COMPRESSION = 0;
95
96 /**
97 * Compression level for fastest compression.
98 */
99 public static final int BEST_SPEED = 1;
100
101 /**
102 * Compression level for best compression.
103 */
104 public static final int BEST_COMPRESSION = 9;
105
106 /**
107 * Default compression level.
108 */
109 public static final int DEFAULT_COMPRESSION = -1;
110
111 /**
112 * Compression strategy best used for data consisting mostly of small
113 * values with a somewhat random distribution. Forces more Huffman coding
114 * and less string matching.
115 */
116 public static final int FILTERED = 1;
117
118 /**
119 * Compression strategy for Huffman coding only.
120 */
121 public static final int HUFFMAN_ONLY = 2;
122
123 /**
124 * Default compression strategy.
125 */
126 public static final int DEFAULT_STRATEGY = 0;
127
128 /**
129 * Compression flush mode used to achieve best compression result.
130 *
131 * @see Deflater#deflate(byte[], int, int, int)
132 * @since 1.7
133 */
134 public static final int NO_FLUSH = 0;
135
136 /**
137 * Compression flush mode used to flush out all pending output; may
138 * degrade compression for some compression algorithms.
139 *
140 * @see Deflater#deflate(byte[], int, int, int)
141 * @since 1.7
142 */
143 public static final int SYNC_FLUSH = 2;
144
145 /**
146 * Compression flush mode used to flush out all pending output and
147 * reset the deflater. Using this mode too often can seriously degrade
148 * compression.
149 *
150 * @see Deflater#deflate(byte[], int, int, int)
151 * @since 1.7
152 */
153 public static final int FULL_FLUSH = 3;
154
155 static {
156 /* Zip library is loaded from System.initializeSystemClass */
157 initIDs();
158 }
159
160 /**
161 * Creates a new compressor using the specified compression level.
162 * If 'nowrap' is true then the ZLIB header and checksum fields will
163 * not be used in order to support the compression format used in
164 * both GZIP and PKZIP.
165 * @param level the compression level (0-9)
166 * @param nowrap if true then use GZIP compatible compression
167 */
168 public Deflater(int level, boolean nowrap) {
169 this.level = level;
170 this.strategy = DEFAULT_STRATEGY;
171 this.zsRef = new ZStreamRef(init(level, DEFAULT_STRATEGY, nowrap));
172 }
173
174 /**
175 * Creates a new compressor using the specified compression level.
176 * Compressed data will be generated in ZLIB format.
177 * @param level the compression level (0-9)
178 */
179 public Deflater(int level) {
180 this(level, false);
181 }
182
183 /**
184 * Creates a new compressor with the default compression level.
185 * Compressed data will be generated in ZLIB format.
186 */
187 public Deflater() {
188 this(DEFAULT_COMPRESSION, false);
189 }
190
191 /**
192 * Sets input data for compression. This should be called whenever
193 * needsInput() returns true indicating that more input data is required.
194 * @param b the input data bytes
195 * @param off the start offset of the data
196 * @param len the length of the data
197 * @see Deflater#needsInput
198 */
199 public void setInput(byte[] b, int off, int len) {
200 if (b== null) {
201 throw new NullPointerException();
202 }
203 if (off < 0 || len < 0 || off > b.length - len) {
204 throw new ArrayIndexOutOfBoundsException();
205 }
206 synchronized (zsRef) {
207 this.buf = b;
208 this.off = off;
209 this.len = len;
210 }
211 }
212
213 /**
214 * Sets input data for compression. This should be called whenever
215 * needsInput() returns true indicating that more input data is required.
216 * @param b the input data bytes
217 * @see Deflater#needsInput
218 */
219 public void setInput(byte[] b) {
220 setInput(b, 0, b.length);
221 }
222
223 /**
224 * Sets preset dictionary for compression. A preset dictionary is used
225 * when the history buffer can be predetermined. When the data is later
226 * uncompressed with Inflater.inflate(), Inflater.getAdler() can be called
227 * in order to get the Adler-32 value of the dictionary required for
228 * decompression.
229 * @param b the dictionary data bytes
230 * @param off the start offset of the data
231 * @param len the length of the data
232 * @see Inflater#inflate
233 * @see Inflater#getAdler
234 */
235 public void setDictionary(byte[] b, int off, int len) {
236 if (b == null) {
237 throw new NullPointerException();
238 }
239 if (off < 0 || len < 0 || off > b.length - len) {
240 throw new ArrayIndexOutOfBoundsException();
241 }
242 synchronized (zsRef) {
243 ensureOpen();
244 setDictionary(zsRef.address(), b, off, len);
245 }
246 }
247
248 /**
249 * Sets preset dictionary for compression. A preset dictionary is used
250 * when the history buffer can be predetermined. When the data is later
251 * uncompressed with Inflater.inflate(), Inflater.getAdler() can be called
252 * in order to get the Adler-32 value of the dictionary required for
253 * decompression.
254 * @param b the dictionary data bytes
255 * @see Inflater#inflate
256 * @see Inflater#getAdler
257 */
258 public void setDictionary(byte[] b) {
259 setDictionary(b, 0, b.length);
260 }
261
262 /**
263 * Sets the compression strategy to the specified value.
264 *
265 * <p> If the compression strategy is changed, the next invocation
266 * of {@code deflate} will compress the input available so far with
267 * the old strategy (and may be flushed); the new strategy will take
268 * effect only after that invocation.
269 *
270 * @param strategy the new compression strategy
271 * @exception IllegalArgumentException if the compression strategy is
272 * invalid
273 */
274 public void setStrategy(int strategy) {
275 switch (strategy) {
276 case DEFAULT_STRATEGY:
277 case FILTERED:
278 case HUFFMAN_ONLY:
279 break;
280 default:
281 throw new IllegalArgumentException();
282 }
283 synchronized (zsRef) {
284 if (this.strategy != strategy) {
285 this.strategy = strategy;
286 setParams = true;
287 }
288 }
289 }
290
291 /**
292 * Sets the compression level to the specified value.
293 *
294 * <p> If the compression level is changed, the next invocation
295 * of {@code deflate} will compress the input available so far
296 * with the old level (and may be flushed); the new level will
297 * take effect only after that invocation.
298 *
299 * @param level the new compression level (0-9)
300 * @exception IllegalArgumentException if the compression level is invalid
301 */
302 public void setLevel(int level) {
303 if ((level < 0 || level > 9) && level != DEFAULT_COMPRESSION) {
304 throw new IllegalArgumentException("invalid compression level");
305 }
306 synchronized (zsRef) {
307 if (this.level != level) {
308 this.level = level;
309 setParams = true;
310 }
311 }
312 }
313
314 /**
315 * Returns true if the input data buffer is empty and setInput()
316 * should be called in order to provide more input.
317 * @return true if the input data buffer is empty and setInput()
318 * should be called in order to provide more input
319 */
320 public boolean needsInput() {
321 return len <= 0;
322 }
323
324 /**
325 * When called, indicates that compression should end with the current
326 * contents of the input buffer.
327 */
328 public void finish() {
329 synchronized (zsRef) {
330 finish = true;
331 }
332 }
333
334 /**
335 * Returns true if the end of the compressed data output stream has
336 * been reached.
337 * @return true if the end of the compressed data output stream has
338 * been reached
339 */
340 public boolean finished() {
341 synchronized (zsRef) {
342 return finished;
343 }
344 }
345
346 /**
347 * Compresses the input data and fills specified buffer with compressed
348 * data. Returns actual number of bytes of compressed data. A return value
349 * of 0 indicates that {@link #needsInput() needsInput} should be called
350 * in order to determine if more input data is required.
351 *
352 * <p>This method uses {@link #NO_FLUSH} as its compression flush mode.
353 * An invocation of this method of the form {@code deflater.deflate(b, off, len)}
354 * yields the same result as the invocation of
355 * {@code deflater.deflate(b, off, len, Deflater.NO_FLUSH)}.
356 *
357 * @param b the buffer for the compressed data
358 * @param off the start offset of the data
359 * @param len the maximum number of bytes of compressed data
360 * @return the actual number of bytes of compressed data written to the
361 * output buffer
362 */
363 public int deflate(byte[] b, int off, int len) {
364 return deflate(b, off, len, NO_FLUSH);
365 }
366
367 /**
368 * Compresses the input data and fills specified buffer with compressed
369 * data. Returns actual number of bytes of compressed data. A return value
370 * of 0 indicates that {@link #needsInput() needsInput} should be called
371 * in order to determine if more input data is required.
372 *
373 * <p>This method uses {@link #NO_FLUSH} as its compression flush mode.
374 * An invocation of this method of the form {@code deflater.deflate(b)}
375 * yields the same result as the invocation of
376 * {@code deflater.deflate(b, 0, b.length, Deflater.NO_FLUSH)}.
377 *
378 * @param b the buffer for the compressed data
379 * @return the actual number of bytes of compressed data written to the
380 * output buffer
381 */
382 public int deflate(byte[] b) {
383 return deflate(b, 0, b.length, NO_FLUSH);
384 }
385
386 /**
387 * Compresses the input data and fills the specified buffer with compressed
388 * data. Returns actual number of bytes of data compressed.
389 *
390 * <p>Compression flush mode is one of the following three modes:
391 *
392 * <ul>
393 * <li>{@link #NO_FLUSH}: allows the deflater to decide how much data
394 * to accumulate, before producing output, in order to achieve the best
395 * compression (should be used in normal use scenario). A return value
396 * of 0 in this flush mode indicates that {@link #needsInput()} should
397 * be called in order to determine if more input data is required.
398 *
399 * <li>{@link #SYNC_FLUSH}: all pending output in the deflater is flushed,
400 * to the specified output buffer, so that an inflater that works on
401 * compressed data can get all input data available so far (In particular
402 * the {@link #needsInput()} returns {@code true} after this invocation
403 * if enough output space is provided). Flushing with {@link #SYNC_FLUSH}
404 * may degrade compression for some compression algorithms and so it
405 * should be used only when necessary.
406 *
407 * <li>{@link #FULL_FLUSH}: all pending output is flushed out as with
408 * {@link #SYNC_FLUSH}. The compression state is reset so that the inflater
409 * that works on the compressed output data can restart from this point
410 * if previous compressed data has been damaged or if random access is
411 * desired. Using {@link #FULL_FLUSH} too often can seriously degrade
412 * compression.
413 * </ul>
414 *
415 * <p>In the case of {@link #FULL_FLUSH} or {@link #SYNC_FLUSH}, if
416 * the return value is {@code len}, the space available in output
417 * buffer {@code b}, this method should be invoked again with the same
418 * {@code flush} parameter and more output space.
419 *
420 * @param b the buffer for the compressed data
421 * @param off the start offset of the data
422 * @param len the maximum number of bytes of compressed data
423 * @param flush the compression flush mode
424 * @return the actual number of bytes of compressed data written to
425 * the output buffer
426 *
427 * @throws IllegalArgumentException if the flush mode is invalid
428 * @since 1.7
429 */
430 public int deflate(byte[] b, int off, int len, int flush) {
431 if (b == null) {
432 throw new NullPointerException();
433 }
434 if (off < 0 || len < 0 || off > b.length - len) {
435 throw new ArrayIndexOutOfBoundsException();
436 }
437 synchronized (zsRef) {
438 ensureOpen();
439 if (flush == NO_FLUSH || flush == SYNC_FLUSH ||
440 flush == FULL_FLUSH) {
441 int thisLen = this.len;
442 int n = deflateBytes(zsRef.address(), b, off, len, flush);
443 bytesWritten += n;
444 bytesRead += (thisLen - this.len);
445 return n;
446 }
447 throw new IllegalArgumentException();
448 }
449 }
450
451 /**
452 * Returns the ADLER-32 value of the uncompressed data.
453 * @return the ADLER-32 value of the uncompressed data
454 */
455 public int getAdler() {
456 synchronized (zsRef) {
457 ensureOpen();
458 return getAdler(zsRef.address());
459 }
460 }
461
462 /**
463 * Returns the total number of uncompressed bytes input so far.
464 *
465 * <p>Since the number of bytes may be greater than
466 * Integer.MAX_VALUE, the {@link #getBytesRead()} method is now
467 * the preferred means of obtaining this information.</p>
468 *
469 * @return the total number of uncompressed bytes input so far
470 */
471 public int getTotalIn() {
472 return (int) getBytesRead();
473 }
474
475 /**
476 * Returns the total number of uncompressed bytes input so far.
477 *
478 * @return the total (non-negative) number of uncompressed bytes input so far
479 * @since 1.5
480 */
481 public long getBytesRead() {
482 synchronized (zsRef) {
483 ensureOpen();
484 return bytesRead;
485 }
486 }
487
488 /**
489 * Returns the total number of compressed bytes output so far.
490 *
491 * <p>Since the number of bytes may be greater than
492 * Integer.MAX_VALUE, the {@link #getBytesWritten()} method is now
493 * the preferred means of obtaining this information.</p>
494 *
495 * @return the total number of compressed bytes output so far
496 */
497 public int getTotalOut() {
498 return (int) getBytesWritten();
499 }
500
501 /**
502 * Returns the total number of compressed bytes output so far.
503 *
504 * @return the total (non-negative) number of compressed bytes output so far
505 * @since 1.5
506 */
507 public long getBytesWritten() {
508 synchronized (zsRef) {
509 ensureOpen();
510 return bytesWritten;
511 }
512 }
513
514 /**
515 * Resets deflater so that a new set of input data can be processed.
516 * Keeps current compression level and strategy settings.
517 */
518 public void reset() {
519 synchronized (zsRef) {
520 ensureOpen();
521 reset(zsRef.address());
522 finish = false;
523 finished = false;
524 off = len = 0;
525 bytesRead = bytesWritten = 0;
526 }
527 }
528
529 /**
530 * Closes the compressor and discards any unprocessed input.
531 * This method should be called when the compressor is no longer
532 * being used, but will also be called automatically by the
533 * finalize() method. Once this method is called, the behavior
534 * of the Deflater object is undefined.
535 */
536 public void end() {
537 synchronized (zsRef) {
538 long addr = zsRef.address();
539 zsRef.clear();
540 if (addr != 0) {
541 end(addr);
542 buf = null;
543 }
544 }
545 }
546
547 /**
548 * Closes the compressor when garbage is collected.
549 */
550 protected void finalize() {
551 end();
552 }
553
554 private void ensureOpen() {
555 assert Thread.holdsLock(zsRef);
556 if (zsRef.address() == 0)
557 throw new NullPointerException("Deflater has been closed");
558 }
559
560 private static native void initIDs();
561 private native static long init(int level, int strategy, boolean nowrap);
562 private native static void setDictionary(long addr, byte[] b, int off, int len);
563 private native int deflateBytes(long addr, byte[] b, int off, int len,
564 int flush);
565 private native static int getAdler(long addr);
566 private native static void reset(long addr);
567 private native static void end(long addr);
568 }