#
# @(#)OpRegistry.txt 1.15 00/12/14 16:29:35
#
JAI OperationRegistry Modification Proposal
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Brian Burkhalter
Krishna Gadepalli
Created: 10 March 2000 bpb
Revised: 17 August 2000 Krishna Gadepalli/bpb
Revised: 31 August 2000 Krishna Gadepalli
Revised: 10 Sep 2000 Krishna Gadepalli
Revised: 13 Sep 2000 Krishna Gadepalli
Revised: 29 Sep 2000 Krishna Gadepalli
Revised: 11 Oct 2000 Krishna Gadepalli
CHANGES SINCE COMMUNITY REVIEW INCEPTION
----------------------------------------
- removed package scope "static ... initializeRegistry()" from
OperationRegistry since it is not relevant to the public
proposal.
- The OR constructor is no longer thread-safe. Added a new
method "getThreadSafeOperationRegistry" which returns a
thread-safe wrapped version of OR.
- "registerServices" in OR now throws an IOException and
has updated docs.
- throw IllegalArgumentException instead of NullPointerException
whenever arguments are null.
- made ParameterListImpl implement Serializable
Documentation update/clarifications :
OperationRegistry
- initializeFromStream, updateFromStream, readExternal,
writeExternal
- removed "synchronized" keyword from deprecated methods
"suppressAllProperties" and "clearOperationPreferences"
- minor class comments correction.
JAI
- update docs for getDefaultInstance & getOperationRegistry
to clarify thread-safety of OR
OperationDescriptorImpl
- added a warning on use of deprecated constructors to the
following methods
. getPropertyGenerators(String)
. validateSources(String, ParameterBlock, StringBuffer)
. getDestClass(String)
- improved docs for the new validate* methods
RED
- minor modification to getParameterListDescriptor doc.
1. Motivation
-------------
The current implementation of the OperationRegistry in JAI does not
provide sufficient flexibility in terms of the ability to manage
operations which have image factories of as yet unknown type. One
existing problem that was created by this lack of flexibility is the
fact that the code which handles the CollectionImageFactory (CIF) is
essentially a wholesale duplication of the previously existing code
which handled RenderedImageFactory (RIF). This problem will be
encountered again if, for example, volumetric or other operation
categories were added to the product.
2. Objective
------------
The aim of this proposal is to suggest ideas for making the
OperationRegistry more flexible particularly as relates to
simplifying the ability to add image factories the nature of which
have yet to be identified. Other areas of investigation include
automatic discovery of user-defined operations and a revision of
the interface with the property mechanism.
3. Proposed changes
-------------------
3.1 OperationGraph
------------------
The various graph classes mentioned in this section are all
private to the package javax.media.jai.
3.1.1 Suggested changes
-----------------------
a. Rewrite the current "OperationGraph" implementation to
handle generic factory types. It is currently hard-coded
to handle RIFs and CIFs with much code duplication.
b. ProductOperationGraph also shares a lot of code with
"OperationGraph" It pretty much does what
"OperationGraph" does for either a RIF or a CIF.
So, abstract out the common portions of OperationGraph
and ProductOperationGraph into a new class so that it
can be re-used.
3.1.2 New methods
-----------------
a. Move the current functionality of OperationGraph to
FactoryOperationGraph.
b. Pull the common functionality of ProductOperationGraph
and the "old" OperationGraph into the "new"
OperationGraph
3.2 RegistryElementDescriptor
-----------------------------
A new interface "RegistryElementDescriptor" will be introduced
and all descriptors (for example OperationDescriptor,
TileCodecDescriptor etc.) wanting to register themselves with
the OperationRegistry will have to extend or implement this
interface.
package javax.media.jai;
/**
* An interface for all JAI descriptors that register themselves
* with the OperationRegistry
. Examples include
* OperationDescriptor
, TileCodecDescriptor
,
* RemoteDescriptor
etc.
*
* @see OperationRegistry
* @see RegistryMode
*
* @since JAI 1.1
*/
public interface RegistryElementDescriptor {
/**
* The name this descriptor will be registered under in the
* OperationRegistry
. Individual descriptors
* implementing this interface will define what this name means
* in their space. For example this would be "operation name" for
* OperationDescriptor
and "format name" for
* TileCodecDescriptor
etc.
*/
String getName();
/**
* The registry modes supported by this descriptor. Known modes
* include those returned by RegistryMode.getModes()
.
*
* @return an array of String
s specifying the supported modes.
*
* @see RegistryMode
*/
String[] getSupportedModes();
/**
* Whether this descriptor supports the specified registry mode.
* The modeName
s are to be treated in a case-insensitive
* (but retentive) manner.
*
* @param modeName the registry mode name
*
* @return true, if the implementation of this descriptor supports
* the specified mode. false otherwise.
*
* @throws IllegalArgumentException if modeName
is null
*/
boolean isModeSupported(String modeName);
/**
* Whether this descriptor supports JAI properties.
*
* @return true, if the implementation of this descriptor supports
* JAI properties. false otherwise.
*
* @see PropertyGenerator
*/
boolean arePropertiesSupported();
/**
* Returns an array of PropertyGenerator
s implementing
* the property inheritance for this descriptor. They may be used
* as a basis for the descriptor's property management.
*
* @param modeName the registry mode name
*
* @return An array of PropertyGenerator
s, or
* null
if this operation does not have any of
* its own PropertyGenerator
s.
*
* @throws IllegalArgumentException if modeName
is null
* @throws UnsupportedOperationException if arePropertiesSupported()
* returns false
*/
PropertyGenerator[] getPropertyGenerators(String modeName);
/**
* Returns the ParameterListDescriptor
that describes
* the associated parameters (not sources). This method returns
* null if the specified modeName does not support parameters.
* If the specified modeName supports parameters but the
* implementing class does not have parameters, then this method
* returns a non-null ParameterListDescriptor
whose
* getNumParameters()
returns 0.
*
* @param modeName
*
* @throws IllegalArgumentException if modeName
is null
*/
ParameterListDescriptor getParameterListDescriptor(String modeName);
}
3.3 OperationDescriptor
-----------------------
Some of the functionality from OperationDescriptor and
ParameterBlockJAI are being abstracted out to create new interfaces
& classes so that these can be used uniformly across other
descriptors (TileCodeDescriptor, RemoteDescriptor etc.) Other
changes are also suggested to improve the flexibility of these
interfaces in using the concept of registry modes.
3.3.1 ParameterListDescriptor
-----------------------------
package javax.media.jai;
/**
* This interface provides a comprehensive description of a set of
* parameters including parameter names, parameter defaults,
* valid parameter value ranges, etc.
*
* The parameter names should be used in a case retentive manner. i.e.
* all lookups and comparisons are case-insensitive but any request
* for a parameter name should return the original name with the case
* preserved.
*
* @see ParameterList
*
* @since JAI 1.1
*/
public interface ParameterListDescriptor {
/**
* An Object
that signifies that a parameter has
* no default value.
*/
public static final Object NO_PARAMETER_DEFAULT;
/**
* Returns the total number of parameters.
*/
int getNumParameters();
/**
* Returns an array of Class
es that describe the types
* of parameters. If there are no parameters, this method returns
* null
.
*/
Class[] getParamClasses();
/**
* Returns an array of String
s that are the
* names of the parameters associated with this descriptor. If there
* are no parameters, this method returns null
.
*/
String[] getParamNames();
/**
* Returns an array of Object
s that define the default
* values of the parameters. Since null
might be a
* valid parameter value, the NO_PARAMETER_DEFAULT
* static Object
is used to indicate that a parameter
* has no default value. If there are no parameters, this method
* returns null
.
*/
Object[] getParamDefaults();
/**
* 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
.
*
* @param parameterName The name of the parameter whose default
* value is queried.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
*/
Object getParamDefaultValue(String parameterName);
/**
* Returns the Range
that represents the range of valid
* values for the specified parameter. Returns null
if
* the parameter can take on any value or if the valid values are
* not representable as a Range.
*
* @param parameterName The name of the parameter whose valid range
* of values is to be determined.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
*/
Range getParamValueRange(String parameterName);
/**
* Return an array of the names of all parameters the type of which is
* EnumeratedParameter
.
*
* @return The requested array of names or null
if there
* are no parameters with EnumeratedParameter
type.
*/
String[] getEnumeratedParameterNames();
/**
* Return an array of EnumeratedParameter
objects
* corresponding to the parameter with the specified name.
*
* @param parameterName The name of the parameter for which the
* EnumeratedParameter
array is to be returned.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
* @throws UnsupportedOperationException if there are no enumerated
* parameters associated with the descriptor.
* @throws IllegalArgumentException if parameterName
is
* a parameter the class of which is not a subclass of
* EnumeratedParameter
.
*
* @return An array of EnumeratedParameter
objects
* representing the range of values for the named parameter.
*/
EnumeratedParameter[] getEnumeratedParameterValues(String parameterName);
/**
* Checks to see whether the specified parameter can take on the specified
* value.
*
* @param parameterName The name of the parameter for which the
* validity check is to be performed.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
* @throws IllegalArgumentException if the class of the object "value"
* is not an instance of the class type of parameter
* pointed to by the parameterName
*
* @return true, if it is valid to pass this value in for this
* parameter, false otherwise.
*/
boolean isParameterValueValid(String parameterName, Object value);
}
3.3.2 ParameterListDescriptorImpl
---------------------------------
package javax.media.jai;
/**
* A concrete implementation of the ParameterListDescriptor
* interface.
*
* @see ParameterListDescriptor
*
* @since JAI 1.1
*/
public class ParameterListDescriptorImpl implements ParameterListDescriptor {
/**
* Uses reflection to examine "descriptor" for public
,
* static
final
Field
s
* that are instances of "paramClass".
*
* @param descriptor the object to be reflected upon.
* @param paramClass the parameter class
*
* @return a Set
of enumerated values.
*
* @throws IllegalArgumentException if descriptor is null
* or paramClass is null
* @throws IllegalArgumentException if "paramClass" is not an instance of
* EnumeratedParameter
*/
public static Set getEnumeratedValues(
Object descriptor, Class paramClass) {}
/**
* Constructor for descriptors that dont have any parameters.
*/
public ParameterListDescriptorImpl() {}
/**
* Constructor.
*
* @param descriptor the object to be reflected upon for enumerated values
* @param paramNames the names of each parameter. can be null
* if there are no parameters.
* @param paramClasses the Class
type of each parameter.
* can be null
if there are no parameters.
* @param paramDefaults the default values for each parameter. can be
* null
if there are no parameters or if
* there are no default values, in which case the parameter
* defaults are assumed to be
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
* @param validParamValues defines the valid values for each parameter.
*
*
Each element of this array can be null
(if the parameter
* can take on any value of its class or if it is an enumerated parameter
* whose values are to be auto-detected - see getEnumeratedValues
*
), or a Set
(for user specified enumerated
* values) or a Range
(for parameters that are
* Comparable
.)
*
*
The valid set of values for an object which is neither an
* EnumeratedParameter
nor Comparable
* should just be the set of all possible instances of the associated
* class, i.e., the parameter has to be an instance of the specified
* class.
*
*
If this array itself is All comparisons using Once constructed, a Additionally, The 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.
*/
public class ParameterBlockJAI extends ParameterBlock
implements ParameterList {
/**
* Constructs a Each image operation in JAI must have a descriptor
* that implements this interface. The following basic resource data
* must be provided:
* JAI currently knows about the following operation modes :
* "rendered", "renderable", "collection" and "renderableCollection"
* (these form a subset of the known registry modes returned by
* For example an operation supporting the "rendered" mode
* takes This method is the standard place where input arguments are
* validated against this operation's specification for the specified
* mode. It is called by This method sets all the undefined parameters in the
* 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
* If this method returns This method is the standard place where input arguments are
* validated against this operation's specification for the rendered
* mode. It is called by This method sets all the undefined parameters in the
* If this method returns This method is the standard place where input arguments are
* validated against this operation's specification for the renderable
* mode. It is called by This method sets all the undefined parameters in the
* If this operation does not support the renderable mode,
* this method returns The return value should be of the class type appropriate for
* the parameter's type, that is, If the parameter is not a sub-class of the Else if the above getParamValueRange() returns a non-null
* Else for The return value should be of the class type appropriate for
* the parameter's type, that is, If the parameter is not a sub-class of the Else if the above getParamValueRange() returns a non-null
* Else returns the For the sake of backward compatibilty, if a
* deprecated constructor was used to create this object,
* then this method simply calls its deprecated equivalent,
* The default implementation simply returns a reference to
* the local "resources" variable, which should be supplied by
* each subclass by way of the superclass constructor. It also
* ignores the The default implementation ignores the For the sake of backward compatibilty, if a
* deprecated constructor was used to create this object, then this
* method simply calls its deprecated equivalent, if the modeName is
* either "rendered" or "renderable".
*
* @param modeName the operation mode name
* @param args a JAI allows unspecified tailing parameters if these parameters
* have default values. This method automatically sets these unspecified
* parameters to their default values. However, if a parameter, which
* has a default value, is followed by one or more parameters that
* have no default values, this parameter must be specified in the
* This method sets all the undefined parameters in the
* Note that For the sake of backward compatibilty, if a
* deprecated constructor was used to create this object, then this
* method simply calls its deprecated equivalent, if the modeName is
* either "rendered" or "renderable".
*
* @throws IllegalArgumentException if For the sake of backward compatibilty, if a
* deprecated constructor was used to create this object, then this
* method simply calls its deprecated equivalent, if the modeName is
* either "rendered" or "renderable".
*
* @param modeName the operation mode name
*
* @throws IllegalArgumentException if modeName is This method is the standard place where input arguments are
* validated against this operation's specification for the specified
* mode. It is called by The default implementation of this method makes sure that
* this operator supports the specified mode and then calls
* This method sets all the undefined parameters in the
* Note that 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
* The default implementation in this class returns
* The At the highest level all objects are registered against some mode.
* A mode is specified by a Each registry mode is associated with a If a registry mode supports preferences (for example "rendered",
* "tileEncoder" etc.), then the hierarchy of objects registered under
* that mode looks like that of "mode1" above. Descriptors are first
* registered against all modes that the specific instance supports. Each
* factory object that implements the functionality specified by that
* descriptor is registered against some product (name) under that
* descriptor. Preferences can be set among products under a given
* descriptor or among objects under a specific product/descriptor.
*
* The ordering of such factory objects is determined by the order
* of the products attached to an The ordering of factory objects within a product is intended to
* allow vendors to create complex "fallback" chains. An example would
* be installing a If a registry mode does not support preferences (for example,
* "renderable", "remoteRenderable" etc.) then the hierarchy of objects
* registered under that mode looks like that of "mode2" above. Only a
* single factory object belonging to this mode can be associated with a
* given descriptor. If multiple objects are registered under the same
* descriptor, the last one registered is retained.
*
* The Vendors are encouraged to use unique product names (by means
* of the Java programming language convention of reversed Internet
* addresses) in order to maximize the likelihood of clean installation.
* See The Java Programming Language, §10.1 for a discussion
* of this convention in the context of package naming.
*
* Users will, for the most part, only wish to set ordering
* preferences on the product level, since the factory object level
* orderings will be complex. However, it is possible for a knowledgable
* user to insert a specific factory object into an existing product for
* tuning purposes.
*
* The The registry handles all names (except class names) in a
* case-insensitive but retentive manner.
*
* ... more automatic loading comments below....
*
* @see OperationRegistrySpi
* @see RegistryMode
* @see RegistryElementDescriptor
*/
public class OperationRegistry {
/**
* Default Constructor. The If none of the RIFs registered with this
* The user has two options for automatic loading of registry
* objects.
* The initialization of the default The user could give the registry file a package qualified name
* for e.g xxx.yyy.registryFile.jai and put this in the META-INF
* directory of the jar file. Then in the concrete class that implements
* An interface definition to aid in the automatic loading of
* user-defined JAI operations.
*
* All concrete classes that implement this
* interface can register by listing themselves in the
* META-INF/services/javax.media.jai.OperationRegistrySpi jar-file. The
* file should contain a list of fully-qualified concrete provider-class
* names, one per line. Space and tab characters surrounding each
* name, as well as blank lines, are ignored. The comment character is
* '#' (0x23); on each line all characters following
* the first comment character are ignored. The file must be encoded in
* UTF-8.
*
* If a particular concrete provider class is named in more than one
* configuration file, or is named in the same configuration file more
* than once, then the duplicates will be ignored. The configuration
* file naming a particular provider need not be in the same jar file or
* other distribution unit as the provider itself. The provider must be
* accessible from the same class loader that was initially queried to
* locate the configuration file; note that this is not necessarily the
* class loader that found the file.
*
* All such concrete classes must have a zero-argument
* constructor so that they may be instantiated during lookup. The
* The This is a convenience method to do automatic detection in runtime
* loaded jar files
*
* Note that the JAI does not keep track of which JAR files have
* their registry files loaded and/or services initialized. Hence
* if null
then it is treated
* as an array full of null
s as described above.
*
* @throws IllegalArgumentException if paramNames
is non-null
* and the number of
paramClasses
or a non-null
* paramDefaults
does not match the length of
* paramNames
* @throws IllegalArgumentException if null
is passed in for
*
validParamValues
for a parameter whose
* class is of EnumeratedParameter
type.
*/
public ParameterListDescriptorImpl(Object descriptor,
String[] paramNames,
Class [] paramClasses,
Object[] paramDefaults,
Object[] validParamValues) {}
/**
* Returns the total number of parameters.
*/
public int getNumParameters() {}
/**
* Returns an array of Class
es that describe the types
* of parameters. If there are no parameters, this method returns
* null
.
*/
public Class[] getParamClasses() {}
/**
* Returns an array of String
s that are the
* names of the parameters associated with this descriptor. If there
* are no parameters, this method returns null
.
*/
public String[] getParamNames() {}
/**
* Returns an array of Object
s that define the default
* values of the parameters. Default values may be null
.
* The NO_PARAMETER_DEFAULT
static Object
* indicates that a parameter has no default value. If there are no
* parameters, this method returns null
.
*/
public Object[] getParamDefaults() {}
/**
* 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
.
*
* @param parameterName The name of the parameter whose default
* value is queried.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
*/
public Object getParamDefaultValue(String parameterName) {}
/**
* Returns the Range
that represents the range of valid
* values for the specified parameter. Returns null
if
* the parameter can take on any value or if the valid values are
* not representable as a Range.
*
* @param parameterName The name of the parameter whose valid range
* of values is to be determined.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
*/
public Range getParamValueRange(String parameterName) {}
/**
* Return an array of the names of all parameters the type of which is
* EnumeratedParameter
.
*
* @return The requested array of names or null
if there
* are no parameters with EnumeratedParameter
type.
*/
public String[] getEnumeratedParameterNames() {}
/**
* Return an array of EnumeratedParameter
objects
* corresponding to the parameter with the specified name.
*
* @param parameterName The name of the parameter for which the
* EnumeratedParameter
array is to be returned.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
* @throws UnsupportedOperationException if there are no enumerated
* parameters associated with the descriptor.
* @throws IllegalArgumentException if parameterName
is
* a parameter the class of which is not a subclass of
* EnumeratedParameter
.
*
* @return An array of EnumeratedParameter
objects
* representing the range of values for the named parameter.
*/
public EnumeratedParameter[] getEnumeratedParameterValues(String parameterName) {}
/**
* Checks to see if the specified parameter can take on the specified
* value.
*
* @param parameterName The name of the parameter for which the
* validity check is to be performed.
*
* @throws IllegalArgumentException if parameterName
is null
* or if the parameter does not exist.
* @throws IllegalArgumentException if the class of the object "value"
* is not an instance of the class type of parameter
* pointed to by the parameterName
*
* @return true, if it is valid to pass this value in for this
* parameter, false otherwise.
*/
public boolean isParameterValueValid(String parameterName, Object value) {}
}
3.3.3 ParameterList
-------------------
package javax.media.jai;
/**
* An interface to represent a list of parameter name-value pairs.
*
* String
s are done in a case
* insensitive (but retentive) manner.
*
* @see ParameterListDescriptor
*
* @since JAI 1.1
*/
public interface ParameterList {
/**
* Returns the associated ParameterListDescriptor
.
*/
public ParameterListDescriptor getParameterListDescriptor();
/**
* Sets a named parameter to a byte
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param b a byte
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, byte b);
/**
* Sets a named parameter to a boolean
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param b a boolean
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, boolean b);
/**
* Sets a named parameter to a char
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param c a char
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, char c);
/**
* Sets a named parameter to a short
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param s a short
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, short s);
/**
* Sets a named parameter to an int
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param i an int
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, int i);
/**
* Sets a named parameter to a long
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param l a long
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, long l);
/**
* Sets a named parameter to a float
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param f a float
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, float f);
/**
* Sets a named parameter to a double
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param d a double
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*/
public ParameterList setParameter(String paramName, double d);
/**
* Sets a named parameter to an Object
value.
*
* Implementing classes are free but not required to check class type,
* ranges, and enumeration types.
*
* @param paramName a String
naming a parameter.
* @param obj an Object
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* pointed to by the paramName.
*/
public ParameterList setParameter(String paramName, Object obj);
/**
* 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 wrapper class, such as
* Integer
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public Object getObjectParameter(String paramName);
/**
* A convenience method to return a parameter as a byte
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public byte getByteParameter(String paramName);
/**
* A convenience method to return a parameter as a boolean
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public boolean getBooleanParameter(String paramName);
/**
* A convenience method to return a parameter as a char
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public char getCharParameter(String paramName);
/**
* A convenience method to return a parameter as a short
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public short getShortParameter(String paramName);
/**
* A convenience method to return a parameter as an int
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public int getIntParameter(String paramName);
/**
* A convenience method to return a parameter as a long
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public long getLongParameter(String paramName);
/**
* A convenience method to return a parameter as a float
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public float getFloatParameter(String paramName);
/**
* A convenience method to return a parameter as a double
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public double getDoubleParameter(String paramName);
}
3.3.4 ParameterListImpl
-----------------------
package javax.media.jai;
/**
* A concrete implementation of the ParameterList
* interface. The number, names, Class types and default values are
* specified via the associated ParameterListDescriptor
* which should be supplied at construction time. This
* default implementation should be sufficient for most
* ParameterList
s and normally need not be sub-classed.
*
* @see ParameterList
* @see ParameterListDescriptor
*
* @since JAI 1.1
*/
public class ParameterListImpl
implements ParameterList, java.io.Serializable {
/**
* Creates a ParameterListImpl
using the specified
* ParameterListDescriptor
.
*
* @param descriptor a ParameterListDescriptor
describing
* the parameter names, defaults etc.
*
* @throws IllegalArgumentException if descriptor is null
* @throws IllegalArgumentException if the number of parameters in
* in "descriptor" is not the same as number of parameter
* names or defaults.
*/
public ParameterListImpl(ParameterListDescriptor descriptor) {}
/**
* Returns the associated ParameterListDescriptor
.
*/
public ParameterListDescriptor getParameterListDescriptor() {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param b a byte
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Byte
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, byte 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.
*
* @param paramName a String
naming a parameter.
* @param b a boolean
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Boolean
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, boolean b) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param c a char
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Character
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, char c) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param s a short
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a
Short
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, short s) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param i an int
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Integer
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, int i) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param l a long
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Long
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, long l) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param f a float
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Float
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, float f) {}
/**
* 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.
*
* @param paramName a String
naming a parameter.
* @param d a double
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the class type of parameter
* pointed to by the paramName is not a Double
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, double d) {}
/**
* Sets a named parameter to an Object
value.
* Checks are made to verify that the parameter is of the right
* Class
type and that the value is valid.
*
* @param paramName a String
naming a parameter.
* @param obj an Object
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalArgumentException if the parameter value is invalid.
*/
public ParameterList setParameter(String paramName, Object obj) {}
/**
* 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 wrapper class, such as
* Integer
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public Object getObjectParameter(String paramName) {}
/**
* A convenience method to return a parameter as a byte
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public byte getByteParameter(String paramName) {}
/**
* A convenience method to return a parameter as a boolean
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public boolean getBooleanParameter(String paramName) {}
/**
* A convenience method to return a parameter as a char
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public char getCharParameter(String paramName) {}
/**
* A convenience method to return a parameter as a short
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public short getShortParameter(String paramName) {}
/**
* A convenience method to return a parameter as an int
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public int getIntParameter(String paramName) {}
/**
* A convenience method to return a parameter as a long
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public long getLongParameter(String paramName) {}
/**
* A convenience method to return a parameter as a float
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public float getFloatParameter(String paramName) {}
/**
* A convenience method to return a parameter as a double
.
*
* @param paramName the name of the parameter to be returned.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public double getDoubleParameter(String paramName) {}
}
3.3.5 ParameterBlockJAI
-----------------------
Make ParameterBlockJAI implement ParameterList and
make it mode-aware. All the get/set methods will now work
on parameters for a specific "mode".
package javax.media.jai;
/**
* 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 String
s
* returned by OperationDescriptor.getSupportedModes()
.
*
* 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
.
*
* 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.
*
* 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.
*
* ParameterBlockJAI
for
* use with an operation described by a particular
* OperationDescriptor
. It uses the first
* mode in the array of String
s returned by
* OperationDescriptor.getSupportedModes()
* to get the ParameterListDescriptor
from
* OperationDescriptor
. The default values of the
* parameters are filled in.
*
* @param odesc the OperationDescriptor describing the parameters
* to be managed.
*/
public ParameterBlockJAI(OperationDescriptor odesc) {}
/**
* 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 String
s
* returned by OperationDescriptor.getSupportedModes()
* to get the ParameterListDescriptor
from
* OperationDescriptor
. The default values of the
* parameters are filled in.
*
* @param operationName a String
giving the name of the operation.
*
* @throws IllegalArgumentException if operationName is null.
*/
public ParameterBlockJAI(String operationName) {}
/**
* 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.
*
* @param odesc the OperationDescriptor describing the parameters
* to be managed.
* @param modeName the operation mode whose paramters are to be managed.
*
* @throws IllegalArgumentException if modeName is null or odesc is null
*
* @since JAI 1.1
*/
public ParameterBlockJAI(OperationDescriptor odesc, 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.
*
* @param operationName a String
giving the name of the operation.
* @param modeName the operation mode whose paramters are to be managed.
*
* @throws IllegalArgumentException if operationName or modeName is null
*
* @since JAI 1.1
*/
public ParameterBlockJAI(String operationName, String modeName) {}
/**
* Returns the zero-relative index of a named source within the list of
* sources.
*
* @param sourceName a String
containing the parameter name.
* @throws IllegalArgumentException if sourceName is null.
* @throws IllegalArgumentException if there is no source with the
* specified name.
*/
public int indexOfSource(String sourceName) {}
/**
* Returns the zero-relative index of a named parameter within the list of
* parameters.
*
* @param paramName a String
containing the parameter name.
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use "indexOfParam" instead.
*/
public int indexOf(String paramName) {}
/**
* Returns the zero-relative index of a named parameter within the list of
* parameters.
*
* @param paramName a String
containing the parameter name.
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @since JAI 1.1
*/
public int indexOfParam(String paramName) {}
/**
* Returns the OperationDescriptor
associated with this
* ParameterBlockJAI
.
*/
public OperationDescriptor getOperationDescriptor() {}
/**
* Returns the ParameterListDescriptor
that provides
* descriptions of the parameters associated with the operator
* and mode.
*
* @since JAI 1.1
*/
public ParameterListDescriptor getParameterListDescriptor() {}
/**
* Get the operation mode used to determine parameter names,
* classes and default values.
*
* @since JAI 1.1
*/
public String getMode() {}
/**
* Sets a named source to a given Object
value.
*
* @param sourceName a String
naming a source.
* @param source an Object
value for the source.
*
* @throws IllegalArgumentException if source
is null.
* @throws IllegalArgumentException if sourceName
is null.
* @throws IllegalArgumentException if source
is not
* an instance of (any of) the
* expected class(es).
* @throws IllegalArgumentException if the associated operation has
* no source with the supplied name.
*
* @since JAI 1.1
*/
public ParameterBlockJAI setSource(String sourceName, Object source) {}
/**
* Sets a named parameter to a byte
value.
*
* @param paramName a String
naming a parameter.
* @param b a byte
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(byte b, String paramName) {}
/**
* Sets a named parameter to a boolean
value.
*
* @param paramName a String
naming a parameter.
* @param b a boolean
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(boolean b, String paramName) {}
/**
* Sets a named parameter to a char
value.
*
* @param paramName a String
naming a parameter.
* @param c a char
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(char c, String paramName) {}
/**
* Sets a named parameter to a short value.
*
* @param paramName a String
naming a parameter.
* @param s a short value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(short s, String paramName) {}
/**
* Sets a named parameter to an int
value.
*
* @param paramName a String
naming a parameter.
* @param i an int
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(int i, String paramName) {}
/**
* Sets a named parameter to a long
value.
*
* @param paramName a String
naming a parameter.
* @param l a long
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(long l, String paramName) {}
/**
* Sets a named parameter to a float
value.
*
* @param paramName a String
naming a parameter.
* @param f a float
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(float f, String paramName) {}
/**
* Sets a named parameter to a double
value.
*
* @param paramName a String
naming a parameter.
* @param d a double
value for the parameter.
*
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(double d, String paramName) {}
/**
* Sets a named parameter to an Object value.
*
* @param paramName a String
naming a parameter.
* @param obj an Object value for the parameter.
*
* @throws IllegalArgumentException if obj is null, or if the class
* type of obj does not match the class type of parameter
* pointed to by the paramName.
* @throws IllegalArgumentException if paramName is null.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
*
* @deprecated as of JAI 1.1 - use setParameter
instead.
*/
public ParameterBlock set(Object obj, String paramName) {}
/**
* Adds an object to the list of parameters.
*
* This method always throws and IllegalStateException
* because the ParameterBlockJAI
constructor initializes
* all parameters with their default values.
*
* @throws IllegalStateException if parameters are added to an already
* initialized ParameterBlockJAI
*/
public ParameterBlock add(Object obj) {}
/**
* 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
.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public Object getObjectParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public byte getByteParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public boolean getBooleanParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public char getCharParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public short getShortParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public int getIntParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public long getLongParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public float getFloatParameter(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.
*
* @param paramName the name of the parameter to be returned.
* @throws IllegalArgumentException if there is no parameter with the
* specified name.
* @throws ClassCastException if the parameter is of a different type.
* @throws IllegalStateException if the parameter value is still
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public double getDoubleParameter(String paramName) {}
// ParameterList setParameter methods.
// Same as in ParameterListImpl
}
3.3.6 OperationDescriptor
-------------------------
Formally define registry modes with respect to operations. The
following modifications are intended to allow better
extensibility to as yet undefined modes, e.g., "volume",
"renderableVolume". Better flexibility is provided since once
could use the same method for multiple modes, e.g.,
isModeSupported() (from RegistryElementDescriptor) will replace
isRenderedSupported() and isRenderableSupported(). Operations
also would not be constrained to having parameters of the same
classes for different modes although the number and names of
parameters should remain constant. The bridge class
OperationDescriptorImpl will need to be extended to support the
changes discussed below.
package javax.media.jai;
/**
* 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.
*
*
*
* Additional information must be provided when appropriate. Only then
* can this operation be added to an Locale
s. OperationRegistry
.
* Furthermore, it is recommended that a detailed description of the
* operation's functionality be included in the class comments.
*
* 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.
*
* 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 JAI
* @see OperationDescriptorImpl
*
*/
public interface OperationDescriptor extends RegistryElementDescriptor {
/**
* An Object
that signifies that
* a parameter has no default value. Same as
* ParameterListDescriptor.NO_PARAMETER_DEFAULT
*/
public static final Object NO_PARAMETER_DEFAULT =
ParameterListDescriptor.NO_PARAMETER_DEFAULT;
/**
* Returns the resource data for this operation in the specified
* Locale
. It must contain String
data
* for the following tags:
*
*
* In addition, it may contain Locale
s. String
data for the
* following tags when appropriate:
*
*
*
* @param locale The Locale
for which the information
* should be localized. It may be different from the default
* Locale
.
*
* @return 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)
*/
String[][] getResources(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.
*
* @param locale The Locale
for which the information
* should be localized. It may be different from the default
* Locale
.
*
* @return A ResourceBundle
containing the mandatory
* and optional resource information.
*/
ResourceBundle getResourceBundle(Locale locale);
/**
* Returns the number of sources required by this operation.
* All modes have the same number of sources.
*/
int getNumSources();
/**
* 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
.
*
* @param modeName the operation mode name
*
* @throws IllegalArgumentException if modeName is null
*
* @since JAI 1.1
*/
Class[] getSourceClasses(String modeName);
/**
* 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 JAI 1.1
*/
String[] getSourceNames();
/**
* Returns a Class
that describes the type of
* destination this operation produces for the specified mode.
*
* @param modeName the operation mode name
*
* @throws IllegalArgumentException if modeName is null
*
* @since JAI 1.1
*/
Class getDestClass(String modeName);
/**
* 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
.
*
* 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.
*
* ParameterBlock
to their default values, if the default
* values are specified.
*
* @param modeName the operation mode name
* @param args Input arguments, including source(s) and/or parameter(s).
* @param msg A string that may contain error messages.
*
* @throws IllegalArgumentException if modeName is null
*
* @since JAI 1.1
*/
boolean validateArguments(String modeName, ParameterBlock args, StringBuffer msg);
/**
* 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.
*
* 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.
*/
boolean isImmediate();
/********************** DEPRECATED METHODS *************************/
// All mode specific methods are deprecated since JAI 1.1
// in favor of the equivalent methods which accept a modeName
// as a parameter.
/**
* 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.
*
* @return An array of PropertyGenerator
s, or
* null
if this operation does not have any of
* its own PropertyGenerator
s.
*
* @deprecated as of JAI 1.1 in favor of
* getPropertyGenerators(modeName)
* This will for the time being return the above value for
* modeName = getSupportedModes()[0]
*/
PropertyGenerator[] getPropertyGenerators();
/********************** Rendered Mode Methods (deprecated) *********/
/**
* 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.
*
* true
, all the additional
* methods that supply the rendered mode information must be
* implemented.
*
* @deprecated in favor of isModeSupported("rendered")
*/
boolean isRenderedSupported();
/**
* 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
.
*
* @deprecated in favor of getSourceClasses("rendered")
*/
Class[] getSourceClasses();
/**
* 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
.
*
* @deprecated in favor of getDestClass("rendered")
*/
Class getDestClass();
/**
* 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
.
*
* 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.
*
* ParameterBlock
to their default values, if the default
* values are specified.
*
* @param args Input arguments, including source(s) and/or parameter(s).
* @param msg A string that may contain error messages.
*
* @deprecated in favor of validateArguments("rendered", ...)
*/
boolean validateArguments(ParameterBlock args, StringBuffer msg);
/********************* Renderable Mode Methods (deprecated) ********/
/**
* 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.
*
* true
, all the additional
* methods that supply the renderable mode information must be
* implemented.
*
* @deprecated in favor of isModeSupported("renderable")
*/
boolean isRenderableSupported();
/**
* 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
.
*
* @deprecated in favor of getSourceClasses("renderable")
*/
Class[] getRenderableSourceClasses();
/**
* 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
.
*
* @deprecated in favor of getDestClass("renderable")
*/
Class getRenderableDestClass();
/**
* 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
.
*
* 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.
*
* ParameterBlock
to their default values, if the default
* values are specified.
*
* false
regardless of the input
* arguments
*
* @param args Input arguments, including source(s) and/or parameter(s).
* @param msg A string that may contain error messages.
*
* @deprecated in favor of validateArguments("renderable", ...)
*/
boolean validateRenderableArguments(ParameterBlock args, StringBuffer msg);
/************************ Parameter Methods (deprecated) ***********/
/**
* Returns the number of parameters (not including the sources)
* required by this operation.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getNumParameters()
* This will for the time being return the above value for
* modeName = getSupportedModes()[0]
*/
int getNumParameters();
/**
* 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
.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getParamClasses()
* This will for the time being return the above value for
* modeName = getSupportedModes()[0]
*/
Class[] getParamClasses();
/**
* 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
.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getParamDefaults()
* This will for the time being return the above value for
* modeName = getSupportedModes()[0]
*/
Object[] getParamDefaults();
/**
* 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
.
*
* @param index The index of the parameter whose default
* value is queried.
*
* @throws IllegalArgumentException if this operation has no parameter.
* @throws ArrayIndexOutOfBoundsException if there is no parameter
* corresponding to the specified index
.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getParamDefaultValue()
* This will for the time being return the above value for
* modeName = getSupportedModes()[0]
*/
Object getParamDefaultValue(int index);
/**
* Returns the minimum legal value of a specified numeric parameter
* for this operation. If the specified parameter is non-numeric,
* this method returns null
.
*
* Byte
for a
* byte
parameter, Integer
for an
* int
parameter, and so forth.
*
* @param index The index of the numeric parameter whose minimum
* value is queried.
*
* @return A Number
representing the minimum legal value
* of the queried parameter, or null
.
*
* @throws IllegalArgumentException if this operation has no parameter.
* @throws ArrayIndexOutOfBoundsException if there is no parameter
* corresponding to the specified index
.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getParamValueRange()
* This will for the time being use getSupportedModes()[0]
*
for modeName.
*
* Number
* class then this method returns null.
*
* Range
then it returns the getMinValue()
* of that Range
.
*
* Float
and Double
parameters
* it returns the corresponding -MAX_VALUE
and
* MIN_VALUE
for other Number
classes.
*/
Number getParamMinValue(int index);
/**
* Returns the maximum legal value of a specified numeric parameter
* for this operation. If the specified parameter is non-numeric,
* this method returns null
.
*
* Byte
for a
* byte
parameter, Integer
for an
* int
parameter, and so forth.
*
* @param index The index of the numeric parameter whose maximum
* value is queried.
*
* @return A Number
representing the maximum legal value
* of the queried parameter, or null
.
*
* @throws IllegalArgumentException if this operation has no parameter.
* @throws ArrayIndexOutOfBoundsException if there is no parameter
* corresponding to the specified index
.
*
* @deprecated in favor of
* getParameterListDescriptor(modeName).getParamValueRange()
* This will for the time being use getSupportedModes()[0]
*
for modeName.
*
* Number
* class then this method returns null.
*
* Range
then it returns the getMaxValue()
* of that Range
.
*
* MAX_VALUE
of the corresponding
* Number
class.
*/
Number getParamMaxValue(int index);
}
3.3.7 OperationDescriptorImpl
-----------------------------
Changes corresponding to those in OperationDescriptor.
package javax.media.jai;
/**
* This class provides an implementation of the
* OperationDescriptor
interface, and is suitable for
* subclassing.
*
* @see OperationDescriptor
* @see RegistryElementDescriptor
*
*/
public abstract class OperationDescriptorImpl implements OperationDescriptor {
// Constructors...
/**
* Constructor. Note that sourceClasses[m][i]
* corresponds to the mode supportedModes[m]
* and the source sourceNames[i]
. Similarly
* paramClasses[m][i]
corresponds to the
* mode supportedModes[m]
and the parameter
* paramNames[i]
. The same holds true for
* paramDefaults
and validParamValues
*
* @param resources The resource tags and their corresponding data.
* @param supportedModes The modes that this operator supports.
* maybe one or more of "rendered", "renderable", "collection",
* and "renderableCollection" (or other image operation related
* modes that maybe defined later). Must support atleast one mode.
* @param sourceNames The source names. It may be null
* if this operation has no sources or if the default source
* naming convention ("source0", "source1", etc.) is to be used.
* @param sourceClasses The source types required by this operation
* for each of the above supported modes. can be null
* if this operation has no sources. The number of
* sources for each mode must be the same.
* @param paramNames The localized parameter names. It may be
* null
if this operation has no parameters.
* @param paramClasses The parameter types required by this operation.
* for each mode. It may be null
if this operation
* has no parameters. The number of parameters for each mode
* must be the same.
* @param paramDefaults The parameter default values for each parameter
* for each mode. It may be null
if this
* operation has no parameters, or none of the parameters has
* a default value for any mode. The parameter defaults for an
* individual mode may be null, if there are no defaults for
* that mode.
* @param validParamValues defines the valid values for each parameter
* for each mode. this can be null
if the operation
* has no parameters. Otherwise each element can be filled in as
* defined in {@link ParameterListDescriptorImpl(
* Object, String[], Class[], Object[], Object[])}
*
* @throws IllegalArgumentException if resources
is
* null
.
* @throws IllegalArgumentException if supportedModes is null
* @throws IllegalArgumentException if the number of sourceClasses
* for each mode is not the same or is not equal to the number
* of sourceNames (if non-null).
* @throws IllegalArgumentException if this operation has parameters and
* paramClasses
or paramNames
is
* null
.
* @throws IllegalArgumentException if sourceNames
* is non-null
and its length does not equal
* the number of sources of this operation.
* @throws IllegalArgumentException if this operation has parameters
* and paramClasses
, paramNames
,
* and paramDefaults
(if all are not
* null
) do not all have the same number of elements.
*
* @since JAI 1.1
*/
public OperationDescriptorImpl(String[][] resources,
String[] supportedModes,
String[] sourceNames,
Class [][] sourceClasses,
String[] paramNames,
Class [][] paramClasses,
Object[][] paramDefaults,
Object[][] validParamValues) {}
/**
* Constructor. This assumes that all modes have the same
* set of parameter classes, defaults and valid values. Note
* that sourceClasses[m][i]
corresponds to
* the mode supportedModes[m]
and the source
* sourceNames[i]
.
*
* @param resources The resource tags and their corresponding data.
* @param supportedModes The modes that this operator supports.
* maybe one or more of "rendered", "renderable", "collection",
* and "renderableCollection". Must support atleast one mode.
* @param sourceNames The source names. It may be null
* if this operation has no sources or if the default source
* naming convention ("source0", "source1", etc.) is to be used.
* @param sourceClasses The source types required by this operation
* for each of the above supported modes. can be null
* if this operation has no sources. The number of
* sources for each mode must be the same.
* @param paramNames The localized parameter names. It may be
* null
if this operation has no parameters.
* @param paramClasses The parameter types required by this operation.
* It may be null
if this operation has no parameters.
* @param paramDefaults The parameter default values for each parameter
* It may be null
if this operation has no
* parameters, or none of the parameters has a default value.
* @param validParamValues defines the valid values for each parameter
* for all modes. this can be null
if the operation
* has no parameters. Otherwise it can be filled in as
* defined in {@link ParameterListDescriptorImpl(
* Object, String[], Class[], Object[], Object[])}
*
* @throws IllegalArgumentException if resources
is
* null
.
* @throws IllegalArgumentException if supportedModes is null
* @throws IllegalArgumentException if the number of sourceClasses
* for each mode is not the same or is not equal to the number
* of sourceNames (if non-null).
* @throws IllegalArgumentException if this operation has parameters and
* paramClasses
or paramNames
is
* null
.
* @throws IllegalArgumentException if sourceNames
* is non-null
and its length does not equal
* the number of sources of this operation.
* @throws IllegalArgumentException if this operation has parameters
* and paramClasses
, paramNames
,
* and paramDefaults
(if all are not
* null
) do not all have the same number of elements.
*
* @since JAI 1.1
*/
public OperationDescriptorImpl(String[][] resources,
String[] supportedModes,
String[] sourceNames,
Class [][] sourceClasses,
String[] paramNames,
Class [] paramClasses,
Object[] paramDefaults,
Object[] validParamValues) {}
/**
* Constructor which accepts a ParameterListDescriptor
* to describe the parameters for each mode. Note
* that sourceClasses[m][i]
corresponds to
* the mode supportedModes[m]
and the source
* sourceNames[i]
.
*
* @param resources The resource tags and their corresponding data.
* @param supportedModes The modes that this operator supports.
* maybe one or more of "rendered", "renderable", "collection",
* and "renderableCollection". Must support atleast one mode.
* @param sourceNames The source names. It may be null
* if this operation has no sources or if the default source
* naming convention ("source0", "source1", etc.) is to be used.
* @param sourceClasses The source types required by this operation
* for each of the above supported modes. can be null
* if this operation has no sources. The number of
* sources for each mode must be the same.
* @param pld the parameter list descriptor for each mode.
* Can be null
if there are no parameters.
*
* @throws IllegalArgumentException if resources
is
* null
.
* @throws IllegalArgumentException if supportedModes is null
* @throws IllegalArgumentException if the number of sourceClasses
* for each mode is not the same or is not equal to the number
* of sourceNames (if non-null).
* @throws IllegalArgumentException if sourceNames
* is non-null
and its length does not equal
* the number of sources of this operation.
*
* @since JAI 1.1
*/
public OperationDescriptorImpl(String[][] resources,
String[] supportedModes,
String[] sourceNames,
Class [][] sourceClasses,
ParameterListDescriptor[] pld) {}
/**
* Constructor. This assumes that all modes use the same
* ParameterListDescriptor
. Note
* that sourceClasses[m][i]
corresponds to
* the mode supportedModes[m]
and the source
* sourceNames[i]
.
*
* @param resources The resource tags and their corresponding data.
* @param supportedModes The modes that this operator supports.
* maybe one or more of "rendered", "renderable", "collection",
* and "renderableCollection". Must support atleast one mode.
* @param sourceNames The source names. It may be null
* if this operation has no sources or if the default source
* naming convention ("source0", "source1", etc.) is to be used.
* @param sourceClasses The source types required by this operation
* for each of the above supported modes. can be null
* if this operation has no sources. The number of
* sources for each mode must be the same.
* @param pld the parameter list descriptor for all modes.
* Can be null
if there are no parameters.
*
* @throws IllegalArgumentException if resources
is
* null
.
* @throws IllegalArgumentException if supportedModes is null
* @throws IllegalArgumentException if the number of sourceClasses
* for each mode is not the same or is not equal to the number
* of sourceNames (if non-null).
* @throws IllegalArgumentException if sourceNames
* is non-null
and its length does not equal
* the number of sources of this operation.
*
* @since JAI 1.1
*/
public OperationDescriptorImpl(String[][] resources,
String[] supportedModes,
String[] sourceNames,
Class [][] sourceClasses,
ParameterListDescriptor pld) {}
// BEGIN : RegistryElementDescriptor methods
/**
* Returns the name of this operation; this is the same as the
* GlobalName
value in the resources and is visible
* to all. This is also descriptor name under which it is registered
* in the OperationRegistry
.
*
* @return A String
representing the operation's
* global name.
*
* @throws MissingResourceException if the GlobalName
* resource value is not supplied in the resources
.
*/
public String getName() {}
/**
* The registry modes supported by this descriptor. Known modes
* include those returned by RegistryMode.getModes()
*
* @return an array of String
s specifying the supported modes.
*
* @see RegistryMode
* @see RegistryElementDescriptor
*
* @since JAI 1.1
*/
public String[] getSupportedModes() {}
/**
* Does this descriptor support the specified registry mode ?.
* The modeName
s are treated in a case-insensitive
* (but retentive) manner.
*
* @param modeName the registry mode name
*
* @return true, if the implementation of this descriptor supports
* the specified mode. false otherwise.
*
* @throws IllegalArgumentException if modeName is null
*
* @see RegistryElementDescriptor
*
* @since JAI 1.1
*/
public boolean isModeSupported(String modeName) {}
/**
* Does this descriptor support properties ?
*
* @return The default implementation in this class returns
* true
so that properties are always supported.
* Operations that do not wish to support properties must
* override this implementation.
*
* @see PropertyGenerator
* @see RegistryElementDescriptor
*
* @since JAI 1.1
*/
public boolean arePropertiesSupported() {}
/**
* Returns an array of PropertyGenerator
s implementing
* the property inheritance for this operator that may be used as
* a basis for the operation's property management. The default
* implementation returns null
, indicating that source
* properties are simply copied. Subclasses should override this
* method if they wish to produce inherited properties.
*
* getPropertyGenerators()
, if the modeName is either
* "rendered" or "renderable".
*
* @param modeName the registry mode name
*
* @return An array of PropertyGenerator
s, or
* null
if this operation does not have any of
* its own PropertyGenerator
s.
*
* @throws IllegalArgumentException if modeName
is null
* @throws UnsupportedOperationException if arePropertiesSupported
* returns false
*
* @see RegistryElementDescriptor
*
* @since Java Advanced Imaging 1.1
*/
public PropertyGenerator[] getPropertyGenerators(String modeName) {}
/**
* Returns the ParameterListDescriptor
that describes
* the associated parameters (not sources). This method returns
* null if there are no parameters for the specified modeName.
* If the specified modeName supports parameters but the
* implementing class does not have parameters, then this method
* returns a non-null ParameterListDescriptor
whose
* getNumParameters()
returns 0.
*
* @param modeName
*
* @throws IllegalArgumentException if modeName is null
*
* @see RegistryElementDescriptor
*
* @since JAI 1.1
*/
public ParameterListDescriptor getParameterListDescriptor(String modeName) {}
// END : RegistryElementDescriptor methods
/**
* Returns the resource data for this operation. It must contain
* String
data for the following tags: "GlobalName",
* "LocalName", "Vendor", "Description", "DocURL", and "Version".
* Additional resources should be supplied when appropriate.
*
* Locale
argument, and always returns
* the String
s in the default Locale
.
*
* @param locale The Locale
in which to localize the
* resource data.
*
* @return 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)
*/
public String[][] getResources(Locale locale) {}
/**
* Returns the resource data for this operation in a
* ResourceBundle
. The resource data are taken from the
* getResources()
method.
*
* Locale
* argument, and always returns the resources in the default
* Locale
.
*
* @param locale The Locale
in which to localize the
* resource data.
*
* @return A ResourceBundle
containing mandatory and
* optional resource information.
*/
public ResourceBundle getResourceBundle(Locale locale) {}
/**
* Returns the number of sources required by this operation.
* All modes have the same number of sources.
*/
public int getNumSources() {}
/**
* 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
.
*
* @param modeName the operation mode name
*
* @throws IllegalArgumentException if modeName is null
*
* @since JAI 1.1
*/
public Class[] getSourceClasses(String modeName) {}
/**
* 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
. If this
* operation has sources but their names were not provided at
* construction time, then the returned names will be of the
* form "source0", "source1", etc.
*
* @since JAI 1.1
*/
public String[] getSourceNames() {}
/**
* Returns true
if this operation supports the specified
* mode, and is capable of handling the given input source(s) for the
* specified mode. The default implementation ensures that the
* ParameterBlock
has atleast the required number of
* sources, the class type of the first getNumSources()
,
* and any null sources. Any extra sources in the
* ParameterBlock
are ignored. Subclasses
* should override this implementation if their requirement on the
* sources are different from the default. This could be used by
* validateArguments
to validate the sources.
*
* ParameterBlock
that has the sources
* @param msg A string that may contain error messages.
*
* @throws IllegalArgumentException if args
is null
.
* @throws IllegalArgumentException if msg
is null
* and the validation fails.
*
* @since Java Advanced Imaging 1.1
*
* @see #validateArguments
*/
protected boolean validateSources(String modeName,
ParameterBlock args,
StringBuffer msg) {}
/**
* Returns true
if this operation is capable of
* handling the input parameters for the specified mode. The default
* implementation validates the number of parameters, the class type
* of each parameter, and null parameter. For non-null parameters,
* it also checks to see if the parameter value is valid. Subclasses
* should override this implementation if their requirement on the
* parameter objects are different from the default. This could be used by
* validateArguments
to validate the parameters.
*
* ParameterBlock
; else this method returns
* false
.
*
* ParameterBlock
to their default values, if the default
* values are specified.
*
* DeferredData
parameters will not be
* recognized as valid unless the parameter is defined to have class
* DeferredData.class
.
*
* args
is null
.
* @throws IllegalArgumentException if msg
is null
* and the validation fails.
*
* @since Java Advanced Imaging 1.1
*
* @see #validateArguments
* @see ParameterListDescriptorImpl#isParameterValueValid
*/
protected boolean validateParameters(String modeName, ParameterBlock args,
StringBuffer msg) {}
/**
* Returns a Class
that describes the type of
* destination this operation produces for the specified mode.
*
* null
*
* @since JAI 1.1
*/
public Class getDestClass(String modeName) {}
/**
* 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
.
*
* 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.
*
* validateSources
and validateParameters
.
*
* ParameterBlock
to their default values, if the default
* values are specified.
*
* DeferredData
parameters will not be
* recognized as valid unless the parameter is defined to have class
* DeferredData.class
.
*
* @param modeName the operation mode name
* @param args Input arguments, including source(s) and/or parameter(s).
* @param msg A string that may contain error messages.
*
* @throws IllegalArgumentException if modeName is null
*
* @since Java Advanced Imaging 1.1
*
* @see #validateSources
* @see #validateParameters
*/
public boolean validateArguments(String modeName, ParameterBlock args, StringBuffer msg) {}
/**
* 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.
*
* 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.
*
* false
so that deferred execution is invoked.
* Operations that wish to be placed in the immediate mode must
* override this implementation.
*/
public boolean isImmediate() {}
/********************** DEPRECATED Constructors ********************/
/**
* Constructor.
*
* ...
*
* @deprecated as of Java(tm) Advanced Imaging 1.1 in favor of
* constructors where supported modes are explicitly specified.
* Uses isRenderedSupported()
and
* isRenderableSupported()
to figure out the supported modes.
*/
public OperationDescriptorImpl(String[][] resources,
Class[] sourceClasses,
Class[] renderableSourceClasses,
Class[] paramClasses,
String[] paramNames,
Object[] paramDefaults) {}
/**
* Constructor for operations that supports only the rendered mode
* and requires no parameters.
*
* ...
*
* @deprecated since JAI 1.1 in favor of constructors where the mode
* specfic information is explicitly specified.
*/
public OperationDescriptorImpl(String[][] resources,
Class[] sourceClasses) {}
/**
* Constructor for operations that supports either the rendered
* or the renderable or both modes and requires no parameters.
*
* ...
*
* @deprecated since JAI 1.1 in favor of constructors where the mode
* specfic information is explicitly specified.
*/
public OperationDescriptorImpl(String[][] resources,
Class[] sourceClasses,
Class[] renderableSourceClasses) {}
/**
* Constructor for operations that supports either the rendered
* or the renderable or both modes and requires no sources.
*
* ...
*
* @deprecated since JAI 1.1 in favor of constructors where the mode
* specfic information is explicitly specified.
*/
public OperationDescriptorImpl(String[][] resources,
Class[] paramClasses,
String[] paramNames,
Object[] paramDefaults) {}
/**
* Constructor for operations that support either the rendered
* or the renderable or both modes. The class type for all the
* source(s) of the rendered mode (if supported) is set to
* java.awt.image.RenderedImage.class
.
* The class type for all the source(s) of the renderable mode (if
* supported) is set to
* java.awt.image.renderable.RenderableImage
.
*
* ...
*
* @deprecated as of Java(tm) Advanced Imaging 1.1 in favor of
* constructors where supported modes are explicitly specified.
* Uses isRenderedSupported()
and
* isRenderableSupported()
to figure out the supported modes.
*/
public OperationDescriptorImpl(String[][] resources,
int numSources,
Class[] paramClasses,
String[] paramNames,
Object[] paramDefaults) {}
/**
* Constructor for operations that support the rendered mode and
* possibly the renderable mode and require no parameters. The
* class type for all the source(s) of the rendered mode is set to
* java.awt.image.RenderedImage.class
.
* The class type for all the source(s) of the renderable mode (if
* supported) is set to
* java.awt.image.renderable.RenderableImage
.
*
* ...
*
* @deprecated since JAI 1.1 in favor of constructors where the mode
* specfic information is explicitly specified.
*/
public OperationDescriptorImpl(String[][] resources,
int numSources) {}
/********************** DEPRECATED METHODS *************************/
// Deprecated methods listed in OperationDescriptor
}
3.4. RegistryMode Classes
-------------------------
"Registry Mode" is concept that encompasses all operation modes
(rif/crif/cif etc), tilecodec-s, remoterif/remotecrif and
provides a unified way of registering/unregistering or
setting/unsetting preferences for these through the operation
registry.
RegistryMode is the parent class for registry mode
definition. A registry mode has a name, product type, factory
method definition, and preferences flag. The product type is
redundant as this is available from the factory method
definition but it is provided for convenience nonetheless.
Examples of registry modes include "rendered", "renderable",
"collection", "renderableCollection", "tileEncoder",
"tileDecoder", "remoteRendered" & "remoteRenderable"
RenderedRegistryMode and RenderableRegistryMode are
specific classes for the rendered and renderable modes,
respectively.
package javax.media.jai;
/**
* A class which provides information about a registry mode. The
* static methods of the class act to maintain a global list of
* known modes. All RegistryMode
s known
* to JAI are added to this list when this class is loaded. The
* RegistryMode
s installed by JAI cannot be
* replaced or removed.
*
* The String
s used to represent the registry modes
* are all used in a case-insensitive manner.
*
* @since JAI 1.1
*/
public abstract class RegistryMode {
/**
* Adds a new RegistryMode
to the existing list. This
* succeeds only if the mode is not already present in the
* list. New
method of each
* RegistryMode
names can not clash (in a
* case insensitive manner) with the ones installed by JAI (done
* statically when this class is loaded)
*
* @param mode the new RegistryMode to be added to list
*
* @return false if the mode was already in the list. true otherwise
*/
public static boolean addMode(RegistryMode mode) {}
/**
* Removes a mode from the existing list of known registryModes.
* If the mode is one of the JAI-installed ones, it can not
* be removed.
*/
public static boolean removeMode(String name) {}
/**
* Get the list of the known registry mode names.
*/
public static String[] getModeNames() {}
/**
* Get a list of all known registry modes associated with
* the specified descriptorClass
.
*
* @param descriptorClass a Class
*/
public static synchronized String[] getModeNames(Class descriptorClass) {}
/**
* Get the registry mode corresponding to this name.
*/
public static RegistryMode getMode(String name) {}
/**
* Constructor. Protected access allows only instantiation of
* subclasses.
*
* @param name name of the registry mode
* @param factoryMethod the method used to "create" an object.
* @param arePreferencesSupported does this registry mode support
* preferences between products or instances of the "modes"
* @param arePropertiesSupported do properties have to be managed
* for this registry mode.
*/
protected RegistryMode(String name,
Class descriptorClass,
Method factoryMethod,
boolean arePreferencesSupported,
boolean arePropertiesSupported) {}
// Instance methods.
/** Get the registry mode name (case-preserved) */
public final String getName() {}
/** Get the factory method that corresponds to "create" */
public final Method getFactoryMethod() {}
/**
* Does this registry mode support properties ?
*
* @see PropertyGenerator
*/
public final boolean arePropertiesSupported() {}
/** Does this registry mode support preferences ? */
public final boolean arePreferencesSupported() {}
/**
* Returns the descriptor class that corresponds to this registry mode.
*
* For eg. this would be OperationDescriptor for rendered/renderable etc
* and TileCodecDescriptor for tilecodec-s etc.
*/
public final Class getDescriptorClass() {}
/**
* A convenience method which essentially returns
* getFactoryMethod().getReturnType()
*/
public final Class getProductClass() {}
/**
* A convenience method which essentially returns
* getFactoryMethod().getDeclaringClass()
*/
public final Class getFactoryClass();
}
package javax.media.jai.registry;
/**
* A class that provides information about the "rendered" registry
* (operation) mode.
*
* @since JAI 1.1
*/
public final class RenderedRegistryMode extends RegistryMode {
public RenderedRegistryMode() { }
}
package javax.media.jai.registry;
/**
* A class that provides information about the "renderable" registry
* (operation) mode.
*
* @since JAI 1.1
*/
public final class RenderableRegistryMode extends RegistryMode {
public RenderableRegistryMode() {}
}
// Add Other subclasses of RegistryMode:
// CollectionRegistryMode, RenderableCollectionRegistryMode,
// TileEncoderRegistryMode, TileDecoderRegistryMode,
// RemoteRenderedRegistryMode, RemoteRenderableRegistryMode.
3.5 OperationRegistry
---------------------
The OperationRegistry will be overhauled to add support for
maintaining different types of object factories (RegistryMode)
which have support some type of a RegistryElementDescriptor. These
factories can optionally support preferences and properties.
Examples of these factories (known to JAI) include
RenderedImageFactory, ContextualRenderedImageFactory,
CollectionImageFactory, RenderableCollectionImageFactory,
TileEncoderFactory, TileDecoderFactory, RemoteRenderedFactory &
RemoteRenderableFactory
3.5.1 Revisions to Extant Methods
---------------------------------
All existing methods which refer specifically to RIF, CRIF, or
CIF objects would be re-implemented in terms of the generic
implementation described above. These type-safe methods in the
registry will be deprecated. The compile time type-safe
versions of these methods will be provided though seperate
wrapper classes (RIFRegistry, CIFRegistry etc.) and this would
be the preferred mode of usage.
3.5.2 New Methods
-----------------
The following methods and the implementations thereof would be
added to OperationRegistry.
// Only modifications of OperationRegistry are included below.
/**
* A class responsible for maintaining a registry of various types of
* factory objects and preferences among them. The operation registry
* hierarchy looks as follows
*
*
*
* |-object1-
* |-product1-|-object2-
* |-descriptor1-| |-object3-
* | |
* | | |-object1-
* | |-product2-|-object2-
* |-mode1-| |-object3-
* | |
* |-OperationRegistry-| | |-object1-
* | | |-product1-|-object2-
* | |-descriptor2-| |-object3-
* | |
* | | |-object1-
* | |-product2-|-object2-
* | |-object3-
* |
* |-mode2-|-descriptor1-|-object1--
* |
* |-descriptor2-|-object1--
*
*
* OperationRegistry
class maps a descriptor name
* (for example, an image operation name) into the particular kind of
* factory object requested, capable of implementing the functionality
* described by the descriptor. The mapping is constructed in several
* stages:
*
* String
which must be one
* of those returned by RegistryMode.getModeNames()
.
* Examples of known registry modes include "rendered", "renderable",
* "collection", "renderableCollection", "tileEncoder", "tileDecoder",
* "remoteRendered", "remoteRenderable", etc.
*
*
* RegistryElementDescriptor
which describes some functionality
* to be implemented by factory objects associated with this
* descriptor. For example, the "rendered" registry mode is associated
* with OperationDescriptor.class
and "tileEncoder"
* is associated with TileCodecDescriptor.class
.
* Different registry modes can share the same
* RegistryElementDescriptor
. For example "rendered", "renderable"
* (and other image operation registry modes) are all associated with
* OperationDescriptor.class
.
*
* OperationDescriptor
,
* and by the order of the factory objects within each product. The
* orders are established by setting pairwise preferences, resulting in
* a partial order which is then sorted topologically. The results of
* creating a cycle are undefined.
*
* RenderedImageFactory
that implements
* separable convolution ahead of a RenderedImageFactory
* that implements a more general algorithm.
*
* OperationRegistry
has several methods to manage this
* hierarchy, which accept a modeName
and work with
* Object
s. The preferred manner of usage is through the type-safe
* wrapper class which are specific to each mode (for example
* RIFRegistry
, CRIFRegistry
etc.)
*
* OperationRegistry
also has the responsibility
* of associating a set of PropertyGenerators
* with each descriptor. This set will be coalesced
* into a PropertySource
suitable for
* use by the getPropertySource() method. If several
* PropertyGenerator
s associated with a particular
* descriptor generate the same property, only the last one to be
* registered will have any effect.
*
* OperationRegistry
created is
* not thread-safe.
*
* @see getThreadSafeOperationRegistry
*/
public OperationRegistry() {}
/**
* Creates and returns a new thread-safe version of the
* OperationRegistry
which uses reader-writer
* locks to wrap every method with a read or a write lock
* as appropriate.
*/
public static OperationRegistry getThreadSafeOperationRegistry() {}
/**
* Remove a registry mode (including pre-defined JAI modes) from
* the OperationRegistry. When a mode is removed, all associated
* descriptors are also removed unless associated with another
* mode. Note that this does not unregister this mode from
* RegistryMode
*
* Also note that a registry mode need not be explicitly added to
* the OperationRegistry
. All modes registered under
* RegistryMode
are automatically recognized by the
* OperationRegistry
.
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
*
* @since JAI 1.1
*/
public void removeRegistryMode(String modeName) {}
/**
* Get's the list of known registry modes.
*
* @since JAI 1.1
*/
public String[] getRegistryModes() {}
//////////////////
//
// Set of methods to register/unregister descriptors
// with the operation registry.
/**
* Register a descriptor against all the registry modes it
* supports. The "descriptor" must be an instance of the
* RegistryMode.getDescriptorClass() The "descriptor" is keyed on
* descriptor.getName(). Only one descriptor can be registered
* against a descriptor name for a given mode.
*
* @param descriptor an instance of a concrete sub-class of
* RegistryElementDescriptor
*
* @throws IllegalArgumentException is descriptor is null
* @throws IllegalArgumentException if any of the modes returned
* by descriptor.getSupportedModes()
is not one
* of those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if another descriptor with the
* same name has already been registered against any of the
* modes supported by this descriptor.
*
* @since JAI 1.1
*/
public void registerDescriptor(RegistryElementDescriptor descriptor) {}
/**
* Unregister a descriptor against all its supported modes from the
* operation registry.
*
* @param descriptor an instance of a concrete sub-class of
* RegistryElementDescriptor
*
* @throws IllegalArgumentException is descriptor is null
* @throws IllegalArgumentException if any of the modes returned
* by descriptor.getSupportedModes()
is not one
* of those returned by RegistryMode.getModes()
*
* @since JAI 1.1
*/
public void unregisterDescriptor(RegistryElementDescriptor descriptor) {}
/**
* Get the RegistryElementDescriptor
* corresponding to a descriptorClass
* and a descriptorName
. For example,
* getDescriptor(OperationDescriptor.class, "add")
* would get the operation descriptor for the "add" image operation.
* Note that different descriptors might have been registered
* against each mode associated with the descriptorClass. In this
* case this methods will arbitrarily return the first descriptor
* it encounters with a matching descriptorName and descriptorClass.
*
* @param descriptorClass the descriptor Class
* @param descriptorName the descriptor name as a String
*
* @throws IllegalArgumentException if descriptorClass
is
* null
or if the descriptorClass
is
* not associated with any of the modes returned
* RegistryMode.getModes()
* @throws IllegalArgumentException if descriptorName is null
*
* @since JAI 1.1
*/
public RegistryElementDescriptor getDescriptor(
Class descriptorClass, String descriptorName) {}
/**
* Get a List
of all RegistryElementDescriptor
* corresponding to the descriptorClass
. For example,
* getDescriptors(OperationDescriptor.class)
* would get a list of all image operation descriptors.
*
* @param descriptorClass the descriptor Class
*
* @throws IllegalArgumentException if descriptorClass
is
* null
or if the descriptorClass
is
* not associated with any of the modes returned
* RegistryMode.getModes()
*
* @since JAI 1.1
*/
public List getDescriptors(Class descriptorClass) {}
/**
* Get an array of all the descriptor names
* corresponding to the descriptorClass
. For example,
* getDescriptorNames(OperationDescriptor.class)
* would get an array of all image operation descriptor names.
*
* @param descriptorClass the descriptor Class
*
* @throws IllegalArgumentException if descriptorClass
is
* null
or if the descriptorClass
is
* not associated with any of the modes returned
* RegistryMode.getModes()
*
* @since JAI 1.1
*/
public String[] getDescriptorNames(Class descriptorClass) {}
/**
* Get the RegistryElementDescriptor
corresponding to
* descriptorName
which supports the specified mode.
* This is done by matching up the descriptorName
* against RegistryElementDescriptor.getName
in a
* case-insensitive manner. This returns null
if there
* no RegistryElementDescriptor
corresponding to
* descriptorName
that supports the specified mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
* @throws IllegalArgumentException if descriptorName is null
*
* @since JAI 1.1
*/
public RegistryElementDescriptor getDescriptor(String modeName,
String descriptorName) {}
/**
* Get a list of all RegistryElementDescriptor
s registered
* under a given registry mode.
*
* @param modeName the registry mode name as a String
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
*
* @since JAI 1.1
*/
public List getDescriptors(String modeName) {}
/**
* Get an array of all descriptor-names of descriptors registered
* under a given registry mode.
*
* @param modeName the registry mode name as a String
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
*
* @since JAI 1.1
*/
public String[] getDescriptorNames(String modeName) {}
//////////////////
//
// Set of methods to set/unset/clear product preferences
/**
* Set the preference between two products for a descriptor
* registered under a registry mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param preferredProductName the product to be preferred.
* @param otherProductName the other product.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void setProductPreference(String modeName,
String descriptorName,
String preferredProductName,
String otherProductName) {}
/**
* Remove the preference between two products for a descriptor
* registered under a registry mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param preferredProductName the product formerly preferred.
* @param otherProductName the other product.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void unsetProductPreference(String modeName,
String descriptorName,
String preferredProductName,
String otherProductName) {}
/**
* Remove all the preferences between products for a descriptor
* registered under a registry mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
* @throws IllegalArgumentException if descriptorName is null
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void clearProductPreferences(String modeName,
String descriptorName) {}
/**
* Returns a list of the pairwise product preferences
* under a particular descriptor registered against a registry mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @return an array of 2-element arrays of Strings.
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
* @throws IllegalArgumentException if descriptorName is null
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public String[][] getProductPreferences(String modeName,
String descriptorName) {}
/**
* Returns a list of the products registered under a particular
* descriptor in an ordering that satisfies all of the pairwise
* preferences that have been set. Cycles will be broken in an
* arbitrary manner. Returns null if no descriptor has been
* registered under this descriptorName, or if no products exist for
* this operation.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @return a Vector
of Strings representing product names.
*
* @throws IllegalArgumentException if modeName is null
* or if the modeName is not one of the modes returned
* RegistryMode.getModes()
* @throws IllegalArgumentException if descriptorName is null
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public Vector getOrderedProductList(String modeName,
String descriptorName) {}
//////////////////
//
// Set of methods to maintain factory objects to register/unregister
// & set/unset/clear preferences & get-ordered-lists of factory
// objects
/**
* Register a factory object with a particular product and descriptor
* against a specified mode. For modes that do not support preferences
* the productName is ignored (can be null
)
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
* @param factory the object to be registered.
*
* @throws IllegalArgumentException if any of the arguments
* is null
(productName can be null
* for modes that do not support preferences).
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since JAI 1.1
*/
public void registerFactory(String modeName,
String descriptorName,
String productName,
Object factory) {}
/**
* Unregister a factory object previously registered with a product
* and descriptor against the specified mode. For modes that do
* not support preferences the productName is ignored (can be
* null
)
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
* @param factory the object to be unregistered.
*
* @throws IllegalArgumentException if any of the arguments
* is null
(productName can be null
* for modes that do not support preferences).
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the factory object was not previously
* registered against descriptorName and productName
*
* @since JAI 1.1
*/
public void unregisterFactory(String modeName,
String descriptorName,
String productName,
Object factory) {}
/**
* Sets a preference between two factory instances for a given
* operation under a specified product.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
* @param preferredOp the preferred factory object
* @param otherOp the other factory object
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if either of the factory objects
* were not previously registered against
* descriptorName and productName
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void setFactoryPreference(String modeName,
String descriptorName,
String productName,
Object preferredOp,
Object otherOp) {}
/**
* Unsets a preference between two factory instances for a given
* operation under a specified product.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
* @param preferredOp the factory object formerly preferred
* @param otherOp the other factory object
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if either of the factory objects
* were not previously registered against
* descriptorName and productName
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void unsetFactoryPreference(String modeName,
String descriptorName,
String productName,
Object preferredOp,
Object otherOp) {}
/**
* Removes all preferences between instances of a factory
* within a product registered under a particular
* OperationDescriptor
.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the registry mode does not
* support preferences
*
* @since JAI 1.1
*/
public void clearFactoryPreferences(String modeName,
String descriptorName,
String productName) {}
/**
* Get all pairwise preferences between instances of a factory
* within a product registered under a particular
* OperationDescriptor
.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since Java Advanced Imaging 1.1
*/
public Object[][] getFactoryPreferences(String modeName,
String descriptorName,
String productName) {}
/**
* Returns a list of the factory instances of a product registered
* under a particular OperationDescriptor
, in an
* ordering that satisfies all of the pairwise preferences that have
* been set. Cycles will be broken in an arbitrary manner. Returns
* null, if the product does not exist under this descriptorName.
*
* If the particular factory does not have preferences then the
* returned List
will contain single factory.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param productName the product name as a String
*
* @return an ordered List
of factory instances
*
* @throws IllegalArgumentException if any of the arguments
* is null
(productName can be null
* for modes that do not support preferences).
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since JAI 1.1
*/
public List getOrderedFactoryList(String modeName,
String descriptorName,
String productName) {}
/**
* Returns an Iterator
over all factory objects
* registered with the specified factory and operation names
* over all products. The order of objects in the iteration will
* be according to the pairwise preferences among products and
* image factories within a product. The remove()
* method of the Iterator
may not implemented. If the
* particular factory does not have preferences then the returned
* Iterator
will traverse a collection containing the
* single factory.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @return an Iterator
over factory objects
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since JAI 1.1
*/
public Iterator getFactoryIterator(String modeName,
String descriptorName) {}
/**
* Returns the factory of the specified type for the named
* operation. This method will return the first factory that would
* be encountered by the Iterator
returned by the
* getFactoryIterator()
method.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @return a registered factory object
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since JAI 1.1
*/
public Object getFactory(String modeName, String descriptorName) {}
/**
* Finds the factory of the specified type for the named operation
* and invokes its default factory method with the supplied
* parameters. The class of the returned object is that of the
* object returned by the factory's object creation method.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @return an object created by the factory method
*
* @throws IllegalArgumentException if modeName or descriptorName
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
*
* @since JAI 1.1
*/
public Object invokeFactory(String modeName,
String descriptorName,
Object[] args) {}
//////////////////
//
// Property related methods :
// If a RegistryElementDescriptor supports properties
// (arePropertiesSupported() return true) then a property
// environment has to be managed.
//
// In the next four methods if the mode is null then apply to all modes
// that support properties.
/**
* Adds a PropertyGenerator
to the registry,
* associating it with a particular descriptor registered against a
* registry mode.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param generator the PropertyGenerator
to be added.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void addPropertyGenerator(String modeName,
String descriptorName,
PropertyGenerator generator) {}
/**
* Removes a PropertyGenerator
from its association
* with a particular descriptor/registry-mode in the registry. If
* the generator was not associated with the operation, nothing
* happens.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param generator the PropertyGenerator
to be removed.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void removePropertyGenerator(String modeName,
String descriptorName,
PropertyGenerator generator) {}
/**
* Forces a property to be copied from the specified source by nodes
* performing a particular operation. By default, a property is
* copied from the first source node that emits it. The result of
* specifying an invalid source is undefined.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param propertyName the name of the property to be copied.
* @param sourceIndex the index of the source to copy the property from.
*
* @throws IllegalArgumentException if any of the String
* arguments is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void copyPropertyFromSource(String modeName,
String descriptorName,
String propertyName,
int sourceIndex) {}
/**
* Forces a particular property to be suppressed by nodes
* performing a particular operation. By default, properties
* are passed through operations unchanged.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param propertyName the name of the property to be suppressed.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void suppressProperty(String modeName,
String descriptorName,
String propertyName) {}
/**
* Forces all properties to be suppressed by nodes performing a
* particular operation. By default, properties are passed
* through operations unchanged.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void suppressAllProperties(String modeName,
String descriptorName) {}
/**
* Removes all property associated information for this registry
* mode from this OperationRegistry
.
*
* @param modeName the registry mode name as a String
*
* @throws IllegalArgumentException if modeName is null or is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public void clearPropertyState(String modeName) {}
/**
* Returns a list of the properties generated by nodes
* implementing the descriptor associated with a particular
* descriptor Name. Returns null if no properties are
* generated.
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public String[] getGeneratedPropertyNames(String modeName,
String descriptorName) {}
/**
* Merge mode-specific property environment with mode-independent
* property environment of the descriptor. Array elements of
* "sources" are expected to be in the same ordering as referenced
* by the "sourceIndex" parameter of copyPropertyFromSource().
*
* @param modeName the registry mode name as a String
* @param descriptorName the descriptor name as a String
* @param sources the PropertySource
s corresponding to
* the sources of the object representing the named descriptor
* in the indicated mode.
* @param op the Object
from which properties will
* be generated.
*
* @return A ode>PropertySource
ode> which encapsulates
* the global property environment for the object representing
* the named descriptor in the indicated mode.
*
* @throws IllegalArgumentException if any of the arguments
* is null
* @throws IllegalArgumentException if modeName is not one of
* those returned by RegistryMode.getModes()
* @throws IllegalArgumentException if there is no
* RegistryElementDescriptor
registered against
* the descriptorName
* @throws IllegalArgumentException if the specified mode does not
* support properties.
*
* @since JAI 1.1
*/
public PropertySource getPropertySource(String modeName,
String descriptorName,
Vector sources,
Object op) {}
// All mode-specific deprecated methods here.
}
3.6 Type-safe registry wrapper classes
--------------------------------------
package javax.media.jai.registry;
/**
* Utility class to provide type-safe interaction with the
* OperationRegistry
for RenderedImageFactory
* objects.
*
* If the OperationRegistry
is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
will be used.
*
* @since JAI 1.1
*/
public final class RIFRegistry {
/**
* Register a RIF with a particular product and operation
* against a specified mode. This is JAI 1.0.x equivalent
* of registry.registerRIF(...)
*
* @param registry the OperationRegistry
to register with.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
* @param rif the RenderedImageFactory
to be registered
*
* @throws IllegalArgumentException if operationName, productName,
* or rif is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static void register(OperationRegistry registry,
String operationName,
String productName,
RenderedImageFactory rif) {}
/**
* Unregister a RIF previously registered with a product
* and operation against the specified mode.
*
* @param registry the OperationRegistry
to unregister from.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
* @param rif the RenderedImageFactory
to be unregistered
*
* @throws IllegalArgumentException if operationName, productName,
* or rif is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
* @throws IllegalArgumentException if the rif was not previously
* registered against operationName and productName
*/
public static void unregister(OperationRegistry registry,
String operationName,
String productName,
RenderedImageFactory rif) {}
/**
* Sets a preference between two rifs for a given operation under a
* specified product.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
* @param preferredRIF the preferred rif
* @param otherRIF the other rif
*
* @throws IllegalArgumentException if operationName, productName,
* preferredRIF or otherRIF is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
* @throws IllegalArgumentException if either of the rifs
* were not previously registered against
* operationName and productName
*/
public static void setPreference(OperationRegistry registry,
String operationName,
String productName,
RenderedImageFactory preferredRIF,
RenderedImageFactory otherRIF) {}
/**
* Unsets a preference between two rifs for a given operation under
* a specified product.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
* @param preferredRIF the factory object formerly preferred
* @param otherRIF the other factory object
*
* @throws IllegalArgumentException if operationName, productName,
* preferredRIF or otherRIF is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
* @throws IllegalArgumentException if either of the rifs
* were not previously registered against
* operationName and productName
*/
public static void unsetPreference(OperationRegistry registry,
String operationName,
String productName,
RenderedImageFactory preferredRIF,
RenderedImageFactory otherRIF) {}
/**
* Removes all preferences between RIFs within a product registered
* under a particular OperationDescriptor
.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
*
* @throws IllegalArgumentException if operationName or productName
* is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static void clearPreferences(OperationRegistry registry,
String operationName,
String productName) {}
/**
* Returns a list of the RIFs of a product registered under a
* particular OperationDescriptor
, in an ordering that
* satisfies all of the pairwise preferences that have been set.
* Cycles will be broken in an arbitrary manner. Returns null, if
* the product does not exist under this operationName.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param productName the product name as a String
*
* @return an ordered List
of RIFs
*
* @throws IllegalArgumentException if operationName or productName
* is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static List getOrderedList(OperationRegistry registry,
String operationName,
String productName) {}
/**
* Returns an Iterator
over all
* RenderedImageFactory
objects registered under the
* operation name over all products. The order of objects in
* the iteration will be according to the pairwise preferences
* among products and image factories within a product. The
* remove()
method of the Iterator
may not
* implemented.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
*
* @return an Iterator
over RenderedImageFactory
objects
*
* @throws IllegalArgumentException if operationName is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*
* @since JAI 1.1
*/
public static Iterator getIterator(OperationRegistry registry, String operationName) {}
/**
* Returns the the most preferred RenderedImageFactory
* object registered against the operation name. This
* method will return the first object that would be
* encountered by the Iterator
returned by the
* getIterator()
method.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
*
* @return a registered RenderedImageFactory
object
*
* @throws IllegalArgumentException if operationName is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static RenderedImageFactory get(OperationRegistry registry, String operationName) {}
/**
* Constructs a RenderedImage
(usually a
* RenderedOp
) representing the results of applying
* a given operation to a particular ParameterBlock and rendering
* hints. The registry is used to determine the RIF to be used to
* instantiate the operation.
*
* OperationRegistry
returns a non-null value, null is
* returned. Exceptions thrown by the RIFs will be caught by this
* method and will not be propagated.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param paramBlock the operation's ParameterBlock.
* @param renderHints a RenderingHints
object
* containing rendering hints.
*
* @throws IllegalArgumentException if operationName is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static RenderedImage create(OperationRegistry registry,
String operationName,
ParameterBlock paramBlock,
RenderingHints renderHints) {}
/**
* Constructs and returns a PropertySource
suitable for
* use by a given RenderedOp
. The
* PropertySource
includes properties copied from prior
* nodes as well as those generated at the node itself. Additionally,
* property suppression is taken into account. The actual
* implementation of getPropertySource()
may make use
* of deferred execution and caching.
*
* @param op the RenderedOp
requesting its
* PropertySource
.
*
* @throws IllegalArgumentException if op is null.
*/
public static PropertySource getPropertySource(RenderedOp op) {}
}
package javax.media.jai.registry;
/**
* Utility class to provide type-safe interaction
* with the OperationRegistry
for
* ContextualRenderedImageFactory
objects.
*
* If the OperationRegistry
is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
will be used.
*
* @since JAI 1.1
*/
public final class CRIFRegistry {
/**
* Register a CRIF with a particular operation
* against a specified mode. This is JAI 1.0.x equivalent
* of registry.registerCRIF(...)
*
* @param registry the OperationRegistry
to register with.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param crif the ContextualRenderedImageFactory
to be registered
*
* @throws IllegalArgumentException if operationName
* or crif is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static void register(OperationRegistry registry,
String operationName,
ContextualRenderedImageFactory crif) {}
/**
* Unregister a CRIF previously registered with
* an operation against the specified mode.
*
* @param registry the OperationRegistry
to unregister from.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param crif the ContextualRenderedImageFactory
to be unregistered
*
* @throws IllegalArgumentException if operationName
* or crif is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
* @throws IllegalArgumentException if the crif was not previously
* registered against operationName
*/
public static void unregister(OperationRegistry registry,
String operationName,
ContextualRenderedImageFactory crif) {}
/**
* Returns the ContextualRenderedImageFactory
object
* registered against the operation name.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
*
* @return a registered ContextualRenderedImageFactory
object
*
* @throws IllegalArgumentException if operationName is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static ContextualRenderedImageFactory get(OperationRegistry registry, String operationName) {}
/**
* Creates a rendering, given a RenderContext and a ParameterBlock
* containing the operation's sources and parameters. The registry
* is used to determine the CRIF to be used to instantiate the
* operation.
*
* @param registry the OperationRegistry
to use.
* if this is null
, then
* JAI.getDefaultInstance().getOperationRegistry()
* will be used.
* @param operationName the operation name as a String
* @param context a RenderContext
object containing
* the rendering context.
* @param paramBlock the operation's ParameterBlock.
*
* @throws IllegalArgumentException if operationName is null
* @throws IllegalArgumentException if there is no
* OperationDescriptor
registered against
* the operationName
*/
public static RenderedImage create(OperationRegistry registry,
String operationName,
RenderContext context,
ParameterBlock paramBlock) {}
/**
* Constructs and returns a PropertySource
suitable for
* use by a given RenderableOp
. The
* PropertySource
includes properties copied from prior
* nodes as well as those generated at the node itself. Additionally,
* property suppression is taken into account. The actual implementation
* of getPropertySource()
may make use of deferred
* execution and caching.
*
* @param op the RenderableOp
requesting its
* PropertySource
.
*
* @throws IllegalArgumentException if op is null.
*/
public static PropertySource getPropertySource(RenderableOp op) {}
}
// Add other similar wrapper classes for collection, renderableCollection,
// tileEncoder, tileDecoder, remoteRendered & remoteRenderable
3.7 Automatic detection of operators
------------------------------------
The following goes into the class comments for OperationRegistry.
/**
*
* ...
*
* Initialization and automatic loding of registry objects.
*
*
*
*
*
* OperationRegistrySpi
interface
* and register it as service provider (see
* OperationRegistrySpi
for more details). The updateRegistry
*
method of such registered service providers will be called
* with the default OperationRegistry
of JAI
* once it has been initialized.
* OperationRegistry
* of JAI
happens as follows
*
*
*
* Note that the user should not make any assumption about the order
* of loading WITHIN step 2 or 3. If there is a need for the
* OperationRegistrySpi
*
in the classpath and call their updateRegistry
* method passing in the default OperationRegistry. The order of these
* calls to updateRegistry
is arbitrary.
* updateRegistry
method to be called right after the associated
* registryFile.jai is read in, the following could be done.
*
* OperationRegistrySpi
*
*
* void updateRegistry(OperationRegistry or) {
* String registryFile = "META-INF/xxx.yyy.registryFile.jai";
* InputStream is = ClassLoader.getResourceAsStream(registryFile);
*
* or.updateFromStream(is);
*
* // Make other changes to "or" ...
* }
*
*
* @see OperationRegistrySpi
*/
3.7.1 OperationRegistrySpi
--------------------------
Use the ImageIO idea of "services" to look for concrete classes
that implement this interface. These concrete classes must have
been registered/listed in the
META-INF/services/javax.media.jai.OperationRegistrySpi file in
the JAR file which contains all implementation classes
associated with the operators.
/**
* updateRegistry()
method of all such registered
* classes will be called with the default instance of the JAI
* OperationRegistry
after it has been initialized with the
* default JAI registry file (META-INF/javax.media.jai.registryFile.jai)
* and once all "META-INF/registryFile.jai"s found in the
* classpath are loaded. There is no guarantee of the order
* in which OperationRegistrySpi
instance will be invoked.
*
* OperationRegistrySpi
could also be used to for
* the registration of other JAI related objects done through static
* methods such as the Serializer
objects and image
* codecs.
*
* @see javax.media.jai.remote.Serializer
*
* @since JAI 1.1
*/
public interface OperationRegistrySpi {
/**
* Update the OperationRegistry
*/
public void updateRegistry(OperationRegistry registry);
}
3.7.2 Related changes/note
--------------------------
- rename "registryFile.jai" (from JAI 1.0.2) to
"META-INF/javax.media.jai.registryFile.jai"
- remove the "registryFile.jai" that sits outside jai_core.jar
from the JAI distribution (this should solve some of the
security problems)
- no longer look for a "registryFile.jai" which sits outside
jar files i.e. will no longer look in JAVA_HOME/lib/ext.
Note that this is backward incompatible with JAI 1.0.2
if users have made changes to the distributed registry file.
- Add the following to OperationRegistry ...
/**
* Load all the "META-INF/registryFile.jai" files and then
* called the updateRegistry()
of the registered
* service provider of OperationRegistrySpi
found
* in the classpath corresponding to this class loader. All
* non-IO exceptions encountered while parsing the registry
* files are caught and their error messages are redirected to
* System.err
. If System.err
is null the
* error messages will never be seen.
*
* registerServices
is called twice with the
* same ClassLoader, the loading of the registry files and/or
* initialization of the services will happen twice.
*
* @since Java Advanced Imaging 1.1
*/
public void registerServices(ClassLoader cl) throws IOException {}
3.8 Miscellaneous changes
-------------------------
- Add "Continuing in pure Java mode" (and the word accelerator to
mediaLib) to the "Could not load mediaLib" and "Could not find
mediaLib wrapper classes" messages.
- The registry methods should throw RuntimeException-s instead of
printing messages on System.err
- Catch all exceptions during initialization of OperationRegistry
(reading in the registry file) and send error messages to
System.err (instead of System.out). Also do a null check of
System.err before printing messages.