Package eu.bandm.tools.util.multi

Interface Multimap<A,B>

Type Parameters:
A - type of the domain elements
B - type of the range elements
All Superinterfaces:
BiPredicate<A,B>, Collection<Map.Entry<A,B>>, Iterable<Map.Entry<A,B>>, Set<Map.Entry<A,B>>
All Known Subinterfaces:
SortedMultimap<A,B>
All Known Implementing Classes:
AbstractMultimap, HashMultimap, 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. Implementations should fail early when the user tries to add null, by IllegalArgumentException or NullPointerException. Implementations need not guarantee that null values are never observed.

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.

  • Field Details

    • DEFAULT_PAIR_FORMAT_STRING

      static final String DEFAULT_PAIR_FORMAT_STRING
      A format string for the string representation of contained entries.
      See Also:

  • 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:
      whether this multimap has been changed by this operation
      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.
      Returns:
      whether this multimap contains a pair with the given components.

    • test

      default boolean test(A a, B b)
      Specified by:
      test in interface BiPredicate<A,B>

    • containsUnchecked

      default boolean containsUnchecked(Object a, Object b)
      Convenience method for untyped inquiry.
      Parameters:
      a - the left component of the pair to test
      b - the right component of the pair to test
      Returns:
      whether this multimap contains a pair with the given components.
      See Also:

    • remove

      boolean remove(A a, B b)
      Removes a pair from 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:
      whether this multimap has been changed by this operation
      Throws:
      NullPointerException - (optionally) if a or b is null.
      IllegalArgumentException - (optionally) if a or b is null.

    • removeUnchecked

      default boolean removeUnchecked(Object a, Object b)
      Convenience method for untyped remove.
      Parameters:
      a - the left component of the pair to remove.
      b - the right component of the pair to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • removeAll

      default boolean removeAll(Collection<?> data)
      Specified by:
      removeAll in interface Collection<A>
      Specified by:
      removeAll in interface Set<A>

    • retainAll

      default boolean retainAll(Collection<?> data)
      Specified by:
      retainAll in interface Collection<A>
      Specified by:
      retainAll in interface Set<A>

    • removeDomain

      default 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:
      whether this multimap has been changed by this operation
      Throws:
      NullPointerException - (optionally) if a is null.
      IllegalArgumentException - (optionally) if a is null.

    • removeDomainUnchecked

      default boolean removeDomainUnchecked(Object a)
      Convenience method for untyped remove.
      Parameters:
      a - the left component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • removeAllDomain

      default boolean removeAllDomain(Collection<? extends A> c)
      Removes all pairs with a left component in the given collection from this multimap.
      Parameters:
      c - the set of left component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation

    • removeAllDomainUnchecked

      default boolean removeAllDomainUnchecked(Collection<?> c)
      Convenience method for untyped remove.
      Parameters:
      c - the set of left component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • retainAllDomain

      default boolean retainAllDomain(Collection<? extends A> c)
      Removes from this multimap all pairs with a left component which is not in the given collection.
      Parameters:
      c - the set of left component of all pairs not to remove.
      Returns:
      whether this multimap has been changed by this operation

    • retainAllDomainUnchecked

      default boolean retainAllDomainUnchecked(Collection<?> c)
      Convenience method for untyped remove.
      Parameters:
      c - the set of left component of all pairs not to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • removeRange

      default 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:
      whether this multimap has been changed by this operation
      Throws:
      NullPointerException - (optionally) if b is null.
      IllegalArgumentException - (optionally) if b is null.

    • removeRangeUnchecked

      default boolean removeRangeUnchecked(Object b)
      Convenience method for untyped remove. Removes all pairs with a given right component from this multimap.
      Parameters:
      b - the right component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • removeAllRange

      default boolean removeAllRange(Collection<? extends B> c)
      Removes all pairs with a right component in the given collection from this multimap.
      Parameters:
      c - the set of the right component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation

    • removeAllRangeUnchecked

      default boolean removeAllRangeUnchecked(Collection<?> c)
      Convenience method for untyped remove. Removes all pairs with a right component in the given collection from this multimap.
      Parameters:
      c - the set of the right component of all pairs to remove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • retainAllRange

      default boolean retainAllRange(Collection<? extends B> c)
      Removes from this multimap all pairs with a right component which is not in the given collection.
      Parameters:
      c - the set of the right component of all pairs not emove.
      Returns:
      whether this multimap has been changed by this operation

    • retainAllRangeUnchecked

      default boolean retainAllRangeUnchecked(Collection<?> c)
      Convenience method for untyped remove. Removes all pairs with a right component which is not the given collection from this multimap.
      Parameters:
      c - the set of the right component of all pairs not emove.
      Returns:
      whether this multimap has been changed by this operation
      See Also:

    • addAll

      default boolean addAll(Collection<? extends Map.Entry<A,B>> c)
      Specified by:
      addAll in interface Collection<A>
      Specified by:
      addAll in interface Set<A>

    • containsAll

      default boolean containsAll(Collection<?> c)
      Specified by:
      containsAll in interface Collection<A>
      Specified by:
      containsAll in interface Set<A>

    • toArray

      default <T> T[] toArray(T[] proto)
      Specified by:
      toArray in interface Collection<A>
      Specified by:
      toArray in interface Set<A>

    • toArray

      default Object[] toArray()
      Specified by:
      toArray in interface Collection<A>
      Specified by:
      toArray in interface Set<A>

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

      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 removeRange 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 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)
      Convenience method for untyped inquiry.
      Parameters:
      a - a left component.
      Returns:
      the set of right components of pairs with a left component that equals(a) in this multimap.
      See Also:

    • imageAll

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

    • imageAllUnchecked

      default Set<B> imageAllUnchecked(Collection<?> c)
      Convenience method for untyped inquiry.
      Parameters:
      c - a set of left components.
      Returns:
      the set of right components of pairs with a left component in the given set.
      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. The result is backed by the argument. Subsequent changes to either Collection are reflected by the other.
      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)
      Convenience method for untyped inquiry.
      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.
      See Also:

    • preimageAll

      default Set<A> preimageAll(Collection<? extends B> c)
      Returns the set of left components of pairs in this multimap which have a right component in the given set.
      Parameters:
      c - a set of right components.
      Returns:
      the set of left components of pairs with a right component in the given set.
      Throws:
      NullPointerException - if b is null.
      IllegalArgumentException - if b is null.

    • preimageAllUnchecked

      default Set<A> preimageAllUnchecked(Collection<?> c)
      Convenience method for untyped inquiry.
      Parameters:
      c - a set of right components.
      Returns:
      the set of left components of pairs with a right component in the given set.
      See Also:

    • 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. The result is backed by the argument. Subsequent changes to either Collection are reflected by the other.
      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.

    • toString

      default String toString(String pairFormatString)
      Returns a string representation of this instance.
      Parameters:
      pairFormatString - a format string applied to key and value of all contained entries.
      Returns:
      a string representation of this instance.

    • toString

      default String toString(BiFunction<? super A,? super B,String> pairToString)
      Returns a string representation of this instance.
      Parameters:
      pairToString - a function to get the string representation of all contained entries.
      Returns:
      a string representation of this instance.