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 }
323