6206189: Graphics2D.clip specifies incorrectly that a 'null' is a valid value for this method

Reviewed-by: aivanov, kizune, azvegint

Author: prsadhuk

src/java.desktop/share/classes/java/awt/Graphics.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1995, 2018, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 2021, 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
@@ -354,7 +354,8 @@ public FontMetrics getFontMetrics() {
      * {@code Rectangle} objects.  This method sets the
      * user clip, which is independent of the clipping associated
      * with device bounds and window visibility.
-     * @param clip the {@code Shape} to use to set the clip
+     * @param clip the {@code Shape} to use to set the clip.
+     *             Passing {@code null} clears the current {@code clip}.
      * @see         java.awt.Graphics#getClip()
      * @see         java.awt.Graphics#clipRect
      * @see         java.awt.Graphics#setClip(int, int, int, int)

src/java.desktop/share/classes/java/awt/Graphics2D.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, 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
@@ -1195,15 +1195,20 @@ public abstract boolean hit(Rectangle rect,
      * {@code Clip}.  This method is used to make the current
      * {@code Clip} smaller.
      * To make the {@code Clip} larger, use {@code setClip}.
-     * The <i>user clip</i> modified by this method is independent of the
+     * <p>The <i>user clip</i> modified by this method is independent of the
      * clipping associated with device bounds and visibility.  If no clip has
      * previously been set, or if the clip has been cleared using
      * {@link Graphics#setClip(Shape) setClip} with a {@code null}
      * argument, the specified {@code Shape} becomes the new
      * user clip.
+     * <p>Since this method intersects the specified shape
+     * with the current clip, it will throw {@code NullPointerException}
+     * for a {@code null} shape unless the user clip is also {@code null}.
+     * So calling this method with a {@code null} argument is not recommended.
      * @param s the {@code Shape} to be intersected with the current
-     *          {@code Clip}.  If {@code s} is {@code null},
-     *          this method clears the current {@code Clip}.
+     *          {@code Clip}. This method updates the current {@code Clip}.
+     * @throws NullPointerException if {@code s} is {@code null}
+     *         and a user clip is currently set.
      */
      public abstract void clip(Shape s);
 

test/jdk/java/awt/Graphics2D/TestNullClip.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright (c) 2021, 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 java.awt.Graphics2D;
+import java.awt.image.BufferedImage;
+import java.awt.Shape;
+
+/**
+ * @test
+ * @bug 6206189
+ * @summary Verifies passing null to Graphics2D.clip(Shape) throws NPE.
+ */
+public class TestNullClip {
+
+    public static void main(String[] argv) {
+        BufferedImage bi = new BufferedImage(100, 100, BufferedImage.TYPE_INT_ARGB);
+        Graphics2D g2d = (Graphics2D)bi.getGraphics();
+
+        g2d.clip(null); // silently return, no NPE should be thrown
+
+        g2d.setClip(0, 0, 100, 100);
+        g2d.setClip(null);
+        Shape clip1 = g2d.getClip();
+        if (clip1 != null) {
+            throw new RuntimeException("Clip is not cleared");
+        }
+        g2d.setClip(0, 0, 100, 100);
+        try {
+            g2d.clip(null);
+            throw new RuntimeException("NPE is expected");
+        } catch (NullPointerException e) {
+            //expected
+            System.out.println("NPE is thrown");
+        }
+    }
+}