35 * A simple container class to aggregate an image, a set of |
35 * A simple container class to aggregate an image, a set of |
36 * thumbnail (preview) images, and an object representing metadata |
36 * thumbnail (preview) images, and an object representing metadata |
37 * associated with the image. |
37 * associated with the image. |
38 * |
38 * |
39 * <p> The image data may take the form of either a |
39 * <p> The image data may take the form of either a |
40 * <code>RenderedImage</code>, or a <code>Raster</code>. Reader |
40 * {@code RenderedImage}, or a {@code Raster}. Reader |
41 * methods that return an <code>IIOImage</code> will always return a |
41 * methods that return an {@code IIOImage} will always return a |
42 * <code>BufferedImage</code> using the <code>RenderedImage</code> |
42 * {@code BufferedImage} using the {@code RenderedImage} |
43 * reference. Writer methods that accept an <code>IIOImage</code> |
43 * reference. Writer methods that accept an {@code IIOImage} |
44 * will always accept a <code>RenderedImage</code>, and may optionally |
44 * will always accept a {@code RenderedImage}, and may optionally |
45 * accept a <code>Raster</code>. |
45 * accept a {@code Raster}. |
46 * |
46 * |
47 * <p> Exactly one of <code>getRenderedImage</code> and |
47 * <p> Exactly one of {@code getRenderedImage} and |
48 * <code>getRaster</code> will return a non-<code>null</code> value. |
48 * {@code getRaster} will return a non-{@code null} value. |
49 * Subclasses are responsible for ensuring this behavior. |
49 * Subclasses are responsible for ensuring this behavior. |
50 * |
50 * |
51 * @see ImageReader#readAll(int, ImageReadParam) |
51 * @see ImageReader#readAll(int, ImageReadParam) |
52 * @see ImageReader#readAll(java.util.Iterator) |
52 * @see ImageReader#readAll(java.util.Iterator) |
53 * @see ImageWriter#write(javax.imageio.metadata.IIOMetadata, |
53 * @see ImageWriter#write(javax.imageio.metadata.IIOMetadata, |
58 * |
58 * |
59 */ |
59 */ |
60 public class IIOImage { |
60 public class IIOImage { |
61 |
61 |
62 /** |
62 /** |
63 * The <code>RenderedImage</code> being referenced. |
63 * The {@code RenderedImage} being referenced. |
64 */ |
64 */ |
65 protected RenderedImage image; |
65 protected RenderedImage image; |
66 |
66 |
67 /** |
67 /** |
68 * The <code>Raster</code> being referenced. |
68 * The {@code Raster} being referenced. |
69 */ |
69 */ |
70 protected Raster raster; |
70 protected Raster raster; |
71 |
71 |
72 /** |
72 /** |
73 * A <code>List</code> of <code>BufferedImage</code> thumbnails, |
73 * A {@code List} of {@code BufferedImage} thumbnails, |
74 * or <code>null</code>. Non-<code>BufferedImage</code> objects |
74 * or {@code null}. Non-{@code BufferedImage} objects |
75 * must not be stored in this <code>List</code>. |
75 * must not be stored in this {@code List}. |
76 */ |
76 */ |
77 protected List<? extends BufferedImage> thumbnails = null; |
77 protected List<? extends BufferedImage> thumbnails = null; |
78 |
78 |
79 /** |
79 /** |
80 * An <code>IIOMetadata</code> object containing metadata |
80 * An {@code IIOMetadata} object containing metadata |
81 * associated with the image. |
81 * associated with the image. |
82 */ |
82 */ |
83 protected IIOMetadata metadata; |
83 protected IIOMetadata metadata; |
84 |
84 |
85 /** |
85 /** |
86 * Constructs an <code>IIOImage</code> containing a |
86 * Constructs an {@code IIOImage} containing a |
87 * <code>RenderedImage</code>, and thumbnails and metadata |
87 * {@code RenderedImage}, and thumbnails and metadata |
88 * associated with it. |
88 * associated with it. |
89 * |
89 * |
90 * <p> All parameters are stored by reference. |
90 * <p> All parameters are stored by reference. |
91 * |
91 * |
92 * <p> The <code>thumbnails</code> argument must either be |
92 * <p> The {@code thumbnails} argument must either be |
93 * <code>null</code> or contain only <code>BufferedImage</code> |
93 * {@code null} or contain only {@code BufferedImage} |
94 * objects. |
94 * objects. |
95 * |
95 * |
96 * @param image a <code>RenderedImage</code>. |
96 * @param image a {@code RenderedImage}. |
97 * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s, |
97 * @param thumbnails a {@code List} of {@code BufferedImage}s, |
98 * or <code>null</code>. |
98 * or {@code null}. |
99 * @param metadata an <code>IIOMetadata</code> object, or |
99 * @param metadata an {@code IIOMetadata} object, or |
100 * <code>null</code>. |
100 * {@code null}. |
101 * |
101 * |
102 * @exception IllegalArgumentException if <code>image</code> is |
102 * @exception IllegalArgumentException if {@code image} is |
103 * <code>null</code>. |
103 * {@code null}. |
104 */ |
104 */ |
105 public IIOImage(RenderedImage image, |
105 public IIOImage(RenderedImage image, |
106 List<? extends BufferedImage> thumbnails, |
106 List<? extends BufferedImage> thumbnails, |
107 IIOMetadata metadata) { |
107 IIOMetadata metadata) { |
108 if (image == null) { |
108 if (image == null) { |
113 this.thumbnails = thumbnails; |
113 this.thumbnails = thumbnails; |
114 this.metadata = metadata; |
114 this.metadata = metadata; |
115 } |
115 } |
116 |
116 |
117 /** |
117 /** |
118 * Constructs an <code>IIOImage</code> containing a |
118 * Constructs an {@code IIOImage} containing a |
119 * <code>Raster</code>, and thumbnails and metadata |
119 * {@code Raster}, and thumbnails and metadata |
120 * associated with it. |
120 * associated with it. |
121 * |
121 * |
122 * <p> All parameters are stored by reference. |
122 * <p> All parameters are stored by reference. |
123 * |
123 * |
124 * @param raster a <code>Raster</code>. |
124 * @param raster a {@code Raster}. |
125 * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s, |
125 * @param thumbnails a {@code List} of {@code BufferedImage}s, |
126 * or <code>null</code>. |
126 * or {@code null}. |
127 * @param metadata an <code>IIOMetadata</code> object, or |
127 * @param metadata an {@code IIOMetadata} object, or |
128 * <code>null</code>. |
128 * {@code null}. |
129 * |
129 * |
130 * @exception IllegalArgumentException if <code>raster</code> is |
130 * @exception IllegalArgumentException if {@code raster} is |
131 * <code>null</code>. |
131 * {@code null}. |
132 */ |
132 */ |
133 public IIOImage(Raster raster, |
133 public IIOImage(Raster raster, |
134 List<? extends BufferedImage> thumbnails, |
134 List<? extends BufferedImage> thumbnails, |
135 IIOMetadata metadata) { |
135 IIOMetadata metadata) { |
136 if (raster == null) { |
136 if (raster == null) { |
141 this.thumbnails = thumbnails; |
141 this.thumbnails = thumbnails; |
142 this.metadata = metadata; |
142 this.metadata = metadata; |
143 } |
143 } |
144 |
144 |
145 /** |
145 /** |
146 * Returns the currently set <code>RenderedImage</code>, or |
146 * Returns the currently set {@code RenderedImage}, or |
147 * <code>null</code> if only a <code>Raster</code> is available. |
147 * {@code null} if only a {@code Raster} is available. |
148 * |
148 * |
149 * @return a <code>RenderedImage</code>, or <code>null</code>. |
149 * @return a {@code RenderedImage}, or {@code null}. |
150 * |
150 * |
151 * @see #setRenderedImage |
151 * @see #setRenderedImage |
152 */ |
152 */ |
153 public RenderedImage getRenderedImage() { |
153 public RenderedImage getRenderedImage() { |
154 synchronized(this) { |
154 synchronized(this) { |
155 return image; |
155 return image; |
156 } |
156 } |
157 } |
157 } |
158 |
158 |
159 /** |
159 /** |
160 * Sets the current <code>RenderedImage</code>. The value is |
160 * Sets the current {@code RenderedImage}. The value is |
161 * stored by reference. Any existing <code>Raster</code> is |
161 * stored by reference. Any existing {@code Raster} is |
162 * discarded. |
162 * discarded. |
163 * |
163 * |
164 * @param image a <code>RenderedImage</code>. |
164 * @param image a {@code RenderedImage}. |
165 * |
165 * |
166 * @exception IllegalArgumentException if <code>image</code> is |
166 * @exception IllegalArgumentException if {@code image} is |
167 * <code>null</code>. |
167 * {@code null}. |
168 * |
168 * |
169 * @see #getRenderedImage |
169 * @see #getRenderedImage |
170 */ |
170 */ |
171 public void setRenderedImage(RenderedImage image) { |
171 public void setRenderedImage(RenderedImage image) { |
172 synchronized(this) { |
172 synchronized(this) { |
177 this.raster = null; |
177 this.raster = null; |
178 } |
178 } |
179 } |
179 } |
180 |
180 |
181 /** |
181 /** |
182 * Returns <code>true</code> if this <code>IIOImage</code> stores |
182 * Returns {@code true} if this {@code IIOImage} stores |
183 * a <code>Raster</code> rather than a <code>RenderedImage</code>. |
183 * a {@code Raster} rather than a {@code RenderedImage}. |
184 * |
184 * |
185 * @return <code>true</code> if a <code>Raster</code> is |
185 * @return {@code true} if a {@code Raster} is |
186 * available. |
186 * available. |
187 */ |
187 */ |
188 public boolean hasRaster() { |
188 public boolean hasRaster() { |
189 synchronized(this) { |
189 synchronized(this) { |
190 return (raster != null); |
190 return (raster != null); |
191 } |
191 } |
192 } |
192 } |
193 |
193 |
194 /** |
194 /** |
195 * Returns the currently set <code>Raster</code>, or |
195 * Returns the currently set {@code Raster}, or |
196 * <code>null</code> if only a <code>RenderedImage</code> is |
196 * {@code null} if only a {@code RenderedImage} is |
197 * available. |
197 * available. |
198 * |
198 * |
199 * @return a <code>Raster</code>, or <code>null</code>. |
199 * @return a {@code Raster}, or {@code null}. |
200 * |
200 * |
201 * @see #setRaster |
201 * @see #setRaster |
202 */ |
202 */ |
203 public Raster getRaster() { |
203 public Raster getRaster() { |
204 synchronized(this) { |
204 synchronized(this) { |
205 return raster; |
205 return raster; |
206 } |
206 } |
207 } |
207 } |
208 |
208 |
209 /** |
209 /** |
210 * Sets the current <code>Raster</code>. The value is |
210 * Sets the current {@code Raster}. The value is |
211 * stored by reference. Any existing <code>RenderedImage</code> is |
211 * stored by reference. Any existing {@code RenderedImage} is |
212 * discarded. |
212 * discarded. |
213 * |
213 * |
214 * @param raster a <code>Raster</code>. |
214 * @param raster a {@code Raster}. |
215 * |
215 * |
216 * @exception IllegalArgumentException if <code>raster</code> is |
216 * @exception IllegalArgumentException if {@code raster} is |
217 * <code>null</code>. |
217 * {@code null}. |
218 * |
218 * |
219 * @see #getRaster |
219 * @see #getRaster |
220 */ |
220 */ |
221 public void setRaster(Raster raster) { |
221 public void setRaster(Raster raster) { |
222 synchronized(this) { |
222 synchronized(this) { |
228 } |
228 } |
229 } |
229 } |
230 |
230 |
231 /** |
231 /** |
232 * Returns the number of thumbnails stored in this |
232 * Returns the number of thumbnails stored in this |
233 * <code>IIOImage</code>. |
233 * {@code IIOImage}. |
234 * |
234 * |
235 * @return the number of thumbnails, as an <code>int</code>. |
235 * @return the number of thumbnails, as an {@code int}. |
236 */ |
236 */ |
237 public int getNumThumbnails() { |
237 public int getNumThumbnails() { |
238 return thumbnails == null ? 0 : thumbnails.size(); |
238 return thumbnails == null ? 0 : thumbnails.size(); |
239 } |
239 } |
240 |
240 |
241 /** |
241 /** |
242 * Returns a thumbnail associated with the main image. |
242 * Returns a thumbnail associated with the main image. |
243 * |
243 * |
244 * @param index the index of the desired thumbnail image. |
244 * @param index the index of the desired thumbnail image. |
245 * |
245 * |
246 * @return a thumbnail image, as a <code>BufferedImage</code>. |
246 * @return a thumbnail image, as a {@code BufferedImage}. |
247 * |
247 * |
248 * @exception IndexOutOfBoundsException if the supplied index is |
248 * @exception IndexOutOfBoundsException if the supplied index is |
249 * negative or larger than the largest valid index. |
249 * negative or larger than the largest valid index. |
250 * @exception ClassCastException if a |
250 * @exception ClassCastException if a |
251 * non-<code>BufferedImage</code> object is encountered in the |
251 * non-{@code BufferedImage} object is encountered in the |
252 * list of thumbnails at the given index. |
252 * list of thumbnails at the given index. |
253 * |
253 * |
254 * @see #getThumbnails |
254 * @see #getThumbnails |
255 * @see #setThumbnails |
255 * @see #setThumbnails |
256 */ |
256 */ |
260 } |
260 } |
261 return (BufferedImage)thumbnails.get(index); |
261 return (BufferedImage)thumbnails.get(index); |
262 } |
262 } |
263 |
263 |
264 /** |
264 /** |
265 * Returns the current <code>List</code> of thumbnail |
265 * Returns the current {@code List} of thumbnail |
266 * <code>BufferedImage</code>s, or <code>null</code> if none is |
266 * {@code BufferedImage}s, or {@code null} if none is |
267 * set. A live reference is returned. |
267 * set. A live reference is returned. |
268 * |
268 * |
269 * @return the current <code>List</code> of |
269 * @return the current {@code List} of |
270 * <code>BufferedImage</code> thumbnails, or <code>null</code>. |
270 * {@code BufferedImage} thumbnails, or {@code null}. |
271 * |
271 * |
272 * @see #getThumbnail(int) |
272 * @see #getThumbnail(int) |
273 * @see #setThumbnails |
273 * @see #setThumbnails |
274 */ |
274 */ |
275 public List<? extends BufferedImage> getThumbnails() { |
275 public List<? extends BufferedImage> getThumbnails() { |
276 return thumbnails; |
276 return thumbnails; |
277 } |
277 } |
278 |
278 |
279 /** |
279 /** |
280 * Sets the list of thumbnails to a new <code>List</code> of |
280 * Sets the list of thumbnails to a new {@code List} of |
281 * <code>BufferedImage</code>s, or to <code>null</code>. The |
281 * {@code BufferedImage}s, or to {@code null}. The |
282 * reference to the previous <code>List</code> is discarded. |
282 * reference to the previous {@code List} is discarded. |
283 * |
283 * |
284 * <p> The <code>thumbnails</code> argument must either be |
284 * <p> The {@code thumbnails} argument must either be |
285 * <code>null</code> or contain only <code>BufferedImage</code> |
285 * {@code null} or contain only {@code BufferedImage} |
286 * objects. |
286 * objects. |
287 * |
287 * |
288 * @param thumbnails a <code>List</code> of |
288 * @param thumbnails a {@code List} of |
289 * <code>BufferedImage</code> thumbnails, or <code>null</code>. |
289 * {@code BufferedImage} thumbnails, or {@code null}. |
290 * |
290 * |
291 * @see #getThumbnail(int) |
291 * @see #getThumbnail(int) |
292 * @see #getThumbnails |
292 * @see #getThumbnails |
293 */ |
293 */ |
294 public void setThumbnails(List<? extends BufferedImage> thumbnails) { |
294 public void setThumbnails(List<? extends BufferedImage> thumbnails) { |
295 this.thumbnails = thumbnails; |
295 this.thumbnails = thumbnails; |
296 } |
296 } |
297 |
297 |
298 /** |
298 /** |
299 * Returns a reference to the current <code>IIOMetadata</code> |
299 * Returns a reference to the current {@code IIOMetadata} |
300 * object, or <code>null</code> is none is set. |
300 * object, or {@code null} is none is set. |
301 * |
301 * |
302 * @return an <code>IIOMetadata</code> object, or <code>null</code>. |
302 * @return an {@code IIOMetadata} object, or {@code null}. |
303 * |
303 * |
304 * @see #setMetadata |
304 * @see #setMetadata |
305 */ |
305 */ |
306 public IIOMetadata getMetadata() { |
306 public IIOMetadata getMetadata() { |
307 return metadata; |
307 return metadata; |
308 } |
308 } |
309 |
309 |
310 /** |
310 /** |
311 * Sets the <code>IIOMetadata</code> to a new object, or |
311 * Sets the {@code IIOMetadata} to a new object, or |
312 * <code>null</code>. |
312 * {@code null}. |
313 * |
313 * |
314 * @param metadata an <code>IIOMetadata</code> object, or |
314 * @param metadata an {@code IIOMetadata} object, or |
315 * <code>null</code>. |
315 * {@code null}. |
316 * |
316 * |
317 * @see #getMetadata |
317 * @see #getMetadata |
318 */ |
318 */ |
319 public void setMetadata(IIOMetadata metadata) { |
319 public void setMetadata(IIOMetadata metadata) { |
320 this.metadata = metadata; |
320 this.metadata = metadata; |