Package eu.bandm.tools.ops

Interface Multimap<A,B>

All Superinterfaces:
BiPredicate<A,B>, Collection<Map.Entry<A,B>>, Iterable<Map.Entry<A,B>>, Set<Map.Entry<A,B>>
All Known Subinterfaces:
Multimap_checkedLeft<L,R>, Multimap_checkedRight<L,R>, SortedMultimap<A,B>
All Known Implementing Classes:
AbstractMultimap, CheckedMultimap_D, CheckedMultimap_R, CheckedMultimap_RD, ForwardMultimap, HashMultimap, IndexMultimap, MapMultimap, UnmodifiableMultimap
public interface Multimap<A,B> extends BiPredicate<A,B>, Set<Map.Entry<A,B>>
A finite set of pairs. Pairs in a multimap are represented as instances of Map.Entry. The object returned by getKey() is called the left component of the pair; the object returned by getValue() is called the right component of the pair. null components are not supported.

The effect of attempting to change the right component by invoking setValue on a pair is unspecified. Implementations may either prohibit the operation by throwing UnsupportedOperationException or allow the operation but behave in an unspecified way afterwards.

Pairs in a multimap are considered equal if and only if both their left and right components are equal according to their respective equals methods. Such pairs are said to be equal componentwise. The implementations of Map.Entry returned by implementations must implement equals and hashCode accordingly.

  • Method Details

    • add

      boolean add(A a, B b)
      Adds a pair to this multimap. This operation must be stable: adding a pair that equals any pair contained in this multimap componentwise must not change this multimap.
      Parameters:
      a - the left component of the pair to add.
      b - the right component of the pair to add.
      Returns:
      true if this multimap has been changed by this operation, false otherwise.
      Throws:
      NullPointerException - (optionally) if a or b is null.
      IllegalArgumentException - (optionally) if a or b is null.

    • contains

      boolean contains(A a, B b)
      Whether this multimap contains a pair with the given components.
      Parameters:
      a - the left component of the pair to add.
      b - the right component of the pair to add.

    • containsUnchecked

      boolean containsUnchecked(Object a, Object b)

    • remove

      boolean remove(A a, B b)
      Removes a pair from this this multimap. Removing a pair that equals no pair contained in this multimap componentwise must not change this multimap.
      Parameters:
      a - the left component of the pair to remove.
      b - the right component of the pair to remove.
      Returns:
      true if this multimap has been changed by this operation, false otherwise.
      Throws:
      NullPointerException - (optionally) if a or b is null.
      IllegalArgumentException - (optionally) if a or b is null.

    • removeUnchecked

      boolean removeUnchecked(Object a, Object b)

    • removeDomain

      boolean removeDomain(A a)
      Removes all pairs with a given left component from this multimap. The effect of the implementation on this multimap must be equivalent to the following code: 
       removeDomain(final A a) {
   for (B b : new HashSet<B>(range())) remove(a, b) ;
 }
      Parameters:
      a - the left component of all pairs to remove.
      Returns:
      true if this multimap has been changed by this operation, false otherwise.
      Throws:
      NullPointerException - (optionally) if a is null.
      IllegalArgumentException - (optionally) if a is null.

    • removeRange

      boolean removeRange(B b)
      Removes all pairs with a given right component from this multimap. The effect of the implementation on this multimap must be equivalent to the following code: 
       removeRange(final B b) {
   for (A a : new HashSet<A>(domain())) remove(a, b) ;
 }
      Parameters:
      b - the right component of all pairs to remove.
      Returns:
      true if this multimap has been changed by this operation, false otherwise.
      Throws:
      NullPointerException - (optionally) if b is null.
      IllegalArgumentException - (optionally) if b is null.

    • removeAllDomain

      boolean removeAllDomain(Collection<? extends A> c)
      Removes all pairs with a left component in the given collection from this multimap.

    • removeAllDomainUnchecked

      boolean removeAllDomainUnchecked(Collection<?> c)
      See Also:

    • retainAllDomain

      boolean retainAllDomain(Collection<? extends A> c)
      Removes all pairs with a left component which is not the given collection from this multimap.

    • retainAllDomainUnchecked

      boolean retainAllDomainUnchecked(Collection<?> c)
      See Also:

    • removeAllRange

      boolean removeAllRange(Collection<? extends B> c)
      Removes all pairs with a right component in the given collection from this multimap.

    • removeAllRangeUnchecked

      boolean removeAllRangeUnchecked(Collection<?> c)
      See Also:

    • retainAllRange

      boolean retainAllRange(Collection<? extends B> c)
      Removes all pairs with a right component which is not the given collection from this multimap.

    • retainAllRangeUnchecked

      boolean retainAllRangeUnchecked(Collection<?> c)
      See Also:

    • domain

      Set<A> domain()
      Returns the set of left components of pairs in this multimap.

      The returned set is backed by this multimap, such that changes to this multimap are reflected by the set. The behavior of modifications of this multimap concurrent to iteration of the set is unspecified.

      If this multimap supports the removeDomain operation, then the returned set and its iterators must support the remove operation, and changes by these operations must be reflected by this multimap.

      Returns:
      the set of left components of pairs in this multimap.

    • range

      Set<B> range()
      Returns the set of right components of pairs in this multimap.

      If this multimap supports the removeRange operation, then the returned set and its iterators must support the remove operation.

      Returns:
      the set of right components of pairs in this multimap.

    • image

      Set<B> image(A a)
      Returns the set of right components of pairs with a given left component in this multimap.

      The returned set need not be modifiable. The behaviour of this multimap after successfully modifying the returned set is unspecified.

      Parameters:
      a - a left component.
      Returns:
      the set of right components of pairs with a left component that equals(a) in this multimap.
      Throws:
      NullPointerException - if a is null.
      IllegalArgumentException - if a is null.

    • imageUnchecked

      Set<B> imageUnchecked(Object a)
      See Also:

    • imageAll

      Set<B> imageAll(Collection<? extends A> a)
      Returns the set of right components of pairs in this multimap, which have a left component in the given set.

    • imageAllUnchecked

      Set<B> imageAllUnchecked(Collection<?> a)
      See Also:

    • imageMap

      Map<A,Set<B>> imageMap()
      Returns a map which maps each A which appears as a left component to a set of all B which appear as its right component.

    • preimage

      Set<A> preimage(B b)
      Returns the set of left components of pairs with a given right component in this multimap.

      The returned set need not be modifiable. The behaviour of this multimap after successfully modifying the returned set is unspecified.

      Parameters:
      b - a right component.
      Returns:
      the set of left components of pairs with a right component that equals(b) in this multimap.
      Throws:
      NullPointerException - if b is null.
      IllegalArgumentException - if b is null.

    • preimageUnchecked

      Set<A> preimageUnchecked(Object b)
      See Also:

    • preimageAll

      Set<A> preimageAll(Collection<? extends B> b)
      Returns the set of left components of pairs in this multimap, which have a right component in the given set.

    • preimageAllUnchecked

      Set<A> preimageAllUnchecked(Collection<?> b)

    • preimageMap

      Map<B,Set<A>> preimageMap()
      Returns a map which maps each B which appears as a right component to a set of all A which appear as its left component.