ImageReaders and ImageWriters, and
performing simple encoding and decoding.-
Method Summary
Modifier and TypeMethodDescriptionstatic ImageInputStreamcreateImageInputStream(Object input) Returns anImageInputStreamthat will take its input from the givenObject.static ImageOutputStreamcreateImageOutputStream(Object output) Returns anImageOutputStreamthat will send its output to the givenObject.static FileReturns the current value set bysetCacheDirectory, ornullif no explicit setting has been made.static ImageReadergetImageReader(ImageWriter writer) Returns anImageReadercorresponding to the givenImageWriter, if there is one, ornullif the plug-in for thisImageWriterdoes not specify a correspondingImageReader, or if the givenImageWriteris not registered.static Iterator<ImageReader> getImageReaders(Object input) Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode the suppliedObject, typically anImageInputStream.static Iterator<ImageReader> getImageReadersByFormatName(String formatName) Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode the named format.static Iterator<ImageReader> getImageReadersByMIMEType(String MIMEType) Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode files with the given MIME type.static Iterator<ImageReader> getImageReadersBySuffix(String fileSuffix) Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode files with the given suffix.static Iterator<ImageTranscoder> getImageTranscoders(ImageReader reader, ImageWriter writer) Returns anIteratorcontaining all currently registeredImageTranscoders that claim to be able to transcode between the metadata of the givenImageReaderandImageWriter.static ImageWritergetImageWriter(ImageReader reader) Returns anImageWritercorresponding to the givenImageReader, if there is one, ornullif the plug-in for thisImageReaderdoes not specify a correspondingImageWriter, or if the givenImageReaderis not registered.static Iterator<ImageWriter> getImageWriters(ImageTypeSpecifier type, String formatName) Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode images of the given layout (specified using anImageTypeSpecifier) in the given format.static Iterator<ImageWriter> getImageWritersByFormatName(String formatName) Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode the named format.static Iterator<ImageWriter> getImageWritersByMIMEType(String MIMEType) Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode files with the given MIME type.static Iterator<ImageWriter> getImageWritersBySuffix(String fileSuffix) Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode files with the given suffix.static String[]Returns an array ofStrings listing all of the file suffixes associated with the formats understood by the current set of registered readers.static String[]Returns an array ofStrings listing all of the informal format names understood by the current set of registered readers.static String[]Returns an array ofStrings listing all of the MIME types understood by the current set of registered readers.static booleanReturns the current value set bysetUseCache, ortrueif no explicit setting has been made.static String[]Returns an array ofStrings listing all of the file suffixes associated with the formats understood by the current set of registered writers.static String[]Returns an array ofStrings listing all of the informal format names understood by the current set of registered writers.static String[]Returns an array ofStrings listing all of the MIME types understood by the current set of registered writers.static BufferedImageReturns aBufferedImageas the result of decoding a suppliedFilewith anImageReaderchosen automatically from among those currently registered.static BufferedImageread(InputStream input) Returns aBufferedImageas the result of decoding a suppliedInputStreamwith anImageReaderchosen automatically from among those currently registered.static BufferedImageReturns aBufferedImageas the result of decoding a suppliedURLwith anImageReaderchosen automatically from among those currently registered.static BufferedImageread(ImageInputStream stream) Returns aBufferedImageas the result of decoding a suppliedImageInputStreamwith anImageReaderchosen automatically from among those currently registered.static voidScans for plug-ins on the application class path, loads their service provider classes, and registers a service provider instance for each one found with theIIORegistry.static voidsetCacheDirectory(File cacheDirectory) Sets the directory where cache files are to be created.static voidsetUseCache(boolean useCache) Sets a flag indicating whether a disk-based cache file should be used when creatingImageInputStreams andImageOutputStreams.static booleanwrite(RenderedImage im, String formatName, File output) Writes an image using an arbitraryImageWriterthat supports the given format to aFile.static booleanwrite(RenderedImage im, String formatName, OutputStream output) Writes an image using an arbitraryImageWriterthat supports the given format to anOutputStream.static booleanwrite(RenderedImage im, String formatName, ImageOutputStream output) Writes an image using an arbitraryImageWriterthat supports the given format to anImageOutputStream.
-
Method Details
-
scanForPlugins
public static void scanForPlugins()Scans for plug-ins on the application class path, loads their service provider classes, and registers a service provider instance for each one found with theIIORegistry.This method is needed because the application class path can theoretically change, or additional plug-ins may become available. Rather than re-scanning the classpath on every invocation of the API, the class path is scanned automatically only on the first invocation. Clients can call this method to prompt a re-scan. Thus this method need only be invoked by sophisticated applications which dynamically make new plug-ins available at runtime.
The
getResourcesmethod of the contextClassLoaderis used locate JAR files containing files namedMETA-INF/services/javax.imageio.spi.classname, where classname is one ofImageReaderSpi,ImageWriterSpi,ImageTranscoderSpi,ImageInputStreamSpi, orImageOutputStreamSpi, along the application class path.The contents of the located files indicate the names of actual implementation classes which implement the aforementioned service provider interfaces; the default class loader is then used to load each of these classes and to instantiate an instance of each class, which is then placed into the registry for later retrieval.
The exact set of locations searched depends on the implementation of the Java runtime environment.
- See Also:
-
setUseCache
public static void setUseCache(boolean useCache) Sets a flag indicating whether a disk-based cache file should be used when creatingImageInputStreams andImageOutputStreams.When reading from a standard
InputStream, it may be necessary to save previously read information in a cache since the underlying stream does not allow data to be re-read. Similarly, when writing to a standardOutputStream, a cache may be used to allow a previously written value to be changed before flushing it to the final destination.The cache may reside in main memory or on disk. Setting this flag to
falsedisallows the use of disk for future streams, which may be advantageous when working with small images, as the overhead of creating and destroying files is removed.On startup, the value is set to
true.- Parameters:
useCache- abooleanindicating whether a cache file should be used, in cases where it is optional.- See Also:
-
getUseCache
public static boolean getUseCache()Returns the current value set bysetUseCache, ortrueif no explicit setting has been made.- Returns:
- true if a disk-based cache may be used for
ImageInputStreams andImageOutputStreams. - See Also:
-
setCacheDirectory
Sets the directory where cache files are to be created. A value ofnullindicates that the system-dependent default temporary-file directory is to be used. IfgetUseCachereturns false, this value is ignored.- Parameters:
cacheDirectory- aFilespecifying a directory.- Throws:
SecurityException- if the security manager denies access to the directory.IllegalArgumentException- ifcacheDiris non-nullbut is not a directory.- See Also:
-
getCacheDirectory
Returns the current value set bysetCacheDirectory, ornullif no explicit setting has been made.- Returns:
- a
Fileindicating the directory where cache files will be created, ornullto indicate the system-dependent default temporary-file directory. - See Also:
-
createImageInputStream
Returns anImageInputStreamthat will take its input from the givenObject. The set ofImageInputStreamSpis registered with theIIORegistryclass is queried and the first one that is able to take input from the supplied object is used to create the returnedImageInputStream. If no suitableImageInputStreamSpiexists,nullis returned.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching.- Parameters:
input- anObjectto be used as an input source, such as aFile, readableRandomAccessFile, orInputStream.- Returns:
- an
ImageInputStream, ornull. - Throws:
IllegalArgumentException- ifinputisnull.IOException- if a cache file is needed but cannot be created.- See Also:
-
createImageOutputStream
Returns anImageOutputStreamthat will send its output to the givenObject. The set ofImageOutputStreamSpis registered with theIIORegistryclass is queried and the first one that is able to send output from the supplied object is used to create the returnedImageOutputStream. If no suitableImageOutputStreamSpiexists,nullis returned.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching.- Parameters:
output- anObjectto be used as an output destination, such as aFile, writableRandomAccessFile, orOutputStream.- Returns:
- an
ImageOutputStream, ornull. - Throws:
IllegalArgumentException- ifoutputisnull.IOException- if a cache file is needed but cannot be created.- See Also:
-
getReaderFormatNames
Returns an array ofStrings listing all of the informal format names understood by the current set of registered readers.- Returns:
- an array of
Strings.
-
getReaderMIMETypes
Returns an array ofStrings listing all of the MIME types understood by the current set of registered readers.- Returns:
- an array of
Strings.
-
getReaderFileSuffixes
Returns an array ofStrings listing all of the file suffixes associated with the formats understood by the current set of registered readers.- Returns:
- an array of
Strings. - Since:
- 1.6
-
getImageReaders
Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode the suppliedObject, typically anImageInputStream.The stream position is left at its prior position upon exit from this method.
- Parameters:
input- anImageInputStreamor otherObjectcontaining encoded image data.- Returns:
- an
IteratorcontainingImageReaders. - Throws:
IllegalArgumentException- ifinputisnull.- See Also:
-
getImageReadersByFormatName
Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode the named format.- Parameters:
formatName- aStringcontaining the informal name of a format (e.g., "jpeg" or "tiff".- Returns:
- an
IteratorcontainingImageReaders. - Throws:
IllegalArgumentException- ifformatNameisnull.- See Also:
-
getImageReadersBySuffix
Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode files with the given suffix.- Parameters:
fileSuffix- aStringcontaining a file suffix (e.g., "jpg" or "tiff").- Returns:
- an
IteratorcontainingImageReaders. - Throws:
IllegalArgumentException- iffileSuffixisnull.- See Also:
-
getImageReadersByMIMEType
Returns anIteratorcontaining all currently registeredImageReaders that claim to be able to decode files with the given MIME type.- Parameters:
MIMEType- aStringcontaining a file suffix (e.g., "image/jpeg" or "image/x-bmp").- Returns:
- an
IteratorcontainingImageReaders. - Throws:
IllegalArgumentException- ifMIMETypeisnull.- See Also:
-
getWriterFormatNames
Returns an array ofStrings listing all of the informal format names understood by the current set of registered writers.- Returns:
- an array of
Strings.
-
getWriterMIMETypes
Returns an array ofStrings listing all of the MIME types understood by the current set of registered writers.- Returns:
- an array of
Strings.
-
getWriterFileSuffixes
Returns an array ofStrings listing all of the file suffixes associated with the formats understood by the current set of registered writers.- Returns:
- an array of
Strings. - Since:
- 1.6
-
getImageWritersByFormatName
Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode the named format.- Parameters:
formatName- aStringcontaining the informal name of a format (e.g., "jpeg" or "tiff".- Returns:
- an
IteratorcontainingImageWriters. - Throws:
IllegalArgumentException- ifformatNameisnull.- See Also:
-
getImageWritersBySuffix
Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode files with the given suffix.- Parameters:
fileSuffix- aStringcontaining a file suffix (e.g., "jpg" or "tiff").- Returns:
- an
IteratorcontainingImageWriters. - Throws:
IllegalArgumentException- iffileSuffixisnull.- See Also:
-
getImageWritersByMIMEType
Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode files with the given MIME type.- Parameters:
MIMEType- aStringcontaining a file suffix (e.g., "image/jpeg" or "image/x-bmp").- Returns:
- an
IteratorcontainingImageWriters. - Throws:
IllegalArgumentException- ifMIMETypeisnull.- See Also:
-
getImageWriter
Returns anImageWritercorresponding to the givenImageReader, if there is one, ornullif the plug-in for thisImageReaderdoes not specify a correspondingImageWriter, or if the givenImageReaderis not registered. This mechanism may be used to obtain anImageWriterthat will understand the internal structure of non-pixel metadata (as encoded byIIOMetadataobjects) generated by theImageReader. By obtaining this data from theImageReaderand passing it on to theImageWriterobtained with this method, a client program can read an image, modify it in some way, and write it back out preserving all metadata, without having to understand anything about the structure of the metadata, or even about the image format. Note that this method returns the "preferred" writer, which is the first in the list returned byjavax.imageio.spi.ImageReaderSpi.getImageWriterSpiNames().- Parameters:
reader- an instance of a registeredImageReader.- Returns:
- an
ImageWriter, or null. - Throws:
IllegalArgumentException- ifreaderisnull.- See Also:
-
getImageReader
Returns anImageReadercorresponding to the givenImageWriter, if there is one, ornullif the plug-in for thisImageWriterdoes not specify a correspondingImageReader, or if the givenImageWriteris not registered. This method is provided principally for symmetry withgetImageWriter(ImageReader). Note that this method returns the "preferred" reader, which is the first in the list returned by javax.imageio.spi.ImageWriterSpi.getImageReaderSpiNames().- Parameters:
writer- an instance of a registeredImageWriter.- Returns:
- an
ImageReader, or null. - Throws:
IllegalArgumentException- ifwriterisnull.- See Also:
-
getImageWriters
Returns anIteratorcontaining all currently registeredImageWriters that claim to be able to encode images of the given layout (specified using anImageTypeSpecifier) in the given format.- Parameters:
type- anImageTypeSpecifierindicating the layout of the image to be written.formatName- the informal name of theformat.- Returns:
- an
IteratorcontainingImageWriters. - Throws:
IllegalArgumentException- if any parameter isnull.- See Also:
-
getImageTranscoders
Returns anIteratorcontaining all currently registeredImageTranscoders that claim to be able to transcode between the metadata of the givenImageReaderandImageWriter.- Parameters:
reader- anImageReader.writer- anImageWriter.- Returns:
- an
IteratorcontainingImageTranscoders. - Throws:
IllegalArgumentException- ifreaderorwriterisnull.
-
read
Returns aBufferedImageas the result of decoding a suppliedFilewith anImageReaderchosen automatically from among those currently registered. TheFileis wrapped in anImageInputStream. If no registeredImageReaderclaims to be able to read the resulting stream,nullis returned.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching in theImageInputStreamthat is created.Note that there is no
readmethod that takes a filename as aString; use this method instead after creating aFilefrom the filename.This method does not attempt to locate
ImageReaders that can read directly from aFile; that may be accomplished usingIIORegistryandImageReaderSpi.- Parameters:
input- aFileto read from.- Returns:
- a
BufferedImagecontaining the decoded contents of the input, ornull. - Throws:
IllegalArgumentException- ifinputisnull.IOException- if an error occurs during reading or when not able to create required ImageInputStream.
-
read
Returns aBufferedImageas the result of decoding a suppliedInputStreamwith anImageReaderchosen automatically from among those currently registered. TheInputStreamis wrapped in anImageInputStream. If no registeredImageReaderclaims to be able to read the resulting stream,nullis returned.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching in theImageInputStreamthat is created.This method does not attempt to locate
ImageReaders that can read directly from anInputStream; that may be accomplished usingIIORegistryandImageReaderSpi.This method does not close the provided
InputStreamafter the read operation has completed; it is the responsibility of the caller to close the stream, if desired.- Parameters:
input- anInputStreamto read from.- Returns:
- a
BufferedImagecontaining the decoded contents of the input, ornull. - Throws:
IllegalArgumentException- ifinputisnull.IOException- if an error occurs during reading or when not able to create required ImageInputStream.
-
read
Returns aBufferedImageas the result of decoding a suppliedURLwith anImageReaderchosen automatically from among those currently registered. AnInputStreamis obtained from theURL, which is wrapped in anImageInputStream. If no registeredImageReaderclaims to be able to read the resulting stream,nullis returned.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching in theImageInputStreamthat is created.This method does not attempt to locate
ImageReaders that can read directly from aURL; that may be accomplished usingIIORegistryandImageReaderSpi.- Parameters:
input- aURLto read from.- Returns:
- a
BufferedImagecontaining the decoded contents of the input, ornull. - Throws:
IllegalArgumentException- ifinputisnull.IOException- if an error occurs during reading or when not able to create required ImageInputStream.
-
read
Returns aBufferedImageas the result of decoding a suppliedImageInputStreamwith anImageReaderchosen automatically from among those currently registered. If no registeredImageReaderclaims to be able to read the stream,nullis returned.Unlike most other methods in this class, this method does close the provided
ImageInputStreamafter the read operation has completed, unlessnullis returned, in which case this method does not close the stream.- Parameters:
stream- anImageInputStreamto read from.- Returns:
- a
BufferedImagecontaining the decoded contents of the input, ornull. - Throws:
IllegalArgumentException- ifstreamisnull.IOException- if an error occurs during reading.
-
write
public static boolean write(RenderedImage im, String formatName, ImageOutputStream output) throws IOException Writes an image using an arbitraryImageWriterthat supports the given format to anImageOutputStream. The image is written to theImageOutputStreamstarting at the current stream pointer, overwriting existing stream data from that point forward, if present.This method does not close the provided
ImageOutputStreamafter the write operation has completed; it is the responsibility of the caller to close the stream, if desired.- Parameters:
im- aRenderedImageto be written.formatName- aStringcontaining the informal name of the format.output- anImageOutputStreamto be written to.- Returns:
falseif no appropriate writer is found.- Throws:
IllegalArgumentException- if any parameter isnull.IOException- if an error occurs during writing.
-
write
Writes an image using an arbitraryImageWriterthat supports the given format to aFile. If there is already aFilepresent, its contents are discarded.- Parameters:
im- aRenderedImageto be written.formatName- aStringcontaining the informal name of the format.output- aFileto be written to.- Returns:
falseif no appropriate writer is found.- Throws:
IllegalArgumentException- if any parameter isnull.IOException- if an error occurs during writing or when not able to create required ImageOutputStream.
-
write
public static boolean write(RenderedImage im, String formatName, OutputStream output) throws IOException Writes an image using an arbitraryImageWriterthat supports the given format to anOutputStream.This method does not close the provided
OutputStreamafter the write operation has completed; it is the responsibility of the caller to close the stream, if desired.The current cache settings from
getUseCacheandgetCacheDirectorywill be used to control caching.- Parameters:
im- aRenderedImageto be written.formatName- aStringcontaining the informal name of the format.output- anOutputStreamto be written to.- Returns:
falseif no appropriate writer is found.- Throws:
IllegalArgumentException- if any parameter isnull.IOException- if an error occurs during writing or when not able to create required ImageOutputStream.
-