javax.media.jai
Interface OperationDescriptor

All Superinterfaces:

RegistryElementDescriptor

All Known Implementing Classes:

OperationDescriptorImpl

public interface OperationDescriptor

extends RegistryElementDescriptor

This interface provides a comprehensive description of a specific image operation. All information regarding the operation, such as its name, version, input, and properties should be listed. Any conditions placed on the operation, such as its source class types and legal parameter range, should also be included, and the methods to enforce these conditions should be implemented. A set of PropertyGenerators may be specified to be used as a basis for the operation's property management.

Each image operation in JAI must have a descriptor that implements this interface. The following basic resource data must be provided:

• A global operation name that is visible to all and is the same in all Locales.
• A localized operation name that may be used as a synonym for the global operation name.
• The name of the vendor defining this operation.
• A brief description of this operation.
• An URL where additional documentation on this operation may be found.
• The version of this operation.

Additional information must be provided when appropriate. Only then can this operation be added to an OperationRegistry. Furthermore, it is recommended that a detailed description of the operation's functionality be included in the class comments.

JAI currently knows about the following operation modes : "rendered", "renderable", "collection" and "renderableCollection" (these form a subset of the known registry modes returned by RegistryMode.getModes()). All mode names are dealt with in a case insensitive (but retentive) manner. All modes have to accept the same number of source images and the same number of parameters. All the source names and parameter names are also the same across all modes. The class types of the sources and parameters can be different for each mode.

For example an operation supporting the "rendered" mode takes RenderedImages as its sources, can only be used in a rendered operation chain, and produces a RenderedImage. An operation supporting the renderable mode takes RenderableImages as its sources, can only be used in a renderable operation chain, and produces a RenderableImage.

See Also:

JAI, OperationDescriptorImpl

Field Summary

static Object

NO_PARAMETER_DEFAULT An Object that signifies that a parameter has no default value.

Method Summary

Class	getDestClass() Deprecated. as of JAI 1.1 in favor of getDestClass("rendered")
Class	getDestClass(String modeName) Returns a Class that describes the type of destination this operation produces for the specified mode.
Object	getInvalidRegion(String registryModeName, ParameterBlock oldParamBlock, RenderingHints oldHints, ParameterBlock newParamBlock, RenderingHints newHints, OperationNode node) Calculates the region over which two distinct renderings of an operation may be expected to differ.
int	getNumParameters() Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getNumParameters() This will for the time being return the above value for modeName = getSupportedModes()[0]
int	getNumSources() Returns the number of sources required by this operation.
Class[]	getParamClasses() Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamClasses() This will for the time being return the above value for modeName = getSupportedModes()[0]
Object[]	getParamDefaults() Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamDefaults() This will for the time being return the above value for modeName = getSupportedModes()[0]
Object	getParamDefaultValue(int index) Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamDefaultValue() This will for the time being return the above value for modeName = getSupportedModes()[0]
Number	getParamMaxValue(int index) Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamValueRange() This will for the time being return "getMaxValue" of the above return value for modeName = getSupportedModes()[0]
Number	getParamMinValue(int index) Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamValueRange() This will for the time being return "getMinValue" of the above return value for modeName = getSupportedModes()[0]
String[]	getParamNames() Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamNames() This will for the time being return the above value for modeName = getSupportedModes()[0]
PropertyGenerator[]	getPropertyGenerators() Deprecated. as of JAI 1.1 in favor of the equivalent method that specifies the mode name.
Class	getRenderableDestClass() Deprecated. as of JAI 1.1 in favor of getDestClass("renderable")
Class[]	getRenderableSourceClasses() Deprecated. as of JAI 1.1 in favor of getSourceClasses("renderable")
ResourceBundle	getResourceBundle(Locale locale) Returns the resource data for this operation in the specified Locale in a ResourceBundle.
String[][]	getResources(Locale locale) Returns the resource data for this operation in the specified Locale.
Class[]	getSourceClasses() Deprecated. as of JAI 1.1 in favor of getSourceClasses("rendered")
Class[]	getSourceClasses(String modeName) Returns an array of Classes that describe the types of sources required by this operation for the specified mode.
String[]	getSourceNames() Returns an array of Strings that are the names of the sources of this operation.
boolean	isImmediate() Returns true if the operation should be computed immediately for all supported modes of this operation during the call to JAI.create(); that is, the operation is placed in immediate mode.
boolean	isRenderableSupported() Deprecated. as of JAI 1.1 in favor of isModeSupported("renderable")
boolean	isRenderedSupported() Deprecated. as of JAI 1.1 in favor of isModeSupported("rendered")
boolean	validateArguments(ParameterBlock args, StringBuffer msg) Deprecated. as of JAI 1.1 in favor of validateArguments("rendered", ...)
boolean	validateArguments(String modeName, ParameterBlock args, StringBuffer msg) Returns true if this operation/mode is capable of handling the input source(s) and/or parameter(s) specified in the ParameterBlock, or false otherwise, in which case an explanatory message may be appended to the StringBuffer.
boolean	validateRenderableArguments(ParameterBlock args, StringBuffer msg) Deprecated. as of JAI 1.1 in favor of validateArguments("renderable", ...)

