8380542: ZipOutputStream.setComment and ZipEntry.setComment spec updates for rejecting unmappable characters and allowing null or empty comments

Reviewed-by: alanb, lancea, jpai

Author: Eirik Bjørsnøs

src/java.base/share/classes/java/util/zip/ZipEntry.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2025, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2026, 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
@@ -651,8 +651,9 @@ public byte[] getExtra() {
     }
 
     /**
-     * Sets the optional comment string for the entry.
-     * @param comment the comment string
+     * Sets the optional comment string for the entry. If {@code comment} is an
+     * empty string or {@code null} then the entry will have no comment.
+     * @param comment the comment string, or an empty string or null for no comment
      * @throws IllegalArgumentException if the combined length
      * of the specified entry comment, the {@linkplain #getName() entry name},
      * the {@linkplain #getExtra() extra field data}, and the

src/java.base/share/classes/java/util/zip/ZipOutputStream.java

@@ -43,6 +43,10 @@
  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
  * or method in this class will cause a {@link NullPointerException} to be
  * thrown.
+ * <p> By default, the UTF-8 charset is used to encode entry names and comments.
+ * {@link #ZipOutputStream(OutputStream, Charset)} may be be used to specify
+ * an alternative charset.
+ *
  * @author      David Connelly
  * @since 1.1
  */
@@ -110,10 +114,8 @@ private void ensureOpen() throws IOException {
     public static final int DEFLATED = ZipEntry.DEFLATED;
 
     /**
-     * Creates a new ZIP output stream.
-     *
-     * <p>The UTF-8 {@link java.nio.charset.Charset charset} is used
-     * to encode the entry names and comments.
+     * Creates a new ZIP output stream using the UTF-8
+     * {@link Charset charset} to encode entry names and comments.
      *
      * @param out the actual output stream
      */
@@ -122,12 +124,13 @@ public ZipOutputStream(OutputStream out) {
     }
 
     /**
-     * Creates a new ZIP output stream.
+     * Creates a new ZIP output stream using the specified
+     * {@link Charset charset} to encode entry names and comments.
      *
      * @param out the actual output stream
      *
      * @param charset the {@linkplain java.nio.charset.Charset charset}
-     *                to be used to encode the entry names and comments
+     *                to be used to encode entry names and comments
      *
      * @since 1.7
      */
@@ -140,10 +143,15 @@ public ZipOutputStream(OutputStream out, Charset charset) {
     }
 
     /**
-     * Sets the ZIP file comment.
-     * @param     comment the comment string
-     * @throws    IllegalArgumentException if the length of the specified
-     *            ZIP file comment is greater than 0xFFFF bytes
+     * Sets the ZIP file comment. If {@code comment} is an empty string or
+     * {@code null} then the output will have no ZIP file comment.
+     *
+     * @param     comment the comment string, or an empty string or null for no comment
+     *
+     * @throws    IllegalArgumentException if the length of the specified ZIP file
+     *            comment is greater than 0xFFFF bytes or if the {@code comment}
+     *            contains characters that cannot be mapped by the {@code Charset}
+     *            used to encode entry names and comments
      */
     public void setComment(String comment) {
         byte[] bytes = null;

test/jdk/java/util/zip/ZipOutputStream/UnmappableZipFileComment.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2026, 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.
+ *
+ * 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.
+ */
+
+import org.junit.jupiter.api.Test;
+
+import java.io.IOException;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.util.zip.ZipOutputStream;
+
+import static java.io.OutputStream.nullOutputStream;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+
+/* @test
+ * @bug 8380542
+ * @summary ZipOutputStream.setComment should throw IllegalArgumentException for unmappable characters in comment
+ * @run junit ${test.main.class}
+ */
+public class UnmappableZipFileComment {
+    /**
+     * Verify that calling ZipOutputStream.setComment with an unmappable
+     * comment is rejected with a IllegalArgumentException.
+     *
+     * @throws IOException if an unexpected IO error occurs
+     */
+    @Test
+    void rejectUnmappableZipFileComment() throws IOException {
+        // Charset used when creating the ZIP file
+         Charset charset = StandardCharsets.US_ASCII;
+        // 'ø' is an unmappable character in US_ASCII
+        String comment = "\u00f8";
+        try (var out = new ZipOutputStream(nullOutputStream(), charset)) {
+            assertThrows(IllegalArgumentException.class, () -> out.setComment(comment));
+        }
+    }
+}