From d8af58941b5dedb9774c0971895c4924e57ac28b Mon Sep 17 00:00:00 2001 From: Jaikiran Pai Date: Fri, 7 Jun 2024 00:35:51 +0000 Subject: [PATCH] 8026127: Deflater/Inflater documentation incomplete/misleading Reviewed-by: lancea --- .../share/classes/java/util/zip/Deflater.java | 31 +----- .../share/classes/java/util/zip/Inflater.java | 30 +----- .../java/util/zip/snippet-files/Snippets.java | 96 +++++++++++++++++++ 3 files changed, 98 insertions(+), 59 deletions(-) create mode 100644 src/java.base/share/classes/java/util/zip/snippet-files/Snippets.java diff --git a/src/java.base/share/classes/java/util/zip/Deflater.java b/src/java.base/share/classes/java/util/zip/Deflater.java index 033e504677b..56d0978dbc0 100644 --- a/src/java.base/share/classes/java/util/zip/Deflater.java +++ b/src/java.base/share/classes/java/util/zip/Deflater.java @@ -57,36 +57,7 @@ import static java.util.zip.ZipUtils.NIO_ACCESS; * 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
- * }
- *
+ * {@snippet id="compdecomp" lang="java" class="Snippets" region="DeflaterInflaterExample"} * * @apiNote * To release resources used by this {@code Deflater}, the {@link #end()} method diff --git a/src/java.base/share/classes/java/util/zip/Inflater.java b/src/java.base/share/classes/java/util/zip/Inflater.java index 4b106fd39ec..22ab21d88c0 100644 --- a/src/java.base/share/classes/java/util/zip/Inflater.java +++ b/src/java.base/share/classes/java/util/zip/Inflater.java @@ -56,35 +56,7 @@ import static java.util.zip.ZipUtils.NIO_ACCESS; * 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\u20AC\u20AC";
- *     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);
- *
- *     // 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
- * }
- *
+ * {@snippet id="compdecomp" lang="java" class="Snippets" region="DeflaterInflaterExample"} * * @apiNote * To release resources used by this {@code Inflater}, the {@link #end()} method diff --git a/src/java.base/share/classes/java/util/zip/snippet-files/Snippets.java b/src/java.base/share/classes/java/util/zip/snippet-files/Snippets.java new file mode 100644 index 00000000000..b59f99a539c --- /dev/null +++ b/src/java.base/share/classes/java/util/zip/snippet-files/Snippets.java @@ -0,0 +1,96 @@ +/* + * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ +package java.util.zip; + +import java.io.ByteArrayOutputStream; +import java.nio.charset.StandardCharsets; + +class Snippets { + + void deflaterInflaterExample() { + // @start region="DeflaterInflaterExample" + + // Encode a String into bytes + String inputString = "blahblahblah\u20AC\u20AC"; + byte[] input = inputString.getBytes(StandardCharsets.UTF_8); + + // Compress the bytes + ByteArrayOutputStream compressedBaos = new ByteArrayOutputStream(); + Deflater compressor = new Deflater(); + try { + compressor.setInput(input); + // Let the compressor know that the complete input + // has been made available + compressor.finish(); + // Keep compressing the input till the compressor + // is finished compressing + while (!compressor.finished()) { + // Use some reasonable size for the temporary buffer + // based on the data being compressed + byte[] tmpBuffer = new byte[100]; + int numCompressed = compressor.deflate(tmpBuffer); + // Copy over the compressed bytes from the temporary + // buffer into the final byte array + compressedBaos.write(tmpBuffer, 0, numCompressed); + } + } finally { + // Release the resources held by the compressor + compressor.end(); + } + + // Decompress the bytes + Inflater decompressor = new Inflater(); + ByteArrayOutputStream decompressedBaos = new ByteArrayOutputStream(); + try { + byte[] compressed = compressedBaos.toByteArray(); + decompressor.setInput(compressed, 0, compressed.length); + while (!decompressor.finished()) { + // Use some reasonable size for the temporary buffer, + // based on the data being decompressed; in this example, + // we use a small buffer size + byte[] tmpBuffer = new byte[100]; + int numDecompressed = 0; + try { + numDecompressed = decompressor.inflate(tmpBuffer); + } catch (DataFormatException dfe) { + // Handle the exception suitably, in this example + // we just rethrow it + throw new RuntimeException(dfe); + } + // Copy over the decompressed bytes from the temporary + // buffer into the final byte array + decompressedBaos.write(tmpBuffer, 0, numDecompressed); + } + } finally { + // Release the resources held by the decompressor + decompressor.end(); + } + // Decode the bytes into a String + String outputString = decompressedBaos.toString(StandardCharsets.UTF_8); + + // @end + } + +} \ No newline at end of file