javax.media.jai.remote
Class NegotiableCapabilitySet

java.lang.Object
  |
  +--javax.media.jai.remote.NegotiableCapabilitySet

All Implemented Interfaces:

Serializable

public class NegotiableCapabilitySet

extends Object

implements Serializable

This class is an aggregation of NegotiableCapability objects. This class can be used to represent all the capabilities of a machine.

This class can be classified as either a preference or a non-preference. For an explanation of the concept of preference, refer to the class comments on javax.media.jai.remote.NegotiableCapability.

If multiple NegotiableCapability objects with the same category and capability name are added to this class, the NegotiableCapability added earliest has the highest preference.

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

Since:

JAI 1.1

See Also:

Serialized Form

Constructor Summary

NegotiableCapabilitySet(boolean isPreference)
Creates a NegotiableCapabilitySet.

Method Summary

void	add(NegotiableCapability capability) Adds a new NegotiableCapability to this NegotiableCapabilitySet.
List	get(String category) Returns all the NegotiableCapabilitys with the given category as a List.
List	get(String category, String capabilityName) Returns all the NegotiableCapabilitys with the given category and capability name added previously, as a List.
List	getCapabilityNames(String category) Returns the capability names of all the NegotiableCapability objects that have been added previously, as a List.
List	getCategories() Returns the category of all the NegotiableCapability objects that have been added previously, as a List.
NegotiableCapability	getNegotiatedValue(NegotiableCapabilitySet other, String category) Performs negotiation with the given NegotiableCapabilitySet for the specified category and returns the single NegotiableCapability that is the negotiated result for the given category, if the negotiation succeeds, null otherwise.
NegotiableCapability	getNegotiatedValue(String category) Returns the single NegotiableCapability that is the negotiated result for the given category from the current class.
boolean	isEmpty() Returns true if no NegotiableCapability objects have been added.
boolean	isPreference() Returns true if this NegotiableCapabilitySet is an aggregation of preference NegotiableCapability's, false otherwise.
NegotiableCapabilitySet	negotiate(NegotiableCapabilitySet other) Returns the common subset supported by this NegotiableCapabilitySet and the given NegotiableCapabilitySet, if the negotiation succeeds.
void	remove(NegotiableCapability capability) Removes the specified NegotiableCapability from this NegotiableCapabilitySet.

Methods inherited from class java.lang.Object

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

Constructor Detail

NegotiableCapabilitySet

public NegotiableCapabilitySet(boolean isPreference)

Creates a NegotiableCapabilitySet. The isPreference argument specifies whether this NegotiableCapabilitySet should be treated as a preference or non-preference. If this NegotiableCapabilitySet is specified to be a non-preference, only non-preference NegotiableCapability's will be allowed to be added to it, otherwise an IllegalArgumentException will be thrown at the time of addition. Similarly only preference NegotiableCapability objects can be added to this NegotiableCapabilitySet if isPreference is true.

Parameters:

isPreference - a boolean that specifies whether the component NegotiableCapability's are preferences.

Method Detail

isPreference

public boolean isPreference()

Returns true if this NegotiableCapabilitySet is an aggregation of preference NegotiableCapability's, false otherwise.

add

public void add(NegotiableCapability capability)

Adds a new NegotiableCapability to this NegotiableCapabilitySet. If a NegotiableCapability with the same category and same capability name as the one currently being added has been added previously, the previous one will have a higher preference.

Parameters:

capability - The NegotiableCapability to be added.

Throws:

IllegalArgumentException - if capability is null.

IllegalArgumentException - if isPreference() returns false, and capability is a preference NegotiableCapability.

IllegalArgumentException - if isPreference() returns true, and capability is a non-preference NegotiableCapability.

remove

public void remove(NegotiableCapability capability)

Removes the specified NegotiableCapability from this NegotiableCapabilitySet. If the specified NegotiableCapability was not added previously, an IllegalArgumentException will be thrown.

