com.sun.media.jai.operator
Class ImageReadDescriptor

java.lang.Object
  extended byjavax.media.jai.OperationDescriptorImpl
      extended bycom.sun.media.jai.operator.ImageReadDescriptor
All Implemented Interfaces:
OperationDescriptor, RegistryElementDescriptor, Serializable

public class ImageReadDescriptor
extends OperationDescriptorImpl

An OperationDescriptor describing the "ImageRead" operation.

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 ImageReader plug-ins are registered with the Image I/O Framework when the operation is invoked.

The input source will usually be an ImageInputStream, but may be a File, RandomAccessFile, InputStream, URL, Socket, ReadableByteChannel, file path represented as a String or some other type compatible with a reader plug-in. The 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 RenderingHints object may be supplied when the operation is created. In addition to the 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

In rendered mode the "ImageRead" operation creates a RenderedImage from the specified input source.

Rendered Mode Parameters

The parameter list of the "ImageRead" operation in rendered mode is as in the following table.

Rendered Mode Parameter List
Name Class Type Default Value
Input java.lang.Object.class NO_PARAMETER_DEFAULT
ImageChoice java.lang.Integer 0
ReadMetadata java.lang.Boolean TRUE
ReadThumbnails java.lang.Boolean TRUE
VerifyInput java.lang.Boolean TRUE
Listeners java.util.EventListener[] null
Locale java.util.Locale null
ReadParam javax.imageio.ImageReadParam null
Reader javax.imageio.ImageReader null

The rendered mode parameters are handled as follows:

Parameters and Synchronization Policy

Note that any supplied ImageReadParam parameter may be modified within this operator. Also, any of the various reading methods of the ImageReader may be invoked at an arbitrary subsequent time to populate the image data. Correct handling of these parameters at the application level is left to the user. Specifically no guarantee as to the correct behavior of this operation is made in the cases wherein a user passes in an ImageReadParam or ImageReader parameter and modifies its state while this operation is still using these objects. This applies especially in the case of multi-threaded applications. In such instances it is recommended that the user either not pass in either of these parameters or simply use the Java Image I/O API directly rather than the JAI operation. (Threads managed internally by JAI, e.g., in the TileScheduler, interact with the image object created by this operation only via synchronized methods thereby preventing potential race conditions.) These caveats also apply to the use of ImageReaders and ImageReadParams obtained from image properties.

The foregoing policy regarding modification of any supplied ImageReadParam or ImageReader is necessary as neither of these classes is cloneable. Given that as a starting point there are in effect three possibilities: (A) do not accept them as parameters, (B) accept them via alternate parameters which do not pose these problems (for example an ImageReaderSpi and a long list of settings represented by the ImageReadParam), or (C) accept them explicitly. Option C has been deemed preferable despite the potential race condition issues.

In the Sun Microsystems implementation of this operation these potential conflicts have been mitigated to a certain extent:

ImageLayout Hint Handling

If an ImageLayout hint is provided via the operation's RenderingHints, its values will be used. In particular a SampleModel or ColorModel supplied via an ImageLayout hint will override any values set via the ImageTypeSpecifier of the ImageReadParam parameter if the latter is non-null. This signifies that the ImageTypeSpecifier of the OpImage rendering associated with the operation node will be forced to match that of the layout even if this type is different from or incompatible with the image types available from the ImageReader. Note that in such an eventuality an extra amount of memory equal to one image tile might be needed for copying purposes. This copying is handled by the JAI operation itself.

Any fields of the supplied ImageLayout which are not set will be set to default values as follows. The ImageLayout will be cloned before it is modified.

ImageLayout Defaults

Image Properties in Rendered Mode

Image properties are used to provide metadata, thumbnails, and reader-related information. The following properties may be obtained from the RenderedOp created for the "ImageRead" operation in rendered mode:

Rendered Mode Image Properties
Property Name Type Comment
JAI.ImageReadParam ImageReadParam Set to ImageReadParam actually used which may differ from the one passed in.
JAI.ImageReader ImageReader Set to ImageReader actually used.
JAI.ImageMetadata IIOMetadata Set if and only if ReadMetadata parameter is TRUE and image metadata are available.
JAI.StreamMetadata IIOMetadata Set if and only if ReadMetadata parameter is TRUE and stream metadata are available.
JAI.Thumbnails BufferedImage[] Set if and only if ReadThumbnails parameter is TRUE and thumbnails are available.

If a given property is not set, this implies of course that the names of absent properties will not appear in the array returned by getPropertyNames() and getProperty() invoked to obtain absent properties will return java.awt.Image.UndefinedProperty as usual.

The ImageReader and ImageReadParam may be used for subsequent invocations of the operation (for example to obtain different images in a multi-page file) or for informational purposes. Care should be taken in using these property values with respect to the synchronization issues previously discussed.

