* * @return the current <code>Locale</code>, or <code>null</code>. * * @see #setLocale */ public Locale getLocale() { return locale; } // Image queries /** * Returns the number of images, not including thumbnails, available * from the current input source. * * <p> Note that some image formats (such as animated GIF) do not * specify how many images are present in the stream. Thus * determining the number of images will require the entire stream * to be scanned and may require memory for buffering. If images * are to be processed in order, it may be more efficient to * simply call <code>read</code> with increasing indices until an * <code>IndexOutOfBoundsException</code> is thrown to indicate * that no more images are available. The * <code>allowSearch</code> parameter may be set to * <code>false</code> to indicate that an exhaustive search is not * desired; the return value will be <code>-1</code> to indicate * that a search is necessary. If the input has been specified * with <code>seekForwardOnly</code> set to <code>true</code>, * this method throws an <code>IllegalStateException</code> if * <code>allowSearch</code> is set to <code>true</code>. * * @param allowSearch if <code>true</code>, the true number of * images will be returned even if a search is required. If * <code>false</code>, the reader may return <code>-1</code> * without performing the search. * * @return the number of images, as an <code>int</code>, or * <code>-1</code> if <code>allowSearch</code> is * <code>false</code> and a search would be required. * * @exception IllegalStateException if the input source has not been set, * or if the input has been specified with <code>seekForwardOnly</code> * set to <code>true</code>. * @exception IOException if an error occurs reading the * information from the input source. * * @see #setInput */ public abstract int getNumImages(boolean allowSearch) throws IOException; /** * Returns the width in pixels of the given image within the input * source. * * <p> If the image can be rendered to a user-specified size, then * this method returns the default width. * * @param imageIndex the index of the image to be queried. * * @return the width of the image, as an <code>int</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the width * information from the input source. */ public abstract int getWidth(int imageIndex) throws IOException; /** * Returns the height in pixels of the given image within the * input source. * * <p> If the image can be rendered to a user-specified size, then * this method returns the default height. * * @param imageIndex the index of the image to be queried. * * @return the height of the image, as an <code>int</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the height * information from the input source. */ public abstract int getHeight(int imageIndex) throws IOException; /** * Returns <code>true</code> if the storage format of the given * image places no inherent impediment on random access to pixels. * For most compressed formats, such as JPEG, this method should * return <code>false</code>, as a large section of the image in * addition to the region of interest may need to be decoded. * * <p> This is merely a hint for programs that wish to be * efficient; all readers must be able to read arbitrary regions * as specified in an <code>ImageReadParam</code>. * * <p> Note that formats that return <code>false</code> from * this method may nonetheless allow tiling (<i>e.g.</i> Restart * Markers in JPEG), and random access will likely be reasonably * efficient on tiles. See {@link #isImageTiled * <code>isImageTiled</code>}. * * <p> A reader for which all images are guaranteed to support * easy random access, or are guaranteed not to support easy * random access, may return <code>true</code> or * <code>false</code> respectively without accessing any image * data. In such cases, it is not necessary to throw an exception * even if no input source has been set or the image index is out * of bounds. * * <p> The default implementation returns <code>false</code>. * * @param imageIndex the index of the image to be queried. * * @return <code>true</code> if reading a region of interest of * the given image is likely to be efficient. * * @exception IllegalStateException if an input source is required * to determine the return value, but none has been set. * @exception IndexOutOfBoundsException if an image must be * accessed to determine the return value, but the supplied index * is out of bounds. * @exception IOException if an error occurs during reading. */ public boolean isRandomAccessEasy(int imageIndex) throws IOException { return false; } /** * Returns the aspect ratio of the given image (that is, its width * divided by its height) as a <code>float</code>. For images * that are inherently resizable, this method provides a way to * determine the appropriate width given a deired height, or vice * versa. For non-resizable images, the true width and height * are used. * * <p> The default implementation simply returns * <code>(float)getWidth(imageIndex)/getHeight(imageIndex)</code>. * * @param imageIndex the index of the image to be queried. * * @return a <code>float</code> indicating the aspect ratio of the * given image. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public float getAspectRatio(int imageIndex) throws IOException { return (float)getWidth(imageIndex)/getHeight(imageIndex); } /** * Returns an <code>ImageTypeSpecifier</code> indicating the * <code>SampleModel</code> and <code>ColorModel</code> which most * closely represents the "raw" internal format of the image. For * example, for a JPEG image the raw type might have a YCbCr color * space even though the image would conventionally be transformed * into an RGB color space prior to display. The returned value * should also be included in the list of values returned by * <code>getImageTypes</code>. * * <p> The default implementation simply returns the first entry * from the list provided by <code>getImageType</code>. * * @param imageIndex the index of the image to be queried. * * @return an <code>ImageTypeSpecifier</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the format * information from the input source. */ public ImageTypeSpecifier getRawImageType(int imageIndex) throws IOException { return (ImageTypeSpecifier)getImageTypes(imageIndex).next(); } /** * Returns an <code>Iterator</code> containing possible image * types to which the given image may be decoded, in the form of * <code>ImageTypeSpecifiers</code>s. At least one legal image * type will be returned. * * <p> The first element of the iterator should be the most * "natural" type for decoding the image with as little loss as * possible. For example, for a JPEG image the first entry should * be an RGB image, even though the image data is stored * internally in a YCbCr color space. * * @param imageIndex the index of the image to be * <code>retrieved</code>. * * @return an <code>Iterator</code> containing at least one * <code>ImageTypeSpecifier</code> representing suggested image * types for decoding the current given image. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the format * information from the input source. * * @see ImageReadParam#setDestination(BufferedImage) * @see ImageReadParam#setDestinationType(ImageTypeSpecifier) */ public abstract Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex) throws IOException; /** * Returns a default <code>ImageReadParam</code> object * appropriate for this format. All subclasses should define a * set of default values for all parameters and return them with * this call. This method may be called before the input source * is set. * * <p> The default implementation constructs and returns a new * <code>ImageReadParam</code> object that does not allow source * scaling (<i>i.e.</i>, it returns <code>new * ImageReadParam()</code>. * * @return an <code>ImageReadParam</code> object which may be used * to control the decoding process using a set of default settings. */ public ImageReadParam getDefaultReadParam() { return new ImageReadParam(); } /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the input source as a whole (i.e., not * associated with any particular image), or <code>null</code> if * the reader does not support reading metadata, is set to ignore * metadata, or if no metadata is available. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IOException if an error occurs during reading. */ public abstract IIOMetadata getStreamMetadata() throws IOException; /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the input source as a whole (i.e., * not associated with any particular image). If no such data * exists, <code>null</code> is returned. * * <p> The resuting metadata object is only responsible for * returning documents in the format named by * <code>formatName</code>. Within any documents that are * returned, only nodes whose names are members of * <code>nodeNames</code> are required to be returned. In this * way, the amount of metadata processing done by the reader may * be kept to a minimum, based on what information is actually * needed. * * <p> If <code>formatName</code> is not the name of a supported * metadata format, <code>null</code> is returned. * * <p> In all cases, it is legal to return a more capable metadata * object than strictly necessary. The format name and node names * are merely hints that may be used to reduce the reader's * workload. * * <p> The default implementation simply returns the result of * calling <code>getStreamMetadata()</code>, after checking that * the format name is supported. If it is not, * <code>null</code> is returned. * * @param formatName a metadata format name that may be used to retrieve * a document from the returned <code>IIOMetadata</code> object. * @param nodeNames a <code>Set</code> containing the names of * nodes that may be contained in a retrieved document. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code>. * @exception IllegalArgumentException if <code>nodeNames</code> * is <code>null</code>. * @exception IOException if an error occurs during reading. */ public IIOMetadata getStreamMetadata(String formatName, Set<String> nodeNames) throws IOException { return getMetadata(formatName, nodeNames, true, 0); } private IIOMetadata getMetadata(String formatName, Set nodeNames, boolean wantStream, int imageIndex) throws IOException { if (formatName == null) { throw new IllegalArgumentException("formatName == null!"); } if (nodeNames == null) { throw new IllegalArgumentException("nodeNames == null!"); } IIOMetadata metadata = wantStream ? getStreamMetadata() : getImageMetadata(imageIndex); if (metadata != null) { if (metadata.isStandardMetadataFormatSupported() && formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName)) { return metadata; } String nativeName = metadata.getNativeMetadataFormatName(); if (nativeName != null && formatName.equals(nativeName)) { return metadata; } String[] extraNames = metadata.getExtraMetadataFormatNames(); if (extraNames != null) { for (int i = 0; i < extraNames.length; i++) { if (formatName.equals(extraNames[i])) { return metadata; } } } } return null; } /** * Returns an <code>IIOMetadata</code> object containing metadata * associated with the given image, or <code>null</code> if the * reader does not support reading metadata, is set to ignore * metadata, or if no metadata is available. * * @param imageIndex the index of the image whose metadata is to * be retrieved. * * @return an <code>IIOMetadata</code> object, or * <code>null</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public abstract IIOMetadata getImageMetadata(int imageIndex) throws IOException; /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the given image, or <code>null</code> * if the reader does not support reading metadata or none * is available. * * <p> The resuting metadata object is only responsible for * returning documents in the format named by * <code>formatName</code>. Within any documents that are * returned, only nodes whose names are members of * <code>nodeNames</code> are required to be returned. In this * way, the amount of metadata processing done by the reader may * be kept to a minimum, based on what information is actually * needed. * * <p> If <code>formatName</code> is not the name of a supported * metadata format, <code>null</code> may be returned. * * <p> In all cases, it is legal to return a more capable metadata * object than strictly necessary. The format name and node names * are merely hints that may be used to reduce the reader's * workload. * * <p> The default implementation simply returns the result of * calling <code>getImageMetadata(imageIndex)</code>, after * checking that the format name is supported. If it is not, * <code>null</code> is returned. * * @param imageIndex the index of the image whose metadata is to * be retrieved. * @param formatName a metadata format name that may be used to retrieve * a document from the returned <code>IIOMetadata</code> object. * @param nodeNames a <code>Set</code> containing the names of * nodes that may be contained in a retrieved document. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code>. * @exception IllegalArgumentException if <code>nodeNames</code> * is <code>null</code>. * @exception IOException if an error occurs during reading. */ public IIOMetadata getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames) throws IOException { return getMetadata(formatName, nodeNames, false, imageIndex); } /** * Reads the image indexed by <code>imageIndex</code> and returns * it as a complete <code>BufferedImage</code>, using a default * <code>ImageReadParam</code>. This is a convenience method * that calls <code>read(imageIndex, null)</code>. * * <p> The image returned will be formatted according to the first * <code>ImageTypeSpecifier</code> returned from * <code>getImageTypes</code>. * * <p> Any registered <code>IIOReadProgressListener</code> objects * will be notified by calling their <code>imageStarted</code> * method, followed by calls to their <code>imageProgress</code> * method as the read progresses. Finally their * <code>imageComplete</code> method will be called. * <code>IIOReadUpdateListener</code> objects may be updated at * other times during the read as pixels are decoded. Finally, * <code>IIOReadWarningListener</code> objects will receive * notification of any non-fatal warnings that occur during * decoding. * * @param imageIndex the index of the image to be retrieved. * * @return the desired portion of the image as a * <code>BufferedImage</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public BufferedImage read(int imageIndex) throws IOException { return read(imageIndex, null); } /** * Reads the image indexed by <code>imageIndex</code> and returns * it as a complete <code>BufferedImage</code>, using a supplied * <code>ImageReadParam</code>. * * <p> The actual <code>BufferedImage</code> returned will be * chosen using the algorithm defined by the * <code>getDestination</code> method. * * <p> Any registered <code>IIOReadProgressListener</code> objects * will be notified by calling their <code>imageStarted</code> * method, followed by calls to their <code>imageProgress</code> * method as the read progresses. Finally their * <code>imageComplete</code> method will be called. * <code>IIOReadUpdateListener</code> objects may be updated at * other times during the read as pixels are decoded. Finally, * <code>IIOReadWarningListener</code> objects will receive * notification of any non-fatal warnings that occur during * decoding. * * <p> The set of source bands to be read and destination bands to * be written is determined by calling <code>getSourceBands</code> * and <code>getDestinationBands</code> on the supplied * <code>ImageReadParam</code>. If the lengths of the arrays * returned by these methods differ, the set of source bands * contains an index larger that the largest available source * index, or the set of destination bands contains an index larger * than the largest legal destination index, an * <code>IllegalArgumentException</code> is thrown. * * <p> If the supplied <code>ImageReadParam</code> contains * optional setting values not supported by this reader (<i>e.g.</i> * source render size or any format-specific settings), they will * be ignored. * * @param imageIndex the index of the image to be retrieved. * @param param an <code>ImageReadParam</code> used to control * the reading process, or <code>null</code>. * * @return the desired portion of the image as a * <code>BufferedImage</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IllegalArgumentException if the set of source and * destination bands specified by * <code>param.getSourceBands</code> and * <code>param.getDestinationBands</code> differ in length or * include indices that are out of bounds. * @exception IllegalArgumentException if the resulting image would * have a width or height less than 1. * @exception IOException if an error occurs during reading. */ public abstract BufferedImage read(int imageIndex, ImageReadParam param) throws IOException; Lines 501–1000 of 2898. Previous lines Load more
* * @return the current <code>Locale</code>, or <code>null</code>. * * @see #setLocale */ public Locale getLocale() { return locale; } // Image queries /** * Returns the number of images, not including thumbnails, available * from the current input source. * * <p> Note that some image formats (such as animated GIF) do not * specify how many images are present in the stream. Thus * determining the number of images will require the entire stream * to be scanned and may require memory for buffering. If images * are to be processed in order, it may be more efficient to * simply call <code>read</code> with increasing indices until an * <code>IndexOutOfBoundsException</code> is thrown to indicate * that no more images are available. The * <code>allowSearch</code> parameter may be set to * <code>false</code> to indicate that an exhaustive search is not * desired; the return value will be <code>-1</code> to indicate * that a search is necessary. If the input has been specified * with <code>seekForwardOnly</code> set to <code>true</code>, * this method throws an <code>IllegalStateException</code> if * <code>allowSearch</code> is set to <code>true</code>. * * @param allowSearch if <code>true</code>, the true number of * images will be returned even if a search is required. If * <code>false</code>, the reader may return <code>-1</code> * without performing the search. * * @return the number of images, as an <code>int</code>, or * <code>-1</code> if <code>allowSearch</code> is * <code>false</code> and a search would be required. * * @exception IllegalStateException if the input source has not been set, * or if the input has been specified with <code>seekForwardOnly</code> * set to <code>true</code>. * @exception IOException if an error occurs reading the * information from the input source. * * @see #setInput */ public abstract int getNumImages(boolean allowSearch) throws IOException; /** * Returns the width in pixels of the given image within the input * source. * * <p> If the image can be rendered to a user-specified size, then * this method returns the default width. * * @param imageIndex the index of the image to be queried. * * @return the width of the image, as an <code>int</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the width * information from the input source. */ public abstract int getWidth(int imageIndex) throws IOException; /** * Returns the height in pixels of the given image within the * input source. * * <p> If the image can be rendered to a user-specified size, then * this method returns the default height. * * @param imageIndex the index of the image to be queried. * * @return the height of the image, as an <code>int</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the height * information from the input source. */ public abstract int getHeight(int imageIndex) throws IOException; /** * Returns <code>true</code> if the storage format of the given * image places no inherent impediment on random access to pixels. * For most compressed formats, such as JPEG, this method should * return <code>false</code>, as a large section of the image in * addition to the region of interest may need to be decoded. * * <p> This is merely a hint for programs that wish to be * efficient; all readers must be able to read arbitrary regions * as specified in an <code>ImageReadParam</code>. * * <p> Note that formats that return <code>false</code> from * this method may nonetheless allow tiling (<i>e.g.</i> Restart * Markers in JPEG), and random access will likely be reasonably * efficient on tiles. See {@link #isImageTiled * <code>isImageTiled</code>}. * * <p> A reader for which all images are guaranteed to support * easy random access, or are guaranteed not to support easy * random access, may return <code>true</code> or * <code>false</code> respectively without accessing any image * data. In such cases, it is not necessary to throw an exception * even if no input source has been set or the image index is out * of bounds. * * <p> The default implementation returns <code>false</code>. * * @param imageIndex the index of the image to be queried. * * @return <code>true</code> if reading a region of interest of * the given image is likely to be efficient. * * @exception IllegalStateException if an input source is required * to determine the return value, but none has been set. * @exception IndexOutOfBoundsException if an image must be * accessed to determine the return value, but the supplied index * is out of bounds. * @exception IOException if an error occurs during reading. */ public boolean isRandomAccessEasy(int imageIndex) throws IOException { return false; } /** * Returns the aspect ratio of the given image (that is, its width * divided by its height) as a <code>float</code>. For images * that are inherently resizable, this method provides a way to * determine the appropriate width given a deired height, or vice * versa. For non-resizable images, the true width and height * are used. * * <p> The default implementation simply returns * <code>(float)getWidth(imageIndex)/getHeight(imageIndex)</code>. * * @param imageIndex the index of the image to be queried. * * @return a <code>float</code> indicating the aspect ratio of the * given image. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public float getAspectRatio(int imageIndex) throws IOException { return (float)getWidth(imageIndex)/getHeight(imageIndex); } /** * Returns an <code>ImageTypeSpecifier</code> indicating the * <code>SampleModel</code> and <code>ColorModel</code> which most * closely represents the "raw" internal format of the image. For * example, for a JPEG image the raw type might have a YCbCr color * space even though the image would conventionally be transformed * into an RGB color space prior to display. The returned value * should also be included in the list of values returned by * <code>getImageTypes</code>. * * <p> The default implementation simply returns the first entry * from the list provided by <code>getImageType</code>. * * @param imageIndex the index of the image to be queried. * * @return an <code>ImageTypeSpecifier</code>. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the format * information from the input source. */ public ImageTypeSpecifier getRawImageType(int imageIndex) throws IOException { return (ImageTypeSpecifier)getImageTypes(imageIndex).next(); } /** * Returns an <code>Iterator</code> containing possible image * types to which the given image may be decoded, in the form of * <code>ImageTypeSpecifiers</code>s. At least one legal image * type will be returned. * * <p> The first element of the iterator should be the most * "natural" type for decoding the image with as little loss as * possible. For example, for a JPEG image the first entry should * be an RGB image, even though the image data is stored * internally in a YCbCr color space. * * @param imageIndex the index of the image to be * <code>retrieved</code>. * * @return an <code>Iterator</code> containing at least one * <code>ImageTypeSpecifier</code> representing suggested image * types for decoding the current given image. * * @exception IllegalStateException if the input source has not been set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs reading the format * information from the input source. * * @see ImageReadParam#setDestination(BufferedImage) * @see ImageReadParam#setDestinationType(ImageTypeSpecifier) */ public abstract Iterator<ImageTypeSpecifier> getImageTypes(int imageIndex) throws IOException; /** * Returns a default <code>ImageReadParam</code> object * appropriate for this format. All subclasses should define a * set of default values for all parameters and return them with * this call. This method may be called before the input source * is set. * * <p> The default implementation constructs and returns a new * <code>ImageReadParam</code> object that does not allow source * scaling (<i>i.e.</i>, it returns <code>new * ImageReadParam()</code>. * * @return an <code>ImageReadParam</code> object which may be used * to control the decoding process using a set of default settings. */ public ImageReadParam getDefaultReadParam() { return new ImageReadParam(); } /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the input source as a whole (i.e., not * associated with any particular image), or <code>null</code> if * the reader does not support reading metadata, is set to ignore * metadata, or if no metadata is available. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IOException if an error occurs during reading. */ public abstract IIOMetadata getStreamMetadata() throws IOException; /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the input source as a whole (i.e., * not associated with any particular image). If no such data * exists, <code>null</code> is returned. * * <p> The resuting metadata object is only responsible for * returning documents in the format named by * <code>formatName</code>. Within any documents that are * returned, only nodes whose names are members of * <code>nodeNames</code> are required to be returned. In this * way, the amount of metadata processing done by the reader may * be kept to a minimum, based on what information is actually * needed. * * <p> If <code>formatName</code> is not the name of a supported * metadata format, <code>null</code> is returned. * * <p> In all cases, it is legal to return a more capable metadata * object than strictly necessary. The format name and node names * are merely hints that may be used to reduce the reader's * workload. * * <p> The default implementation simply returns the result of * calling <code>getStreamMetadata()</code>, after checking that * the format name is supported. If it is not, * <code>null</code> is returned. * * @param formatName a metadata format name that may be used to retrieve * a document from the returned <code>IIOMetadata</code> object. * @param nodeNames a <code>Set</code> containing the names of * nodes that may be contained in a retrieved document. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code>. * @exception IllegalArgumentException if <code>nodeNames</code> * is <code>null</code>. * @exception IOException if an error occurs during reading. */ public IIOMetadata getStreamMetadata(String formatName, Set<String> nodeNames) throws IOException { return getMetadata(formatName, nodeNames, true, 0); } private IIOMetadata getMetadata(String formatName, Set nodeNames, boolean wantStream, int imageIndex) throws IOException { if (formatName == null) { throw new IllegalArgumentException("formatName == null!"); } if (nodeNames == null) { throw new IllegalArgumentException("nodeNames == null!"); } IIOMetadata metadata = wantStream ? getStreamMetadata() : getImageMetadata(imageIndex); if (metadata != null) { if (metadata.isStandardMetadataFormatSupported() && formatName.equals (IIOMetadataFormatImpl.standardMetadataFormatName)) { return metadata; } String nativeName = metadata.getNativeMetadataFormatName(); if (nativeName != null && formatName.equals(nativeName)) { return metadata; } String[] extraNames = metadata.getExtraMetadataFormatNames(); if (extraNames != null) { for (int i = 0; i < extraNames.length; i++) { if (formatName.equals(extraNames[i])) { return metadata; } } } } return null; } /** * Returns an <code>IIOMetadata</code> object containing metadata * associated with the given image, or <code>null</code> if the * reader does not support reading metadata, is set to ignore * metadata, or if no metadata is available. * * @param imageIndex the index of the image whose metadata is to * be retrieved. * * @return an <code>IIOMetadata</code> object, or * <code>null</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public abstract IIOMetadata getImageMetadata(int imageIndex) throws IOException; /** * Returns an <code>IIOMetadata</code> object representing the * metadata associated with the given image, or <code>null</code> * if the reader does not support reading metadata or none * is available. * * <p> The resuting metadata object is only responsible for * returning documents in the format named by * <code>formatName</code>. Within any documents that are * returned, only nodes whose names are members of * <code>nodeNames</code> are required to be returned. In this * way, the amount of metadata processing done by the reader may * be kept to a minimum, based on what information is actually * needed. * * <p> If <code>formatName</code> is not the name of a supported * metadata format, <code>null</code> may be returned. * * <p> In all cases, it is legal to return a more capable metadata * object than strictly necessary. The format name and node names * are merely hints that may be used to reduce the reader's * workload. * * <p> The default implementation simply returns the result of * calling <code>getImageMetadata(imageIndex)</code>, after * checking that the format name is supported. If it is not, * <code>null</code> is returned. * * @param imageIndex the index of the image whose metadata is to * be retrieved. * @param formatName a metadata format name that may be used to retrieve * a document from the returned <code>IIOMetadata</code> object. * @param nodeNames a <code>Set</code> containing the names of * nodes that may be contained in a retrieved document. * * @return an <code>IIOMetadata</code> object, or <code>null</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IllegalArgumentException if <code>formatName</code> * is <code>null</code>. * @exception IllegalArgumentException if <code>nodeNames</code> * is <code>null</code>. * @exception IOException if an error occurs during reading. */ public IIOMetadata getImageMetadata(int imageIndex, String formatName, Set<String> nodeNames) throws IOException { return getMetadata(formatName, nodeNames, false, imageIndex); } /** * Reads the image indexed by <code>imageIndex</code> and returns * it as a complete <code>BufferedImage</code>, using a default * <code>ImageReadParam</code>. This is a convenience method * that calls <code>read(imageIndex, null)</code>. * * <p> The image returned will be formatted according to the first * <code>ImageTypeSpecifier</code> returned from * <code>getImageTypes</code>. * * <p> Any registered <code>IIOReadProgressListener</code> objects * will be notified by calling their <code>imageStarted</code> * method, followed by calls to their <code>imageProgress</code> * method as the read progresses. Finally their * <code>imageComplete</code> method will be called. * <code>IIOReadUpdateListener</code> objects may be updated at * other times during the read as pixels are decoded. Finally, * <code>IIOReadWarningListener</code> objects will receive * notification of any non-fatal warnings that occur during * decoding. * * @param imageIndex the index of the image to be retrieved. * * @return the desired portion of the image as a * <code>BufferedImage</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IOException if an error occurs during reading. */ public BufferedImage read(int imageIndex) throws IOException { return read(imageIndex, null); } /** * Reads the image indexed by <code>imageIndex</code> and returns * it as a complete <code>BufferedImage</code>, using a supplied * <code>ImageReadParam</code>. * * <p> The actual <code>BufferedImage</code> returned will be * chosen using the algorithm defined by the * <code>getDestination</code> method. * * <p> Any registered <code>IIOReadProgressListener</code> objects * will be notified by calling their <code>imageStarted</code> * method, followed by calls to their <code>imageProgress</code> * method as the read progresses. Finally their * <code>imageComplete</code> method will be called. * <code>IIOReadUpdateListener</code> objects may be updated at * other times during the read as pixels are decoded. Finally, * <code>IIOReadWarningListener</code> objects will receive * notification of any non-fatal warnings that occur during * decoding. * * <p> The set of source bands to be read and destination bands to * be written is determined by calling <code>getSourceBands</code> * and <code>getDestinationBands</code> on the supplied * <code>ImageReadParam</code>. If the lengths of the arrays * returned by these methods differ, the set of source bands * contains an index larger that the largest available source * index, or the set of destination bands contains an index larger * than the largest legal destination index, an * <code>IllegalArgumentException</code> is thrown. * * <p> If the supplied <code>ImageReadParam</code> contains * optional setting values not supported by this reader (<i>e.g.</i> * source render size or any format-specific settings), they will * be ignored. * * @param imageIndex the index of the image to be retrieved. * @param param an <code>ImageReadParam</code> used to control * the reading process, or <code>null</code>. * * @return the desired portion of the image as a * <code>BufferedImage</code>. * * @exception IllegalStateException if the input source has not been * set. * @exception IndexOutOfBoundsException if the supplied index is * out of bounds. * @exception IllegalArgumentException if the set of source and * destination bands specified by * <code>param.getSourceBands</code> and * <code>param.getDestinationBands</code> differ in length or * include indices that are out of bounds. * @exception IllegalArgumentException if the resulting image would * have a width or height less than 1. * @exception IOException if an error occurs during reading. */ public abstract BufferedImage read(int imageIndex, ImageReadParam param) throws IOException;