diff options
author | Thomas Fitzsimmons <fitzsim@redhat.com> | 2005-10-02 05:29:54 +0000 |
---|---|---|
committer | Thomas Fitzsimmons <fitzsim@redhat.com> | 2005-10-02 05:29:54 +0000 |
commit | 08510d2cd68b43ccbfa7b04a237cc7b76cf157f1 (patch) | |
tree | 5839b2169dd9bbfa3d30217e13b46b665a30acd7 /javax/imageio/ImageIO.java | |
parent | 2e01606db66ab085f9c909df5eb51fc8b6b83642 (diff) | |
download | classpath-08510d2cd68b43ccbfa7b04a237cc7b76cf157f1.tar.gz |
2005-10-02 Thomas Fitzsimmons <fitzsim@redhat.com>
* javax/imageio/IIOException.java: Document.
* javax/imageio/IIOImage.java: Document.
* javax/imageio/IIOParam.java: Complete and document.
* javax/imageio/IIOParamController.java: Document.
* javax/imageio/ImageIO.java: Complete and document.
* javax/imageio/ImageReader.java: Complete and document.
* javax/imageio/ImageTranscoder.java: Document.
* javax/imageio/ImageTypeSpecifier.java: Complete and document.
* javax/imageio/ImageWriter.java: Complete and document.
* javax/imageio/package.html: Write.
Diffstat (limited to 'javax/imageio/ImageIO.java')
-rw-r--r-- | javax/imageio/ImageIO.java | 568 |
1 files changed, 551 insertions, 17 deletions
diff --git a/javax/imageio/ImageIO.java b/javax/imageio/ImageIO.java index 95c7c3251..6fc3365c9 100644 --- a/javax/imageio/ImageIO.java +++ b/javax/imageio/ImageIO.java @@ -60,12 +60,18 @@ import javax.imageio.stream.ImageOutputStream; import javax.imageio.stream.MemoryCacheImageInputStream; import javax.imageio.stream.MemoryCacheImageOutputStream; +/** + * An uninstantiable class that provides static methods for locating + * and using image readers and writers. + */ public final class ImageIO { /** - * This class isn't intended to be instantiated. + * Construct an ImageIO. Private since ImageIO is not instantiable. */ - private ImageIO() {} + private ImageIO() + { + } private static final class ReaderFormatFilter implements ServiceRegistry.Filter { @@ -117,13 +123,13 @@ public final class ImageIO } } - private static final class ReaderSuffixFilter implements ServiceRegistry.Filter + private static final class ReaderObjectFilter implements ServiceRegistry.Filter { - private String fileSuffix; + private Object object; - public ReaderSuffixFilter(String fileSuffix) + public ReaderObjectFilter(Object object) { - this.fileSuffix = fileSuffix; + this.object = object; } public boolean filter(Object provider) @@ -131,17 +137,15 @@ public final class ImageIO if (provider instanceof ImageReaderSpi) { ImageReaderSpi spi = (ImageReaderSpi) provider; - String[] suffixes = spi.getFileSuffixes(); - for (int i = suffixes.length - 1; i >= 0; --i) - if (fileSuffix.equals(suffixes[i])) - return true; + if (spi.canDecodeInput(object)) + return true; } return false; } } - + private static final class WriterFormatFilter implements ServiceRegistry.Filter { private String formatName; @@ -217,6 +221,66 @@ public final class ImageIO } } + private static final class WriterObjectFilter implements ServiceRegistry.Filter + { + private ImageTypeSpecifier type; + private String formatName; + + public WriterObjectFilter(ImageTypeSpecifier type, + String formatName) + { + this.type = type; + this.formatName = formatName; + } + + public boolean filter(Object provider) + { + if (provider instanceof ImageWriterSpi) + { + ImageWriterSpi spi = (ImageWriterSpi) provider; + + if (spi.canEncodeImage(type)) + { + String[] formatNames = spi.getFormatNames(); + for (int i = formatNames.length - 1; i >= 0; --i) + if (formatName.equals(formatNames[i])) + return true; + } + } + + return false; + } + } + + private static final class TranscoderFilter implements ServiceRegistry.Filter + { + private ImageReader reader; + private ImageWriter writer; + + public WriterObjectFilter(ImageReader reader, + ImageWriter writer) + { + this.reader = reader; + this.writer = writer; + } + + public boolean filter(Object provider) + { + if (provider instanceof ImageTranscoderSpi) + { + ImageTranscoderSpi spi = (ImageTranscoderSpi) provider; + + if (spi.getReaderServiceProviderName().equals + (reader.getOriginatingProvider().getClass().getName()) + && spi.getWriterServiceProviderName().equals + (writer.getOriginatingProvider().getClass().getName())) + return true; + } + + return false; + } + } + private static final class ImageReaderIterator implements Iterator { Iterator it; @@ -318,11 +382,26 @@ public final class ImageIO } } + /** + * Retrieve the current cache directory. + * + * @return the current cache directory or null if none is set. + */ public static File getCacheDirectory() { return cacheDirectory; } + /** + * Retrieve an iterator over all registered readers for the given + * format. + * + * @param formatName an infomal format name (e.g. "jpeg" or "bmp") + * + * @return an iterator over a collection of image readers + * + * @exception IllegalArgumentException if formatName is null + */ public static Iterator getImageReadersByFormatName(String formatName) { if (formatName == null) @@ -333,6 +412,17 @@ public final class ImageIO formatName); } + /** + * Retrieve an iterator over all registered readers for the given + * MIME type. + * + * @param MIMEType a MIME specification for an image type + * (e.g. "image/jpeg" or "image/x-bmp") + * + * @return an iterator over a collection of image readers + * + * @exception IllegalArgumentException if MIMEType is null + */ public static Iterator getImageReadersByMIMEType(String MIMEType) { if (MIMEType == null) @@ -343,6 +433,16 @@ public final class ImageIO MIMEType); } + /** + * Retrieve an iterator over all registered readers for the given + * file suffix. + * + * @param fileSuffix an image file suffix (e.g. "jpg" or "bmp") + * + * @return an iterator over a collection of image readers + * + * @exception IllegalArgumentException if fileSuffix is null + */ public static Iterator getImageReadersBySuffix(String fileSuffix) { if (fileSuffix == null) @@ -353,6 +453,16 @@ public final class ImageIO fileSuffix); } + /** + * Retrieve an iterator over all registered writers for the given + * format. + * + * @param formatName an infomal format name (e.g. "jpeg" or "bmp") + * + * @return an iterator over a collection of image writers + * + * @exception IllegalArgumentException if formatName is null + */ public static Iterator getImageWritersByFormatName(String formatName) { if (formatName == null) @@ -363,6 +473,17 @@ public final class ImageIO formatName); } + /** + * Retrieve an iterator over all registered writers for the given + * MIME type. + * + * @param MIMEType a MIME specification for an image type + * (e.g. "image/jpeg" or "image/x-bmp") + * + * @return an iterator over a collection of image writers + * + * @exception IllegalArgumentException if MIMEType is null + */ public static Iterator getImageWritersByMIMEType(String MIMEType) { if (MIMEType == null) @@ -373,6 +494,16 @@ public final class ImageIO MIMEType); } + /** + * Retrieve an iterator over all registered writers for the given + * file suffix. + * + * @param fileSuffix an image file suffix (e.g. "jpg" or "bmp") + * + * @return an iterator over a collection of image writers + * + * @exception IllegalArgumentException if fileSuffix is null + */ public static Iterator getImageWritersBySuffix(String fileSuffix) { if (fileSuffix == null) @@ -383,6 +514,12 @@ public final class ImageIO fileSuffix); } + /** + * Retrieve all the informal format names supported by the + * collection of registered image readers. + * + * @return an array of format names + */ public static String[] getReaderFormatNames() { try @@ -408,6 +545,12 @@ public final class ImageIO } } + /** + * Retrieve all the MIME types supported by the collection of + * registered image readers. + * + * @return an array of MIME types + */ public static String[] getReaderMIMETypes() { try @@ -438,11 +581,23 @@ public final class ImageIO return IIORegistry.getDefaultInstance(); } + /** + * Check whether or not an on-disk cache is used for image input and + * output streams. + * + * @return true if an on-disk cache is available, false otherwise + */ public static boolean getUseCache() { return useCache; } + /** + * Retrieve all the informal format names supported by the + * collection of registered image writers. + * + * @return an array of format names + */ public static String[] getWriterFormatNames() { try @@ -468,6 +623,12 @@ public final class ImageIO } } + /** + * Retrieve all the MIME types supported by the collection of + * registered image writers. + * + * @return an array of MIME types + */ public static String[] getWriterMIMETypes() { try @@ -502,8 +663,20 @@ public final class ImageIO IIORegistry.getDefaultInstance().registerApplicationClasspathSpis(); } + /** + * Set the directory to be used for caching image data. A null + * argument means to use the default system temporary directory. + * This cache directory is only used if getUseCache returns true. + * + * @param cacheDirectory the directory where image data should be + * cached + * + * @exception IllegalArgumentException if cacheDirectory is not a + * directory + */ public static void setCacheDirectory(File cacheDirectory) { + // FIXME: add SecurityManager call if (cacheDirectory != null) { if (!cacheDirectory.isDirectory()) @@ -515,37 +688,98 @@ public final class ImageIO ImageIO.cacheDirectory = cacheDirectory; } + /** + * Control whether or not an on-disk cache is used. This cache is + * used to store input or output data from an image data stream when + * data in the stream needs to be re-processed. + * + * If useCache is false the cache will be stored in memory. Doing + * so eliminates file creation and deletion overhead. The default + * is to use an on-disk cache. + * + * @param useCache true to use an on-disk cache, false otherwise + */ public static void setUseCache(boolean useCache) { ImageIO.useCache = useCache; } - /* - * "Standard" simplified entry points. + /** + * Write an image to a file using a registered writer that supports + * the given format, overwriting the file if it already exists. + * + * @param im the image data to write + * @param formatName an informal description of the output format + * @param output the file to which the image will be written + * + * @return false if no registered writer supports the given format, + * true otherwise + * + * @exception IllegalArgumentException if any argument is null + * @exception IOException if a writing error occurs */ - public static boolean write(RenderedImage im, String formatName, File output) throws IOException { + if (im == null || formatName == null || output == null) + throw new IllegalArgumentException ("null argument"); + return write(im, formatName, new FileOutputStream(output)); } + /** + * Write an image to an output stream using a registered writer that + * supports the given format. + * + * @param im the image data to write + * @param formatName an informal description of the output format + * @param output the output stream to which the image will be + * written + * + * @return false if no registered writer supports the given format, + * true otherwise + * + * @exception IllegalArgumentException if any argument is null + * @exception IOException if a writing error occurs + */ public static boolean write(RenderedImage im, String formatName, OutputStream output) throws IOException { + if (im == null || formatName == null || output == null) + throw new IllegalArgumentException ("null argument"); + return write(im, formatName, new MemoryCacheImageOutputStream(output)); } - - + + /** + * Write an image to an ImageOutputStream using a registered writer + * that supports the given format. Image data is written starting + * at the ImageOutputStream's current stream pointer, overwriting + * any existing data. + * + * @param im the image data to write + * @param formatName an informal description of the output format + * @param output the image output stream to which the image will be + * written + * + * @return false if no registered writer supports the given format, + * true otherwise + * + * @exception IllegalArgumentException if any argument is null + * @exception IOException if a writing error occurs + */ public static boolean write(RenderedImage im, String formatName, ImageOutputStream output) throws IOException { + if (im == null || formatName == null || output == null) + throw new IllegalArgumentException ("null argument"); + Iterator writers = getImageWritersByFormatName(formatName); IIOImage img = new IIOImage(im, null, null); while (writers.hasNext()) @@ -567,9 +801,27 @@ public final class ImageIO return false; } + /** + * Create a buffered image from an image input stream. An image + * reader that supports the given image data is automatically + * selected from the collection of registered readers. If no + * registered reader can handle the input format, null is returned. + * + * @param stream the image input stream from which to read image + * data + * + * @return a new buffered image created from the given image data, + * or null + * + * @exception IllegalArgumentException if stream is null + * @exception IOException if a reading error occurs + */ public static BufferedImage read(ImageInputStream stream) throws IOException { + if (stream == null) + throw new IllegalArgumentException("null argument"); + Iterator providers = getRegistry().getServiceProviders(ImageReaderSpi.class, true); while (providers.hasNext()) { @@ -583,23 +835,305 @@ public final class ImageIO } return null; } - + + /** + * Create a buffered image from a URL. An image reader that + * supports the given image data is automatically selected from the + * collection of registered readers. If no registered reader can + * handle the input format, null is returned. + * + * The image data will be cached in the current cache directory if + * caching is enabled. + * + * This method does not locate readers that read data directly from + * a URL. To locate such readers manually, use IIORegistry and + * ImageReaderSpi. + * + * @param input the URL from which to retrieve the image file + * + * @return a new buffered image created from the given image URL, or + * null + * + * @exception IllegalArgumentException if input is null + * @exception IOException if a reading error occurs + */ public static BufferedImage read(URL input) throws IOException { + if (input == null) + throw new IllegalArgumentException("null argument"); + return read(input.openStream()); } + /** + * Create a buffered image from an input stream. An image reader + * that supports the given image data is automatically selected from + * the collection of registered readers. If no registered reader + * can handle the input format, null is returned. + * + * The image data will be cached in the current cache directory if + * caching is enabled. + * + * This method does not locate readers that read data directly from + * an input stream. To locate such readers manually, use + * IIORegistry and ImageReaderSpi. + * + * @param input the input stream from which to read the image data + * + * @return a new buffered image created from the given input stream, + * or null + * + * @exception IllegalArgumentException if input is null + * @exception IOException if a reading error occurs + */ public static BufferedImage read(InputStream input) throws IOException { + if (input == null) + throw new IllegalArgumentException("null argument"); + return read(new MemoryCacheImageInputStream(input)); } + /** + * Create a buffered image from a file. An image reader that + * supports the given image data is automatically selected from the + * collection of registered readers. If no registered reader can + * handle the input format, null is returned. + * + * The image data will be cached in the current cache directory if + * caching is enabled. + * + * This method does not locate readers that read data directly from + * a file. To locate such readers manually, use IIORegistry and + * ImageReaderSpi. + * + * @param input the file from which to read image data + * + * @return a new buffered image created from the given image file, + * or null + * + * @exception IllegalArgumentException if input is null + * @exception IOException if a reading error occurs + */ public static BufferedImage read(File input) throws IOException { + if (input == null) + throw new IllegalArgumentException("null argument"); + return read(new FileInputStream(input)); } + /** + * Create an image input stream from the given object. The + * collection of ImageInputStreamSpis registered with the + * IIORegistry is searched for an image input stream that can take + * input from the given object. null is returned if no such SPI is + * registered. + * + * The image data will be cached in the current cache directory if + * caching is enabled. + * + * @param input an object from which to read image data + * + * @return an ImageInputStream that can read data from input, or + * null + * + * @exception IllegalArgumentException if input is null + * @exception IOException if caching is required but not enabled + */ + public static ImageInputStream createImageInputStream (Object input) + throws IOException + { + if (input == null) + throw new IllegalArgumentException ("null argument"); + + Iterator spis = getRegistry().getServiceProviders + (ImageInputStreamSpi.class, true); + + ImageInputStreamSpi foundSpi = null; + + while(spis.hasNext()) + { + ImageInputStreamSpi spi = (ImageInputStreamSpi) spis.next(); + + if (input instanceof spi.getInputClass()) + { + foundSpi = spi; + break; + } + } + + if (foundSpi == false) + return null; + else + return foundSpi.createInputStreamInstance (input, + getUseCache(), + getCacheDirectory()); + } + + /** + * Create an image output stream from the given object. The + * collection of ImageOutputStreamSpis registered with the + * IIORegistry is searched for an image output stream that can send + * output to the given object. null is returned if no such SPI is + * registered. + * + * The image data will be cached in the current cache directory if + * caching is enabled. + * + * @param input an object to which to write image data + * + * @return an ImageOutputStream that can send data to output, or + * null + * + * @exception IllegalArgumentException if output is null + * @exception IOException if caching is required but not enabled + */ + public static ImageOutputStream createImageOutputStream (Object output) + throws IOException + { + if (output == null) + throw new IllegalArgumentException ("null argument"); + + Iterator spis = getRegistry().getServiceProviders + (ImageOutputStreamSpi.class, true); + + ImageOutputStreamSpi foundSpi = null; + + while(spis.hasNext()) + { + ImageOutputStreamSpi spi = (ImageOutputStreamSpi) spis.next(); + + if (input instanceof spi.getOutputClass()) + { + foundSpi = spi; + break; + } + } + + if (foundSpi == false) + return null; + else + return foundSpi.createOutputStreamInstance (input, + getUseCache(), + getCacheDirectory()); + } + + /** + * Retrieve an image reader corresponding to an image writer, or + * null if writer is not registered or if no corresponding reader is + * registered. + * + * @param writer a registered image writer + * + * @return an image reader corresponding to writer, or null + * + * @exception IllegalArgumentException if writer is null + */ + public static ImageReader getImageReader (ImageWriter writer) + { + if (writer == null) + throw new IllegalArgumentException ("null argument"); + + ImageWriterSpi spi = (ImageWriterSpi) getRegistry() + .getServiceProviderByClass(writer.getClass()); + + String[] readerSpiNames = spi.getImageReaderSpiNames(); + + return readerSpiNames == null ? null : readerSpiNames[0]; + } + + /** + * Retrieve an iterator over the collection of registered image + * readers that support reading data from the given object. + * + * @param input the object for which to retrieve image readers + * + * @return an iterator over a collection of image readers + */ + public static Iterator getImageReaders (Object input) + { + if (input == null) + throw new IllegalArgumentException ("null argument"); + + return getRegistry().getServiceProviders (ImageReaderSpi.class, + new ReaderObjectFilter(object), + true); + } + + /** + * Retrieve an iterator over the collection of registered image + * writers that support writing images of the given type and in the + * given format. + * + * @param type the output image's colour and sample models + * @param formatName the output image format + * + * @return an iterator over a collection of image writers + */ + public static Iterator getImageWriters (ImageTypeSpecifier type, + String formatName) + { + if (type == null || formatName == null) + throw new IllegalArgumentException ("null argument"); + + return getRegistry().getServiceProviders (ImageWriterSpi.class, + new WriterObjectFilter(object), + true); + } + + /** + * Retrieve an image writer corresponding to an image reader, or + * null if reader is not registered or if no corresponding writer is + * registered. This method is useful for preserving metadata + * without needing to understand its format, since the returned + * writer will be able to write, unchanged, the metadata passed to + * it by the reader. + * + * @param reader a registered image reader + * + * @return an image writer corresponding to reader, or null + * + * @exception IllegalArgumentException if reader is null + */ + public static ImageWriter getImageWriter (ImageReader reader) + { + if (reader == null) + throw new IllegalArgumentException ("null argument"); + + ImageReaderSpi spi = (ImageReaderSpi) getRegistry() + .getServiceProviderByClass(reader.getClass()); + + String[] writerSpiNames = spi.getImageWriterSpiNames(); + + return writerSpiNames == null ? null : writerSpiNames[0]; + } + + /** + * Retrieve an iterator over a collection of image transcoders that + * support transcoding from the given image reader's metadata format + * to the given writer's metadata format. + * + * @param reader an image reader + * @param writer an image writer + * + * @return an iterator over a collection of image transcoders + * + * @exception IllegalArgumentException if either reader or writer is + * null + */ + public static Iterator getImageTranscoders (ImageReader reader, + ImageWriter writer) + { + if (reader == null || writer == null) + throw new IllegalArgumentException ("null argument"); + + return getRegistry().getServiceProviders (ImageTranscoderSpi.class, + new ImageTranscoderSpi (reader, + writer), + true); + } } |