View Javadoc
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 }