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>

- All Implemented Interfaces:
    Iterable<E>, Collection<E>, MultiSet<E>
  Direct Known Subclasses:
    HashMultiSet

      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
  Version:
    $Id: AbstractMapMultiSet.java 1715563 2015-11-21 20:13:35Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and 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 and Description
    --- | ---
    `protected` | `AbstractMapMultiSet()` Constructor needed for subclass serialisation.
    `protected` | `AbstractMapMultiSet(Map<E,AbstractMapMultiSet.MutableInteger> map)` Constructor that assigns the specified Map as the backing store.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `add(E object, int occurrences)` Adds a number of occurrences of the specified object to the MultiSet.
    `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)` Read the multiset in using a custom routine.
    `protected void` | `doWriteObject(ObjectOutputStream out)` Write the multiset out using a custom routine.
    `boolean` | `equals(Object object)` Compares this MultiSet to another object.
    `int` | `getCount(Object object)` Returns 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()` Utility method for implementations to access 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)` Removes a number of occurrences of the specified object from the MultiSet.
    `protected void` | `setMap(Map<E,AbstractMapMultiSet.MutableInteger> map)` Sets the map being wrapped.
    `int` | `size()` Returns the number of elements in this multiset.
    `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 org.apache.commons.collections4.MultiSet

      `containsAll, retainAll`

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

      `addAll`

- - ### Constructor Detail

    - #### AbstractMapMultiSet

          protected AbstractMapMultiSet()

      Constructor needed for subclass serialisation.

    - #### 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

  - ### Method Detail

    - #### getMap

          protected Map<E,AbstractMapMultiSet.MutableInteger> getMap()

      Utility method for implementations to access the map that backs this multiset. Not intended for interactive use outside of subclasses.
      Returns:
        the map being used by the MultiSet

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

    - #### 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

    - #### getCount

          public int getCount(Object object)

      Returns 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

    - #### 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

    - #### 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 `Iterable<E>`
      Specified by:
        `iterator` in interface `Collection<E>`
      Specified by:
        `iterator` in interface `MultiSet<E>`
      Overrides:
        `iterator` in class `AbstractMultiSet<E>`
      Returns:
        the iterator

    - #### add

          public int add(E object,
                int occurrences)

      Description copied from interface: `MultiSet`
      Adds a number of occurrences 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 `occurrences`.

      Specified by:
        `add` in interface `MultiSet<E>`
      Overrides:
        `add` in class `AbstractMultiSet<E>`
      Parameters:
        `object` - the object to add
        `occurrences` - the number of occurrences to add, may be zero, in which case no change is made to the multiset
      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>`

    - #### remove

          public int remove(Object object,
                   int occurrences)

      Description copied from interface: `MultiSet`
      Removes a number of occurrences of the specified object from the MultiSet.

      If the number of occurrences to remove is greater than the actual number of occurrences in the multiset, the object will be removed from the multiset.

      Specified by:
        `remove` in interface `MultiSet<E>`
      Overrides:
        `remove` in class `AbstractMultiSet<E>`
      Parameters:
        `object` - the object to remove
        `occurrences` - the number of occurrences to remove, may be zero, in which case no change is made to the multiset
      Returns:
        the number of occurrences of the object in the multiset before the operation; possibly zero

    - #### 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

    - #### 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

    - #### 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

    - #### doWriteObject

          protected void doWriteObject(ObjectOutputStream out)
                                throws IOException

      Write 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

    - #### doReadObject

          protected void doReadObject(ObjectInputStream in)
                               throws IOException,
                                      ClassNotFoundException

      Read 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 can not be loaded
        `ClassCastException` - if the stream does not contain the correct objects

    - #### 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

    - #### 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

    - #### 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()) ^ noOccurances)`.
      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

Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.