Java Advanced Imaging: Class ParameterBlockJAI

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.media.jai
Class ParameterBlockJAI

java.lang.Object
  |
  +--java.awt.image.renderable.ParameterBlock
        |
        +--javax.media.jai.ParameterBlockJAI

All Implemented Interfaces:: Cloneable, ParameterList, Serializable

public class ParameterBlockJAI
extends ParameterBlock
implements ParameterList

A convenience subclass of ParameterBlock that allows the use of default parameter values and getting/setting sources and parameters by name. A ParameterBlockJAI is constructed using either an OperationDescriptor, or an operation name (that will be looked up in the appropriate default OperationRegistry) and a mode which should be in OperationDescriptor.getSupportedModes() (such as rendered, renderable, collection or renderableCollection). If the mode is not specified ParameterBlockJAI will by default work with the first mode in the array of Strings returned by OperationDescriptor.getSupportedModes().

Once constructed, a ParameterBlockJAI appears to have no sources. It contains all the parameters required by its OperationDescriptor for a specified mode, each having its default value as given by the OperationDescriptor. Such a ParameterBlockJAI may not yet be usable, its sources (if any) are not set, and some or all of its parameters may have inapproriate values. The addSource methods of ParameterBlock may be used to initialize the source values, and the set(value, index) methods may be used to modify new parameter values. The preferred way of setting parameter values is the setParameter(name, value) described below. The add() methods should not be used since the parameter list is already long enough to hold all of the parameters required by the OperationDescriptor.

Additionally, ParameterBlockJAI offers setParameter(name, value) methods that take a parameter name; the index of the parameter is determined from the OperationDescriptor and the corresponding parameter is set. (users are strongly recommended to use this method instead of the equivalent set(value, index) or the deprecated set(value, name) methods). As in ParameterBlock, all parameters are stored internally as subclasses of Object and all get/set methods that take or return values of primitive types are simply convenience methods that transform values between the primitive types and their corresponding wrapper classes subclasses.

The OperationDescriptor that is used to initialize a ParameterBlockJAI at construction is not serializable and thus cannot be serialized using the default serialization mechanism. The operation name is serialized instead and included in the serialized ParameterBlockJAI stream. During de-serialization, the operation name is de-serialized and then looked up in the default OperationRegistry available at the time of de-serialization. If no OperationDescriptor has been registered with this OperationRegistry under the given operation name, a NotSerializableException will be thrown. The serialization of ParameterBlockJAI works correctly only if the OperationDescriptor registered for the operation name in question is identical to the OperationDescriptor that was registered with the OperationRegistry available at serialization time.

All parameter names are treated in a case-insensitive but retentive manner.

Warning: Serialized objects of this class will not be compatible with future releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of JAI. A future release of JAI will provide support for long term persistence.

See Also:: Serialized Form

Fields inherited from class java.awt.image.renderable.ParameterBlock

parameters, sources

Constructor Summary

ParameterBlockJAI(OperationDescriptor odesc)
          Constructs a ParameterBlockJAI for use with an operation described by a particular OperationDescriptor.

ParameterBlockJAI(OperationDescriptor odesc, String modeName)
          Constructs a ParameterBlockJAI for use with an operation described by a particular OperationDescriptor and a registry mode.

ParameterBlockJAI(String operationName)
          Constructs a ParameterBlockJAI for a particular operation by name.

ParameterBlockJAI(String operationName, String modeName)
          Constructs a ParameterBlockJAI for a particular operation by name and a registry mode.

Method Summary

ParameterBlock add(Object obj)
          Adds an object to the list of parameters.

Object clone()
          Creates a copy of a ParameterBlockJAI.

boolean getBooleanParameter(String paramName)
          A convenience method to return a parameter as a boolean.

byte getByteParameter(String paramName)
          A convenience method to return a parameter as a byte.

char getCharParameter(String paramName)
          A convenience method to return a parameter as a char.

double getDoubleParameter(String paramName)
          A convenience method to return a parameter as a double.

float getFloatParameter(String paramName)
          A convenience method to return a parameter as a float.

