1 /*
   2  * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.imageio;
  27 
  28 import java.awt.image.BufferedImage;
  29 import java.awt.image.Raster;
  30 import java.awt.image.RenderedImage;
  31 import java.util.List;
  32 import javax.imageio.metadata.IIOMetadata;
  33 
  34 /**
  35  * A simple container class to aggregate an image, a set of
  36  * thumbnail (preview) images, and an object representing metadata
  37  * associated with the image.
  38  *
  39  * <p> The image data may take the form of either a
  40  * <code>RenderedImage</code>, or a <code>Raster</code>.  Reader
  41  * methods that return an <code>IIOImage</code> will always return a
  42  * <code>BufferedImage</code> using the <code>RenderedImage</code>
  43  * reference.  Writer methods that accept an <code>IIOImage</code>
  44  * will always accept a <code>RenderedImage</code>, and may optionally
  45  * accept a <code>Raster</code>.
  46  *
  47  * <p> Exactly one of <code>getRenderedImage</code> and
  48  * <code>getRaster</code> will return a non-<code>null</code> value.
  49  * Subclasses are responsible for ensuring this behavior.
  50  *
  51  * @see ImageReader#readAll(int, ImageReadParam)
  52  * @see ImageReader#readAll(java.util.Iterator)
  53  * @see ImageWriter#write(javax.imageio.metadata.IIOMetadata,
  54  *                        IIOImage, ImageWriteParam)
  55  * @see ImageWriter#write(IIOImage)
  56  * @see ImageWriter#writeToSequence(IIOImage, ImageWriteParam)
  57  * @see ImageWriter#writeInsert(int, IIOImage, ImageWriteParam)
  58  *
  59  */
  60 public class IIOImage {
  61 
  62     /**
  63      * The <code>RenderedImage</code> being referenced.
  64      */
  65     protected RenderedImage image;
  66 
  67     /**
  68      * The <code>Raster</code> being referenced.
  69      */
  70     protected Raster raster;
  71 
  72     /**
  73      * A <code>List</code> of <code>BufferedImage</code> thumbnails,
  74      * or <code>null</code>.  Non-<code>BufferedImage</code> objects
  75      * must not be stored in this <code>List</code>.
  76      */
  77     protected List<? extends BufferedImage> thumbnails = null;
  78 
  79     /**
  80      * An <code>IIOMetadata</code> object containing metadata
  81      * associated with the image.
  82      */
  83     protected IIOMetadata metadata;
  84 
  85     /**
  86      * Constructs an <code>IIOImage</code> containing a
  87      * <code>RenderedImage</code>, and thumbnails and metadata
  88      * associated with it.
  89      *
  90      * <p> All parameters are stored by reference.
  91      *
  92      * <p> The <code>thumbnails</code> argument must either be
  93      * <code>null</code> or contain only <code>BufferedImage</code>
  94      * objects.
  95      *
  96      * @param image a <code>RenderedImage</code>.
  97      * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s,
  98      * or <code>null</code>.
  99      * @param metadata an <code>IIOMetadata</code> object, or
 100      * <code>null</code>.
 101      *
 102      * @exception IllegalArgumentException if <code>image</code> is
 103      * <code>null</code>.
 104      */
 105     public IIOImage(RenderedImage image,
 106                     List<? extends BufferedImage> thumbnails,
 107                     IIOMetadata metadata) {
 108         if (image == null) {
 109             throw new IllegalArgumentException("image == null!");
 110         }
 111         this.image = image;
 112         this.raster = null;
 113         this.thumbnails = thumbnails;
 114         this.metadata = metadata;
 115     }
 116 
 117     /**
 118      * Constructs an <code>IIOImage</code> containing a
 119      * <code>Raster</code>, and thumbnails and metadata
 120      * associated with it.
 121      *
 122      * <p> All parameters are stored by reference.
 123      *
 124      * @param raster a <code>Raster</code>.
 125      * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s,
 126      * or <code>null</code>.
 127      * @param metadata an <code>IIOMetadata</code> object, or
 128      * <code>null</code>.
 129      *
 130      * @exception IllegalArgumentException if <code>raster</code> is
 131      * <code>null</code>.
 132      */
 133     public IIOImage(Raster raster,
 134                     List<? extends BufferedImage> thumbnails,
 135                     IIOMetadata metadata) {
 136         if (raster == null) {
 137             throw new IllegalArgumentException("raster == null!");
 138         }
 139         this.raster = raster;
 140         this.image = null;
 141         this.thumbnails = thumbnails;
 142         this.metadata = metadata;
 143     }
 144 
 145     /**
 146      * Returns the currently set <code>RenderedImage</code>, or
 147      * <code>null</code> if only a <code>Raster</code> is available.
 148      *
 149      * @return a <code>RenderedImage</code>, or <code>null</code>.
 150      *
 151      * @see #setRenderedImage
 152      */
 153     public RenderedImage getRenderedImage() {
 154         synchronized(this) {
 155             return image;
 156         }
 157     }
 158 
 159     /**
 160      * Sets the current <code>RenderedImage</code>.  The value is
 161      * stored by reference.  Any existing <code>Raster</code> is
 162      * discarded.
 163      *
 164      * @param image a <code>RenderedImage</code>.
 165      *
 166      * @exception IllegalArgumentException if <code>image</code> is
 167      * <code>null</code>.
 168      *
 169      * @see #getRenderedImage
 170      */
 171     public void setRenderedImage(RenderedImage image) {
 172         synchronized(this) {
 173             if (image == null) {
 174                 throw new IllegalArgumentException("image == null!");
 175             }
 176             this.image = image;
 177             this.raster = null;
 178         }
 179     }
 180 
 181     /**
 182      * Returns <code>true</code> if this <code>IIOImage</code> stores
 183      * a <code>Raster</code> rather than a <code>RenderedImage</code>.
 184      *
 185      * @return <code>true</code> if a <code>Raster</code> is
 186      * available.
 187      */
 188     public boolean hasRaster() {
 189         synchronized(this) {
 190             return (raster != null);
 191         }
 192     }
 193 
 194     /**
 195      * Returns the currently set <code>Raster</code>, or
 196      * <code>null</code> if only a <code>RenderedImage</code> is
 197      * available.
 198      *
 199      * @return a <code>Raster</code>, or <code>null</code>.
 200      *
 201      * @see #setRaster
 202      */
 203     public Raster getRaster() {
 204         synchronized(this) {
 205             return raster;
 206         }
 207     }
 208 
 209     /**
 210      * Sets the current <code>Raster</code>.  The value is
 211      * stored by reference.  Any existing <code>RenderedImage</code> is
 212      * discarded.
 213      *
 214      * @param raster a <code>Raster</code>.
 215      *
 216      * @exception IllegalArgumentException if <code>raster</code> is
 217      * <code>null</code>.
 218      *
 219      * @see #getRaster
 220      */
 221     public void setRaster(Raster raster) {
 222         synchronized(this) {
 223             if (raster == null) {
 224                 throw new IllegalArgumentException("raster == null!");
 225             }
 226             this.raster = raster;
 227             this.image = null;
 228         }
 229     }
 230 
 231     /**
 232      * Returns the number of thumbnails stored in this
 233      * <code>IIOImage</code>.
 234      *
 235      * @return the number of thumbnails, as an <code>int</code>.
 236      */
 237     public int getNumThumbnails() {
 238         return thumbnails == null ? 0 : thumbnails.size();
 239     }
 240 
 241     /**
 242      * Returns a thumbnail associated with the main image.
 243      *
 244      * @param index the index of the desired thumbnail image.
 245      *
 246      * @return a thumbnail image, as a <code>BufferedImage</code>.
 247      *
 248      * @exception IndexOutOfBoundsException if the supplied index is
 249      * negative or larger than the largest valid index.
 250      * @exception ClassCastException if a
 251      * non-<code>BufferedImage</code> object is encountered in the
 252      * list of thumbnails at the given index.
 253      *
 254      * @see #getThumbnails
 255      * @see #setThumbnails
 256      */
 257     public BufferedImage getThumbnail(int index) {
 258         if (thumbnails == null) {
 259             throw new IndexOutOfBoundsException("No thumbnails available!");
 260         }
 261         return (BufferedImage)thumbnails.get(index);
 262     }
 263 
 264     /**
 265      * Returns the current <code>List</code> of thumbnail
 266      * <code>BufferedImage</code>s, or <code>null</code> if none is
 267      * set.  A live reference is returned.
 268      *
 269      * @return the current <code>List</code> of
 270      * <code>BufferedImage</code> thumbnails, or <code>null</code>.
 271      *
 272      * @see #getThumbnail(int)
 273      * @see #setThumbnails
 274      */
 275     public List<? extends BufferedImage> getThumbnails() {
 276         return thumbnails;
 277     }
 278 
 279     /**
 280      * Sets the list of thumbnails to a new <code>List</code> of
 281      * <code>BufferedImage</code>s, or to <code>null</code>.  The
 282      * reference to the previous <code>List</code> is discarded.
 283      *
 284      * <p> The <code>thumbnails</code> argument must either be
 285      * <code>null</code> or contain only <code>BufferedImage</code>
 286      * objects.
 287      *
 288      * @param thumbnails a <code>List</code> of
 289      * <code>BufferedImage</code> thumbnails, or <code>null</code>.
 290      *
 291      * @see #getThumbnail(int)
 292      * @see #getThumbnails
 293      */
 294     public void setThumbnails(List<? extends BufferedImage> thumbnails) {
 295         this.thumbnails = thumbnails;
 296     }
 297 
 298     /**
 299      * Returns a reference to the current <code>IIOMetadata</code>
 300      * object, or <code>null</code> is none is set.
 301      *
 302      * @return an <code>IIOMetadata</code> object, or <code>null</code>.
 303      *
 304      * @see #setMetadata
 305      */
 306     public IIOMetadata getMetadata() {
 307         return metadata;
 308     }
 309 
 310     /**
 311      * Sets the <code>IIOMetadata</code> to a new object, or
 312      * <code>null</code>.
 313      *
 314      * @param metadata an <code>IIOMetadata</code> object, or
 315      * <code>null</code>.
 316      *
 317      * @see #getMetadata
 318      */
 319     public void setMetadata(IIOMetadata metadata) {
 320         this.metadata = metadata;
 321     }
 322 }