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}, or a {@code Raster}.  Reader
  41  * methods that return an {@code IIOImage} will always return a
  42  * {@code BufferedImage} using the {@code RenderedImage}
  43  * reference.  Writer methods that accept an {@code IIOImage}
  44  * will always accept a {@code RenderedImage}, and may optionally
  45  * accept a {@code Raster}.
  46  *
  47  * <p> Exactly one of {@code getRenderedImage} and
  48  * {@code getRaster} will return a non-{@code null} 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} being referenced.
  64      */
  65     protected RenderedImage image;
  66 
  67     /**
  68      * The {@code Raster} being referenced.
  69      */
  70     protected Raster raster;
  71 
  72     /**
  73      * A {@code List} of {@code BufferedImage} thumbnails,
  74      * or {@code null}.  Non-{@code BufferedImage} objects
  75      * must not be stored in this {@code List}.
  76      */
  77     protected List<? extends BufferedImage> thumbnails = null;
  78 
  79     /**
  80      * An {@code IIOMetadata} object containing metadata
  81      * associated with the image.
  82      */
  83     protected IIOMetadata metadata;
  84 
  85     /**
  86      * Constructs an {@code IIOImage} containing a
  87      * {@code RenderedImage}, and thumbnails and metadata
  88      * associated with it.
  89      *
  90      * <p> All parameters are stored by reference.
  91      *
  92      * <p> The {@code thumbnails} argument must either be
  93      * {@code null} or contain only {@code BufferedImage}
  94      * objects.
  95      *
  96      * @param image a {@code RenderedImage}.
  97      * @param thumbnails a {@code List} of {@code BufferedImage}s,
  98      * or {@code null}.
  99      * @param metadata an {@code IIOMetadata} object, or
 100      * {@code null}.
 101      *
 102      * @exception IllegalArgumentException if {@code image} is
 103      * {@code null}.
 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} containing a
 119      * {@code Raster}, and thumbnails and metadata
 120      * associated with it.
 121      *
 122      * <p> All parameters are stored by reference.
 123      *
 124      * @param raster a {@code Raster}.
 125      * @param thumbnails a {@code List} of {@code BufferedImage}s,
 126      * or {@code null}.
 127      * @param metadata an {@code IIOMetadata} object, or
 128      * {@code null}.
 129      *
 130      * @exception IllegalArgumentException if {@code raster} is
 131      * {@code null}.
 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}, or
 147      * {@code null} if only a {@code Raster} is available.
 148      *
 149      * @return a {@code RenderedImage}, or {@code null}.
 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}.  The value is
 161      * stored by reference.  Any existing {@code Raster} is
 162      * discarded.
 163      *
 164      * @param image a {@code RenderedImage}.
 165      *
 166      * @exception IllegalArgumentException if {@code image} is
 167      * {@code null}.
 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} if this {@code IIOImage} stores
 183      * a {@code Raster} rather than a {@code RenderedImage}.
 184      *
 185      * @return {@code true} if a {@code Raster} 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}, or
 196      * {@code null} if only a {@code RenderedImage} is
 197      * available.
 198      *
 199      * @return a {@code Raster}, or {@code null}.
 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}.  The value is
 211      * stored by reference.  Any existing {@code RenderedImage} is
 212      * discarded.
 213      *
 214      * @param raster a {@code Raster}.
 215      *
 216      * @exception IllegalArgumentException if {@code raster} is
 217      * {@code null}.
 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}.
 234      *
 235      * @return the number of thumbnails, as an {@code int}.
 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}.
 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} 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} of thumbnail
 266      * {@code BufferedImage}s, or {@code null} if none is
 267      * set.  A live reference is returned.
 268      *
 269      * @return the current {@code List} of
 270      * {@code BufferedImage} thumbnails, or {@code null}.
 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} of
 281      * {@code BufferedImage}s, or to {@code null}.  The
 282      * reference to the previous {@code List} is discarded.
 283      *
 284      * <p> The {@code thumbnails} argument must either be
 285      * {@code null} or contain only {@code BufferedImage}
 286      * objects.
 287      *
 288      * @param thumbnails a {@code List} of
 289      * {@code BufferedImage} thumbnails, or {@code null}.
 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}
 300      * object, or {@code null} is none is set.
 301      *
 302      * @return an {@code IIOMetadata} object, or {@code null}.
 303      *
 304      * @see #setMetadata
 305      */
 306     public IIOMetadata getMetadata() {
 307         return metadata;
 308     }
 309 
 310     /**
 311      * Sets the {@code IIOMetadata} to a new object, or
 312      * {@code null}.
 313      *
 314      * @param metadata an {@code IIOMetadata} object, or
 315      * {@code null}.
 316      *
 317      * @see #getMetadata
 318      */
 319     public void setMetadata(IIOMetadata metadata) {
 320         this.metadata = metadata;
 321     }
 322 }
--- EOF ---