## javax.media.jai.remote
Class NegotiableCapabilitySet

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

All Implemented Interfaces:
  java.io.Serializable

public class NegotiableCapabilitySet
extends java.lang.Object
implements java.io.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:
  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`.
`java.util.List` `get(java.lang.String category)` Returns all the `NegotiableCapability`s with the given category as a `List`.
`java.util.List` `get(java.lang.String category, java.lang.String capabilityName)` Returns all the `NegotiableCapability`s with the given category and capability name added previously, as a `List`.
`java.util.List` `getCapabilityNames(java.lang.String category)` Returns the capability names of all the `NegotiableCapability` objects that have been added previously, as a `List`.
`java.util.List` `getCategories()` Returns the category of all the `NegotiableCapability` objects that have been added previously, as a `List`.
`NegotiableCapability` `getNegotiatedValue(NegotiableCapabilitySet other, java.lang.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(java.lang.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:
    `java.lang.IllegalArgumentException` - if capability is null.
    `java.lang.IllegalArgumentException` - if `isPreference()` returns false, and capability is a preference `NegotiableCapability`.
    `java.lang.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:
    `java.lang.IllegalArgumentException` - if capability is null.
    `java.lang.IllegalArgumentException` - if the specified `NegotiableCapabilitySet` was not added previously.

### get

    public java.util.List get(java.lang.String category,
                              java.lang.String capabilityName)

  Returns all the `NegotiableCapability`s 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:
    `java.lang.IllegalArgumentException` - if category is null.
    `java.lang.IllegalArgumentException` - if capabilityName is null.

### get

    public java.util.List get(java.lang.String category)

  Returns all the `NegotiableCapability`s with the given category as a `List`. Returns an empty `List` if no such `NegotiableCapability`s were added.
  Parameters:
    `category` - The category of the `NegotiableCapability`s to return.
  Throws:
    `java.lang.IllegalArgumentException` - if category is null.

### getCategories

    public java.util.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 java.util.List getCapabilityNames(java.lang.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:
    `java.lang.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(java.lang.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:
    `java.lang.IllegalArgumentException` - if category is null.

### getNegotiatedValue

    public NegotiableCapability getNegotiatedValue(NegotiableCapabilitySet other,
                                                   java.lang.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:
    `java.lang.IllegalArgumentException` - if category is null.

### isEmpty

    public boolean isEmpty()

  Returns true if no `NegotiableCapability` objects have been added.