Parameters:

capability - The NegotiableCapability to be removed.

Throws:

IllegalArgumentException - if capability is null.

IllegalArgumentException - if the specified NegotiableCapabilitySet was not added previously.

get

public List get(String category,
                String capabilityName)

Returns all the NegotiableCapabilitys with the given category and capability name added previously, as a List. If none were added, returns an empty List.

Parameters:

category - The category of the NegotiableCapability.

capabilityName - The name of the NegotiableCapability.

Throws:

IllegalArgumentException - if category is null.

IllegalArgumentException - if capabilityName is null.

get

public List get(String category)

Returns all the NegotiableCapabilitys with the given category as a List. Returns an empty List if no such NegotiableCapabilitys were added.

Parameters:

category - The category of the NegotiableCapabilitys to return.

Throws:

IllegalArgumentException - if category is null.

getCategories

public List getCategories()

Returns the category of all the NegotiableCapability objects that have been added previously, as a List. Returns an empty List, if no NegotiableCapability objects have been added.

The returned List does not contain any duplicates.

getCapabilityNames

public List getCapabilityNames(String category)

Returns the capability names of all the NegotiableCapability objects that have been added previously, as a List. Returns an empty List if no such NegotiableCapability objects have been added.

The returned List does not contain any duplicates.

Parameters:

category - The category of the NegotiableCapability.

Throws:

IllegalArgumentException - if category is null.

negotiate

public NegotiableCapabilitySet negotiate(NegotiableCapabilitySet other)

Returns the common subset supported by this NegotiableCapabilitySet and the given NegotiableCapabilitySet, if the negotiation succeeds. This method returns null if negotiation fails for all categories.

For those categories that are common to both the NegotiableCapabilitySet objects, negotiation is performed on a per category basis. Within each category, negotiation is performed on a per capabilityName basis. The categories which exist only in one or the other NegotiableCapabilitySet are not negotiated upon and do not show up in the resultant NegotiableCapabilitySet, if the negotiation is successful. If this class contains 'm' NegotiableCapability objects for the same category and capabilityName for which the NegotiableCapabilitySet being negotiated with contains 'n' NegotiableCapability objects, then the negotiation for this category and capabilityName will require m x n number of negotiations between two NegotiableCapability objects. The ones that succeed will produce new NegotiableCapability objects which will be added to the returned NegotiableCapabilitySet.

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

Parameters:

other - The NegotiableCapabilitySet to negotiate with.

getNegotiatedValue

public NegotiableCapability getNegotiatedValue(String category)

Returns the single NegotiableCapability that is the negotiated result for the given category from the current class. Returns null if negotiation for this category failed. If the negotiation is successful, then this method will return the most prefered (the one that was added first i.e. the one that is first in the list) NegotiableCapability from the list of NegotiableCapability that are valid for this category.

Parameters:

category - The category to find the negotiated result for.

Throws:

IllegalArgumentException - if category is null.

getNegotiatedValue

public NegotiableCapability getNegotiatedValue(NegotiableCapabilitySet other,
                                               String category)

Performs negotiation with the given NegotiableCapabilitySet for the specified category and returns the single NegotiableCapability that is the negotiated result for the given category, if the negotiation succeeds, null otherwise.

Negotiation is only performed for the specified category. For the specified category, if there are 'm' NegotiableCapability objects for which the NegotiableCapabilitySet being negotiated with contains 'n' NegotiableCapability objects, then the negotiation for this category may require m x n number of negotiations at a maximum and one negotiation at a minimum as the negotiation process stops as soon as a negotiation is successful. The results of this successful negotiation are then returned. If all the m x n negotiations fail, null is returned.

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

Parameters:

other - The NegotiableCapabilitySet to negotiate with.

category - The category to negotiate for.

Throws:

IllegalArgumentException - if category is null.

isEmpty

public boolean isEmpty()

Returns true if no NegotiableCapability objects have been added.