Java Advanced Imaging: Class NegotiableCapability

Overview

Package

Class

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

javax.media.jai.remote
Class NegotiableCapability

java.lang.Object
  |
  +--javax.media.jai.ParameterListImpl
        |
        +--javax.media.jai.remote.NegotiableCapability

All Implemented Interfaces:: ParameterList, Serializable

public class NegotiableCapability
extends ParameterListImpl
implements Serializable

A NegotiableCapability represents the capabilities of an object. These capabilities can be used to negotiate with the capabilities of a similar object. Each NegotiableCapability is characterized by the category it belongs to, as returned by the getCategory() method, by the actual name of the capability it represents, as returned by the getCapabilityName() method and by a list of parameter name-value pairs that define the NegotiableCapability. Every NegotiableCapability object also holds references to a representation of the objects that generated it. These can be accessed via the getGenerators() method. The creator or generator of a NegotiableCapability can supply any representation of itself while constructing the NegotiableCapability. No interpretation is forced by this class, that is left upto the generating class and to the class that utilizes the NegotiableCapability to get the negotiated results. The negotiation is performed by the negotiate() method. Since this method returns a NegotiableCapability, this method can be used repeatedly to perform multiple negotiations. If the negotiation fails, null will be returned from the negotiate() method. Every successful negotiation will add the generator of the NegotiableCapability negotiated with, to the set of generators of the resultant NegotiableCapability. The generators are intended to help the user of NegotiableCapability identify the object that created the NegotiableCapability and therefore the object that can be relied on to be able to handle the parameters agreed on during negotiation. For example, if the negotiation is to be performed to choose a compatible TileEncoder, TileDecoder pair for data compression/decompression, the category would be "tileCodec", the capabilityName would be a specific tile encoding format, say "jpeg" and the generator for the NegotiableCapability could be the TileDecoderFactory/TileEncoderFactory object that generated that NegotiableCapability. After a successful negotiation, the NegotiableCapability that is the result of the negotiation will contain a TileEncoderFactory and a TileDecoderFactory object as the generators for that NegotiableCapability. These two objects can then be retrieved using the getGenerators method and used to do the encoding and decoding and can be relied to be compatible, since the negotiation was successful between their respective NegotiableCapability objects.

The number, name, Class type and default values for the parameters in this class is specified by the ParameterListDescriptor returned from getParameterListDescriptor method. Each parameter value in this class must be a class that implements the Negotiable interface. It is for this reason that all of the ParameterList set methods that take primitive data types as arguments and all the ParameterList get methods that return primitive data types are overridden in this class to throw an IllegalArgumentException, as this class only accepts Negotiable's as parameter values in order to facilitate negotiation on parameters. It may be noted that the implementation of the version of ParameterList.setParameter that takes an Object as the parameter value, in this class throws an IllegalArgumentException if the supplied Object to be set does not implement the Negotiable interface. If no Negotiable value is available as the value for a particular parameter, null should be set as the value. A null value returned from the getNegotiatedValue(String) method is however valid, since the single value result of the negotiation can be null. Similarly the Object returned from the ParameterList.getObjectParameter implementation in this class is always a class that implements the Negotiable interface, and not a wrapper class of a primitive data type, as documented for this method in ParameterList. The getParamValueRange(String parameterName) and the getEnumeratedParameterValues(String parameterName) methods of the ParameterListDescriptor returned from getParameterListDescriptor method of this class should be implemented to return null, since these methods are not meaningful when the parameter values are Negotiable.

In order for the negotiation to be successful, the category and the capabilityName of the two NegotiableCapability objects must be the same. In addition, negotiation on each of the parameters must be successful. Since each parameter is represented as a Negotiable, negotiation on it can be performed using the Negotiable.negotiate(Negotiable negotiable) method. The NegotiableCapability returned from the negotiate(NegotiableCapability capability) method contains the same category and capabilityName as that of the NegotiableCapability objects being negotiated as well as including the negotiated values for each parameter. If the negotiation fails for any one parameter, the negotiation for the NegotiableCapabilitys as a whole is said to fail (unless preference NegotiableCapability objects are involved in the negotiation, as described below) and a null is returned.

In order to get a single negotiated value from the set of valid values represented as the Negotiable value for a parameter, the getNegotiatedValue(String parameterName) method can be called. If the negotiation was successful, an Object which is the negotiated result will be returned, otherwise a null (signifying that the negotiation failed) will be returned.

