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 }