KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > imageio > IIOImage


1 /*
2  * @(#)IIOImage.java 1.21 04/05/05
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package javax.imageio;
9
10 import java.awt.image.BufferedImage JavaDoc;
11 import java.awt.image.Raster JavaDoc;
12 import java.awt.image.RenderedImage JavaDoc;
13 import java.util.List JavaDoc;
14 import javax.imageio.metadata.IIOMetadata JavaDoc;
15
16 /**
17  * A simple container class to aggregate an image, a set of
18  * thumbnail (preview) images, and an object representing metadata
19  * associated with the image.
20  *
21  * <p> The image data may take the form of either a
22  * <code>RenderedImage</code>, or a <code>Raster</code>. Reader
23  * methods that return an <code>IIOImage</code> will always return a
24  * <code>BufferedImage</code> using the <code>RenderedImage</code>
25  * reference. Writer methods that accept an <code>IIOImage</code>
26  * will always accept a <code>RenderedImage</code>, and may optionally
27  * accept a <code>Raster</code>.
28  *
29  * <p> Exactly one of <code>getRenderedImage</code> and
30  * <code>getRaster</code> will return a non-<code>null</code> value.
31  * Subclasses are responsible for ensuring this behavior.
32  *
33  * @see ImageReader#readAll(int, ImageReadParam)
34  * @see ImageReader#readAll(java.util.Iterator)
35  * @see ImageWriter#write(javax.imageio.metadata.IIOMetadata,
36  * IIOImage, ImageWriteParam)
37  * @see ImageWriter#write(IIOImage)
38  * @see ImageWriter#writeToSequence(IIOImage, ImageWriteParam)
39  * @see ImageWriter#writeInsert(int, IIOImage, ImageWriteParam)
40  *
41  * @version 0.5
42  */

