001    /* IIOImage.java --
002       Copyright (C) 2003 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package javax.imageio;
040    
041    import java.awt.image.BufferedImage;
042    import java.awt.image.Raster;
043    import java.awt.image.RenderedImage;
044    import java.util.List;
045    
046    import javax.imageio.metadata.IIOMetadata;
047    
048    /**
049     * IIOImage is a container class for components of an image file that
050     * stores image data, image metadata and thumbnails.
051     *
052     * The image data can be either a RenderedImage or a Raster but not
053     * both.  Image readers that produce IIOImages will always produce
054     * BufferedImages from the RenderedImage field.  Image writers that
055     * accept IIOImages will always accept RenderedImages and may
056     * optionally accept Rasters.
057     *
058     * @author Thomas Fitzsimmons (fitzsim@redhat.com)
059     */
060    public class IIOImage
061    {
062      /**
063       * Image data as a RenderedImage.  null if this IIOImage uses the
064       * Raster representation.
065       */
066      protected RenderedImage image;
067    
068      /**
069       * Image metadata.
070       */
071      protected IIOMetadata metadata;
072    
073      /**
074       * Image data as a Raster.  null if this IIOImage uses the
075       * RenderedImage representation.
076       */
077      protected Raster raster;
078    
079      /**
080       * A list of BufferedImage thumbnails of this image.
081       */
082      protected List<? extends BufferedImage> thumbnails;
083    
084      /**
085       * Construct an IIOImage containing raster image data, thumbnails
086       * and metadata.
087       *
088       * @param raster image data
089       * @param thumbnails a list of BufferedImage thumbnails or null
090       * @param metadata image metadata or null
091       *
092       * @exception IllegalArgumentException if raster is null
093       */
094      public IIOImage (Raster raster, List<? extends BufferedImage> thumbnails,
095                       IIOMetadata metadata)
096      {
097        if (raster == null)
098          throw new IllegalArgumentException ("raster may not be null");
099    
100        this.raster = raster;
101        this.thumbnails = thumbnails;
102        this.metadata = metadata;
103      }
104    
105      /**
106       * Construct an IIOImage containing rendered image data, thumbnails
107       * and metadata.
108       *
109       * @param image rendered image data
110       * @param thumbnails a list of BufferedImage thumbnails or null
111       * @param metadata image metadata or null
112       *
113       * @exception IllegalArgumentException if image is null
114       */
115      public IIOImage (RenderedImage image, List<? extends BufferedImage> thumbnails,
116                       IIOMetadata metadata)
117      {
118        if (image == null)
119          throw new IllegalArgumentException ("image may not be null");
120    
121        this.image = image;
122        this.thumbnails = thumbnails;
123        this.metadata = metadata;
124      }
125    
126      /**
127       * Retrieve the image metadata or null if there is no metadata
128       * associated with this IIOImage.
129       *
130       * @return image metadata or null
131       */
132      public IIOMetadata getMetadata()
133      {
134        return metadata;
135      }
136    
137      /**
138       * Retrieve the number of thumbnails in this IIOImage.
139       *
140       * @return the number of thumbnails
141       */
142      public int getNumThumbnails()
143      {
144        return thumbnails == null ? 0 : thumbnails.size();
145      }
146    
147      /**
148       * Retrieve the raster image data stored in this IIOImage or null if
149       * this image stores data using the RenderedImage representation.
150       *
151       * @return the raster image data or null
152       */
153      public Raster getRaster()
154      {
155        return raster;
156      }
157    
158      /**
159       * Retrieve the rendered image data stored in this IIOImage or null
160       * if this image stores data using the Raster representation.
161       *
162       * @return the rendered image data or null
163       */
164      public RenderedImage getRenderedImage()
165      {
166        return image;
167      }
168    
169      /**
170       * Retrieve the thumbnail stored at the specified index in the
171       * thumbnails list.
172       *
173       * @param index the index of the thumbnail to retrieve
174       *
175       * @return the buffered image thumbnail
176       *
177       * @exception IndexOutOfBoundsException if index is out-of-bounds
178       * @exception ClassCastException if the object returned from the
179       * thumbnails list is not a BufferedImage
180       */
181      public BufferedImage getThumbnail (int index)
182      {
183        // This throws a ClassCastException if the returned object is not
184        // a BufferedImage or an IndexOutOfBoundsException if index is
185        // out-of-bounds.
186        return (BufferedImage) thumbnails.get (index);
187      }
188    
189      /**
190       * Retrieve the list of thumbnails or null if there are no
191       * thumbnails associated with this IIOImage.  The returned reference
192       * can be used to update the thumbnails list.
193       *
194       * @return a list of thumbnails or null
195       */
196      public List<? extends BufferedImage> getThumbnails()
197      {
198        return thumbnails;
199      }
200    
201      /**
202       * Check whether this IIOImage stores its image data as a Raster or
203       * as a RenderedImage.
204       *
205       * @return true if this IIOImage uses the Raster representation,
206       * false if it uses the RenderedImage representation.
207       */
208      public boolean hasRaster()
209      {
210        return raster != null;
211      }
212    
213      /**
214       * Set this IIOImage's metadata.
215       *
216       * @param metadata the image metadata
217       */
218      public void setMetadata (IIOMetadata metadata)
219      {
220        this.metadata = metadata;
221      }
222    
223      /**
224       * Set the raster data for this image.  This disposes of any
225       * existing rendered image data stored in this IIOImage.
226       *
227       * @param raster the image raster data
228       *
229       * @exception IllegalArgumentException if raster is null
230       */
231      public void setRaster (Raster raster)
232      {
233        if (raster == null)
234          throw new IllegalArgumentException ("raster may not be null");
235    
236        this.image = null;
237        this.raster = raster;
238      }
239    
240      /**
241       * Set the rendered image data for this image.  This disposes of any
242       * existing raster data stored in this IIOImage.
243       *
244       * @param image the rendered image data
245       *
246       * @exception IllegalArgumentException if image is null
247       */
248      public void setRenderedImage (RenderedImage image)
249      {
250        if (image == null)
251          throw new IllegalArgumentException ("image may not be null");
252    
253        this.image = image;
254        this.raster = null;
255      }
256    
257      /**
258       * Set the list of thumbnails for this IIOImage to a new list of
259       * BufferedImages or to null.  Any existing thumbnails list is
260       * disposed.
261       *
262       * @param thumbnails a new list of thumbnails or null
263       */
264      public void setThumbnails (List<? extends BufferedImage> thumbnails)
265      {
266        this.thumbnails = thumbnails;
267      }
268    }