Package org.apache.commons.collections4.multiset

# Class AbstractMapMultiSet<E>

java.lang.Object
java.util.AbstractCollection<E>
org.apache.commons.collections4.multiset.AbstractMultiSet<E>
org.apache.commons.collections4.multiset.AbstractMapMultiSet<E>

Type Parameters:
  `E` - The type held in the multiset.

All Implemented Interfaces:
  `Iterable<E>`, `Collection<E>`, `MultiSet<E>`

Direct Known Subclasses:
  `HashMultiSet`, `TreeMultiSet`

public abstract class AbstractMapMultiSet<E> extends AbstractMultiSet<E>
Abstract implementation of the `MultiSet` interface to simplify the creation of subclass implementations.

Subclasses specify a Map implementation to use as the internal storage. The map will be used to map multiset elements to a number; the number represents the number of occurrences of that element in the multiset.

Since:
  4.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractMapMultiSet.EntrySetIterator<E>`
  Inner class EntrySetIterator.
  `protected static class`
  `AbstractMapMultiSet.MultiSetEntry<E>`
  Inner class MultiSetEntry.
  `protected static class`
  `AbstractMapMultiSet.MutableInteger`
  Mutable integer class for storing the data.
  `protected static class`
  `AbstractMapMultiSet.UniqueSetIterator<E>`
  Inner class UniqueSetIterator.

  ## Nested classes/interfaces inherited from class org.apache.commons.collections4.multiset.AbstractMultiSet

  `AbstractMultiSet.AbstractEntry<E>, AbstractMultiSet.EntrySet<E>, AbstractMultiSet.UniqueSet<E>`

  ## Nested classes/interfaces inherited from interface org.apache.commons.collections4.MultiSet

  `MultiSet.Entry<E>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMapMultiSet()`
  Constructor needed for subclass serialization.
  `protected`
  `AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map)`
  Constructor that assigns the specified Map as the backing store.
  `protected`
  `AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map, Iterable<? extends E> iterable)`
  Constructs a new instance that assigns the specified Map as the backing store.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `int`
  `add(E object, int occurrences)`
  Always throws `UnsupportedOperationException`.
  `void`
  `clear()`
  Clears the multiset by clearing the underlying map.
  `boolean`
  `contains(Object object)`
  Determines if the multiset contains the given element by checking if the underlying map contains the element as a key.
  `protected Iterator<MultiSet.Entry<E>>`
  `createEntrySetIterator()`
  Creates an entry set iterator.
  `protected Iterator<E>`
  `createUniqueSetIterator()`
  Creates a unique set iterator.
  `protected void`
  `doReadObject(ObjectInputStream in)`
  Reads the multiset in using a custom routine.
  `protected void`
  `doWriteObject(ObjectOutputStream out)`
  Writes the multiset out using a custom routine.
  `boolean`
  `equals(Object object)`
  Compares this MultiSet to another object.
  `int`
  `getCount(Object object)`
  Gets the number of occurrence of the given element in this multiset by looking up its count in the underlying map.
  `protected Map<E,AbstractMapMultiSet.MutableInteger>`
  `getMap()`
  Gets the map that backs this multiset.
  `int`
  `hashCode()`
  Gets a hash code for the MultiSet compatible with the definition of equals.
  `boolean`
  `isEmpty()`
  Returns true if the underlying map is empty.
  `Iterator<E>`
  `iterator()`
  Gets an iterator over the multiset elements.
  `int`
  `remove(Object object, int occurrences)`
  Always throws `UnsupportedOperationException`.
  `protected void`
  `setMap(Map<E,AbstractMapMultiSet.MutableInteger> map)`
  Sets the map being wrapped.
  `int`
  `size()`
  Returns the number of elements in this multiset, or `Integer.MAX_VALUE` if the multiset contains more than `Integer.MAX_VALUE` elements.
  `Object[]`
  `toArray()`
  Returns an array of all of this multiset's elements.
  `<T> T[]`
  `toArray(T[] array)`
  Returns an array of all of this multiset's elements.
  `protected int`
  `uniqueElements()`
  Returns the number of unique elements in this multiset.

  ### Methods inherited from class org.apache.commons.collections4.multiset.AbstractMultiSet

  `add, createEntrySet, createUniqueSet, entrySet, remove, removeAll, setCount, toString, uniqueSet`

  ### Methods inherited from class java.util.AbstractCollection

  `addAll, containsAll, retainAll`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

  ### Methods inherited from interface java.util.Collection

  `addAll, parallelStream, removeIf, spliterator, stream`

  ### Methods inherited from interface java.lang.Iterable

  `forEach`

  ### Methods inherited from interface org.apache.commons.collections4.MultiSet

  `containsAll, retainAll`

- ## Constructor Details

  - ### AbstractMapMultiSet

    protected AbstractMapMultiSet()
    Constructor needed for subclass serialization.

  - ### AbstractMapMultiSet

    protected AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map)
    Constructor that assigns the specified Map as the backing store. The map must be empty and non-null.
    Parameters:
      `map` - The map to assign.

  - ### AbstractMapMultiSet

    protected AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map, Iterable<? extends E> iterable)
    Constructs a new instance that assigns the specified Map as the backing store. The map must be empty and non-null. The multiset is filled from the iterable elements.
    Parameters:
      `map` - The map to assign.
      `iterable` - The iterable of elements to add.
    Since:
      4.6.0

- ## Method Details

  - ### add

    public int add(E object, int occurrences)
    Description copied from class: `AbstractMultiSet`
    Always throws `UnsupportedOperationException`.
    Specified by:
      `add` in interface `MultiSet<E>`
    Overrides:
      `add` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - Ignored.
      `occurrences` - Ignored.
    Returns:
      The number of occurrences of the object in the multiset before this operation; possibly zero.

  - ### clear

    public void clear()
    Clears the multiset by clearing the underlying map.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractMultiSet<E>`

  - ### contains

    public boolean contains(Object object)
    Determines if the multiset contains the given element by checking if the underlying map contains the element as a key.
    Specified by:
      `contains` in interface `Collection<E>`
    Overrides:
      `contains` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - The object to search for.
    Returns:
      true if the multiset contains the given element.

  - ### createEntrySetIterator

    protected Iterator<MultiSet.Entry<E>> createEntrySetIterator()
    Description copied from class: `AbstractMultiSet`
    Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
    Specified by:
      `createEntrySetIterator` in class `AbstractMultiSet<E>`
    Returns:
      The entrySet iterator

  - ### createUniqueSetIterator

    protected Iterator<E> createUniqueSetIterator()
    Description copied from class: `AbstractMultiSet`
    Creates a unique set iterator. Subclasses can override this to return iterators with different properties.
    Overrides:
      `createUniqueSetIterator` in class `AbstractMultiSet<E>`
    Returns:
      The uniqueSet iterator

  - ### doReadObject

    protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
    Reads the multiset in using a custom routine.
    Overrides:
      `doReadObject` in class `AbstractMultiSet<E>`
    Parameters:
      `in` - The input stream.
    Throws:
      `IOException` - any of the usual I/O related exceptions.
      `ClassNotFoundException` - if the stream contains an object which class cannot be loaded.
      `ClassCastException` - if the stream does not contain the correct objects.

  - ### doWriteObject

    protected void doWriteObject(ObjectOutputStream out) throws IOException
    Writes the multiset out using a custom routine.
    Overrides:
      `doWriteObject` in class `AbstractMultiSet<E>`
    Parameters:
      `out` - The output stream.
    Throws:
      `IOException` - any of the usual I/O related exceptions.

  - ### equals

    public boolean equals(Object object)
    Description copied from interface: `MultiSet`
    Compares this MultiSet to another object.

    This MultiSet equals another object if it is also a MultiSet that contains the same number of occurrences of the same elements.

    Specified by:
      `equals` in interface `Collection<E>`
    Specified by:
      `equals` in interface `MultiSet<E>`
    Overrides:
      `equals` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - The object to compare to.
    Returns:
      true if equal.

  - ### getCount

    public int getCount(Object object)
    Gets the number of occurrence of the given element in this multiset by looking up its count in the underlying map.
    Specified by:
      `getCount` in interface `MultiSet<E>`
    Overrides:
      `getCount` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - The object to search for.
    Returns:
      The number of occurrences of the object, zero if not found.

  - ### getMap

    protected Map<E,AbstractMapMultiSet.MutableInteger> getMap()
    Gets the map that backs this multiset. Not intended for interactive use outside of subclasses.
    Returns:
      The map being used by the MultiSet.

  - ### hashCode

    public int hashCode()
    Description copied from interface: `MultiSet`
    Gets a hash code for the MultiSet compatible with the definition of equals. The hash code is defined as the sum total of a hash code for each element. The per element hash code is defined as `(e==null ? 0 : e.hashCode()) ^ noOccurrences)`.
    Specified by:
      `hashCode` in interface `Collection<E>`
    Specified by:
      `hashCode` in interface `MultiSet<E>`
    Overrides:
      `hashCode` in class `AbstractMultiSet<E>`
    Returns:
      The hash code of the MultiSet.

  - ### isEmpty

    public boolean isEmpty()
    Returns true if the underlying map is empty.
    Specified by:
      `isEmpty` in interface `Collection<E>`
    Overrides:
      `isEmpty` in class `AbstractCollection<E>`
    Returns:
      true if multiset is empty.

  - ### iterator

    public Iterator<E> iterator()
    Gets an iterator over the multiset elements. Elements present in the MultiSet more than once will be returned repeatedly.
    Specified by:
      `iterator` in interface `Collection<E>`
    Specified by:
      `iterator` in interface `Iterable<E>`
    Specified by:
      `iterator` in interface `MultiSet<E>`
    Overrides:
      `iterator` in class `AbstractMultiSet<E>`
    Returns:
      The iterator.

  - ### remove

    public int remove(Object object, int occurrences)
    Description copied from class: `AbstractMultiSet`
    Always throws `UnsupportedOperationException`.
    Specified by:
      `remove` in interface `MultiSet<E>`
    Overrides:
      `remove` in class `AbstractMultiSet<E>`
    Parameters:
      `object` - Ignored.
      `occurrences` - Ignored.
    Returns:
      The number of occurrences of the object in the multiset before the operation; possibly zero.

  - ### setMap

    protected void setMap(Map<E,AbstractMapMultiSet.MutableInteger> map)
    Sets the map being wrapped.

    Note: this method should only be used during deserialization

    Parameters:
      `map` - The map to wrap.

  - ### size

    public int size()
    Returns the number of elements in this multiset, or `Integer.MAX_VALUE` if the multiset contains more than `Integer.MAX_VALUE` elements.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in interface `MultiSet<E>`
    Overrides:
      `size` in class `AbstractMultiSet<E>`
    Returns:
      current size of the multiset.

  - ### toArray

    public Object[] toArray()
    Returns an array of all of this multiset's elements.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Returns:
      An array of all of this multiset's elements.

  - ### toArray

    public <T> T[] toArray(T[] array)
    Returns an array of all of this multiset's elements. If the input array has more elements than are in the multiset, trailing elements will be set to null.
    Specified by:
      `toArray` in interface `Collection<E>`
    Overrides:
      `toArray` in class `AbstractCollection<E>`
    Type Parameters:
      `T` - The type of the array elements.
    Parameters:
      `array` - The array to populate.
    Returns:
      An array of all of this multiset's elements.
    Throws:
      `ArrayStoreException` - if the runtime type of the specified array is not a supertype of the runtime type of the elements in this list.
      `NullPointerException` - if the specified array is null.

  - ### uniqueElements

    protected int uniqueElements()
    Description copied from class: `AbstractMultiSet`
    Returns the number of unique elements in this multiset.
    Specified by:
      `uniqueElements` in class `AbstractMultiSet<E>`
    Returns:
      The number of unique elements