1 files changed, 133 insertions, 4 deletions

diff --git a/libjava/classpath/javax/imageio/IIOImage.java b/libjava/classpath/javax/imageio/IIOImage.java
index 651c9baaa21..0d987476239 100644
--- a/libjava/classpath/javax/imageio/IIOImage.java
+++ b/libjava/classpath/javax/imageio/IIOImage.java
@@ -45,13 +45,53 @@ import java.util.List;
 
 import javax.imageio.metadata.IIOMetadata;
 
+/**
+ * IIOImage is a container class for components of an image file that
+ * stores image data, image metadata and thumbnails.
+ *
+ * The image data can be either a RenderedImage or a Raster but not
+ * both.  Image readers that produce IIOImages will always produce
+ * BufferedImages from the RenderedImage field.  Image writers that
+ * accept IIOImages will always accept RenderedImages and may
+ * optionally accept Rasters.
+ *
+ * @author Thomas Fitzsimmons (fitzsim@redhat.com)
+ */
 public class IIOImage
 {
+  /**
+   * Image data as a RenderedImage.  null if this IIOImage uses the
+   * Raster representation.
+   */
   protected RenderedImage image;
+
+  /**
+   * Image metadata.
+   */
   protected IIOMetadata metadata;
+
+  /**
+   * Image data as a Raster.  null if this IIOImage uses the
+   * RenderedImage representation.
+   */
   protected Raster raster;
+
+  /**
+   * A list of BufferedImage thumbnails of this image.
+   */
+  // for 1.5 these lists are List<? extends BufferedImage>
   protected List thumbnails;
-  
+
+  /**
+   * Construct an IIOImage containing raster image data, thumbnails
+   * and metadata.
+   *
+   * @param raster image data
+   * @param thumbnails a list of BufferedImage thumbnails or null
+   * @param metadata image metadata or null
+   *
+   * @exception IllegalArgumentException if raster is null
+   */
   public IIOImage (Raster raster, List thumbnails, IIOMetadata metadata)
   {
     if (raster == null)
@@ -62,6 +102,16 @@ public class IIOImage
     this.metadata = metadata;
   }
   
+  /**
+   * Construct an IIOImage containing rendered image data, thumbnails
+   * and metadata.
+   *
+   * @param image rendered image data
+   * @param thumbnails a list of BufferedImage thumbnails or null
+   * @param metadata image metadata or null
+   *
+   * @exception IllegalArgumentException if image is null
+   */
   public IIOImage (RenderedImage image, List thumbnails, IIOMetadata metadata)
   {
     if (image == null)
@@ -72,46 +122,111 @@ public class IIOImage
     this.metadata = metadata;
   }
 
+  /**
+   * Retrieve the image metadata or null if there is no metadata
+   * associated with this IIOImage.
+   *
+   * @return image metadata or null
+   */
   public IIOMetadata getMetadata()
   {
     return metadata;
   }
 
+  /**
+   * Retrieve the number of thumbnails in this IIOImage.
+   *
+   * @return the number of thumbnails
+   */
   public int getNumThumbnails()
   {
-    return thumbnails.size();
+    return thumbnails == null ? 0 : thumbnails.size();
   }
 
+  /**
+   * Retrieve the raster image data stored in this IIOImage or null if
+   * this image stores data using the RenderedImage representation.
+   *
+   * @return the raster image data or null
+   */
   public Raster getRaster()
   {
     return raster;
   }
 
+  /**
+   * Retrieve the rendered image data stored in this IIOImage or null
+   * if this image stores data using the Raster representation.
+   *
+   * @return the rendered image data or null
+   */
   public RenderedImage getRenderedImage()
   {
     return image;
   }
 
+  /**
+   * Retrieve the thumbnail stored at the specified index in the
+   * thumbnails list.
+   *
+   * @param index the index of the thumbnail to retrieve
+   *
+   * @return the buffered image thumbnail
+   *
+   * @exception IndexOutOfBoundsException if index is out-of-bounds
+   * @exception ClassCastException if the object returned from the
+   * thumbnails list is not a BufferedImage
+   */
   public BufferedImage getThumbnail (int index)
   {
+    // This throws a ClassCastException if the returned object is not
+    // a BufferedImage or an IndexOutOfBoundsException if index is
+    // out-of-bounds.
     return (BufferedImage) thumbnails.get (index);
   }
 
+  /**
+   * Retrieve the list of thumbnails or null if there are no
+   * thumbnails associated with this IIOImage.  The returned reference
+   * can be used to update the thumbnails list.
+   *
+   * @return a list of thumbnails or null
+   */
   public List getThumbnails()
   {
     return thumbnails;
   }
 
+  /**
+   * Check whether this IIOImage stores its image data as a Raster or
+   * as a RenderedImage.
+   *
+   * @return true if this IIOImage uses the Raster representation,
+   * false if it uses the RenderedImage representation.
+   */
   public boolean hasRaster()
   {
     return raster != null;
   }
 
+  /**
+   * Set this IIOImage's metadata.
+   *
+   * @param metadata the image metadata
+   */
   public void setMetadata (IIOMetadata metadata)
   {
     this.metadata = metadata;
   }
 
+  /**
+   * Set the raster data for this image.  This disposes of any
+   * existing rendered image data stored in this IIOImage.
+   *
+   * @param raster the image raster data
+   *
+   * @exception IllegalArgumentException if raster is null
+   */
   public void setRaster (Raster raster)
   {
     if (raster == null)
@@ -121,6 +236,14 @@ public class IIOImage
     this.raster = raster;
   }
 
+  /**
+   * Set the rendered image data for this image.  This disposes of any
+   * existing raster data stored in this IIOImage.
+   *
+   * @param image the rendered image data
+   *
+   * @exception IllegalArgumentException if image is null
+   */
   public void setRenderedImage (RenderedImage image)
   {
     if (image == null)
@@ -130,9 +253,15 @@ public class IIOImage
     this.raster = null;
   }
 
+  /**
+   * Set the list of thumbnails for this IIOImage to a new list of
+   * BufferedImages or to null.  Any existing thumbnails list is
+   * disposed.
+   *
+   * @param thumbnails a new list of thumbnails or null
+   */
   public void setThumbnails (List thumbnails)
   {
     this.thumbnails = thumbnails;
   }
-  
-} // class IIOParam
+}