NegotiableCapability objects can be classified as being either preferences or non-preferences. A non-preference describes the capabilities of an object completely by specifying Negotiable values for each and every parameter defined in the ParameterListDescriptor returned from getParameterListDescriptor method. A non-preference is allowed to not specify the value of a particular parameter, if a default value for that parameter exists (i.e. the default value is not null). When a non-preference is created, all parameter values are initialized to their default values, and therefore if any parameter value is left unset at the time of the negotiation, the default value that was set at time of initialization will be used for the negotiation. If the default value happened to be null, the negotiation in this case would fail. Note that all references to values in this paragraph, whether default or not, refered to the objects implementing the Negotiable interface that are the values set for a particular parameter name. A preference on the other hand specifies preferences for the selection of a prefered set of (maybe even a single) parameter value from the set of valid ones at negotiation time. A preference is allowed to specify Negotiable parameter values for a subset of parameters, if it so wishes. For those parameters for whom the preference does not specify values, the preference is indicating a don't-care attitude, and the result of the negotiation for such a parameter will be the Negotiable value from the non-preference object the preference is negotiating with. Note that the default value is not substituted for a parameter whose value has not been specified in a preference. A NegotiableCapability which is a preference should return true from the isPreference method, a non-preference object that defines values for all the parameters (or relies on defaults) should return false from this method. As a rule, the result of negotiation between one non-preference and another is a non-preference, between a preference and a non-preference is a non-preference and that between two preferences is a preference, if the negotiation is successful. It may be noted that preferences are not expected to specify their generators, since in general, preferences don't come from objects that can support them. However if generators are specified within a preference, they will be added to the set of generators of the resultant NegotiableCapability in the event of a successful negotiation.

Negotiation between a preference and a non-preference NegotiableCapability results in a non-preference NegotiableCapability. For each parameter, if a value is specified (i.e the value is not null) in both the preference and the non-preference, then if these values have a common subset, the negotiation will succeed on this parameter, if there is no commonality, then the negotiation will fail on this parameter and thus also fail as a whole. If the preference doesn't specify a value for a parameter (i.e the value is null), then the value specified by the non-preference for that same parameter is chosen as a result of the successful negotiation on that parameter.

Negotiation between two preference NegotiableCapability objects results in a preference NegotiableCapability. For each parameter, if a value is specified (i.e the value is not null) in both the preference objects, the negotiation on that parameter will have a value which is the portion that is common to both. If there is no commonality, negotiation will fail on this parameter (null will be returned) and thus also fail as a whole. If the value for a particular parameter is specified in one preference and not in the other, the negotiated value will be the one specified. If for a particular parameter, no value is specified in either preference, the negotiated value for that parameter will be null, and the negotiation as a whole on the NegotiableCapability will not fail.

When a preference NegotiableCapability is constructed, the values of all the parameters defined in the ParameterListDescriptor returned from getParameterListDescriptor method, are initialized to null. null within this class represents a value that has not been specified. Such values are only allowed on a preference NegotiableCapability. On the other hand when a non-preference NegotiableCapability is constructed, all the values are initialized to their default values.

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

Since:: JAI 1.1
See Also:: Serialized Form

Constructor Summary

NegotiableCapability(String category, String capabilityName, List generators, ParameterListDescriptor descriptor, boolean isPreference)
          Creates a NegotiableCapability with the specified category and capabilityName.

Method Summary

boolean areParameterListDescriptorsCompatible(NegotiableCapability other)
          Returns true if the ParameterListDescriptor of the supplied NegotiableCapability is compatible with the ParameterListDescriptor of this class for negotiation purposes.

boolean getBooleanParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

byte getByteParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

String getCapabilityName()
          Returns the name of this NegotiableCapability.

String getCategory()
          Returns the category of this NegotiableCapability.

char getCharParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

double getDoubleParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

float getFloatParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

List getGenerators()
          Returns the List containing representations of the objects that generated this NegotiableCapability.

int getIntParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

long getLongParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

Object getNegotiatedValue(String parameterName)
          Returns a single negotiated value from the Negotiable that represents the set of valid values for the given parameter.

short getShortParameter(String paramName)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values in this class are Negotiable and therefore cannot be returned as a primitive data type.

boolean isPreference()
          Returns true if this NegotiableCapability is a preference, false otherwise.

NegotiableCapability negotiate(NegotiableCapability capability)
          Performs negotiation between this NegotiableCapability and the given NegotiableCapability.

void setGenerators(List generators)
          Set the specified List as the generators for this NegotiableCapability.

ParameterList setParameter(String paramName, boolean b)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, byte b)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, char c)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, double d)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, float f)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, int i)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, long l)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

ParameterList setParameter(String paramName, Object obj)
          Overrides the superclass method to ensure only a Negotiable object can be added as the value of the parameter.

ParameterList setParameter(String paramName, short s)
          Overrides the method in ParameterListImpl to throw an IllegalArgumentException since parameter values set on this class must be a Negotiable.

Methods inherited from class javax.media.jai.ParameterListImpl

getObjectParameter, getParameterListDescriptor

Methods inherited from class java.lang.Object

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

Constructor Detail

NegotiableCapability

public NegotiableCapability(String category,
                            String capabilityName,
                            List generators,
                            ParameterListDescriptor descriptor,
                            boolean isPreference)

Creates a NegotiableCapability with the specified category and capabilityName.

Parameters:: category - The category this capability belongs to.; capabilityName - The name of this capability.; generators - A List containing representations of the objects that generated this NegotiableCapability or null, if there are none.; descriptor - The descriptor that describes the parameters for this class.; isPreference - Boolean specifying whether this class represents a preference or a non-preference.
Throws:: IllegalArgumentException - if category is null.; IllegalArgumentException - if capabilityName is null.; IllegalArgumentException - if descriptor is null.; IllegalArgumentException - if any of the default values returned from the supplied descriptor's getParamDefaults() method is ParameterListDescriptor.NO_PARAMETER_DEFAULT. null should be used to represent the absence of a default.; IllegalArgumentException - if any of the Class types returned from the supplied descriptor's getParamClasses() method does not implement Negotiable.