Methods inherited from interface javax.media.jai.RegistryElementDescriptor

arePropertiesSupported, getName, getParameterListDescriptor, getPropertyGenerators, getSupportedModes, isModeSupported

Field Detail

NO_PARAMETER_DEFAULT

public static final Object NO_PARAMETER_DEFAULT

An Object that signifies that a parameter has no default value. Same as ParameterListDescriptor.NO_PARAMETER_DEFAULT

Method Detail

getResources

public String[][] getResources(Locale locale)

Returns the resource data for this operation in the specified Locale. It must contain String data for the following tags:

• "GlobalName" - A global operation name that is visible to all and is the same in all Locales.
• "LocalName" - A localized operation name that may be used as a synonym for the "GlobalName".
• "Vendor" - The name of the vendor defining this operation. Vendors are encouraged to use the Java convention of reversed Internet addresses.
• "Description" - A brief description of this operation.
• "DocURL" - An URL where additional documentation on this operation may be found.
• "Version" - A free-form version indicator of this operation.

In addition, it may contain String data for the following tags when appropriate:

• "arg0Desc", "arg1Desc", ... - Description of the input parameters.
• "hint0Desc", hint1Desc", ... - Description of the rendering hints.

Parameters:

locale - The Locale for which the information should be localized. It may be different from the default Locale.

Returns:

A two-dimensional array of Strings containing the mandatory and optional resource tags and their corresponding resource data. (String[i][0] is the tag for the i-th resource and String[i][1] is the corresponding data)

getResourceBundle

public ResourceBundle getResourceBundle(Locale locale)

Returns the resource data for this operation in the specified Locale in a ResourceBundle. The resource data values are taken from the getResources() method which must be implemented by each operation descriptor.

Parameters:

locale - The Locale for which the information should be localized. It may be different from the default Locale.

Returns:

A ResourceBundle containing the mandatory and optional resource information.

getNumSources

public int getNumSources()

Returns the number of sources required by this operation. All modes have the same number of sources.

getSourceClasses

public Class[] getSourceClasses(String modeName)

Returns an array of Classes that describe the types of sources required by this operation for the specified mode. If this operation has no sources, this method returns null.

Parameters:

modeName - the operation mode name

Throws:

IllegalArgumentException - if modeName is null or if it is not one of the supported modes.

Since:

JAI 1.1

getSourceNames

public String[] getSourceNames()

Returns an array of Strings that are the names of the sources of this operation. If this operation has no sources, this method returns null.

Since:

JAI 1.1

getDestClass

public Class getDestClass(String modeName)

Returns a Class that describes the type of destination this operation produces for the specified mode.

Parameters:

modeName - the operation mode name

Throws:

IllegalArgumentException - if modeName is null or if it is not one of the supported modes.

Since:

JAI 1.1

validateArguments

public boolean validateArguments(String modeName,
                                 ParameterBlock args,
                                 StringBuffer msg)

Returns true if this operation/mode is capable of handling the input source(s) and/or parameter(s) specified in the ParameterBlock, or false otherwise, in which case an explanatory message may be appended to the StringBuffer.

This method is the standard place where input arguments are validated against this operation's specification for the specified mode. It is called by JAI.create() as a part of its validation process. Thus it is strongly recommended that the application programs use the JAI.create() methods to instantiate all the rendered operations.

This method sets all the undefined parameters in the ParameterBlock to their default values, if the default values are specified.

Note that DeferredData parameters will not be recognized as valid unless the parameter is defined to have class DeferredData.class.

Parameters:

modeName - the operation mode name

args - Input arguments, including source(s) and/or parameter(s).

msg - A string that may contain error messages.

Throws:

IllegalArgumentException - if modeName is null

Since:

JAI 1.1

isImmediate

public boolean isImmediate()