In all cases image metadata properties will be set when the node is rendered, i.e., metadata reading is not subject to the same deferred execution as is image data reading. The thumbnail property value will not be set however until its value is actually requested.

Renderable Mode

In renderable mode the "ImageRead" operation creates a RenderableImage from the specified input source.

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

The parameter list of the "ImageRead" operation in renderable mode is identical to the rendered mode parameter list mode except as indicated in the following table.

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

The following property will be set on the RenderableOp created for the "ImageRead" operation 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

In collection mode the "ImageRead" operation creates a Collection of RenderedImages from the specified input source. This could be used for example to load an animated GIF image or a multi-page TIFF image.

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

The parameter list of the "ImageRead" operation in collection mode is identical to the renderable mode parameter list. In this case the RenderedImages loaded for the specified indices will be used to create a Collection of RenderedImages. The images will be loaded in the order of the indices in the supplied array and appended to a List. The rendering of the operation will be a CollectionImage the 'imageCollection' instance variable of which will be set to this List.

Image Properties in Collection Mode

Contingent on parameter settings and the presence of the appropriate metadata, the rendered Collection may have the "JAI.StreamMetadata", "JAI.ImageReadParam", and "JAI.ImageReader" properties set. Each RenderedImage in the Collection may contain the rendered mode properties contingent on parameter settings and data availability.

See Also:
OperationDescriptor, ImageReader, ImageReadParam, IIOMetadata, ImageInputStream, Serialized Form

Field Summary
static String PROPERTY_NAME_IMAGE_READ_PARAM
          ImageReadParam property name "JAI.ImageReadParam".
static String PROPERTY_NAME_IMAGE_READER
          ImageReader property name "JAI.ImageReader".
static String PROPERTY_NAME_METADATA_IMAGE
          Image metadata property name "JAI.ImageMetadata".
static String PROPERTY_NAME_METADATA_STREAM
          Stream metadata property name "JAI.StreamMetadata".
static String PROPERTY_NAME_RENDERABLE_INPUT
          Renderable input property name "JAI.RenderableInput".
static String PROPERTY_NAME_THUMBNAILS
          Thumbnail property name "JAI.Thumbnails".
 
Fields inherited from class javax.media.jai.OperationDescriptorImpl
sourceNames, supportedModes
 
Fields inherited from interface javax.media.jai.OperationDescriptor
NO_PARAMETER_DEFAULT
 
Constructor Summary
ImageReadDescriptor()
          Constructor.
 
