Java Doc for ImageReadDescriptor.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » com » sun » media » jai » operator » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The "ImageRead" operation uses the Java Image I/O Framework to read images from an input source. Which formats may be read depends on which javax.imageio.ImageReader plug-ins are registered with the Image I/O Framework when the operation is invoked.

The input source will usually be an javax.imageio.stream.ImageInputStream , but may be a java.io.File , java.io.RandomAccessFile , java.io.InputStream , java.net.URL , java.net.Socket , java.nio.channels.ReadableByteChannel , file path represented as a String or some other type compatible with a reader plug-in. The javax.imageio.ImageIO class should be used to specify the location and enable the use of cache files via its setCacheDirectory() and setUseCache() methods, respectively. Note that this cache pertains to image stream caching and is unrelated to the JAI TileCache.

The "ImageRead" operation supports rendered, renderable, and collection modes and requires no source image. A java.awt.RenderingHints object may be supplied when the operation is created. In addition to the java.awt.RenderingHints.Key hints recognized by the eventual OpImage constructor, an ImageLayout hint may also be supplied. The settings of this ImageLayout override any other possible derivation of its components. In particular, it is possible that the generated image(s) have a different tile layout than that present in the image read from the input source.

Image properties are used to make available metadata and other information. Property provision is mode-specific.

Resource List

Name	Value
GlobalName	ImageRead
LocalName	ImageRead
Vendor	com.sun.media.jai
Description	Reads an image using the Java Image I/O Framework.
DocURL	http://java.sun.com/products/java-media/jai/forDevelopers/jai-imageio-1_0-rc-docs/com/sun/media/jai/operator/ImageReadDescriptor.html
Version	1.0
arg0Desc	The input source.
arg1Desc	The index or indices of the image(s) to read.
arg2Desc	Whether metadata should be read if available.
arg3Desc	Whether thumbnails should be read if available.
arg4Desc	Whether to verify the validity of the input source.
arg5Desc	EventListeners to be registered with the ImageReader.
arg6Desc	The Locale for the ImageReader to use.
arg7Desc	Java Image I/O read parameter instance.
arg8Desc	Java Image I/O reader instance.

Rendered Mode

Rendered Mode Parameters

• If Input is a String it is assumed to represent a file path. When the node is rendered, if Input is not already an ImageInputStream, then ImageIO.createImageInputStream() will be used to attempt to derive an ImageInputStream. If such an ImageInputStream is available, it will be set as the input of the ImageReader; otherwise the original value of Input will be used. Before attempting to apply createImageInputStream(), if Input is a String it will be converted to a RandomAccessFile, or if it is a Socket or a URL to an InputStream. If the conversion of the Input String to RandomAccessFile fails, it will be converted to an InputStream by accessing it as a resource bundled in a JAR file.
• If ImageChoice is negative an exception will be thrown when the operation is created.
• Image properties associated with metadata will be set if and only if ReadMetadata is TRUE and the respective metadata are defined. This parameter overrides the setting of the ignoreMetadata field of the Reader parameter if the latter is also supplied. Metadata property values will not be set until requested, i.e., their computation is deferred.
• The image property associated with thumbnails will be set if and only if ReadThumbnails is TRUE and thumbnails are defined for the image at the specified index. Thumbnail property values are not set until requested, i.e., their computation is deferred.
• If VerifyInput is TRUE and Input is either a File or a String which specifies a file path, then canRead() will be invoked on Input or a derived File object as appropriate. If canRead() returns 'false' an exception will be thrown. Note that the canRead() method can not be invoked in the case of the Input being a String specifying a file path which can be accessed only as an InputStream resource from a JAR file. This option is useful to suppress verifying the existence of a file on the local file system when this operation is created as the local portion of a remote operation which will be rendered on a remote peer. This verification will occur when the operation is created.
• If VerifyInput is TRUE and Input is a Socket, then an exception will be thrown if the socket is not bound, not connected, is closed, or its read-half is shut down. This verification will occur when the operation is created.
• Listeners will be used to set any progress, update, or warning listeners of the ImageReader. Each element in the java.util.EventListener array will be added for all types of listener it implements. For example if a listener object implements all of the javax.imageio.event.IIORead*Listeners interfaces then it will be added as a listener of each of the three types. Any elements in the array which do not implement any of the IIORead*Listeners will be ignored.
• Locale will be used to set the Locale of the ImageReader. This parameter overrides the equivalent setting of the Reader parameter if the latter is also supplied.
• If ReadParam is null, an ImageReadParam will be derived internally using ImageReader.getDefaultReadParam(). Supplying an ImageReadParam can be useful for special operations such as setting the bands to read via setSourceBands() or the subsampling factors via setSourceSubsampling(). If the ImageReadParam parameter is not an instance of a cloneable subclass of javax.imageio.ImageReadParam, then it would be best to avoid using the setDestinationType(), setDestinationOffset(), and setSourceRegion() methods on the supplied object as these methods will be invoked internally by the reader.
• If Reader is null, an attempt will be made to derive an ImageReader using ImageIO.getImageReaders().

