## 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 `PropertyGenerator`s 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 `Locale`s.
- 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 `RenderedImage`s as its sources, can only be used in a rendered operation chain, and produces a `RenderedImage`. An operation supporting the renderable mode takes `RenderableImage`s as its sources, can only be used in a renderable operation chain, and produces a `RenderableImage`.

See Also:
  `JAI`, `OperationDescriptorImpl`

Field Summary
`static java.lang.Object` `NO_PARAMETER_DEFAULT` An `Object` that signifies that a parameter has no default value.

Method Summary
`java.lang.Class` `getDestClass()` Deprecated. in favor of `getDestClass("rendered")`
`java.lang.Class` `getDestClass(java.lang.String modeName)` Returns a `Class` that describes the type of destination this operation produces for the specified mode.
`java.lang.Object` `getInvalidRegion(java.lang.String registryModeName, java.awt.image.renderable.ParameterBlock oldParamBlock, java.awt.RenderingHints oldHints, java.awt.image.renderable.ParameterBlock newParamBlock, java.awt.RenderingHints newHints, OperationNode node)` Calculates the region over which two distinct renderings of an operation may be expected to differ.
`int` `getNumParameters()` Deprecated. 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.
`java.lang.Class[]` `getParamClasses()` Deprecated. in favor of `getParameterListDescriptor(modeName).getParamClasses()` This will for the time being return the above value for modeName = getSupportedModes()[0]
`java.lang.Object[]` `getParamDefaults()` Deprecated. in favor of `getParameterListDescriptor(modeName).getParamDefaults()` This will for the time being return the above value for modeName = getSupportedModes()[0]
`java.lang.Object` `getParamDefaultValue(int index)` Deprecated. in favor of `getParameterListDescriptor(modeName).getParamDefaultValue()` This will for the time being return the above value for modeName = getSupportedModes()[0]
`java.lang.Number` `getParamMaxValue(int index)` Deprecated. in favor of `getParameterListDescriptor(modeName).getParamValueRange()` This will for the time being return "getMaxValue" of the above return value for modeName = getSupportedModes()[0]
`java.lang.Number` `getParamMinValue(int index)` Deprecated. in favor of `getParameterListDescriptor(modeName).getParamValueRange()` This will for the time being return "getMinValue" of the above return value for modeName = getSupportedModes()[0]
`java.lang.String[]` `getParamNames()` Deprecated. 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.
`java.lang.Class` `getRenderableDestClass()` Deprecated. in favor of `getDestClass("renderable")`
`java.lang.Class[]` `getRenderableSourceClasses()` Deprecated. in favor of `getSourceClasses("renderable")`
`java.util.ResourceBundle` `getResourceBundle(java.util.Locale locale)` Returns the resource data for this operation in the specified `Locale` in a `ResourceBundle`.
`java.lang.String[][]` `getResources(java.util.Locale locale)` Returns the resource data for this operation in the specified `Locale`.
`java.lang.Class[]` `getSourceClasses()` Deprecated. in favor of `getSourceClasses("rendered")`
`java.lang.Class[]` `getSourceClasses(java.lang.String modeName)` Returns an array of `Class`es that describe the types of sources required by this operation for the specified mode.
`java.lang.String[]` `getSourceNames()` Returns an array of `String`s 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. in favor of `isModeSupported("renderable")`
`boolean` `isRenderedSupported()` Deprecated. in favor of `isModeSupported("rendered")`
`boolean` `validateArguments(java.awt.image.renderable.ParameterBlock args, java.lang.StringBuffer msg)` Deprecated. in favor of `validateArguments("rendered", ...)`
`boolean` `validateArguments(java.lang.String modeName, java.awt.image.renderable.ParameterBlock args, java.lang.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(java.awt.image.renderable.ParameterBlock args, java.lang.StringBuffer msg)` Deprecated. 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 java.lang.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 java.lang.String[][] getResources(java.util.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 `Locale`s.
  - "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 `String`s 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 java.util.ResourceBundle getResourceBundle(java.util.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 java.lang.Class[] getSourceClasses(java.lang.String modeName)

  Returns an array of `Class`es 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:
    `java.lang.IllegalArgumentException` - if modeName is `null`
  Since:
    Java Advanced Imaging 1.1

### getSourceNames

    public java.lang.String[] getSourceNames()

  Returns an array of `String`s that are the names of the sources of this operation. If this operation has no sources, this method returns `null`.
  Since:
    Java Advanced Imaging 1.1

### getDestClass

    public java.lang.Class getDestClass(java.lang.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:
    `java.lang.IllegalArgumentException` - if modeName is `null`
  Since:
    Java Advanced Imaging 1.1

### validateArguments

    public boolean validateArguments(java.lang.String modeName,
                                     java.awt.image.renderable.ParameterBlock args,
                                     java.lang.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:
    `java.lang.IllegalArgumentException` - if modeName is `null`
  Since:
    Java Advanced Imaging 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 java.lang.Object getInvalidRegion(java.lang.String registryModeName,
                                             java.awt.image.renderable.ParameterBlock oldParamBlock,
                                             java.awt.RenderingHints oldHints,
                                             java.awt.image.renderable.ParameterBlock newParamBlock,
                                             java.awt.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:
    `java.lang.IllegalArgumentException` - if `registryModeName` is `null` or if the operation requires either sources or parameters and either `oldParamBlock` or `newParamBlock` is `null`.
    `java.lang.IllegalArgumentException` - if `oldParamBlock` or `newParamBlock` do not contain sufficient sources or parameters for the operation in question.

### 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 `PropertyGenerator`s implementing the property inheritance for this operation. They may be used as a basis for the operation's property management.
  Returns:
    An array of `PropertyGenerator`s, or `null` if this operation does not have any of its own `PropertyGenerator`s.

### isRenderedSupported

    public boolean isRenderedSupported()

  Deprecated. 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 java.lang.Class[] getSourceClasses()

  Deprecated. in favor of `getSourceClasses("rendered")`

  Returns an array of `Class`es 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 java.lang.Class getDestClass()

  Deprecated. 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(java.awt.image.renderable.ParameterBlock args,
                                     java.lang.StringBuffer msg)

  Deprecated. 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. 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 java.lang.Class[] getRenderableSourceClasses()

  Deprecated. in favor of `getSourceClasses("renderable")`

  Returns an array of `Class`es 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 java.lang.Class getRenderableDestClass()

  Deprecated. 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(java.awt.image.renderable.ParameterBlock args,
                                               java.lang.StringBuffer msg)

  Deprecated. 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. 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 java.lang.Class[] getParamClasses()

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

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

### getParamNames

    public java.lang.String[] getParamNames()

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

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

### getParamDefaults

    public java.lang.Object[] getParamDefaults()

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

  Returns an array of `Object`s 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 java.lang.Object getParamDefaultValue(int index)

  Deprecated. 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 java.lang.Number getParamMinValue(int index)

  Deprecated. 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 java.lang.Number getParamMaxValue(int index)

  Deprecated. 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`.