Package org.apache.commons.collections4.multiset

# Class AbstractMultiSet<E>

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

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

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

Direct Known Subclasses:
  `AbstractMapMultiSet`

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

Since:
  4.1

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected static class`
  `AbstractMultiSet.AbstractEntry<E>`
  Inner class AbstractEntry.
  `protected static class`
  `AbstractMultiSet.EntrySet<E>`
  Inner class EntrySet.
  `protected static class`
  `AbstractMultiSet.UniqueSet<E>`
  Inner class UniqueSet.

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

  `MultiSet.Entry<E>`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AbstractMultiSet()`
  Constructs a new instance subclasses.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E object)`
  Adds one copy of the specified object to the MultiSet.
  `int`
  `add(E object, int occurrences)`
  Always throws `UnsupportedOperationException`.
  `void`
  `clear()`
  Clears the multiset removing all elements from the entrySet.
  `boolean`
  `contains(Object object)`
  Determines if the multiset contains the given element.
  `protected Set<MultiSet.Entry<E>>`
  `createEntrySet()`
  Create a new view for the set of entries in this multiset.
  `protected abstract Iterator<MultiSet.Entry<E>>`
  `createEntrySetIterator()`
  Creates an entry set iterator.
  `protected Set<E>`
  `createUniqueSet()`
  Create a new view for the set of unique elements in this multiset.
  `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.
  `Set<MultiSet.Entry<E>>`
  `entrySet()`
  Returns an unmodifiable view of the entries of this multiset.
  `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 iterating over its entrySet.
  `int`
  `hashCode()`
  Gets a hash code for the MultiSet compatible with the definition of equals.
  `Iterator<E>`
  `iterator()`
  Gets an iterator over the multiset elements.
  `boolean`
  `remove(Object object)`
  Removes one occurrence of the given object from the MultiSet.
  `int`
  `remove(Object object, int occurrences)`
  Always throws `UnsupportedOperationException`.
  `boolean`
  `removeAll(Collection<?> coll)`
  Remove all occurrences of all elements from this MultiSet represented in the given collection.
  `int`
  `setCount(E object, int count)`
  Sets the number of occurrences of the specified object in the MultiSet to the given count.
  `int`
  `size()`
  Returns the number of elements in this multiset.
  `String`
  `toString()`
  Implement a toString() method suitable for debugging.
  `protected abstract int`
  `uniqueElements()`
  Returns the number of unique elements in this multiset.
  `Set<E>`
  `uniqueSet()`
  Returns a view of the unique elements of this multiset.

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

  `addAll, containsAll, isEmpty, retainAll, toArray, toArray`

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

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

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

  `addAll, isEmpty, parallelStream, removeIf, spliterator, stream, toArray, toArray`

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

  `forEach`

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

  `containsAll, retainAll`

- ## Constructor Details

  - ### AbstractMultiSet

    protected AbstractMultiSet()
    Constructs a new instance subclasses.

- ## Method Details

  - ### add

    public boolean add(E object)
    Description copied from interface: `MultiSet`
    Adds one copy of the specified object to the MultiSet.

    If the object is already in the `MultiSet.uniqueSet()` then increment its count as reported by `MultiSet.getCount(Object)`. Otherwise, add it to the `MultiSet.uniqueSet()` and report its count as 1.

    Specified by:
      `add` in interface `Collection<E>`
    Specified by:
      `add` in interface `MultiSet<E>`
    Overrides:
      `add` in class `AbstractCollection<E>`
    Parameters:
      `object` - The object to add.
    Returns:
      `true` always, as the size of the MultiSet is increased in any case.

  - ### add

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

  - ### clear

    public void clear()
    Clears the multiset removing all elements from the entrySet.
    Specified by:
      `clear` in interface `Collection<E>`
    Overrides:
      `clear` in class `AbstractCollection<E>`

  - ### contains

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

  - ### createEntrySet

    protected Set<MultiSet.Entry<E>> createEntrySet()
    Create a new view for the set of entries in this multiset.
    Returns:
      A view of the set of entries

  - ### createEntrySetIterator

    protected abstract Iterator<MultiSet.Entry<E>> createEntrySetIterator()
    Creates an entry set iterator. Subclasses can override this to return iterators with different properties.
    Returns:
      The entrySet iterator

  - ### createUniqueSet

    protected Set<E> createUniqueSet()
    Create a new view for the set of unique elements in this multiset.
    Returns:
      A view of the set of unique elements

  - ### createUniqueSetIterator

    protected Iterator<E> createUniqueSetIterator()
    Creates a unique set iterator. Subclasses can override this to return iterators with different properties.
    Returns:
      The uniqueSet iterator

  - ### doReadObject

    protected void doReadObject(ObjectInputStream in) throws IOException, ClassNotFoundException
    Reads the multiset in using a custom routine.
    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.
    Parameters:
      `out` - The output stream
    Throws:
      `IOException` - any of the usual I/O related exceptions

  - ### entrySet

    public Set<MultiSet.Entry<E>> entrySet()
    Returns an unmodifiable view of the entries of this multiset.
    Specified by:
      `entrySet` in interface `MultiSet<E>`
    Returns:
      The set of entries in this multiset

  - ### 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 `Object`
    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 iterating over its entrySet.
    Specified by:
      `getCount` in interface `MultiSet<E>`
    Parameters:
      `object` - The object to search for
    Returns:
      The number of occurrences of the object, zero if not found

  - ### 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 `Object`
    Returns:
      The hash code of the MultiSet.

  - ### 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>`
    Specified by:
      `iterator` in class `AbstractCollection<E>`
    Returns:
      The iterator

  - ### remove

    public boolean remove(Object object)
    Description copied from interface: `MultiSet`
    Removes one occurrence of the given object from the MultiSet.

    If the number of occurrences after this operation is reduced to zero, the object will be removed from the `MultiSet.uniqueSet()`.

    Specified by:
      `remove` in interface `Collection<E>`
    Specified by:
      `remove` in interface `MultiSet<E>`
    Overrides:
      `remove` in class `AbstractCollection<E>`
    Parameters:
      `object` - The object to remove.
    Returns:
      `true` if this call changed the collection.

  - ### remove

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

  - ### removeAll

    public boolean removeAll(Collection<?> coll)
    Description copied from interface: `MultiSet`
    Remove all occurrences of all elements from this MultiSet represented in the given collection.
    Specified by:
      `removeAll` in interface `Collection<E>`
    Specified by:
      `removeAll` in interface `MultiSet<E>`
    Overrides:
      `removeAll` in class `AbstractCollection<E>`
    Parameters:
      `coll` - The collection of elements to remove.
    Returns:
      `true` if this call changed the multiset.

  - ### setCount

    public int setCount(E object, int count)
    Description copied from interface: `MultiSet`
    Sets the number of occurrences of the specified object in the MultiSet to the given count.

    If the provided count is zero, the object will be removed from the `MultiSet.uniqueSet()`.

    Specified by:
      `setCount` in interface `MultiSet<E>`
    Parameters:
      `object` - The object to update.
      `count` - The number of occurrences of the object.
    Returns:
      The number of occurrences of the object before this operation, zero if the object was not contained in the multiset.

  - ### size

    public int size()
    Returns the number of elements in this multiset.
    Specified by:
      `size` in interface `Collection<E>`
    Specified by:
      `size` in interface `MultiSet<E>`
    Specified by:
      `size` in class `AbstractCollection<E>`
    Returns:
      current size of the multiset, or `Integer.MAX_VALUE` if the total exceeds it.

  - ### toString

    public String toString()
    Implement a toString() method suitable for debugging.
    Overrides:
      `toString` in class `AbstractCollection<E>`
    Returns:
      A debugging toString

  - ### uniqueElements

    protected abstract int uniqueElements()
    Returns the number of unique elements in this multiset.
    Returns:
      The number of unique elements

  - ### uniqueSet

    public Set<E> uniqueSet()
    Returns a view of the unique elements of this multiset.
    Specified by:
      `uniqueSet` in interface `MultiSet<E>`
    Returns:
      The set of unique elements in this multiset