Summary

The specification of javax.swing.ImageIcon is updated to describe the behavior on receiving null image parameters and invalid image data

Problem

The javax.swing.ImageIcon constructors and the setImage method do not say what happens if null or invalid image parameters are passed.

Solution

Document the existing behaviour of ImageIcon constructors and ImageIcon.setImage when receiving a null parameter. Document how invalid image data is handled.

Specification

javax.swing.ImageIcon

Add the following statement to the class javadoc

  * <p>
+ * If the image source parameter to a constructor or method is non-null,
+ * but does not reference valid accessible image data,
+ * no exceptions will be thrown but no image will be rendered
+ * even though {@link #getImage()} will return a non-null value,
+ * as the image will have no dimensions
+ * and {@link #getImageLoadStatus()} will report {@code MediaTracker.ERRORED}.
+ *
+ * <p>

Update constructor and method documentation as follows

     /**
      * Creates an ImageIcon from the specified URL. The image will
      * be preloaded by using MediaTracker to monitor the loaded state
      * of the image.
      * @param location the URL for the image
      * @param description a brief textual description of the image
+     * @throws NullPointerException if {@code location} is {@code null}
      * @see #ImageIcon(String)
      */
     public ImageIcon(URL location, String description);

     /**
      * Creates an ImageIcon from the specified URL. The image will
      * be preloaded by using MediaTracker to monitor the loaded state
      * of the image.
      * The icon's description is initialized to be
      * a string representation of the URL.
      * @param location the URL for the image
+     * @throws NullPointerException if {@code location} is {@code null}
      * @see #getDescription
      */
     public ImageIcon(URL location);

     /**
      * Creates an ImageIcon from the image.
      * @param image the image
      * @param description a brief textual description of the image
+     * @throws NullPointerException if {@code image} is {@code null}
      */
     public ImageIcon(Image image, String description);

      * If the image has a "comment" property that is a string,
      * then the string is used as the description of this icon.
      * @param image the image
+     * @throws NullPointerException if {@code image} is {@code null}
      * @see #getDescription
      * @see java.awt.Image#getProperty
      */
     public ImageIcon (Image image);

      * the byte array may also be statically stored in a class.
      *
      * @param  imageData an array of pixels in an image format supported
      *         by the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG
      * @param  description a brief textual description of the image
+     * @throws NullPointerException if {@code imageData} is {@code null}
      * @see    java.awt.Toolkit#createImage
      */
     public ImageIcon (byte[] imageData, String description);

      * then the string is used as the description of this icon.
      *
      * @param  imageData an array of pixels in an image format supported by
      *             the AWT Toolkit, such as GIF, JPEG, or (as of 1.3) PNG
+     * @throws NullPointerException if {@code imageData} is {@code null}
      * @see    java.awt.Toolkit#createImage
      * @see #getDescription
      * @see java.awt.Image#getProperty
      */
     public ImageIcon (byte[] imageData);

     /**
      * Sets the image displayed by this icon.
      * @param image the image
+     * @throws NullPointerException if {@code image} is {@code null}
      */
     public void setImage(Image image);