int getIntParameter(String paramName)
          A convenience method to return a parameter as an int.

long getLongParameter(String paramName)
          A convenience method to return a parameter as a long.

String getMode()
          Get the operation mode used to determine parameter names, classes and default values.

Object getObjectParameter(String paramName)
          Gets a named parameter as an Object.

OperationDescriptor getOperationDescriptor()
          Returns the OperationDescriptor associated with this ParameterBlockJAI.

Class[] getParamClasses()
          Returns an array of Class objects describing the types of the parameters.

ParameterListDescriptor getParameterListDescriptor()
          Returns the ParameterListDescriptor that provides descriptions of the parameters associated with the operator and mode.

short getShortParameter(String paramName)
          A convenience method to return a parameter as an short.

int indexOf(String paramName)
          Deprecated. as of JAI 1.1 - use "indexOfParam" instead.

int indexOfParam(String paramName)
          Returns the zero-relative index of a named parameter within the list of parameters.

int indexOfSource(String sourceName)
          Returns the zero-relative index of a named source within the list of sources.

ParameterBlock set(byte b, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(char c, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(double d, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(float f, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(int i, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(long l, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(Object obj, int index)
          Replaces an Object in the list of parameters.

ParameterBlock set(Object obj, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterBlock set(short s, String paramName)
          Deprecated. as of JAI 1.1 - use setParameter instead.

ParameterList setParameter(String paramName, boolean b)
          Sets a named parameter to a boolean value.

ParameterList setParameter(String paramName, byte b)
          Sets a named parameter to a byte value.

ParameterList setParameter(String paramName, char c)
          Sets a named parameter to a char value.

ParameterList setParameter(String paramName, double d)
          Sets a named parameter to a double value.

ParameterList setParameter(String paramName, float f)
          Sets a named parameter to a float value.

ParameterList setParameter(String paramName, int i)
          Sets a named parameter to an int value.

ParameterList setParameter(String paramName, long l)
          Sets a named parameter to a long value.

ParameterList setParameter(String paramName, Object obj)
          Sets a named parameter to an Object value.

ParameterList setParameter(String paramName, short s)
          Sets a named parameter to a short value.

void setParameters(Vector parameters)
          Sets the entire Vector of parameters to a given Vector.

ParameterBlockJAI setSource(String sourceName, Object source)
          Sets a named source to a given Object value.

Methods inherited from class java.awt.image.renderable.ParameterBlock

add, add, add, add, add, add, add, addSource, getByteParameter, getCharParameter, getDoubleParameter, getFloatParameter, getIntParameter, getLongParameter, getNumParameters, getNumSources, getObjectParameter, getParameters, getRenderableSource, getRenderedSource, getShortParameter, getSource, getSources, removeParameters, removeSources, set, set, set, set, set, set, set, setSource, setSources, shallowClone

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ParameterBlockJAI

public ParameterBlockJAI(OperationDescriptor odesc)

Constructs a ParameterBlockJAI for use with an operation described by a particular OperationDescriptor. It uses the first mode in the array of Strings returned by OperationDescriptor.getSupportedModes() to get the ParameterListDescriptor from OperationDescriptor. The default values of the parameters are filled in.

Parameters:: odesc - the OperationDescriptor describing the parameters to be managed.
Throws:: IllegalArgumentException - if odesc is null

ParameterBlockJAI

public ParameterBlockJAI(String operationName)

Constructs a ParameterBlockJAI for a particular operation by name. The OperationRegistry associated with the default instance of the JAI class is used to locate the OperationDescriptor associated with the operation name. It uses the first mode in the array of Strings returned by OperationDescriptor.getSupportedModes() to get the ParameterListDescriptor from OperationDescriptor. The default values of the parameters are filled in.

Parameters:: operationName - a String giving the name of the operation.
Throws:: IllegalArgumentException - if operationName is null.

ParameterBlockJAI

public ParameterBlockJAI(OperationDescriptor odesc,
                         String modeName)

Constructs a ParameterBlockJAI for use with an operation described by a particular OperationDescriptor and a registry mode. The default values of the parameters are filled in.

Parameters:: odesc - the OperationDescriptor describing the parameters to be managed.; modeName - the operation mode whose paramters are to be managed.
Throws:: IllegalArgumentException - if modeName is null or odesc is null
Since:: JAI 1.1

ParameterBlockJAI

public ParameterBlockJAI(String operationName,
                         String modeName)

Constructs a ParameterBlockJAI for a particular operation by name and a registry mode. The OperationRegistry associated with the default instance of the JAI class is used to locate the OperationDescriptor associated with the operation name. The default values of the parameters are filled in.

Parameters:: operationName - a String giving the name of the operation.; modeName - the operation mode whose paramters are to be managed.
Throws:: IllegalArgumentException - if operationName or modeName is null
Since:: JAI 1.1

Method Detail

indexOfSource

public int indexOfSource(String sourceName)

Returns the zero-relative index of a named source within the list of sources.

Parameters:: sourceName - a String containing the parameter name.
Throws:: IllegalArgumentException - if source is null or if there is no source with the specified name.
Since:: JAI 1.1

indexOfParam

public int indexOfParam(String paramName)

Returns the zero-relative index of a named parameter within the list of parameters.

Parameters:: paramName - a String containing the parameter name.
Throws:: IllegalArgumentException - if paramName is null or if there is no parameter with the specified name.
Since:: JAI 1.1

getOperationDescriptor

public OperationDescriptor getOperationDescriptor()

Returns the OperationDescriptor associated with this ParameterBlockJAI.

getParameterListDescriptor

public ParameterListDescriptor getParameterListDescriptor()

Returns the ParameterListDescriptor that provides descriptions of the parameters associated with the operator and mode.

Specified by:: getParameterListDescriptor in interface ParameterList

Since:: JAI 1.1

getMode

public String getMode()

Get the operation mode used to determine parameter names, classes and default values.

Since:: JAI 1.1

setSource

public ParameterBlockJAI setSource(String sourceName,
                                   Object source)

Sets a named source to a given Object value.

Parameters:: sourceName - a String naming a source.; source - an Object value for the source.
Throws:: IllegalArgumentException - if source is null.; IllegalArgumentException - if sourceName is null.; IllegalArgumentException - if source is not an instance of (any of) the expected class(es).; IllegalArgumentException - if the associated operation has no source with the supplied name.
Since:: JAI 1.1

getParamClasses

public Class[] getParamClasses()

Returns an array of Class objects describing the types of the parameters. This is a more efficient implementation than that of the superclass as the parameter classes are known a priori.

Overrides:: getParamClasses in class ParameterBlock

Since:: JAI 1.1

getObjectParameter

public Object getObjectParameter(String paramName)

Gets a named parameter as an Object. Parameters belonging to a primitive type, such as int, will be returned as a member of the corresponding Number subclass, such as Integer.

Specified by:: getObjectParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getByteParameter

public byte getByteParameter(String paramName)

A convenience method to return a parameter as a byte. An exception will be thrown if the parameter is of a different type.

Specified by:: getByteParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getBooleanParameter

public boolean getBooleanParameter(String paramName)

A convenience method to return a parameter as a boolean. An exception will be thrown if the parameter is of a different type.

Specified by:: getBooleanParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT
Since:: JAI 1.1

getCharParameter

public char getCharParameter(String paramName)

A convenience method to return a parameter as a char. An exception will be thrown if the parameter is of a different type.

Specified by:: getCharParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getShortParameter

public short getShortParameter(String paramName)

A convenience method to return a parameter as an short. An exception will be thrown if the parameter is of a different type.

Specified by:: getShortParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT
Since:: JAI 1.1

getIntParameter

public int getIntParameter(String paramName)

A convenience method to return a parameter as an int. An exception will be thrown if the parameter is of a different type.

Specified by:: getIntParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getLongParameter

public long getLongParameter(String paramName)

A convenience method to return a parameter as a long. An exception will be thrown if the parameter is of a different type.

Specified by:: getLongParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getFloatParameter

public float getFloatParameter(String paramName)

A convenience method to return a parameter as a float. An exception will be thrown if the parameter is of a different type.

Specified by:: getFloatParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

getDoubleParameter

public double getDoubleParameter(String paramName)

A convenience method to return a parameter as a double. An exception will be thrown if the parameter is of a different type.

Specified by:: getDoubleParameter in interface ParameterList

Parameters:: paramName - the name of the parameter to be returned.
Throws:: IllegalArgumentException - if there is no parameter with the specified name.; ClassCastException - if the parameter is of a different type.; IllegalStateException - if the parameter value is still ParameterListDescriptor.NO_PARAMETER_DEFAULT

setParameter

public ParameterList setParameter(String paramName,
                                  byte b)

Sets a named parameter to a byte value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; b - a byte value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Byte; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  boolean b)

Sets a named parameter to a boolean value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; b - a boolean value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Boolean; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  char c)

Sets a named parameter to a char value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; c - a char value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Character; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  short s)

Sets a named parameter to a short value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; s - a short value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Short; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  int i)

Sets a named parameter to an int value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; i - an int value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Integer; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  long l)

Sets a named parameter to a long value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; l - a long value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Long; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  float f)

Sets a named parameter to a float value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; f - a float value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Float; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  double d)