Parameters and Synchronization Policy

ImageLayout Hint Handling

Image Properties in Rendered Mode

Renderable Mode

It should be noted that although they are discussed in the context of rendered mode, the parameter synchronization policy and ImageLayout handling methodology apply to renderable mode as well.

Renderable Mode Parameters

Renderable Mode Parameter Differences

Name	Class Type	Default Value
ImageChoice	int[]	int[] {0,...,NumImages-1}

In the Sun Microsystems renderable mode implementation of the "ImageRead" operation, when createRendering() is invoked on the RenderableImage created by the operation, a MultiResolutionRenderableImage is constructed from a Vector of RenderedImages consisting of the images at the specified indices. These images will be sorted into order of decreasing resolution (as determined by the product of width and height for each image) and inserted in this order in the Vector of images used to construct the MultiResolutionRenderableImage. Metadata will be set on the component RenderedImages as usual for rendered mode. Finally the createRendering() invocation will be forwarded to the underlying MultiResolutionRenderableImage and the resulting RenderedImage returned.

Note that using this approach the entire MultiResolutionRenderableImage must be regenerated for each invocation of createRendering(). If multiple renderings are to be created from the RenderableImage without changing the operation parameters, then a more efficient approach would be to use the "JAI.RenderableInput" property to be described.

Image Properties in Renderable Mode

Renderable Mode Image Properties

Property Name	Type	Comment
JAI.RenderableInput	RenderableImage	A RenderableImage derived from the input source according to the supplied set of parameters.

The RenderableImage which is the value of the foregoing property may have set on it any of the properties previously described for rendered mode contingent on parameter settings and data availability. The image metadata and thumbnail properties would be copied from the highest resolution image among those specified by the ImageChoice parameter.

If multiple renderings are to be created from the RenderableImage without changing the operation parameters, then an efficient alternative approach to multiple invocations of createRendering() on the RenderableImage is to obtain the RenderableImage value of the "JAI.RenderableInput" property and invoke createRendering() on this value.

Collection Mode

It should be noted that although they are discussed in the context of rendered mode, the parameter synchronization policy and ImageLayout handling methodology apply to collection mode as well.

Collection Mode Parameters

Image Properties in Collection Mode

For renderable mode returns an array containing a single PropertyGenerator which defines a RenderableImage -valued property named "JAI.RenderableInput". For all other modes null is returned.

In addition to the standard validation performed by the corresponding superclass method, this method verifies the following:

• whether ImageChoice is negative (rendered mode) or contains any negative indices (other modes); and
• if VerifyInput is TRUE and Input is a File or String, whether the corresponding physical file exists and is readable; and
• if VerifyInput is TRUE and Input is a String, converting which to a corresponding physical file failed, whether it can be converted to an InputStream accessed as a resource from a JAR file; and
• if VerifyInput is TRUE and Input is a Socket, whether it is bound, connected, open, and the read-half is not shut down.

The file existence and readability verification may be suppressed by setting the VerifyInput parameter to FALSE. This might be desirable for example if the operation is being created for remote rendering and Input is a file which is at a location visible on the remote peer but not on the host on which the operation is created.

For renderable mode returns an array containing a single PropertyGenerator which defines a RenderableImage -valued property named "JAI.RenderableInput". For all other modes null is returned.

In addition to the standard validation performed by the corresponding superclass method, this method verifies the following:

• whether ImageChoice is negative (rendered mode) or contains any negative indices (other modes); and
• if VerifyInput is TRUE and Input is a File or String, whether the corresponding physical file exists and is readable; and
• if VerifyInput is TRUE and Input is a String, converting which to a corresponding physical file failed, whether it can be converted to an InputStream accessed as a resource from a JAR file; and
• if VerifyInput is TRUE and Input is a Socket, whether it is bound, connected, open, and the read-half is not shut down.

The file existence and readability verification may be suppressed by setting the VerifyInput parameter to FALSE. This might be desirable for example if the operation is being created for remote rendering and Input is a file which is at a location visible on the remote peer but not on the host on which the operation is created.