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  ;
11  import java.awt.image.Raster  ;
12  import java.awt.image.RenderedImage  ;
13  import java.util.List  ;
14  import javax.imageio.metadata.IIOMetadata  ;
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   image;
49  
50      /**
51       * The <code>Raster</code> being referenced.
52       */
53      protected Raster   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  <? extends BufferedImage  > thumbnails = null;
61  
62      /**
63       * An <code>IIOMetadata</code> object containing metadata
64       * associated with the image.
65       */
66      protected IIOMetadata   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   image,
89                      List  <? extends BufferedImage  > thumbnails,
90                      IIOMetadata   metadata) {
91          if (image == null) {
92              throw new IllegalArgumentException  ("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   raster,
117                     List  <? extends BufferedImage  > thumbnails,
118                     IIOMetadata   metadata) {
119         if (raster == null) {
120             throw new IllegalArgumentException  ("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   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   image) {
155         synchronized(this) {
156             if (image == null) {
157                 throw new IllegalArgumentException  ("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   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   raster) {
205         synchronized(this) {
206             if (raster == null) {
207                 throw new IllegalArgumentException  ("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   getThumbnail(int index) {
241         if (thumbnails == null) {
242             throw new IndexOutOfBoundsException  ("No thumbnails available!");
243         }
244         return (BufferedImage  )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  <? extends BufferedImage  > 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  <? extends BufferedImage  > 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   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   metadata) {
303         this.metadata = metadata;
304     }
305 }
306
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags