com.sun.media.jai.operator
Class ImageWriteDescriptor

java.lang.Object
  |
  +--javax.media.jai.OperationDescriptorImpl
        |
        +--com.sun.media.jai.operator.ImageWriteDescriptor

All Implemented Interfaces:

javax.media.jai.OperationDescriptor, javax.media.jai.RegistryElementDescriptor, Serializable

public class ImageWriteDescriptor

extends javax.media.jai.OperationDescriptorImpl

An OperationDescriptor describing the "ImageWrite" operation.

The "ImageWrite" operation uses the Java Image I/O Framework to write images to an output destination. Which formats may be written depends on which ImageWriter plug-ins are registered with the Image I/O Framework when the operation is invoked.

The output destination will usually be an ImageOutputStream, but may be a File, RandomAccessFile, OutputStream, Socket, WritableByteChannel, file path represented as a String or some other type compatible with a writer 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 "ImageWrite" operation supports rendered, renderable, and collection modes and requires a single source. The operation is "immediate" for all modes as specified by OperationDescriptor.isImmediate() so that isImmediate() returns true. The operation will therefore be rendered when created via either JAI.create[NS]() or JAI.createCollection[NS](). A RenderingHints object supplied when the operation is created will have no effect except with respect to the mapping of JAI.KEY_INTERPOLATION and then only in renderable mode.

Image properties are used to pass metadata and other information to the writer plug-in and to make available metadata as actually written to the output destination. Property handling is mode-specific.

Resource List

Name	Value
GlobalName	ImageWrite
LocalName	ImageWrite
Vendor	com.sun.media.jai
Description	Writes 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/ImageWriteDescriptor.html
Version	1.0
arg0Desc	The output destination.
arg1Desc	The format name of the output.
arg2Desc	Whether to use image metadata properties as fallbacks.
arg3Desc	Whether to transcode metadata before writing.
arg4Desc	Whether to verify the validity of the output destination.
arg5Desc	Whether to allow pixel replacement in the output image.
arg6Desc	The tile size of the output image.
arg7Desc	Stream metadata to write to the output.
arg8Desc	Image metadata to write to the output.
arg9Desc	Thumbnails to write to the output.
arg10Desc	EventListeners to be registered with the ImageWriter.
arg11Desc	The Locale for the ImageWriter to use.
arg12Desc	Java Image I/O write parameter instance.
arg13Desc	Java Image I/O writer instance.

Rendered Mode

In rendered mode the "ImageWrite" operation writes a RenderedImage to the specified output destination.

Rendered Mode Parameters

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

Rendered Mode Parameter List

Name	Class Type	Default Value
Output	java.lang.Object.class	NO_PARAMETER_DEFAULT
Format	java.lang.String	null
UseProperties	java.lang.Boolean	TRUE
Transcode	java.lang.Boolean	TRUE
VerifyOutput	java.lang.Boolean	TRUE
AllowPixelReplacement	java.lang.Boolean	FALSE
TileSize	java.awt.Dimension	null
StreamMetadata	javax.imageio.metadata.IIOMetadata	null
ImageMetadata	javax.imageio.metadata.IIOMetadata	null
Thumbnails	java.awt.BufferedImage[]	null
Listeners	java.util.EventListener[]	null
Locale	java.util.Locale	null
WriteParam	javax.imageio.ImageWriteParam	null
Writer	javax.imageio.ImageWriter	null

The rendered mode parameters are handled as follows:

• If Output is a String it is assumed to represent a file path.
• Format will be used to obtain an ImageWriter if one is not supplied. If this parameter is null and Writer is non-null and has an originating ImageWriterSpi, then the first format name listed by that provider will be used. If Writer is null and Output is a File or a String, an attempt will be made to derive the format name from the suffix of the file path. If this fails, then the format will default to "PNG" as this is the most versatile writer plug-in in the Java 2 core.
• If UseProperties is TRUE, then if stream or image metadata or thumbnails are not provided as parameters, an attempt will be made to derive them from the source image using the respective image properties previously described for the "ImageRead" operation.
• If Transcode is TRUE, then any stream or metadata derived either from operation parameters or source image properties will be converted using the ImageWriter's implementation of ImageTranscoder.
• If VerifyOutput is TRUE, then if the Output is a File or a String it will be verified that a file at the specified location may either be overwritten or created. If Output is a Socket, it will be verified that it is bound, connected, not closed, and its write-half is not shut down. If any of these checks fails, an exception will be thrown when the operation is created. This parameter is ignored for other output types.
• If AllowPixelReplacement is TRUE, and the ImageWriter supports pixel replacement, then a construct will be enabled to allow "live" updating of the output in response to RenderingChangeEvents or "InvalidRegion" events.
• TileSize specifies the desired tile size; it is used as defined by the tiling algorithm. This parameter is ignored if the ImageWriter does not support tiling. Regardless of the capabilities of the writer, an exception will be thrown when the operation is created if this parameter is non-null and either its width or height is not positive.
• If StreamMetadata is non-null, then the parameter will take priority over the corresponding image property as the source of stream metadata to be written.
• If ImageMetadata is non-null, then the parameter will take priority over the corresponding image property as the source of image metadata to be written.
• If Thumbnails is non-null, then the parameter will take priority over the corresponding image property as the source of image thumbnails to be written.
• Listeners will be used to set any progress or warning listeners of the ImageWriter. 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.IIOWrite*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 IIOWrite*Listeners will be ignored.
• Locale will be used to set the Locale of the ImageWriter. This parameter overrides the equivalent setting of the Writer parameter if the latter is also supplied.
• If WriteParam is null, an ImageWriteParam will be derived internally using ImageWriter.getDefaultWriteParam().
• If Writer is null, an attempt will be made to find an ImageWriter capable of writing the image. If this attempt to obtain an ImageWriter fails, an exception will be thrown.

Parameters and Synchronization Policy

Similarly to the case of any ImageReadParam or ImageReader supplied to the "ImageRead" operation, any ImageWriteParam or ImageWriter supplied to the "ImageWrite" operation is subject to modification within the operation classes. A policy similar to the "ImageRead" synchronization policy therefore applies as well for "ImageWrite".

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

• If the param is cloneable then it is cloned and the clone used internally. Otherwise if the param is an instance of ImageWriteParam itself rather than of a subclass thereof, i.e., getClass().getName() invoked on the param returns "javax.imageio.ImageWriteParam", then a new ImageWriteParam is constructed and the settings of the original param copied to it. If the param is not cloneable and is an instance of a proper subclass of ImageWriteParam then it is used directly.
• The only ImageWriter methods invoked after rendering are prepareReplacePixels(int,Rectangle), replacePixels(Raster,ImageWriteParam), and endReplacePixels() and these are invoked within a method synchronized on the ImageWriter object.

Tiling

The following algorithm is used to determine the tile size of the image written to the output destination:

 if ImageWriter cannot write tiles
    output is untiled
 else
    if TileSize parameter is non-null
       set tile size to TileSize
    else
       if WriteParam is null
          set tile size to source tile size
       else
          if tilingMode is ImageWriteParam.MODE_EXPLICIT
             if tile dimension is set in WriteParam
                set tile size to tile dimension from WriteParam
             else
                if preferred tile dimension is set in WriteParam
 		  set tile size to average of first two preferred dimensions
                else
                   set tile size to source tile size
          else // tilingMode is not ImageWriteParam.MODE_EXPLICIT
             the plug-in decides the tile size
 

There is no mechanism to set the tile grid offsets of the output.

Pixel Replacement

If AllowPixelReplacement is TRUE, the ImageWriter can replace pixels, and the source is a PlanarImage, then the rendering of the operation will respond to RenderingChangeEvents and Shape-valued PropertyChangeEvents named "InvalidRegion". The rendering will be automatically registered as a sink of the rendering of the operation node's source. As the source rendering does not usually generate events, the calling code must also explicitly register the "ImageWrite" rendering as a sink of the source node. By whatever means the event is generated, when the rendering receives such an event, it will determine the indices of all tiles which overlap the invalid region and will replace the pixels of all these tiles in the output.

Note that this behavior differs from what would happen if the RenderedOp created by the operation received a RenderingChangeEvent: in this case a new rendering of the node would be created using the ParameterBlock and RenderingHints currently in effect. This would cause the entire image to be rewritten at the current position of the output. This will also happen when AllowPixelReplacement is FALSE. In effect in both of these cases the behavior in response to a RenderingChangeEvent is unspecified and the result will likely be unexpected.

To avoid any inadvertent overwriting of the destination as a result of events received by the RenderedOp, the following usage is recommended when the objective is automatic pixel replacement:

        // Sources, parameters, and hints.
        ParameterBlock args;
        RenderingHints hints;
 
        // Create the OperationNode.
        RenderedOp imageWriteNode = JAI.create("ImageWrite", args, hints);
 
        // Get the rendering which already exists due to "immediate" status.
        RenderedImage imageWriteRendering = imageWriteNode.getRendering();
 
        // Unhook the OperationNode as a sink of its source OperationNode.
        imageWriteNode.getSourceImage(0).removeSink(imageWriteNode);

        // Add the rendering as a sink of the source OperationNode.
        imageWriteNode.getSourceImage(0).addSink(imageWriteRendering);
 
        // Free the OperationNode for garbage collection.
        imageWriteNode = null;
 

At this point a reference to imageWriteRendering must be held as long as the data of the source of the operation may change. Then provided the events are correctly propagated to imageWriteRendering, the data in the output file will be automatically updated to match the source data.

If pixel replacement is not the objective and inadvertent overwriting is to be avoided then the safest approach would be the following:

        // Create the OperationNode.
        RenderedOp imageWriteNode = JAI.create("ImageWrite", args, hints);
 
        // Unhook the OperationNode as a sink of its source
        imageWriteNode.getSourceImage(0).removeSink(imageWriteNode);
 

The image is written by the first statement and no reference to the rendering need be retained as before.

Image Properties in Rendered Mode

Image properties are used for metadata, thumbnails, and writer-related information. The following properties may be set on the RenderedOp created for the "ImageWrite" operation in rendered mode:

Rendered Mode Image Properties

Property Name	Type	Comment
JAI.ImageWriteParam	ImageWriteParam	Set to ImageWriteParam actually used which may differ from the one passed in.
JAI.ImageWriter	ImageWriter	Set to ImageWriter actually used.
JAI.ImageMetadata	IIOMetadata	Set if and only if image metadata are available; may be transcoded.
JAI.StreamMetadata	IIOMetadata	Set if and only if stream metadata are available; may be transcoded.
JAI.Thumbnails	BufferedImage[]	Set if and only thumbnails are provided and the writer supportes writing them.

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 ImageWriter and ImageWriteParam may be used for subsequent invocations of the operation or for informational purposes. Care should be taken in using these property values with respect to the synchronization issues previously discussed.

Metadata properties will be set to those actually written to the output. They may be derived either from input parameters or source properties depending on the values of the StreamMetadata, ImageMetadata, and UseProperties parameters. They will be transcoded data if Transcode is TRUE and the ImageWriter supports transcoding.

All properties will be set when the node is rendered.

Renderable Mode

In renderable mode the "ImageWrite" operation requires a RenderableImage source and writes a RenderedImage to the specified output destination. As the "immediate" designation specified by isImmediate() has no effect in renderable mode, no image will be written without further action by the calling code. To write an image, createRendering(), createScaledRendering(), or createDefaultRendering() must be invoked. Each of these will create a RenderedImage by forwarding the createRendering() or equivalent call to the source image. The resulting RenderedImage will be written to the output according to the rendered mode operation of "ImageWrite". If a mapping of JAI.KEY_INTERPOLATION is supplied via a RenderingHints passed to the operation, then the interpolation type it specifies will be used to create the rendering if interpolation is required.

Renderable Mode Parameters

The parameter list of the "ImageRead" operation in renderable mode is identical to the rendered mode parameter list.

Pixel Replacement in Renderable Mode

Pixel replacement pertains only to RenderedImages generated by rendering the RenderableOp. It may occur if the same conditions apply as described for pixel replacement in rendered mode. Due to the unspecified nature of the underlying rendered sources of any rendering, this is not a recommended procedure.

Image Properties in Renderable Mode

The RenderableOp node itself does not have any ImageWrite-related properties. Any RenderedImages created by rendering the RenderableOp (thereby writing an image to the output as described), may have rendered mode properties set.

Collection Mode

In collection mode the "ImageWrite" operation requires a Collection source and writes its contents to the specified output destination.

The Collection is treated as a sequence of images which will be extracted from the Collection in the order returned by a new Iterator. Elements in the Collection which are not RenderedImages will be ignored. The derived sequence of images will then be written to the output.

If there is only one RenderedImage in the source Collection, this image will be written as done in rendered mode operation. If there is more than one RenderedImage, the sequence of RenderedImages will be written as an image sequence. In the latter case the ImageWriter must be able to write sequences.

Collection Mode Parameters

Identical parameter list to rendered mode except:

Collection Mode Parameter Differences

Name	Class Type	Default Value
ImageMetadata	javax.imageio.metadataIIOMetadata[]	null
Thumbnails	java.awt.image.BufferedImage[][]	null

• If the source is not a CollectionOp then the number of RenderedImages in the source is counted. If it is not at least one then an exception is thrown when the operation is created. If it is greater than one, then the ImageWriter is checked to determine whether it can write sequences. If it cannot then an exception is thrown when the operation is created.
• The first index of the thumbnails array corresponds to the ordinal position of the image in the collection and the second index to the thumbnails of that image.

The change to the ImageMetadata and Thumbnails parameters is that there can now be a distinct image metadata object and thumbnail array for each image in the Collection. The components of these respective arrays will be indexed using the sequence of RenderedImages extracted from the source Collection by the Iterator. It is the responsibility of the caller to ensure that this sequencing is correct. In this context it is advisable to use a source Collection which maintains the order of its elements such as a List.

Pixel Replacement in Collection Mode

If the value of the AllowPixelReplacement parameter is TRUE, then the rendered Collection will contain RenderedImages which are registered as listeners of their respective sources. Each image in the rendered Collection will however be a rendering as opposed to a RenderedOp. This obviates the need to unhook such a RenderedOp from its source as suggested. Two actions on the part of the application are however necessary in this case: 1) the sequence must be manually ended, and 2) the Collection node must be removed as a sink of its source Collection. The first action is necessary as pixels may be replaced at various times in various images in the sequence and it is not possible to terminate the sequence at rendering time, and there is no reliable mechanism to detect programmatically when this may later be effected. The second action is necessary because a CollectionChangeEvent received by the Collection node would cause the node to be re-rendered, i.e., the collection data to be rewritten using the current state of all parameters. This will in fact also happen when AllowPixelReplacement is FALSE. In effect in both of these cases the behavior in response to a CollectionChangeEvent is unspecified and the result will likely be unexpected.

To ensure proper termination of the image sequence and avoid any inadvertent overwriting of the destination as a result of events received by the CollectionOp, the following usage is recommended when the objective is automatic pixel replacement:

        // Sources, parameters, and hints.
        ParameterBlock args;
        RenderingHints hints;
 
        // Create the Collection.
        CollectionImage imageWriteCollection =
            (CollectionImage)JAI.createCollection("ImageWrite", args, hints);
 
        // Unhook the Collection node from the source to avoid
        // re-renderings caused by CollectionChangeEvents.
        if(args.getSource(0) instanceof CollectionImage) {
            CollectionImage sourceCollection =
 	       (CollectionImage)args.getSource(0);
            sourceCollection.removeSink(imageWriteCollection);
        }
 
        // !!! Pixel replacement activity happens here ... !!!
 
        // Get the ImageWriter.
        ImageWriter writer =
            (ImageWriter)imageWriteCollection.getProperty("JAI.ImageWriter");
 
        // End the sequence if necessary.
        if(writer.canWriteSequence()) {
            writer.endWriteSequence();
        }
 

Using the foregoing construct, all pixels in all images written to the output sequence will remain current with the in-memory data of their respective source provided all events are propagated as expected. Note that it is not necessary to end the sequence manually if pixel replacement is not allowed or is not supported. Also the sequence must be manually ended if and only if the writer is capable of writing sequences. This permits pixel replacement to work in the case where the source collection contains only a single image and the writer supports pixel replacement but cannot write sequences.

If pixel replacement is not the objective, i.e., AllowPixelReplacement is FALSE, and inadvertent overwriting is to be avoided then the safest approach would be the following:

        // Create the Collection.
        Collection imageWriteCollection =
            JAI.create("ImageWrite", args, hints);
 
        // Unhook the Collection node from the source to avoid
        // re-renderings caused by CollectionChangeEvents.
        if(args.getSource(0) instanceof CollectionImage) {
            CollectionImage sourceCollection =
 	       (CollectionImage)args.getSource(0);
            sourceCollection.removeSink(imageWriteCollection);
        }
 

The image is written by the first statement and no reference to the rendering need be retained.

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 rendered mode properties contingent on parameter settings and data availability. Metadata properties may be transcoded.

See Also:

OperationDescriptor, ImageWriter, ImageWriteParam, IIOMetadata, ImageOutputStream, Serialized Form

Field Summary

static String	PROPERTY_NAME_IMAGE_WRITE_PARAM ImageWriteParam property name "JAI.ImageWriteParam".
static String	PROPERTY_NAME_IMAGE_WRITER ImageWriter property name "JAI.ImageWriter".
static String	PROPERTY_NAME_METADATA_IMAGE Image metadata property name.
static String	PROPERTY_NAME_METADATA_STREAM Stream metadata property name.
static String	PROPERTY_NAME_THUMBNAILS Thumbnail property name.

Fields inherited from class javax.media.jai.OperationDescriptorImpl

resources, sourceNames, supportedModes

Fields inherited from interface javax.media.jai.OperationDescriptor

NO_PARAMETER_DEFAULT

Constructor Summary

ImageWriteDescriptor()
Constructor.

Method Summary

static javax.media.jai.RenderedOp	create(RenderedImage source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata imageMetadata, BufferedImage[] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints) Type-safe convenience method for creating a RenderedOp representing the "ImageWrite" operation in rendered mode.
static Collection	createCollection(Collection source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata[] imageMetadata, BufferedImage[][] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints) Type-safe convenience method for creating a Collection representing the "ImageWrite" operation in collection mode.
static javax.media.jai.RenderableOp	createRenderable(RenderableImage source, ImageOutputStream output, String format, Boolean useProperties, Boolean transcode, Boolean verifyOutput, Boolean allowPixelReplacement, Dimension tileSize, IIOMetadata streamMetadata, IIOMetadata imageMetadata, BufferedImage[] thumbnails, EventListener[] listeners, Locale locale, ImageWriteParam writeParam, ImageWriter writer, RenderingHints hints) Type-safe convenience method for creating a RenderableOp representing the "ImageWrite" operation in renderable mode.
boolean	isImmediate() Returns true indicating that the operation should be rendered immediately during a call to JAI.create[]() or JAI.createCollection[NS]().
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, getPropertyGenerators, getRenderableDestClass, getRenderableSourceClasses, getResourceBundle, getResources, getSourceClasses, getSourceClasses, getSourceNames, getSupportedModes, 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_WRITE_PARAM

public static final String PROPERTY_NAME_IMAGE_WRITE_PARAM

ImageWriteParam property name "JAI.ImageWriteParam".

See Also:

Constant Field Values

PROPERTY_NAME_IMAGE_WRITER

public static final String PROPERTY_NAME_IMAGE_WRITER

ImageWriter property name "JAI.ImageWriter".

See Also:

Constant Field Values

PROPERTY_NAME_METADATA_IMAGE

public static final String PROPERTY_NAME_METADATA_IMAGE

Image metadata property name. Set to same value as ImageReadDescriptor.PROPERTY_NAME_METADATA_IMAGE.

See Also:

Constant Field Values

PROPERTY_NAME_METADATA_STREAM

public static final String PROPERTY_NAME_METADATA_STREAM

Stream metadata property name. Set to same value as ImageReadDescriptor.PROPERTY_NAME_METADATA_STREAM.

See Also:

Constant Field Values

PROPERTY_NAME_THUMBNAILS

public static final String PROPERTY_NAME_THUMBNAILS

Thumbnail property name. Set to same value as ImageReadDescriptor.PROPERTY_NAME_THUMBNAILS.

See Also:

Constant Field Values

Constructor Detail

ImageWriteDescriptor

public ImageWriteDescriptor()

Constructor.

Method Detail

create

public static javax.media.jai.RenderedOp create(RenderedImage source,
                                                ImageOutputStream output,
                                                String format,
                                                Boolean useProperties,
                                                Boolean transcode,
                                                Boolean verifyOutput,
                                                Boolean allowPixelReplacement,
                                                Dimension tileSize,
                                                IIOMetadata streamMetadata,
                                                IIOMetadata imageMetadata,
                                                BufferedImage[] thumbnails,
                                                EventListener[] listeners,
                                                Locale locale,
                                                ImageWriteParam writeParam,
                                                ImageWriter writer,
                                                RenderingHints hints)

Type-safe convenience method for creating a RenderedOp representing the "ImageWrite" operation in rendered mode. The method packs the source and parameters into a new ParameterBlock and invokes JAI.create(String,ParameterBlock,RenderingHints).

Parameters:

source - The image to be written.

output - The output destination.

format - The format name of the output.

useProperties - Whether to use image metadata properties as fallbacks.

transcode - Whether to transcode metadata before writing.

verifyOutput - Whether to verify the validity of the output destination.

allowPixelReplacement - Whether to allow pixel replacement in the output image.

tileSize - The tile size of the output image.

streamMetadata - Stream metadata to write to the output.

imageMetadata - Image metadata to write to the output.

thumbnails - Thumbnails to write to the output.

listeners - EventListeners to be registered with the ImageWriter.

locale - The Locale for the ImageWriter to use.

writeParam - Java Image I/O write parameter instance.

writer - Java Image I/O writer instance.

hints - Operation hints.

Returns:

a reference to the operation source.

createCollection

public static Collection createCollection(Collection source,
                                          ImageOutputStream output,
                                          String format,
                                          Boolean useProperties,
                                          Boolean transcode,
                                          Boolean verifyOutput,
                                          Boolean allowPixelReplacement,
                                          Dimension tileSize,
                                          IIOMetadata streamMetadata,
                                          IIOMetadata[] imageMetadata,
                                          BufferedImage[][] thumbnails,
                                          EventListener[] listeners,
                                          Locale locale,
                                          ImageWriteParam writeParam,
                                          ImageWriter writer,
                                          RenderingHints hints)

Type-safe convenience method for creating a Collection representing the "ImageWrite" operation in collection mode. The method packs the source and parameters into a new ParameterBlock and invokes JAI.createCollection(String,ParameterBlock,RenderingHints).

Parameters:

source - The collection to be written.

output - The output destination.

format - The format name of the output.

useProperties - Whether to use image metadata properties as fallbacks.

transcode - Whether to transcode metadata before writing.

verifyOutput - Whether to verify the validity of the output destination.

allowPixelReplacement - Whether to allow pixel replacement in the output image.

tileSize - The tile size of the output image.

streamMetadata - Stream metadata to write to the output.

imageMetadata - Image metadata to write to the output.

thumbnails - Thumbnails to write to the output.

listeners - EventListeners to be registered with the ImageWriter.

locale - The Locale for the ImageWriter to use.

writeParam - Java Image I/O write parameter instance.

writer - Java Image I/O writer instance.

hints - Operation hints.

Returns:

a reference to the operation source.

createRenderable

public static javax.media.jai.RenderableOp createRenderable(RenderableImage source,
                                                            ImageOutputStream output,
                                                            String format,
                                                            Boolean useProperties,
                                                            Boolean transcode,
                                                            Boolean verifyOutput,
                                                            Boolean allowPixelReplacement,
                                                            Dimension tileSize,
                                                            IIOMetadata streamMetadata,
                                                            IIOMetadata imageMetadata,
                                                            BufferedImage[] thumbnails,
                                                            EventListener[] listeners,
                                                            Locale locale,
                                                            ImageWriteParam writeParam,
                                                            ImageWriter writer,
                                                            RenderingHints hints)

Type-safe convenience method for creating a RenderableOp representing the "ImageWrite" operation in renderable mode. The method packs the source and parameters into a new ParameterBlock and invokes JAI.createRenderable(String,ParameterBlock,RenderingHints).

Parameters:

source - The renderable source to be written.

output - The output destination.

format - The format name of the output.

useProperties - Whether to use image metadata properties as fallbacks.

transcode - Whether to transcode metadata before writing.

verifyOutput - Whether to verify the validity of the output destination.

allowPixelReplacement - Whether to allow pixel replacement in the output image.

tileSize - The tile size of the output image.

streamMetadata - Stream metadata to write to the output.

imageMetadata - Image metadata to write to the output.

thumbnails - Thumbnails to write to the output.

listeners - EventListeners to be registered with the ImageWriter.

locale - The Locale for the ImageWriter to use.

writeParam - Java Image I/O write parameter instance.

writer - Java Image I/O writer instance.

hints - Operation hints.

Returns:

a reference to the operation source.

isImmediate

public boolean isImmediate()

Returns true indicating that the operation should be rendered immediately during a call to JAI.create[]() or JAI.createCollection[NS]().

Specified by:

isImmediate in interface javax.media.jai.OperationDescriptor

Overrides:

isImmediate in class javax.media.jai.OperationDescriptorImpl

See Also:

OperationDescriptor

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 VerifyOutput is TRUE and Output is a File or String, whether the corresponding physical file is writable, i.e., exists and may be overwritten or does not exist and may be created; and
• if VerifyOutput is TRUE and Output is a Socket, whether it is bound, connected, open, and the write-half is not shut down; and
• if in collection mode (modeName equals CollectionRegistryMode.MODE_NAME), the source is not a CollectionOp, and the size of the source Collection is greater than unity, whether the ImageWriter cannot write sequences.

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.

Overrides:

validateParameters in class javax.media.jai.OperationDescriptorImpl

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.