Returns true if the operation should be computed immediately for all supported modes of this operation during the call to JAI.create(); that is, the operation is placed in immediate mode. If true, and the computation fails, null will be returned from JAI.create(). If false, JAI.create() will return an instance of the appropriate destination class that may be asked to compute itself at a later time; this computation may fail at that time.

Operations that rely on an external resource, such as a source file, or that produce externally-visible side effects, such as writing to an output file, should return true from this method. Operations that rely only on their sources and parameters usually wish to return false in order to defer rendering as long as possible.

getInvalidRegion

public Object getInvalidRegion(String registryModeName,
                               ParameterBlock oldParamBlock,
                               RenderingHints oldHints,
                               ParameterBlock newParamBlock,
                               RenderingHints newHints,
                               OperationNode node)

Calculates the region over which two distinct renderings of an operation may be expected to differ.

The class of the returned object will vary as a function of the mode of the operation. For rendered and renderable two- dimensional images this should be an instance of a class which implements java.awt.Shape.

Parameters:

registryModeName - The name of the mode.

oldParamBlock - The previous sources and parameters.

oldHints - The previous hints.

newParamBlock - The current sources and parameters.

newHints - The current hints.

node - The affected node in the processing chain.

Returns:

The region over which the data of two renderings of this operation may be expected to be invalid or null if there is no common region of validity. If an empty java.awt.Shape is returned, this indicates that all pixels within the bounds of the old rendering remain valid.

Throws:

IllegalArgumentException - if registryModeName is null or if the operation requires either sources or parameters and either oldParamBlock or newParamBlock is null.

IllegalArgumentException - if oldParamBlock or newParamBlock do not contain sufficient sources or parameters for the operation in question.

Since:

JAI 1.1

getPropertyGenerators

public PropertyGenerator[] getPropertyGenerators()

Deprecated. as of JAI 1.1 in favor of the equivalent method that specifies the mode name.

Returns an array of PropertyGenerators implementing the property inheritance for this operation. They may be used as a basis for the operation's property management.

Returns:

An array of PropertyGenerators, or null if this operation does not have any of its own PropertyGenerators.

isRenderedSupported

public boolean isRenderedSupported()

Deprecated. as of JAI 1.1 in favor of isModeSupported("rendered")

Returns true if this operation supports the rendered image mode. That is, it may be performed on RenderedImage sources in a rendered operation chain, and produces a rendered result. The JAI.create() and the JAI.createCollection() methods should be used to instantiate the operation.

If this method returns true, all the additional methods that supply the rendered mode information must be implemented.

getSourceClasses

public Class[] getSourceClasses()

Deprecated. as of JAI 1.1 in favor of getSourceClasses("rendered")

Returns an array of Classes that describe the types of sources required by this operation in the rendered image mode. If this operation has no source, this method returns null.

getDestClass

public Class getDestClass()

Deprecated. as of JAI 1.1 in favor of getDestClass("rendered")

Returns a Class that describes the type of destination this operation produces in the rendered image mode. Currently JAI supports two destination class types: java.awt.image.RenderedImage.class and java.util.Collection.class.

validateArguments

public boolean validateArguments(ParameterBlock args,
                                 StringBuffer msg)

Deprecated. as of JAI 1.1 in favor of validateArguments("rendered", ...)

Returns true if this operation is capable of handling the input rendered source(s) and/or parameter(s) specified in the ParameterBlock, or false otherwise, in which case an explanatory message may be appended to the StringBuffer.

This method is the standard place where input arguments are validated against this operation's specification for the rendered mode. It is called by JAI.create() as a part of its validation process. Thus it is strongly recommended that the application programs use the JAI.create() methods to instantiate all the rendered operations.

This method sets all the undefined parameters in the ParameterBlock to their default values, if the default values are specified.

Note that DeferredData parameters will not be recognized as valid unless the parameter is defined to have class DeferredData.class.

Parameters:

args - Input arguments, including source(s) and/or parameter(s).

msg - A string that may contain error messages.

isRenderableSupported

public boolean isRenderableSupported()

Deprecated. as of JAI 1.1 in favor of isModeSupported("renderable")

Returns true if this operation supports the renderable image mode. That is, it may be performed on RenderableImage sources in a renderable operation chain, and produces a renderable result. The JAI.createRenderable() and the JAI.createCollection() methods should be used to instantiate the operation.

If this method returns true, all the additional methods that supply the renderable mode information must be implemented.

getRenderableSourceClasses

public Class[] getRenderableSourceClasses()

Deprecated. as of JAI 1.1 in favor of getSourceClasses("renderable")

