8325304: Several classes in java.util.jar and java.util.zip don't specify the behaviour for null arguments

Reviewed-by: lancea, alanb

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 class JarEntry extends ZipEntry {
      * 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 class JarEntry extends ZipEntry {
      * 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);

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 @@ import sun.security.util.ManifestEntryVerifier;
  * <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
@@ -242,7 +246,6 @@ public class JarInputStream extends ZipInputStream {
      * @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}

src/java.base/share/classes/java/util/jar/JarOutputStream.java

@@ -35,7 +35,9 @@ import java.io.*;
  * 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

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 @@ import sun.security.util.SecurityProperties;
  * 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
@@ -82,7 +85,8 @@ public class Manifest implements Cloneable {
      * 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 {
@@ -93,7 +97,7 @@ public class Manifest implements Cloneable {
      * 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

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 @@ import static java.util.zip.ZipUtils.NIO_ACCESS;
  * 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

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 class DeflaterInputStream extends FilterInputStream {
      * @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

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

@@ -34,6 +34,9 @@ import java.io.IOException;
  * 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

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 @@ public class GZIPInputStream extends InflaterInputStream {
      *
      * @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 class GZIPInputStream extends InflaterInputStream {
      *
      * @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 {

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 @@ import java.io.IOException;
 /**
  * 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
  *

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 @@ import static java.util.zip.ZipUtils.NIO_ACCESS;
  * 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

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 @@ import java.util.Objects;
  * 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 class InflaterInputStream extends FilterInputStream {
         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 class InflaterInputStream extends FilterInputStream {
      * @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}

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 class ZipEntry implements ZipConstants, Cloneable {
      *
      * @param  time
      *         The last modification time of the entry in local date-time
-     *
+     * @throws NullPointerException if {@code time} is null
      * @see #getTimeLocal()
      * @since 9
      */

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 @@ import static java.util.zip.ZipUtils.*;
  * 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 class ZipInputStream extends InflaterInputStream implements ZipConstants
      * 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 class ZipInputStream extends InflaterInputStream implements ZipConstants
      * 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 class ZipInputStream extends InflaterInputStream implements ZipConstants
      * @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}

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 @@ import sun.security.action.GetBooleanAction;
  * 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
  */