Method Summary
static RenderedOp create(ImageInputStream input, Integer imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
          Type-safe convenience method for creating a RenderedOp representing the "ImageRead" operation in rendered mode.
static Collection createCollection(ImageInputStream input, int[] imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
          Type-safe convenience method for creating a Collection representing the "ImageRead" operation in collection mode.
static RenderableOp createRenderable(ImageInputStream input, int[] imageChoice, Boolean readMetadata, Boolean readThumbnails, Boolean verifyInput, EventListener[] listeners, Locale locale, ImageReadParam readParam, ImageReader reader, RenderingHints hints)
          Type-safe convenience method for creating a RenderableOp representing the "ImageRead" operation in renderable mode.
 PropertyGenerator[] getPropertyGenerators(String modeName)
          Returns the array of PropertyGenerators for the specified mode of this operation.
protected  boolean validateParameters(String modeName, ParameterBlock args, StringBuffer msg)
          Validates the parameters in the supplied ParameterBlock.
 
Methods inherited from class javax.media.jai.OperationDescriptorImpl
arePropertiesSupported, getDefaultSourceClass, getDestClass, getDestClass, getInvalidRegion, getName, getNumParameters, getNumSources, getParamClasses, getParamDefaults, getParamDefaultValue, getParameterListDescriptor, getParamMaxValue, getParamMinValue, getParamNames, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, isImmediate, isModeSupported, isRenderableSupported, isRenderedSupported, makeDefaultSourceClassList, validateArguments, validateArguments, validateParameters, validateRenderableArguments, validateRenderableSources, validateSources, validateSources
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PROPERTY_NAME_IMAGE_READ_PARAM

public static final String PROPERTY_NAME_IMAGE_READ_PARAM
ImageReadParam property name "JAI.ImageReadParam".

See Also:
Constant Field Values

PROPERTY_NAME_IMAGE_READER

public static final String PROPERTY_NAME_IMAGE_READER
ImageReader property name "JAI.ImageReader".

See Also:
Constant Field Values

PROPERTY_NAME_METADATA_IMAGE

public static final String PROPERTY_NAME_METADATA_IMAGE
Image metadata property name "JAI.ImageMetadata".

See Also:
Constant Field Values

PROPERTY_NAME_METADATA_STREAM

public static final String PROPERTY_NAME_METADATA_STREAM
Stream metadata property name "JAI.StreamMetadata".

See Also:
Constant Field Values

PROPERTY_NAME_THUMBNAILS

public static final String PROPERTY_NAME_THUMBNAILS
Thumbnail property name "JAI.Thumbnails".

See Also:
Constant Field Values

PROPERTY_NAME_RENDERABLE_INPUT

public static final String PROPERTY_NAME_RENDERABLE_INPUT
Renderable input property name "JAI.RenderableInput".

See Also:
Constant Field Values
Constructor Detail

ImageReadDescriptor

public ImageReadDescriptor()
Constructor.

Method Detail

create

public static RenderedOp create(ImageInputStream input,
                                Integer imageChoice,
                                Boolean readMetadata,
                                Boolean readThumbnails,
                                Boolean verifyInput,
                                EventListener[] listeners,
                                Locale locale,
                                ImageReadParam readParam,
                                ImageReader reader,
                                RenderingHints hints)
Type-safe convenience method for creating a RenderedOp representing the "ImageRead" operation in rendered mode. The method packs the parameters into a new ParameterBlock and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:
input - The input source.
imageChoice - The index of the image to read.
readMetadata - Whether metadata should be read if available.
readThumbnails - Whether thumbnails should be read if available.
verifyInput - Whether to verify the validity of the input source.
listeners - EventListeners to be registered with the ImageReader.
locale - The Locale for the ImageReader to use.
readParam - Java Image I/O read parameter instance.
reader - Java Image I/O reader instance.
hints - Hints possibly including an ImageLayout.
Returns:
an image derived from the input source.

createCollection

public static Collection createCollection(ImageInputStream input,
                                          int[] imageChoice,
                                          Boolean readMetadata,
                                          Boolean readThumbnails,
                                          Boolean verifyInput,
                                          EventListener[] listeners,
                                          Locale locale,
                                          ImageReadParam readParam,
                                          ImageReader reader,
                                          RenderingHints hints)
Type-safe convenience method for creating a Collection representing the "ImageRead" operation in collection mode. The method packs the parameters into a new ParameterBlock and invokes JAI.createCollection(String,ParameterBlock, RenderingHints).

Parameters:
input - The input source.
imageChoice - The indices of the images to read.
readMetadata - Whether metadata should be read if available.
readThumbnails - Whether thumbnails should be read if available.
verifyInput - Whether to verify the validity of the input source.
listeners - EventListeners to be registered with the ImageReader.
locale - The Locale for the ImageReader to use.
readParam - Java Image I/O read parameter instance.
reader - Java Image I/O reader instance.
hints - Hints possibly including an ImageLayout.
Returns:
a collection of images derived from the input source.

createRenderable

public static RenderableOp createRenderable(ImageInputStream input,
                                            int[] imageChoice,
                                            Boolean readMetadata,
                                            Boolean readThumbnails,
                                            Boolean verifyInput,
                                            EventListener[] listeners,
                                            Locale locale,
                                            ImageReadParam readParam,
                                            ImageReader reader,
                                            RenderingHints hints)
Type-safe convenience method for creating a RenderableOp representing the "ImageRead" operation in renderable mode. The method packs the parameters into a new ParameterBlock and invokes JAI.createRenderable(String,ParameterBlock,RenderingHints).

Parameters:
input - The input source.
imageChoice - The indices of the images to read.
readMetadata - Whether metadata should be read if available.
readThumbnails - Whether thumbnails should be read if available.
verifyInput - Whether to verify the validity of the input source.
listeners - EventListeners to be registered with the ImageReader.
locale - The Locale for the ImageReader to use.
readParam - Java Image I/O read parameter instance.
reader - Java Image I/O reader instance.
hints - Hints possibly including an ImageLayout.
Returns:
an image capable of rendering an image from those in the input source.

getPropertyGenerators

public PropertyGenerator[] getPropertyGenerators(String modeName)
Returns the array of PropertyGenerators for the specified mode of this operation.

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.

Parameters:
modeName - The name of the mode.
Returns:
An array containing a single PropertyGenerator if modeName is "renderable" (case-insensitive) or null otherwise.

validateParameters

protected boolean validateParameters(String modeName,
                                     ParameterBlock args,
                                     StringBuffer msg)
Validates the parameters in the supplied ParameterBlock.

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

If the superclass method finds that the arguments are invalid, or if this method determines that any of the foregoing conditions is true, an error message will be appended to msg and false will be returned; otherwise true will be returned.

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.

Parameters:
modeName - The operation mode.
args - The source and parameters of the operation.
msg - A container for any error messages.
Returns:
Whether the supplied parameters are valid.