Method Detail

getCategory

public String getCategory()

Returns the category of this NegotiableCapability.

getCapabilityName

public String getCapabilityName()

Returns the name of this NegotiableCapability.

getGenerators

public List getGenerators()

Returns the List containing representations of the objects that generated this NegotiableCapability. This method will return null, if there are no generators for this NegotiableCapability.

setGenerators

public void setGenerators(List generators)

Set the specified List as the generators for this NegotiableCapability. A generator is a representation of the object that generated this NegotiableCapability.

Parameters:: generators - The List of generators.

isPreference

public boolean isPreference()

Returns true if this NegotiableCapability is a preference, false otherwise.

getNegotiatedValue

public Object getNegotiatedValue(String parameterName)

Returns a single negotiated value from the Negotiable that represents the set of valid values for the given parameter. This method uses the Negotiable.getNegotiatedValue to get the negotiated value for the Negotiable value of the parameter specified by parameterName. If this NegotiableCapability is a non-preference, then a valid Negotiable must be present as the value of the specified parameter, and a single value from that Negotiable will be returned. If this NegotiableCapability is a preference the specified parameter may have a null as its value. In this case, this null will be returned as the negotiated value.

Parameters:: parameterName - The name of parameter to return the negotiated value for.
Throws:: IllegalArgumentException - if the parameterName is not one of those described by the associated ParameterListDescriptor.

negotiate

public NegotiableCapability negotiate(NegotiableCapability capability)

Performs negotiation between this NegotiableCapability and the given NegotiableCapability. Returns the common subset supported by this NegotiableCapability and the given NegotiableCapability if the negotiation is successful, null otherwise.

In order for the negotiation to be successful, the category and the capabilityName of the supplied NegotiableCapability object must be the same as of this class. In addition, negotiation on each of the parameters must be successful. Since each parameter is represented as a Negotiable, negotiation on it can be performed using the Negotiable.negotiate() method. The NegotiableCapability returned contains the same category, capabilityName as that of this class and also includes the negotiated values for each parameter. If the negotiation fails for any one parameter, the negotiation for the NegotiableCapabilitys as a whole is said to fail and a null is returned. The result of negotiation between one non-preference and another is a non-preference, between a preference and a non-preference is a non-preference and that between two preferences is a preference, if the negotiation is successful. If this NegotiableCapability is a non-preference, i.e the isPreference() method returns false, and the supplied NegotiableCapability argument is also a non-preference, then the negotiation will fail if the number and Class of parameters in both the NegotiableCapability objects is not the same. If either one of the NegotiableCapability objects is a preference and the other is a non-preference, the number of parameters are not required to match. For those parameters whose names are the same in both the NegotiableCapability objects, the Class types have to match, otherwise the negotiation will fail. Those parameters that exist in the non-preference NegotiableCapability object but not in the preference NegotiableCapability object do not take part in the negotiation, but are directly set on the resultant NegotiableCapability object if the negotiation is successful on the common parameters. Those parameters that exist in the preference NegotiableCapability object but not in the non-preference NegotiableCapability object are ignored, do not take part in the negotiation and are not reflected in the resultant NegotiableCapability in the event of a successful negotiation. If both the NegotiableCapability objects are preferences, then only the common parameters take part in the negotiation and the ones that aren't present in both the NegotiableCapabilitys are directly set on the resultant NegotiableCapability object if the negotiation is successful on the common parameters. For the common parameters, the Class types have to match, otherwise the negotiation will fail. The check for the compatibility of the ParameterListDescriptor of the supplied NegotiableCapability with the current NegotiableCapability's ParameterListDescriptor is done using the areParameterListDescriptorsCompatible() method. It may be noted that the ParameterListDescriptor of the NegotiableCapability returned as a result of a successful negotiation will implement the getParamDefaults() and the getParamValueRange() methods in terms of the values returned from the same methods on the ParameterListDescriptor associated with this class, if the negotiation took place between two preferences, or from the same methods on the ParameterListDescriptor associated with the non-preference otherwise.

If the supplied NegotiableCapability is null, then the negotiation will fail and null will be returned.

Parameters:: capability - The NegotiableCapability to negotiate with.

areParameterListDescriptorsCompatible

public boolean areParameterListDescriptorsCompatible(NegotiableCapability other)

Returns true if the ParameterListDescriptor of the supplied NegotiableCapability is compatible with the ParameterListDescriptor of this class for negotiation purposes. If both the NegotiableCapability objects are non-preferences, both the number of parameters as well as the Class type of the parameters has to match for this method to return true. If either one or both of the NegotiableCapability objects is a preference, then the Class type of the same named parameters in both the NegotiableCapability object's ParameterListDescriptors has to match for this method to return true.

Parameters:: other - The NegotiableCapability to check compatibility for negotiation purposes for.
Throws:: IllegalArgumentException - if other is null.