001 /*
002 * Copyright 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.imageio.spi;
027
028 import java.io.IOException;
029 import javax.imageio.ImageReader;
030 import javax.imageio.stream.ImageInputStream;
031
032 /**
033 * The service provider interface (SPI) for <code>ImageReader</code>s.
034 * For more information on service provider classes, see the class comment
035 * for the <code>IIORegistry</code> class.
036 *
037 * <p> Each <code>ImageReaderSpi</code> provides several types of information
038 * about the <code>ImageReader</code> class with which it is associated.
039 *
040 * <p> The name of the vendor who defined the SPI class and a
041 * brief description of the class are available via the
042 * <code>getVendorName</code>, <code>getDescription</code>,
043 * and <code>getVersion</code> methods.
044 * These methods may be internationalized to provide locale-specific
045 * output. These methods are intended mainly to provide short,
046 * human-readable information that might be used to organize a pop-up
047 * menu or other list.
048 *
049 * <p> Lists of format names, file suffixes, and MIME types associated
050 * with the service may be obtained by means of the
051 * <code>getFormatNames</code>, <code>getFileSuffixes</code>, and
052 * <code>getMIMETypes</code> methods. These methods may be used to
053 * identify candidate <code>ImageReader</code>s for decoding a
054 * particular file or stream based on manual format selection, file
055 * naming, or MIME associations (for example, when accessing a file
056 * over HTTP or as an email attachment).
057 *
058 * <p> A more reliable way to determine which <code>ImageReader</code>s
059 * are likely to be able to parse a particular data stream is provided
060 * by the <code>canDecodeInput</code> method. This methods allows the
061 * service provider to inspect the actual stream contents.
062 *
063 * <p> Finally, an instance of the <code>ImageReader</code> class
064 * associated with this service provider may be obtained by calling
065 * the <code>createReaderInstance</code> method. Any heavyweight
066 * initialization, such as the loading of native libraries or creation
067 * of large tables, should be deferred at least until the first
068 * invocation of this method.
069 *
070 * @see IIORegistry
071 * @see javax.imageio.ImageReader
072 *
073 * @version 0.5
074 */
075 public abstract class ImageReaderSpi extends ImageReaderWriterSpi {
076
077 /**
078 * A single-element array, initially containing
079 * <code>ImageInputStream.class</code>, to be returned from
080 * <code>getInputTypes</code>.
081 */
082 public static final Class[] STANDARD_INPUT_TYPE = { ImageInputStream.class };
083
084 /**
085 * An array of <code>Class</code> objects to be returned from
086 * <code>getInputTypes</code>, initially <code>null</code>.
087 */
088 protected Class[] inputTypes = null;
089
090 /**
091 * An array of strings to be returned from
092 * <code>getImageWriterSpiNames</code>, initially
093 * <code>null</code>.
094 */
095 protected String[] writerSpiNames = null;
096
097 /**
098 * The <code>Class</code> of the reader, initially
099 * <code>null</code>.
100 */
101 private Class readerClass = null;
102
103 /**
104 * Constructs a blank <code>ImageReaderSpi</code>. It is up to
105 * the subclass to initialize instance variables and/or override
106 * method implementations in order to provide working versions of
107 * all methods.
108 */
109 protected ImageReaderSpi() {
110 }
111
112 /**
113 * Constructs an <code>ImageReaderSpi</code> with a given
114 * set of values.
115 *
116 * @param vendorName the vendor name, as a non-<code>null</code>
117 * <code>String</code>.
118 * @param version a version identifier, as a non-<code>null</code>
119 * <code>String</code>.
120 * @param names a non-<code>null</code> array of
121 * <code>String</code>s indicating the format names. At least one
122 * entry must be present.
123 * @param suffixes an array of <code>String</code>s indicating the
124 * common file suffixes. If no suffixes are defined,
125 * <code>null</code> should be supplied. An array of length 0
126 * will be normalized to <code>null</code>.
127 * @param MIMETypes an array of <code>String</code>s indicating
128 * the format's MIME types. If no MIME types are defined,
129 * <code>null</code> should be supplied. An array of length 0
130 * will be normalized to <code>null</code>.
131 * @param readerClassName the fully-qualified name of the
132 * associated <code>ImageReader</code> class, as a
133 * non-<code>null</code> <code>String</code>.
134 * @param inputTypes a non-<code>null</code> array of
135 * <code>Class</code> objects of length at least 1 indicating the
136 * legal input types.
137 * @param writerSpiNames an array <code>String</code>s naming the
138 * classes of all associated <code>ImageWriter</code>s, or
139 * <code>null</code>. An array of length 0 is normalized to
140 * <code>null</code>.
141 * @param supportsStandardStreamMetadataFormat a
142 * <code>boolean</code> that indicates whether a stream metadata
143 * object can use trees described by the standard metadata format.
144 * @param nativeStreamMetadataFormatName a
145 * <code>String</code>, or <code>null</code>, to be returned from
146 * <code>getNativeStreamMetadataFormatName</code>.
147 * @param nativeStreamMetadataFormatClassName a
148 * <code>String</code>, or <code>null</code>, to be used to instantiate
149 * a metadata format object to be returned from
150 * <code>getNativeStreamMetadataFormat</code>.
151 * @param extraStreamMetadataFormatNames an array of
152 * <code>String</code>s, or <code>null</code>, to be returned from
153 * <code>getExtraStreamMetadataFormatNames</code>. An array of length
154 * 0 is normalized to <code>null</code>.
155 * @param extraStreamMetadataFormatClassNames an array of
156 * <code>String</code>s, or <code>null</code>, to be used to instantiate
157 * a metadata format object to be returned from
158 * <code>getStreamMetadataFormat</code>. An array of length
159 * 0 is normalized to <code>null</code>.
160 * @param supportsStandardImageMetadataFormat a
161 * <code>boolean</code> that indicates whether an image metadata
162 * object can use trees described by the standard metadata format.
163 * @param nativeImageMetadataFormatName a
164 * <code>String</code>, or <code>null</code>, to be returned from
165 * <code>getNativeImageMetadataFormatName</code>.
166 * @param nativeImageMetadataFormatClassName a
167 * <code>String</code>, or <code>null</code>, to be used to instantiate
168 * a metadata format object to be returned from
169 * <code>getNativeImageMetadataFormat</code>.
170 * @param extraImageMetadataFormatNames an array of
171 * <code>String</code>s to be returned from
172 * <code>getExtraImageMetadataFormatNames</code>. An array of length 0
173 * is normalized to <code>null</code>.
174 * @param extraImageMetadataFormatClassNames an array of
175 * <code>String</code>s, or <code>null</code>, to be used to instantiate
176 * a metadata format object to be returned from
177 * <code>getImageMetadataFormat</code>. An array of length
178 * 0 is normalized to <code>null</code>.
179 *
180 * @exception IllegalArgumentException if <code>vendorName</code>
181 * is <code>null</code>.
182 * @exception IllegalArgumentException if <code>version</code>
183 * is <code>null</code>.
184 * @exception IllegalArgumentException if <code>names</code>
185 * is <code>null</code> or has length 0.
186 * @exception IllegalArgumentException if <code>readerClassName</code>
187 * is <code>null</code>.
188 * @exception IllegalArgumentException if <code>inputTypes</code>
189 * is <code>null</code> or has length 0.
190 */
191 public ImageReaderSpi(String vendorName, String version,
192 String[] names, String[] suffixes, String[] MIMETypes,
193 String readerClassName, Class[] inputTypes,
194 String[] writerSpiNames,
195 boolean supportsStandardStreamMetadataFormat,
196 String nativeStreamMetadataFormatName,
197 String nativeStreamMetadataFormatClassName,
198 String[] extraStreamMetadataFormatNames,
199 String[] extraStreamMetadataFormatClassNames,
200 boolean supportsStandardImageMetadataFormat,
201 String nativeImageMetadataFormatName,
202 String nativeImageMetadataFormatClassName,
203 String[] extraImageMetadataFormatNames,
204 String[] extraImageMetadataFormatClassNames) {
205 super (vendorName, version, names, suffixes, MIMETypes,
206 readerClassName, supportsStandardStreamMetadataFormat,
207 nativeStreamMetadataFormatName,
208 nativeStreamMetadataFormatClassName,
209 extraStreamMetadataFormatNames,
210 extraStreamMetadataFormatClassNames,
211 supportsStandardImageMetadataFormat,
212 nativeImageMetadataFormatName,
213 nativeImageMetadataFormatClassName,
214 extraImageMetadataFormatNames,
215 extraImageMetadataFormatClassNames);
216
217 if (inputTypes == null) {
218 throw new IllegalArgumentException("inputTypes == null!");
219 }
220 if (inputTypes.length == 0) {
221 throw new IllegalArgumentException(
222 "inputTypes.length == 0!");
223 }
224 this .inputTypes = (Class[]) inputTypes.clone();
225 // If length == 0, leave it null
226 if (writerSpiNames != null && writerSpiNames.length > 0) {
227 this .writerSpiNames = (String[]) writerSpiNames.clone();
228 }
229 }
230
231 /**
232 * Returns an array of <code>Class</code> objects indicating what
233 * types of objects may be used as arguments to the reader's
234 * <code>setInput</code> method.
235 *
236 * <p> For most readers, which only accept input from an
237 * <code>ImageInputStream</code>, a single-element array
238 * containing <code>ImageInputStream.class</code> should be
239 * returned.
240 *
241 * @return a non-<code>null</code> array of
242 * <code>Class</code>objects of length at least 1.
243 */
244 public Class[] getInputTypes() {
245 return (Class[]) inputTypes.clone();
246 }
247
248 /**
249 * Returns <code>true</code> if the supplied source object appears
250 * to be of the format supported by this reader. Returning
251 * <code>true</code> from this method does not guarantee that
252 * reading will succeed, only that there appears to be a
253 * reasonable chance of success based on a brief inspection of the
254 * stream contents. If the source is an
255 * <code>ImageInputStream</code>, implementations will commonly
256 * check the first several bytes of the stream for a "magic
257 * number" associated with the format. Once actual reading has
258 * commenced, the reader may still indicate failure at any time
259 * prior to the completion of decoding.
260 *
261 * <p> It is important that the state of the object not be
262 * disturbed in order that other <code>ImageReaderSpi</code>s can
263 * properly determine whether they are able to decode the object.
264 * In particular, if the source is an
265 * <code>ImageInputStream</code>, a
266 * <code>mark</code>/<code>reset</code> pair should be used to
267 * preserve the stream position.
268 *
269 * <p> Formats such as "raw," which can potentially attempt
270 * to read nearly any stream, should return <code>false</code>
271 * in order to avoid being invoked in preference to a closer
272 * match.
273 *
274 * <p> If <code>source</code> is not an instance of one of the
275 * classes returned by <code>getInputTypes</code>, the method
276 * should simply return <code>false</code>.
277 *
278 * @param source the object (typically an
279 * <code>ImageInputStream</code>) to be decoded.
280 *
281 * @return <code>true</code> if it is likely that this stream can
282 * be decoded.
283 *
284 * @exception IllegalArgumentException if <code>source</code> is
285 * <code>null</code>.
286 * @exception IOException if an I/O error occurs while reading the
287 * stream.
288 */
289 public abstract boolean canDecodeInput(Object source)
290 throws IOException;
291
292 /**
293 * Returns an instance of the <code>ImageReader</code>
294 * implementation associated with this service provider.
295 * The returned object will initially be in an initial state
296 * as if its <code>reset</code> method had been called.
297 *
298 * <p> The default implementation simply returns
299 * <code>createReaderInstance(null)</code>.
300 *
301 * @return an <code>ImageReader</code> instance.
302 *
303 * @exception IOException if an error occurs during loading,
304 * or initialization of the reader class, or during instantiation
305 * or initialization of the reader object.
306 */
307 public ImageReader createReaderInstance() throws IOException {
308 return createReaderInstance(null);
309 }
310
311 /**
312 * Returns an instance of the <code>ImageReader</code>
313 * implementation associated with this service provider.
314 * The returned object will initially be in an initial state
315 * as if its <code>reset</code> method had been called.
316 *
317 * <p> An <code>Object</code> may be supplied to the plug-in at
318 * construction time. The nature of the object is entirely
319 * plug-in specific.
320 *
321 * <p> Typically, a plug-in will implement this method using code
322 * such as <code>return new MyImageReader(this)</code>.
323 *
324 * @param extension a plug-in specific extension object, which may
325 * be <code>null</code>.
326 *
327 * @return an <code>ImageReader</code> instance.
328 *
329 * @exception IOException if the attempt to instantiate
330 * the reader fails.
331 * @exception IllegalArgumentException if the
332 * <code>ImageReader</code>'s contructor throws an
333 * <code>IllegalArgumentException</code> to indicate that the
334 * extension object is unsuitable.
335 */
336 public abstract ImageReader createReaderInstance(Object extension)
337 throws IOException;
338
339 /**
340 * Returns <code>true</code> if the <code>ImageReader</code> object
341 * passed in is an instance of the <code>ImageReader</code>
342 * associated with this service provider.
343 *
344 * <p> The default implementation compares the fully-qualified
345 * class name of the <code>reader</code> argument with the class
346 * name passed into the constructor. This method may be overridden
347 * if more sophisticated checking is required.
348 *
349 * @param reader an <code>ImageReader</code> instance.
350 *
351 * @return <code>true</code> if <code>reader</code> is recognized.
352 *
353 * @exception IllegalArgumentException if <code>reader</code> is
354 * <code>null</code>.
355 */
356 public boolean isOwnReader(ImageReader reader) {
357 if (reader == null) {
358 throw new IllegalArgumentException("reader == null!");
359 }
360 String name = reader.getClass().getName();
361 return name.equals(pluginClassName);
362 }
363
364 /**
365 * Returns an array of <code>String</code>s containing the fully
366 * qualified names of all the <code>ImageWriterSpi</code> classes
367 * that can understand the internal metadata representation used
368 * by the <code>ImageReader</code> associated with this service
369 * provider, or <code>null</code> if there are no such
370 * <code>ImageWriter</code>s specified. If a
371 * non-<code>null</code> value is returned, it must have non-zero
372 * length.
373 *
374 * <p> The first item in the array must be the name of the service
375 * provider for the "preferred" writer, as it will be used to
376 * instantiate the <code>ImageWriter</code> returned by
377 * <code>ImageIO.getImageWriter(ImageReader)</code>.
378 *
379 * <p> This mechanism may be used to obtain
380 * <code>ImageWriters</code> that will understand the internal
381 * structure of non-pixel meta-data (see
382 * <code>IIOTreeInfo</code>) generated by an
383 * <code>ImageReader</code>. By obtaining this data from the
384 * <code>ImageReader</code> and passing it on to one of the
385 * <code>ImageWriters</code> obtained with this method, a client
386 * program can read an image, modify it in some way, and write it
387 * back out while preserving all meta-data, without having to
388 * understand anything about the internal structure of the
389 * meta-data, or even about the image format.
390 *
391 * @return an array of <code>String</code>s of length at least 1
392 * containing names of <code>ImageWriterSpi</code>, or
393 * <code>null</code>.
394 *
395 * @see javax.imageio.ImageIO#getImageWriter(ImageReader)
396 */
397 public String[] getImageWriterSpiNames() {
398 return writerSpiNames == null ? null
399 : (String[]) writerSpiNames.clone();
400 }
401 }
|