Summary

The javadoc of various classes in java.util.jar and java.util.zip packages will be updated to specify the behaviour of the constructors and methods of such classes, when null argument is passed.

Problem

Various classes in the java.util.jar and java.util.zip packages currently throw a java.lang.NullPointerException when a null argument is passed to the constructor of such classes and also when null argument is passed to several of their methods. However, this behaviour isn't currently specified - neither at the package level doc, nor at each class level doc nor several of the individual constructors or methods.

Solution

The class level javadoc of several of these classes will be updated to note that unless otherwise noted, passing a null argument to a constructor or method in such class will cause a NullPointerException to be thrown. Wherever relevant, if the number of methods or constructors for a class are relatively few in number, then the NullPointerException being thrown will be specified in such constructor or method's javadoc.

Specification

diff --git a/src/java.base/share/classes/java/util/jar/JarEntry.java b/src/java.base/share/classes/java/util/jar/JarEntry.java
index dd5aae96fab..5e1d687e6c6 100644
--- a/src/java.base/share/classes/java/util/jar/JarEntry.java
+++ b/src/java.base/share/classes/java/util/jar/JarEntry.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -58,6 +58,7 @@ public JarEntry(String name) {
      * specified {@code ZipEntry} object.
      * @param ze the {@code ZipEntry} object to create the
      *           {@code JarEntry} from
+     * @throws    NullPointerException if {@code ze} is null
      */
     public JarEntry(ZipEntry ze) {
         super(ze);
@@ -68,6 +69,7 @@ public JarEntry(ZipEntry ze) {
      * specified {@code JarEntry} object.
      *
      * @param je the {@code JarEntry} to copy
+     * @throws    NullPointerException if {@code je} is null
      */
     public JarEntry(JarEntry je) {
         this((ZipEntry)je);
diff --git a/src/java.base/share/classes/java/util/jar/JarInputStream.java b/src/java.base/share/classes/java/util/jar/JarInputStream.java
index 453470eb990..14436ecba15 100644
--- a/src/java.base/share/classes/java/util/jar/JarInputStream.java
+++ b/src/java.base/share/classes/java/util/jar/JarInputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -36,7 +36,11 @@
  * <a href="{@docRoot}/../specs/jar/jar.html#jar-manifest">Manifest</a>
  * entry. The {@code Manifest} can be used to store
  * meta-information about the JAR file and its entries.
- *
+ * <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>
  * <h2>Accessing the Manifest</h2>
  * <p>
  * The {@link #getManifest() getManifest} method is used to return the
@@ -241,7 +245,6 @@ public JarEntry getNextJarEntry() throws IOException {
      * @param len the maximum number of bytes to read
      * @return the actual number of bytes read, or -1 if the end of the
      *         entry is reached
-     * @throws     NullPointerException If {@code b} is {@code null}.
      * @throws     IndexOutOfBoundsException If {@code off} is negative,
      * {@code len} is negative, or {@code len} is greater than
      * {@code b.length - off}
diff --git a/src/java.base/share/classes/java/util/jar/JarOutputStream.java b/src/java.base/share/classes/java/util/jar/JarOutputStream.java
index 57cd3dd4bbf..f4430a67e7b 100644
--- a/src/java.base/share/classes/java/util/jar/JarOutputStream.java
+++ b/src/java.base/share/classes/java/util/jar/JarOutputStream.java
@@ -35,7 +35,9 @@
  * for writing an optional {@code Manifest} entry. The
  * {@code Manifest} can be used to specify meta-information about
  * the JAR file and its entries.
- *
+ * <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.
  * @author  David Connelly
  * @see     Manifest
  * @see     java.util.zip.ZipOutputStream
diff --git a/src/java.base/share/classes/java/util/jar/Manifest.java b/src/java.base/share/classes/java/util/jar/Manifest.java
index ddc76eed9d1..4853b52d57e 100644
--- a/src/java.base/share/classes/java/util/jar/Manifest.java
+++ b/src/java.base/share/classes/java/util/jar/Manifest.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 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
@@ -43,6 +43,9 @@
  * see the
  * <a href="{@docRoot}/../specs/jar/jar.html">
  * Manifest format specification</a>.
+ * <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.
  *
  * @spec jar/jar.html JAR File Specification
  * @author  David Connelly
@@ -81,7 +84,8 @@ public Manifest(InputStream is) throws IOException {
      * Constructs a new Manifest from the specified input stream.
      *
      * @param is the input stream containing manifest data
-     * @param jarFilename the name of the corresponding jar archive if available
+     * @param jarFilename the name of the corresponding jar archive
+     *                    if available, else null
      * @throws IOException if an I/O error has occurred
      */
     Manifest(InputStream is, String jarFilename) throws IOException {
@@ -92,7 +96,7 @@ public Manifest(InputStream is) throws IOException {
      * Constructs a new Manifest from the specified input stream
      * and associates it with a JarVerifier.
      *
-     * @param jv the JarVerifier to use
+     * @param jv the JarVerifier to use if any, else null
      * @param is the input stream containing manifest data
      * @param jarFilename the name of the corresponding jar archive if available
      * @throws IOException if an I/O error has occurred
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 5b57112bf8a..8c037dfda56 100644
--- a/src/java.base/share/classes/java/util/zip/Deflater.java
+++ b/src/java.base/share/classes/java/util/zip/Deflater.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -44,6 +44,10 @@
  * the <a href="package-summary.html#package-description">java.util.zip
  * package description</a>.
  * <p>
+ * Unless otherwise noted, passing a {@code null} argument to a method
+ * in this class will cause a {@link NullPointerException} to be
+ * thrown.
+ * <p>
  * This class deflates sequences of bytes into ZLIB compressed data format.
  * The input byte sequence is provided in either byte array or byte buffer,
  * via one of the {@code setInput()} methods. The output byte sequence is
diff --git a/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java b/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java
index 84d2c888543..d361af888eb 100644
--- a/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java
+++ b/src/java.base/share/classes/java/util/zip/DeflaterInputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2006, 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
@@ -164,6 +164,7 @@ public int read() throws IOException {
      * @param len maximum number of compressed bytes to read into {@code b}
      * @return the actual number of bytes read, or -1 if the end of the
      * uncompressed input stream is reached
+     * @throws NullPointerException if {@code b} is null
      * @throws IndexOutOfBoundsException  if {@code len > b.length - off}
      * @throws IOException if an I/O error occurs or if this input stream is
      * already closed
diff --git a/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java b/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java
index 9053c199182..66630d5adf0 100644
--- a/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java
+++ b/src/java.base/share/classes/java/util/zip/DeflaterOutputStream.java
@@ -34,6 +34,9 @@
  * This class implements an output stream filter for compressing data in
  * the "deflate" compression format. It is also used as the basis for other
  * types of compression filters, such as GZIPOutputStream.
+ * <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.
  *
  * @see         Deflater
  * @author      David Connelly
diff --git a/src/java.base/share/classes/java/util/zip/GZIPInputStream.java b/src/java.base/share/classes/java/util/zip/GZIPInputStream.java
index d704fd3c925..5163c5a3b6e 100644
--- a/src/java.base/share/classes/java/util/zip/GZIPInputStream.java
+++ b/src/java.base/share/classes/java/util/zip/GZIPInputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -70,6 +70,7 @@ private void ensureOpen() throws IOException {
      *
      * @throws    ZipException if a GZIP format error has occurred or the
      *                         compression method used is unsupported
+     * @throws    NullPointerException if {@code in} is null
      * @throws    IOException if an I/O error has occurred
      * @throws    IllegalArgumentException if {@code size <= 0}
      */
@@ -85,6 +86,7 @@ public GZIPInputStream(InputStream in, int size) throws IOException {
      *
      * @throws    ZipException if a GZIP format error has occurred or the
      *                         compression method used is unsupported
+     * @throws    NullPointerException if {@code in} is null
      * @throws    IOException if an I/O error has occurred
      */
     public GZIPInputStream(InputStream in) throws IOException {
diff --git a/src/java.base/share/classes/java/util/zip/GZIPOutputStream.java b/src/java.base/share/classes/java/util/zip/GZIPOutputStream.java
index cdfac329cfa..d3880c2f4d7 100644
--- a/src/java.base/share/classes/java/util/zip/GZIPOutputStream.java
+++ b/src/java.base/share/classes/java/util/zip/GZIPOutputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -31,6 +31,10 @@
 /**
  * This class implements a stream filter for writing compressed data in
  * the GZIP file format.
+ * <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.
+ *
  * @author      David Connelly
  * @since 1.1
  *
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 1b915253161..4784170eddb 100644
--- a/src/java.base/share/classes/java/util/zip/Inflater.java
+++ b/src/java.base/share/classes/java/util/zip/Inflater.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -44,6 +44,10 @@
  * the <a href="package-summary.html#package-description">java.util.zip
  * package description</a>.
  * <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>
  * This class inflates sequences of ZLIB compressed bytes. The input byte
  * sequence is provided in either byte array or byte buffer, via one of the
  * {@code setInput()} methods. The output byte sequence is written to the
diff --git a/src/java.base/share/classes/java/util/zip/InflaterInputStream.java b/src/java.base/share/classes/java/util/zip/InflaterInputStream.java
index d60b0447066..08429aab8aa 100644
--- a/src/java.base/share/classes/java/util/zip/InflaterInputStream.java
+++ b/src/java.base/share/classes/java/util/zip/InflaterInputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -35,7 +35,9 @@
  * This class implements a stream filter for uncompressing data in the
  * "deflate" compression format. It is also used as the basis for other
  * decompression filters, such as GZIPInputStream.
- *
+ * <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.
  * @see         Inflater
  * @author      David Connelly
  * @since 1.1
@@ -110,7 +112,7 @@ public InflaterInputStream(InputStream in) {
         usesDefaultInflater = true;
     }

-    private byte[] singleByteBuf = new byte[1];
+    private final byte[] singleByteBuf = new byte[1];

     /**
      * Reads a byte of uncompressed data. This method will block until
@@ -143,7 +145,6 @@ public int read() throws IOException {
      * @param len the maximum number of bytes read
      * @return the actual number of bytes inflated, or -1 if the end of the
      *         compressed input is reached or a preset dictionary is needed
-     * @throws     NullPointerException If {@code b} is {@code null}.
      * @throws     IndexOutOfBoundsException If {@code off} is negative,
      * {@code len} is negative, or {@code len} is greater than
      * {@code b.length - off}
diff --git a/src/java.base/share/classes/java/util/zip/ZipEntry.java b/src/java.base/share/classes/java/util/zip/ZipEntry.java
index b3eb47bce37..7a09836fa83 100644
--- a/src/java.base/share/classes/java/util/zip/ZipEntry.java
+++ b/src/java.base/share/classes/java/util/zip/ZipEntry.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 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
@@ -222,7 +222,7 @@ public long getTime() {
      *
      * @param  time
      *         The last modification time of the entry in local date-time
-     *
+     * @throws NullPointerException if {@code time} is null
      * @see #getTimeLocal()
      * @since 9
      */
diff --git a/src/java.base/share/classes/java/util/zip/ZipInputStream.java b/src/java.base/share/classes/java/util/zip/ZipInputStream.java
index e583bc28934..216a914f023 100644
--- a/src/java.base/share/classes/java/util/zip/ZipInputStream.java
+++ b/src/java.base/share/classes/java/util/zip/ZipInputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -42,7 +42,9 @@
  * An input stream for reading compressed and uncompressed
  * {@linkplain ZipEntry ZIP file entries} from a stream of bytes in the ZIP file
  * format.
- *
+ * <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.
  * <H2>Reading Zip File Entries</H2>
  *
  * The {@link #getNextEntry()} method is used to read the next ZIP file entry
@@ -304,7 +306,6 @@ public byte[] readNBytes(int len) throws IOException {
      * may be in an inconsistent state. It is strongly recommended that the
      * stream be promptly closed if an I/O error occurs.
      *
-     * @throws NullPointerException {@inheritDoc}
      * @throws IndexOutOfBoundsException {@inheritDoc}
      *
      * @since 9
@@ -359,8 +360,6 @@ public void skipNBytes(long n) throws IOException {
      * one, or both, streams may be in an inconsistent state. It is strongly
      * recommended that both streams be promptly closed if an I/O error occurs.
      *
-     * @throws NullPointerException {@inheritDoc}
-     *
      * @since 9
      */
     @Override
@@ -390,7 +389,6 @@ public long transferTo(OutputStream out) throws IOException {
      * @param len the maximum number of bytes read
      * @return the actual number of bytes read, or -1 if the end of the
      *         entry is reached
-     * @throws     NullPointerException if {@code b} is {@code null}.
      * @throws     IndexOutOfBoundsException if {@code off} is negative,
      * {@code len} is negative, or {@code len} is greater than
      * {@code b.length - off}
diff --git a/src/java.base/share/classes/java/util/zip/ZipOutputStream.java b/src/java.base/share/classes/java/util/zip/ZipOutputStream.java
index 84174ea3380..d87a18c8c44 100644
--- a/src/java.base/share/classes/java/util/zip/ZipOutputStream.java
+++ b/src/java.base/share/classes/java/util/zip/ZipOutputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 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
@@ -40,7 +40,9 @@
  * This class implements an output stream filter for writing files in the
  * ZIP file format. Includes support for both compressed and uncompressed
  * entries.
- *
+ * <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.
  * @author      David Connelly
  * @since 1.1
  */