Sets a named parameter to a double value. Checks are made to verify that the parameter is of the right Class type and that the value is valid.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; d - a double value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the class type of parameter pointed to by the paramName is not a Double; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

setParameter

public ParameterList setParameter(String paramName,
                                  Object obj)

Sets a named parameter to an Object value. The value may be null, an instance of the class expected for this parameter, or a DeferredData instance the getDataClass() method of which returns the expected class. If the object is a DeferredData instance, then its wrapped data value is checked for validity if and only if its isValid() method returns true. If the object is not a DeferredData instance, then it is always checked for validity.

Specified by:: setParameter in interface ParameterList

Parameters:: paramName - a String naming a parameter.; obj - an Object value for the parameter.
Throws:: IllegalArgumentException - if paramName is null.; IllegalArgumentException - if there is no parameter with the specified name.; IllegalArgumentException - if the parameter value is invalid.
Since:: JAI 1.1

add

public ParameterBlock add(Object obj)

Adds an object to the list of parameters. This method always throws an IllegalStateException because the ParameterBlockJAI constructor initializes all parameters with their default values.

Overrides:: add in class ParameterBlock

Throws:: IllegalStateException - if parameters are added to an already initialized ParameterBlockJAI
Since:: JAI 1.1

set

public ParameterBlock set(Object obj,
                          int index)

