< prev index next >
src/java.desktop/share/classes/javax/imageio/spi/ImageReaderSpi.java
Print this page
*** 28,70 ****
import java.io.IOException;
import javax.imageio.ImageReader;
import javax.imageio.stream.ImageInputStream;
/**
! * The service provider interface (SPI) for <code>ImageReader</code>s.
* For more information on service provider classes, see the class comment
! * for the <code>IIORegistry</code> class.
*
! * <p> Each <code>ImageReaderSpi</code> provides several types of information
! * about the <code>ImageReader</code> class with which it is associated.
*
* <p> The name of the vendor who defined the SPI class and a
* brief description of the class are available via the
! * <code>getVendorName</code>, <code>getDescription</code>,
! * and <code>getVersion</code> methods.
* These methods may be internationalized to provide locale-specific
* output. These methods are intended mainly to provide short,
* human-readable information that might be used to organize a pop-up
* menu or other list.
*
* <p> Lists of format names, file suffixes, and MIME types associated
* with the service may be obtained by means of the
! * <code>getFormatNames</code>, <code>getFileSuffixes</code>, and
! * <code>getMIMETypes</code> methods. These methods may be used to
! * identify candidate <code>ImageReader</code>s for decoding a
* particular file or stream based on manual format selection, file
* naming, or MIME associations (for example, when accessing a file
* over HTTP or as an email attachment).
*
! * <p> A more reliable way to determine which <code>ImageReader</code>s
* are likely to be able to parse a particular data stream is provided
! * by the <code>canDecodeInput</code> method. This methods allows the
* service provider to inspect the actual stream contents.
*
! * <p> Finally, an instance of the <code>ImageReader</code> class
* associated with this service provider may be obtained by calling
! * the <code>createReaderInstance</code> method. Any heavyweight
* initialization, such as the loading of native libraries or creation
* of large tables, should be deferred at least until the first
* invocation of this method.
*
* @see IIORegistry
--- 28,70 ----
import java.io.IOException;
import javax.imageio.ImageReader;
import javax.imageio.stream.ImageInputStream;
/**
! * The service provider interface (SPI) for {@code ImageReader}s.
* For more information on service provider classes, see the class comment
! * for the {@code IIORegistry} class.
*
! * <p> Each {@code ImageReaderSpi} provides several types of information
! * about the {@code ImageReader} class with which it is associated.
*
* <p> The name of the vendor who defined the SPI class and a
* brief description of the class are available via the
! * {@code getVendorName}, {@code getDescription},
! * and {@code getVersion} methods.
* These methods may be internationalized to provide locale-specific
* output. These methods are intended mainly to provide short,
* human-readable information that might be used to organize a pop-up
* menu or other list.
*
* <p> Lists of format names, file suffixes, and MIME types associated
* with the service may be obtained by means of the
! * {@code getFormatNames}, {@code getFileSuffixes}, and
! * {@code getMIMETypes} methods. These methods may be used to
! * identify candidate {@code ImageReader}s for decoding a
* particular file or stream based on manual format selection, file
* naming, or MIME associations (for example, when accessing a file
* over HTTP or as an email attachment).
*
! * <p> A more reliable way to determine which {@code ImageReader}s
* are likely to be able to parse a particular data stream is provided
! * by the {@code canDecodeInput} method. This methods allows the
* service provider to inspect the actual stream contents.
*
! * <p> Finally, an instance of the {@code ImageReader} class
* associated with this service provider may be obtained by calling
! * the {@code createReaderInstance} method. Any heavyweight
* initialization, such as the loading of native libraries or creation
* of large tables, should be deferred at least until the first
* invocation of this method.
*
* @see IIORegistry
*** 73,197 ****
*/
public abstract class ImageReaderSpi extends ImageReaderWriterSpi {
/**
* A single-element array, initially containing
! * <code>ImageInputStream.class</code>, to be returned from
! * <code>getInputTypes</code>.
* @deprecated Instead of using this field, directly create
! * the equivalent array <code>{ ImageInputStream.class }</code>.
*/
@Deprecated
public static final Class<?>[] STANDARD_INPUT_TYPE =
{ ImageInputStream.class };
/**
! * An array of <code>Class</code> objects to be returned from
! * <code>getInputTypes</code>, initially <code>null</code>.
*/
protected Class<?>[] inputTypes = null;
/**
* An array of strings to be returned from
! * <code>getImageWriterSpiNames</code>, initially
! * <code>null</code>.
*/
protected String[] writerSpiNames = null;
/**
! * The <code>Class</code> of the reader, initially
! * <code>null</code>.
*/
private Class<?> readerClass = null;
/**
! * Constructs a blank <code>ImageReaderSpi</code>. It is up to
* the subclass to initialize instance variables and/or override
* method implementations in order to provide working versions of
* all methods.
*/
protected ImageReaderSpi() {
}
/**
! * Constructs an <code>ImageReaderSpi</code> with a given
* set of values.
*
! * @param vendorName the vendor name, as a non-<code>null</code>
! * <code>String</code>.
! * @param version a version identifier, as a non-<code>null</code>
! * <code>String</code>.
! * @param names a non-<code>null</code> array of
! * <code>String</code>s indicating the format names. At least one
* entry must be present.
! * @param suffixes an array of <code>String</code>s indicating the
* common file suffixes. If no suffixes are defined,
! * <code>null</code> should be supplied. An array of length 0
! * will be normalized to <code>null</code>.
! * @param MIMETypes an array of <code>String</code>s indicating
* the format's MIME types. If no MIME types are defined,
! * <code>null</code> should be supplied. An array of length 0
! * will be normalized to <code>null</code>.
* @param readerClassName the fully-qualified name of the
! * associated <code>ImageReader</code> class, as a
! * non-<code>null</code> <code>String</code>.
! * @param inputTypes a non-<code>null</code> array of
! * <code>Class</code> objects of length at least 1 indicating the
* legal input types.
! * @param writerSpiNames an array <code>String</code>s naming the
! * classes of all associated <code>ImageWriter</code>s, or
! * <code>null</code>. An array of length 0 is normalized to
! * <code>null</code>.
* @param supportsStandardStreamMetadataFormat a
! * <code>boolean</code> that indicates whether a stream metadata
* object can use trees described by the standard metadata format.
* @param nativeStreamMetadataFormatName a
! * <code>String</code>, or <code>null</code>, to be returned from
! * <code>getNativeStreamMetadataFormatName</code>.
* @param nativeStreamMetadataFormatClassName a
! * <code>String</code>, or <code>null</code>, to be used to instantiate
* a metadata format object to be returned from
! * <code>getNativeStreamMetadataFormat</code>.
* @param extraStreamMetadataFormatNames an array of
! * <code>String</code>s, or <code>null</code>, to be returned from
! * <code>getExtraStreamMetadataFormatNames</code>. An array of length
! * 0 is normalized to <code>null</code>.
* @param extraStreamMetadataFormatClassNames an array of
! * <code>String</code>s, or <code>null</code>, to be used to instantiate
* a metadata format object to be returned from
! * <code>getStreamMetadataFormat</code>. An array of length
! * 0 is normalized to <code>null</code>.
* @param supportsStandardImageMetadataFormat a
! * <code>boolean</code> that indicates whether an image metadata
* object can use trees described by the standard metadata format.
* @param nativeImageMetadataFormatName a
! * <code>String</code>, or <code>null</code>, to be returned from
! * <code>getNativeImageMetadataFormatName</code>.
* @param nativeImageMetadataFormatClassName a
! * <code>String</code>, or <code>null</code>, to be used to instantiate
* a metadata format object to be returned from
! * <code>getNativeImageMetadataFormat</code>.
* @param extraImageMetadataFormatNames an array of
! * <code>String</code>s to be returned from
! * <code>getExtraImageMetadataFormatNames</code>. An array of length 0
! * is normalized to <code>null</code>.
* @param extraImageMetadataFormatClassNames an array of
! * <code>String</code>s, or <code>null</code>, to be used to instantiate
* a metadata format object to be returned from
! * <code>getImageMetadataFormat</code>. An array of length
! * 0 is normalized to <code>null</code>.
*
! * @exception IllegalArgumentException if <code>vendorName</code>
! * is <code>null</code>.
! * @exception IllegalArgumentException if <code>version</code>
! * is <code>null</code>.
! * @exception IllegalArgumentException if <code>names</code>
! * is <code>null</code> or has length 0.
! * @exception IllegalArgumentException if <code>readerClassName</code>
! * is <code>null</code>.
! * @exception IllegalArgumentException if <code>inputTypes</code>
! * is <code>null</code> or has length 0.
*/
public ImageReaderSpi(String vendorName,
String version,
String[] names,
String[] suffixes,
--- 73,197 ----
*/
public abstract class ImageReaderSpi extends ImageReaderWriterSpi {
/**
* A single-element array, initially containing
! * {@code ImageInputStream.class}, to be returned from
! * {@code getInputTypes}.
* @deprecated Instead of using this field, directly create
! * the equivalent array {@code { ImageInputStream.class }}.
*/
@Deprecated
public static final Class<?>[] STANDARD_INPUT_TYPE =
{ ImageInputStream.class };
/**
! * An array of {@code Class} objects to be returned from
! * {@code getInputTypes}, initially {@code null}.
*/
protected Class<?>[] inputTypes = null;
/**
* An array of strings to be returned from
! * {@code getImageWriterSpiNames}, initially
! * {@code null}.
*/
protected String[] writerSpiNames = null;
/**
! * The {@code Class} of the reader, initially
! * {@code null}.
*/
private Class<?> readerClass = null;
/**
! * Constructs a blank {@code ImageReaderSpi}. It is up to
* the subclass to initialize instance variables and/or override
* method implementations in order to provide working versions of
* all methods.
*/
protected ImageReaderSpi() {
}
/**
! * Constructs an {@code ImageReaderSpi} with a given
* set of values.
*
! * @param vendorName the vendor name, as a non-{@code null}
! * {@code String}.
! * @param version a version identifier, as a non-{@code null}
! * {@code String}.
! * @param names a non-{@code null} array of
! * {@code String}s indicating the format names. At least one
* entry must be present.
! * @param suffixes an array of {@code String}s indicating the
* common file suffixes. If no suffixes are defined,
! * {@code null} should be supplied. An array of length 0
! * will be normalized to {@code null}.
! * @param MIMETypes an array of {@code String}s indicating
* the format's MIME types. If no MIME types are defined,
! * {@code null} should be supplied. An array of length 0
! * will be normalized to {@code null}.
* @param readerClassName the fully-qualified name of the
! * associated {@code ImageReader} class, as a
! * non-{@code null String}.
! * @param inputTypes a non-{@code null} array of
! * {@code Class} objects of length at least 1 indicating the
* legal input types.
! * @param writerSpiNames an array {@code String}s naming the
! * classes of all associated {@code ImageWriter}s, or
! * {@code null}. An array of length 0 is normalized to
! * {@code null}.
* @param supportsStandardStreamMetadataFormat a
! * {@code boolean} that indicates whether a stream metadata
* object can use trees described by the standard metadata format.
* @param nativeStreamMetadataFormatName a
! * {@code String}, or {@code null}, to be returned from
! * {@code getNativeStreamMetadataFormatName}.
* @param nativeStreamMetadataFormatClassName a
! * {@code String}, or {@code null}, to be used to instantiate
* a metadata format object to be returned from
! * {@code getNativeStreamMetadataFormat}.
* @param extraStreamMetadataFormatNames an array of
! * {@code String}s, or {@code null}, to be returned from
! * {@code getExtraStreamMetadataFormatNames}. An array of length
! * 0 is normalized to {@code null}.
* @param extraStreamMetadataFormatClassNames an array of
! * {@code String}s, or {@code null}, to be used to instantiate
* a metadata format object to be returned from
! * {@code getStreamMetadataFormat}. An array of length
! * 0 is normalized to {@code null}.
* @param supportsStandardImageMetadataFormat a
! * {@code boolean} that indicates whether an image metadata
* object can use trees described by the standard metadata format.
* @param nativeImageMetadataFormatName a
! * {@code String}, or {@code null}, to be returned from
! * {@code getNativeImageMetadataFormatName}.
* @param nativeImageMetadataFormatClassName a
! * {@code String}, or {@code null}, to be used to instantiate
* a metadata format object to be returned from
! * {@code getNativeImageMetadataFormat}.
* @param extraImageMetadataFormatNames an array of
! * {@code String}s to be returned from
! * {@code getExtraImageMetadataFormatNames}. An array of length 0
! * is normalized to {@code null}.
* @param extraImageMetadataFormatClassNames an array of
! * {@code String}s, or {@code null}, to be used to instantiate
* a metadata format object to be returned from
! * {@code getImageMetadataFormat}. An array of length
! * 0 is normalized to {@code null}.
*
! * @exception IllegalArgumentException if {@code vendorName}
! * is {@code null}.
! * @exception IllegalArgumentException if {@code version}
! * is {@code null}.
! * @exception IllegalArgumentException if {@code names}
! * is {@code null} or has length 0.
! * @exception IllegalArgumentException if {@code readerClassName}
! * is {@code null}.
! * @exception IllegalArgumentException if {@code inputTypes}
! * is {@code null} or has length 0.
*/
public ImageReaderSpi(String vendorName,
String version,
String[] names,
String[] suffixes,
*** 240,410 ****
this.writerSpiNames = writerSpiNames.clone();
}
}
/**
! * Returns an array of <code>Class</code> objects indicating what
* types of objects may be used as arguments to the reader's
! * <code>setInput</code> method.
*
* <p> For most readers, which only accept input from an
! * <code>ImageInputStream</code>, a single-element array
! * containing <code>ImageInputStream.class</code> should be
* returned.
*
! * @return a non-<code>null</code> array of
! * <code>Class</code> objects of length at least 1.
*/
public Class<?>[] getInputTypes() {
return inputTypes.clone();
}
/**
! * Returns <code>true</code> if the supplied source object appears
* to be of the format supported by this reader. Returning
! * <code>true</code> from this method does not guarantee that
* reading will succeed, only that there appears to be a
* reasonable chance of success based on a brief inspection of the
* stream contents. If the source is an
! * <code>ImageInputStream</code>, implementations will commonly
* check the first several bytes of the stream for a "magic
* number" associated with the format. Once actual reading has
* commenced, the reader may still indicate failure at any time
* prior to the completion of decoding.
*
* <p> It is important that the state of the object not be
! * disturbed in order that other <code>ImageReaderSpi</code>s can
* properly determine whether they are able to decode the object.
* In particular, if the source is an
! * <code>ImageInputStream</code>, a
! * <code>mark</code>/<code>reset</code> pair should be used to
* preserve the stream position.
*
* <p> Formats such as "raw," which can potentially attempt
! * to read nearly any stream, should return <code>false</code>
* in order to avoid being invoked in preference to a closer
* match.
*
! * <p> If <code>source</code> is not an instance of one of the
! * classes returned by <code>getInputTypes</code>, the method
! * should simply return <code>false</code>.
*
* @param source the object (typically an
! * <code>ImageInputStream</code>) to be decoded.
*
! * @return <code>true</code> if it is likely that this stream can
* be decoded.
*
! * @exception IllegalArgumentException if <code>source</code> is
! * <code>null</code>.
* @exception IOException if an I/O error occurs while reading the
* stream.
*/
public abstract boolean canDecodeInput(Object source) throws IOException;
/**
! * Returns an instance of the <code>ImageReader</code>
* implementation associated with this service provider.
* The returned object will initially be in an initial state
! * as if its <code>reset</code> method had been called.
*
* <p> The default implementation simply returns
! * <code>createReaderInstance(null)</code>.
*
! * @return an <code>ImageReader</code> instance.
*
* @exception IOException if an error occurs during loading,
* or initialization of the reader class, or during instantiation
* or initialization of the reader object.
*/
public ImageReader createReaderInstance() throws IOException {
return createReaderInstance(null);
}
/**
! * Returns an instance of the <code>ImageReader</code>
* implementation associated with this service provider.
* The returned object will initially be in an initial state
! * as if its <code>reset</code> method had been called.
*
! * <p> An <code>Object</code> may be supplied to the plug-in at
* construction time. The nature of the object is entirely
* plug-in specific.
*
* <p> Typically, a plug-in will implement this method using code
! * such as <code>return new MyImageReader(this)</code>.
*
* @param extension a plug-in specific extension object, which may
! * be <code>null</code>.
*
! * @return an <code>ImageReader</code> instance.
*
* @exception IOException if the attempt to instantiate
* the reader fails.
* @exception IllegalArgumentException if the
! * <code>ImageReader</code>'s constructor throws an
! * <code>IllegalArgumentException</code> to indicate that the
* extension object is unsuitable.
*/
public abstract ImageReader createReaderInstance(Object extension)
throws IOException;
/**
! * Returns <code>true</code> if the <code>ImageReader</code> object
! * passed in is an instance of the <code>ImageReader</code>
* associated with this service provider.
*
* <p> The default implementation compares the fully-qualified
! * class name of the <code>reader</code> argument with the class
* name passed into the constructor. This method may be overridden
* if more sophisticated checking is required.
*
! * @param reader an <code>ImageReader</code> instance.
*
! * @return <code>true</code> if <code>reader</code> is recognized.
*
! * @exception IllegalArgumentException if <code>reader</code> is
! * <code>null</code>.
*/
public boolean isOwnReader(ImageReader reader) {
if (reader == null) {
throw new IllegalArgumentException("reader == null!");
}
String name = reader.getClass().getName();
return name.equals(pluginClassName);
}
/**
! * Returns an array of <code>String</code>s containing the fully
! * qualified names of all the <code>ImageWriterSpi</code> classes
* that can understand the internal metadata representation used
! * by the <code>ImageReader</code> associated with this service
! * provider, or <code>null</code> if there are no such
! * <code>ImageWriter</code>s specified. If a
! * non-<code>null</code> value is returned, it must have non-zero
* length.
*
* <p> The first item in the array must be the name of the service
* provider for the "preferred" writer, as it will be used to
! * instantiate the <code>ImageWriter</code> returned by
! * <code>ImageIO.getImageWriter(ImageReader)</code>.
*
* <p> This mechanism may be used to obtain
! * <code>ImageWriters</code> that will understand the internal
* structure of non-pixel meta-data (see
! * <code>IIOTreeInfo</code>) generated by an
! * <code>ImageReader</code>. By obtaining this data from the
! * <code>ImageReader</code> and passing it on to one of the
! * <code>ImageWriters</code> obtained with this method, a client
* program can read an image, modify it in some way, and write it
* back out while preserving all meta-data, without having to
* understand anything about the internal structure of the
* meta-data, or even about the image format.
*
! * @return an array of <code>String</code>s of length at least 1
! * containing names of <code>ImageWriterSpi</code>, or
! * <code>null</code>.
*
* @see javax.imageio.ImageIO#getImageWriter(ImageReader)
*/
public String[] getImageWriterSpiNames() {
return writerSpiNames == null ?
--- 240,410 ----
this.writerSpiNames = writerSpiNames.clone();
}
}
/**
! * Returns an array of {@code Class} objects indicating what
* types of objects may be used as arguments to the reader's
! * {@code setInput} method.
*
* <p> For most readers, which only accept input from an
! * {@code ImageInputStream}, a single-element array
! * containing {@code ImageInputStream.class} should be
* returned.
*
! * @return a non-{@code null} array of
! * {@code Class} objects of length at least 1.
*/
public Class<?>[] getInputTypes() {
return inputTypes.clone();
}
/**
! * Returns {@code true} if the supplied source object appears
* to be of the format supported by this reader. Returning
! * {@code true} from this method does not guarantee that
* reading will succeed, only that there appears to be a
* reasonable chance of success based on a brief inspection of the
* stream contents. If the source is an
! * {@code ImageInputStream}, implementations will commonly
* check the first several bytes of the stream for a "magic
* number" associated with the format. Once actual reading has
* commenced, the reader may still indicate failure at any time
* prior to the completion of decoding.
*
* <p> It is important that the state of the object not be
! * disturbed in order that other {@code ImageReaderSpi}s can
* properly determine whether they are able to decode the object.
* In particular, if the source is an
! * {@code ImageInputStream}, a
! * {@code mark}/{@code reset} pair should be used to
* preserve the stream position.
*
* <p> Formats such as "raw," which can potentially attempt
! * to read nearly any stream, should return {@code false}
* in order to avoid being invoked in preference to a closer
* match.
*
! * <p> If {@code source} is not an instance of one of the
! * classes returned by {@code getInputTypes}, the method
! * should simply return {@code false}.
*
* @param source the object (typically an
! * {@code ImageInputStream}) to be decoded.
*
! * @return {@code true} if it is likely that this stream can
* be decoded.
*
! * @exception IllegalArgumentException if {@code source} is
! * {@code null}.
* @exception IOException if an I/O error occurs while reading the
* stream.
*/
public abstract boolean canDecodeInput(Object source) throws IOException;
/**
! * Returns an instance of the {@code ImageReader}
* implementation associated with this service provider.
* The returned object will initially be in an initial state
! * as if its {@code reset} method had been called.
*
* <p> The default implementation simply returns
! * {@code createReaderInstance(null)}.
*
! * @return an {@code ImageReader} instance.
*
* @exception IOException if an error occurs during loading,
* or initialization of the reader class, or during instantiation
* or initialization of the reader object.
*/
public ImageReader createReaderInstance() throws IOException {
return createReaderInstance(null);
}
/**
! * Returns an instance of the {@code ImageReader}
* implementation associated with this service provider.
* The returned object will initially be in an initial state
! * as if its {@code reset} method had been called.
*
! * <p> An {@code Object} may be supplied to the plug-in at
* construction time. The nature of the object is entirely
* plug-in specific.
*
* <p> Typically, a plug-in will implement this method using code
! * such as {@code return new MyImageReader(this)}.
*
* @param extension a plug-in specific extension object, which may
! * be {@code null}.
*
! * @return an {@code ImageReader} instance.
*
* @exception IOException if the attempt to instantiate
* the reader fails.
* @exception IllegalArgumentException if the
! * {@code ImageReader}'s constructor throws an
! * {@code IllegalArgumentException} to indicate that the
* extension object is unsuitable.
*/
public abstract ImageReader createReaderInstance(Object extension)
throws IOException;
/**
! * Returns {@code true} if the {@code ImageReader} object
! * passed in is an instance of the {@code ImageReader}
* associated with this service provider.
*
* <p> The default implementation compares the fully-qualified
! * class name of the {@code reader} argument with the class
* name passed into the constructor. This method may be overridden
* if more sophisticated checking is required.
*
! * @param reader an {@code ImageReader} instance.
*
! * @return {@code true} if {@code reader} is recognized.
*
! * @exception IllegalArgumentException if {@code reader} is
! * {@code null}.
*/
public boolean isOwnReader(ImageReader reader) {
if (reader == null) {
throw new IllegalArgumentException("reader == null!");
}
String name = reader.getClass().getName();
return name.equals(pluginClassName);
}
/**
! * Returns an array of {@code String}s containing the fully
! * qualified names of all the {@code ImageWriterSpi} classes
* that can understand the internal metadata representation used
! * by the {@code ImageReader} associated with this service
! * provider, or {@code null} if there are no such
! * {@code ImageWriter}s specified. If a
! * non-{@code null} value is returned, it must have non-zero
* length.
*
* <p> The first item in the array must be the name of the service
* provider for the "preferred" writer, as it will be used to
! * instantiate the {@code ImageWriter} returned by
! * {@code ImageIO.getImageWriter(ImageReader)}.
*
* <p> This mechanism may be used to obtain
! * {@code ImageWriters} that will understand the internal
* structure of non-pixel meta-data (see
! * {@code IIOTreeInfo}) generated by an
! * {@code ImageReader}. By obtaining this data from the
! * {@code ImageReader} and passing it on to one of the
! * {@code ImageWriters} obtained with this method, a client
* program can read an image, modify it in some way, and write it
* back out while preserving all meta-data, without having to
* understand anything about the internal structure of the
* meta-data, or even about the image format.
*
! * @return an array of {@code String}s of length at least 1
! * containing names of {@code ImageWriterSpi}, or
! * {@code null}.
*
* @see javax.imageio.ImageIO#getImageWriter(ImageReader)
*/
public String[] getImageWriterSpiNames() {
return writerSpiNames == null ?
< prev index next >