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