43 public class IIOImage {
44
45     /**
46      * The <code>RenderedImage</code> being referenced.
47      */

48     protected RenderedImage JavaDoc image;
49
50     /**
51      * The <code>Raster</code> being referenced.
52      */

53     protected Raster JavaDoc raster;
54
55     /**
56      * A <code>List</code> of <code>BufferedImage</code> thumbnails,
57      * or <code>null</code>. Non-<code>BufferedImage</code> objects
58      * must not be stored in this <code>List</code>.
59      */

60     protected List JavaDoc<? extends BufferedImage JavaDoc> thumbnails = null;
61
62     /**
63      * An <code>IIOMetadata</code> object containing metadata
64      * associated with the image.
65      */

66     protected IIOMetadata JavaDoc metadata;
67
68     /**
69      * Constructs an <code>IIOImage</code> containing a
70      * <code>RenderedImage</code>, and thumbnails and metadata
71      * associated with it.
72      *
73      * <p> All parameters are stored by reference.
74      *
75      * <p> The <code>thumbnails</code> argument must either be
76      * <code>null</code> or contain only <code>BufferedImage</code>
77      * objects.
78      *
79      * @param image a <code>RenderedImage</code>.
80      * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s,
81      * or <code>null</code>.
82      * @param metadata an <code>IIOMetadata</code> object, or
83      * <code>null</code>.
84      *
85      * @exception IllegalArgumentException if <code>image</code> is
86      * <code>null</code>.
87      */

88     public IIOImage(RenderedImage JavaDoc image,
89                     List JavaDoc<? extends BufferedImage JavaDoc> thumbnails,
90                     IIOMetadata JavaDoc metadata) {
91         if (image == null) {
92             throw new IllegalArgumentException JavaDoc("image == null!");
93         }
94         this.image = image;
95         this.raster = null;
96         this.thumbnails = thumbnails;
97         this.metadata = metadata;
98     }
99
100     /**
101      * Constructs an <code>IIOImage</code> containing a
102      * <code>Raster</code>, and thumbnails and metadata
103      * associated with it.
104      *
105      * <p> All parameters are stored by reference.
106      *
107      * @param raster a <code>Raster</code>.
108      * @param thumbnails a <code>List</code> of <code>BufferedImage</code>s,
109      * or <code>null</code>.
110      * @param metadata an <code>IIOMetadata</code> object, or
111      * <code>null</code>.
112      *
113      * @exception IllegalArgumentException if <code>raster</code> is
114      * <code>null</code>.
115      */

116     public IIOImage(Raster JavaDoc raster,
117                     List JavaDoc<? extends BufferedImage JavaDoc> thumbnails,
118                     IIOMetadata JavaDoc metadata) {
119         if (raster == null) {
120             throw new IllegalArgumentException JavaDoc("raster == null!");
121         }
122         this.raster = raster;
123         this.image = null;
124         this.thumbnails = thumbnails;
125         this.metadata = metadata;
126     }
127
128     /**
129      * Returns the currently set <code>RenderedImage</code>, or
130      * <code>null</code> if only a <code>Raster</code> is available.
131      *
132      * @return a <code>RenderedImage</code>, or <code>null</code>.
133      *
134      * @see #setRenderedImage
135      */

136     public RenderedImage JavaDoc getRenderedImage() {
137         synchronized(this) {
138             return image;
139         }
140     }
141
142     /**
143      * Sets the current <code>RenderedImage</code>. The value is
144      * stored by reference. Any existing <code>Raster</code> is
145      * discarded.
146      *
147      * @param image a <code>RenderedImage</code>.
148      *
149      * @exception IllegalArgumentException if <code>image</code> is
150      * <code>null</code>.
151      *
152      * @see #getRenderedImage
153      */

154     public void setRenderedImage(RenderedImage JavaDoc image) {
155         synchronized(this) {
156             if (image == null) {
157                 throw new IllegalArgumentException JavaDoc("image == null!");
158             }
159             this.image = image;
160             this.raster = null;
161         }
162     }
163
164     /**
165      * Returns <code>true</code> if this <code>IIOImage</code> stores
166      * a <code>Raster</code> rather than a <code>RenderedImage</code>.
167      *
168      * @return <code>true</code> if a <code>Raster</code> is
169      * available.
170      */

171     public boolean hasRaster() {
172         synchronized(this) {
173             return (raster != null);
174         }
175     }
176
177     /**
178      * Returns the currently set <code>Raster</code>, or
179      * <code>null</code> if only a <code>RenderedImage</code> is
180      * available.
181      *
182      * @return a <code>Raster</code>, or <code>null</code>.
183      *
184      * @see #setRaster
185      */

186     public Raster JavaDoc getRaster() {
187         synchronized(this) {
188             return raster;
189         }
190     }
191
192     /**
193      * Sets the current <code>Raster</code>. The value is
194      * stored by reference. Any existing <code>RenderedImage</code> is
195      * discarded.
196      *
197      * @param raster a <code>Raster</code>.
198      *
199      * @exception IllegalArgumentException if <code>raster</code> is
200      * <code>null</code>.
201      *
202      * @see #getRaster
203      */

204     public void setRaster(Raster JavaDoc raster) {
205         synchronized(this) {
206             if (raster == null) {
207                 throw new IllegalArgumentException JavaDoc("raster == null!");
208             }
209             this.raster = raster;
210             this.image = null;
211         }
212     }
213
214     /**
215      * Returns the number of thumbnails stored in this
216      * <code>IIOImage</code>.
217      *
218      * @return the number of thumbnails, as an <code>int</code>.
219      */

220     public int getNumThumbnails() {
221         return thumbnails == null ? 0 : thumbnails.size();
222     }
223
224     /**
225      * Returns a thumbnail associated with the main image.
226      *
227      * @param index the index of the desired thumbnail image.
228      *
229      * @return a thumbnail image, as a <code>BufferedImage</code>.
230      *
231      * @exception IndexOutOfBoundsException if the supplied index is
232      * negative or larger than the largest valid index.
233      * @exception ClassCastException if a
234      * non-<code>BufferedImage</code> object is encountered in the
235      * list of thumbnails at the given index.
236      *
237      * @see #getThumbnails
238      * @see #setThumbnails
239      */

240     public BufferedImage JavaDoc getThumbnail(int index) {
241         if (thumbnails == null) {
242             throw new IndexOutOfBoundsException JavaDoc("No thumbnails available!");
243         }
244         return (BufferedImage JavaDoc)thumbnails.get(index);
245     }
246
247     /**
248      * Returns the current <code>List</code> of thumbnail
249      * <code>BufferedImage</code>s, or <code>null</code> if none is
250      * set. A live reference is returned.
251      *
252      * @return the current <code>List</code> of
253      * <code>BufferedImage</code> thumbnails, or <code>null</code>.
254      *
255      * @see #getThumbnail(int)
256      * @see #setThumbnails
257      */

258     public List JavaDoc<? extends BufferedImage JavaDoc> getThumbnails() {
259         return thumbnails;
260     }
261
262     /**
263      * Sets the list of thumbnails to a new <code>List</code> of
264      * <code>BufferedImage</code>s, or to <code>null</code>. The
265      * reference to the previous <code>List</code> is discarded.
266      *
267      * <p> The <code>thumbnails</code> argument must either be
268      * <code>null</code> or contain only <code>BufferedImage</code>
269      * objects.
270      *
271      * @param thumbnails a <code>List</code> of
272      * <code>BufferedImage</code> thumbnails, or <code>null</code>.
273      *
274      * @see #getThumbnail(int)
275      * @see #getThumbnails
276      */

277     public void setThumbnails(List JavaDoc<? extends BufferedImage JavaDoc> thumbnails) {
278         this.thumbnails = thumbnails;
279     }
280
281     /**
282      * Returns a reference to the current <code>IIOMetadata</code>
283      * object, or <code>null</code> is none is set.
284      *
285      * @return an <code>IIOMetadata</code> object, or <code>null</code>.
286      *
287      * @see #setMetadata
288      */

289     public IIOMetadata JavaDoc getMetadata() {
290         return metadata;
291     }
292
293     /**
294      * Sets the <code>IIOMetadata</code> to a new object, or
295      * <code>null</code>.
296      *
297      * @param metadata an <code>IIOMetadata</code> object, or
298      * <code>null</code>.
299      *
300      * @see #getMetadata
301      */

302     public void setMetadata(IIOMetadata JavaDoc metadata) {
303         this.metadata = metadata;
304     }
305 }
306
Popular Tags