Replaces an Object in the list of parameters.

Overrides:: set in class ParameterBlock

Parameters:: obj - The new value of the parameter.; index - The zero-relative index of the parameter.
Throws:: ArrayIndexOutOfBoundsException - if index is negative or not less than the number of parameters expected for the associated operation.; IllegalArgumentException - if obj is non-null and not an instance of the class expected for the indicated parameter or if obj is an invalid value for the indicated parameter.
Since:: JAI 1.1

setParameters

public void setParameters(Vector parameters)

Sets the entire Vector of parameters to a given Vector. The Vector is saved by reference.

Overrides:: setParameters in class ParameterBlock

Throws:: IllegalArgumentException - if the size of the supplied Vector does not equal the number of parameters of the associated operation.; IllegalArgumentException - if a non-null, non-DeferredData value is not an instance of the class expected for the indicated parameter or if obj is an invalid value for the indicated parameter.; IllegalArgumentException - if a non-null, DeferredData value does not wrap an instance of the class expected for the indicated parameter or if it is valid but its wrapped value is invalid for the indicated parameter.
Since:: JAI 1.1

indexOf

public int indexOf(String paramName)

Deprecated. as of JAI 1.1 - use "indexOfParam" instead.

Returns the zero-relative index of a named parameter within the list of parameters.

Parameters:: paramName - a String containing the parameter name.
Throws:: IllegalArgumentException - if paramName is null or if there is no parameter with the specified name.
See Also:: indexOfParam(java.lang.String)