Java Doc for NegotiableCapability.java in  » 6.0-JDK-Modules » Java-Advanced-Imaging » javax » media » jai » remote » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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

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 negotiatewith.