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 }