Details
-
CSR
-
Resolution: Approved
-
P4
-
None
-
behavioral
-
minimal
-
No behavior change - specification only so minimal risk
-
Java API
-
SE
Description
Summary
Specify that java.awt.Graphics2D.clip(Shape) will throw NullPointerException when passed a null object reference for the parameter when a user clip is currently set.
Problem
Method clip(Shape) of the java.awt.Graphics2D class throws NullPointerException when passed a null object reference for the parameter when a user clip is currently set, but it is not specified in the specification.
Solution
Update the specification to document that NullPointerException will be thrown for null "Shape" object passed to clip() when a user clip is currently set.
Specification
src/java.desktop/share/classes/java/awt/Graphics.java
* supported are {@code Shape} objects that are
* obtained via the {@code getClip} method and via
* {@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)
* @since 1.1
*/
public abstract void setClip(Shape clip);
src/java.desktop/share/classes/java/awt/Graphics2D.java
* transformed with the current {@code Graphics2D}
* {@code Transform} before being intersected with the current
* {@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);
Attachments
Issue Links
- csr of
-
JDK-6206189 Graphics2D.clip specifies incorrectly that a 'null' is a valid value for this method
-
- Resolved
-