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() 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 image parameter. Document how invalid image data is handled.

Specification

javax.swing.ImageIcon

Add the following statement to the class javadoc

+ * 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 the image will be unsetl,
+ * as it will have no dimensions and never be drawn, and
+ * {@code getImageLoadStatus()} will report {@see java.awt.MediaTracker#ERRORED}.

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 {@code NullPointerException} if (@code null) URL is passed.
      * @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 {@code NullPointerException} if (@code null) URL is passed.
      * @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 {@code NullPointerException} if (@code null) Image is passed.
      */
     public ImageIcon(Image image, String description);

     * then the string is used as the description of this icon.
      * @param image the image
  +  * @throws {@code NullPointerException} if (@code null) Image is passed.
      * @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 {@code NullPointerException} if (@code null) imageData is passed.
      * @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 {@code NullPointerException} if (@code null) imageData is passed.
      * @see    java.awt.Toolkit#createImage
      * @see #getDescription
    public ImageIcon (byte[] imageData);

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