Returns an array of Classes that describe the types of sources required by this operation in the renderable image mode. If this operation does not support the renderable mode, or if it has no source, this method returns null.

getRenderableDestClass

public Class getRenderableDestClass()

Deprecated. as of JAI 1.1 in favor of getDestClass("renderable")

Returns a Class that describes the type of destination this operation produces in the renderable image mode. Currently JAI supports two destination class types: java.awt.image.renderable.RenderableImage.class and java.util.Collection.class.

validateRenderableArguments

public boolean validateRenderableArguments(ParameterBlock args,
                                           StringBuffer msg)

Deprecated. as of JAI 1.1 in favor of validateArguments("renderable", ...)

Returns true if this operation is capable of handling the input renderable source(s) and/or parameter(s) specified in the ParameterBlock, or false otherwise, in which case an explanatory message may be appended to the StringBuffer.

This method is the standard place where input arguments are validated against this operation's specification for the renderable mode. It is called by JAI.createRenderable() as a part of its validation process. Thus it is strongly recommended that the application programs use the JAI.createRenderable() method to instantiate all the renderable operations.

This method sets all the undefined parameters in the ParameterBlock to their default values, if the default values are specified.

Note that DeferredData parameters will not be recognized as valid unless the parameter is defined to have class DeferredData.class.

If this operation does not support the renderable mode, this method returns false regardless of the input arguments

Parameters:

args - Input arguments, including source(s) and/or parameter(s).

msg - A string that may contain error messages.

getNumParameters

public int getNumParameters()

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getNumParameters() This will for the time being return the above value for modeName = getSupportedModes()[0]

Returns the number of parameters (not including the sources) required by this operation.

getParamClasses

public Class[] getParamClasses()

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamClasses() This will for the time being return the above value for modeName = getSupportedModes()[0]

Returns an array of Classes that describe the types of parameters required by this operation. If this operation has no parameter, this method returns null.

getParamNames

public String[] getParamNames()

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamNames() This will for the time being return the above value for modeName = getSupportedModes()[0]

Returns an array of Strings that are the localized parameter names of this operation. If this operation has no parameter, this method returns null.

getParamDefaults

public Object[] getParamDefaults()

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamDefaults() This will for the time being return the above value for modeName = getSupportedModes()[0]

Returns an array of Objects that define the default values of the parameters for this operation. Default values may be null. When instantiating the operation, the default values may be used for those parameters whose values are not supplied. The NO_PARAMETER_DEFAULT static Object indicates that a parameter has no default value. If this operation has no parameter, this method returns null.

getParamDefaultValue

public Object getParamDefaultValue(int index)

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamDefaultValue() This will for the time being return the above value for modeName = getSupportedModes()[0]

Returns the default value of a specified parameter. The default value may be null. If a parameter has no default value, this method returns NO_PARAMETER_DEFAULT.

Parameters:

index - The index of the parameter whose default value is queried.

Throws:

NullPointerException - if this operation has no parameter.

ArrayIndexOutOfBoundsException - if there is no parameter corresponding to the specified index.

getParamMinValue

public Number getParamMinValue(int index)

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamValueRange() This will for the time being return "getMinValue" of the above return value for modeName = getSupportedModes()[0]

Returns the minimum legal value of a specified numeric parameter for this operation. If the specified parameter is non-numeric, this method returns null.

The return value should be of the class type appropriate for the parameter's type, that is, Byte for a byte parameter, Integer for an int parameter, and so forth.

Parameters:

index - The index of the numeric parameter whose minimum value is queried.

Returns:

A Number representing the minimum legal value of the queried parameter, or null.

Throws:

NullPointerException - if this operation has no parameter.

ArrayIndexOutOfBoundsException - if there is no parameter corresponding to the specified index.

getParamMaxValue

public Number getParamMaxValue(int index)

Deprecated. as of JAI 1.1 in favor of getParameterListDescriptor(modeName).getParamValueRange() This will for the time being return "getMaxValue" of the above return value for modeName = getSupportedModes()[0]

Returns the maximum legal value of a specified numeric parameter for this operation. If the specified parameter is non-numeric, this method returns null.

The return value should be of the class type appropriate for the parameter's type, that is, Byte for a byte parameter, Integer for an int parameter, and so forth.

Parameters:

index - The index of the numeric parameter whose maximum value is queried.

Returns:

A Number representing the maximum legal value of the queried parameter, or null.

Throws:

NullPointerException - if this operation has no parameter.

ArrayIndexOutOfBoundsException - if there is no parameter corresponding to the specified index.