org.apache.commons.collections4.bag

## Class AbstractMapBag<E>

- java.lang.Object
- - org.apache.commons.collections4.bag.AbstractMapBag<E>

- All Implemented Interfaces:
    Iterable<E>, Collection<E>, Bag<E>
  Direct Known Subclasses:
    HashBag, TreeBag

      public abstract class AbstractMapBag<E>
      extends Object
      implements Bag<E>

  Abstract implementation of the `Bag` 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 bag elements to a number; the number represents the number of occurrences of that element in the bag.

  Since:
    3.0 (previously DefaultMapBag v2.0)
  Version:
    $Id: AbstractMapBag.java 1491258 2013-06-09 18:35:24Z tn $

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `AbstractMapBag.MutableInteger` Mutable integer class for storing the data.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractMapBag()` Constructor needed for subclass serialisation.
    `protected` | `AbstractMapBag(Map<E,AbstractMapBag.MutableInteger> map)` Constructor that assigns the specified Map as the backing store.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `add(E object)` Adds a new element to the bag, incrementing its count in the underlying map.
    `boolean` | `add(E object, int nCopies)` Adds a new element to the bag, incrementing its count in the map.
    `boolean` | `addAll(Collection<? extends E> coll)` Invokes `add(Object)` for each element in the given collection.
    `void` | `clear()` Clears the bag by clearing the underlying map.
    `boolean` | `contains(Object object)` Determines if the bag contains the given element by checking if the underlying map contains the element as a key.
    `boolean` | `containsAll(Collection<?> coll)` Determines if the bag contains the given elements.
    `protected void` | `doReadObject(Map<E,AbstractMapBag.MutableInteger> map, ObjectInputStream in)` Read the map in using a custom routine.
    `protected void` | `doWriteObject(ObjectOutputStream out)` Write the map out using a custom routine.
    `boolean` | `equals(Object object)` Compares this Bag to another.
    `int` | `getCount(Object object)` Returns the number of occurrence of the given element in this bag by looking up its count in the underlying map.
    `protected Map<E,AbstractMapBag.MutableInteger>` | `getMap()` Utility method for implementations to access the map that backs this bag.
    `int` | `hashCode()` Gets a hash code for the Bag compatible with the definition of equals.
    `boolean` | `isEmpty()` Returns true if the underlying map is empty.
    `Iterator<E>` | `iterator()` Gets an iterator over the bag elements.
    `boolean` | `remove(Object object)` Removes all copies of the specified object from the bag.
    `boolean` | `remove(Object object, int nCopies)` Removes a specified number of copies of an object from the bag.
    `boolean` | `removeAll(Collection<?> coll)` Removes objects from the bag according to their count in the specified collection.
    `boolean` | `retainAll(Collection<?> coll)` Remove any members of the bag that are not in the given bag, respecting cardinality.
    `int` | `size()` Returns the number of elements in this bag.
    `Object[]` | `toArray()` Returns an array of all of this bag's elements.
    `<T> T[]` | `toArray(T[] array)` Returns an array of all of this bag's elements.
    `String` | `toString()` Implement a toString() method suitable for debugging.
    `Set<E>` | `uniqueSet()` Returns an unmodifiable view of the underlying map's key set.

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

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

- - ### Constructor Detail

    - #### AbstractMapBag

          protected AbstractMapBag()

      Constructor needed for subclass serialisation.

    - #### AbstractMapBag

          protected AbstractMapBag(Map<E,AbstractMapBag.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,AbstractMapBag.MutableInteger> getMap()

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

    - #### size

          public int size()

      Returns the number of elements in this bag.
      Specified by:
        `size` in interface `Collection<E>`
      Specified by:
        `size` in interface `Bag<E>`
      Returns:
        current size of the bag

    - #### isEmpty

          public boolean isEmpty()

      Returns true if the underlying map is empty.
      Specified by:
        `isEmpty` in interface `Collection<E>`
      Returns:
        true if bag is empty

    - #### getCount

          public int getCount(Object object)

      Returns the number of occurrence of the given element in this bag by looking up its count in the underlying map.
      Specified by:
        `getCount` in interface `Bag<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 bag contains the given element by checking if the underlying map contains the element as a key.
      Specified by:
        `contains` in interface `Collection<E>`
      Parameters:
        `object` - the object to search for
      Returns:
        true if the bag contains the given element

    - #### containsAll

          public boolean containsAll(Collection<?> coll)

      Determines if the bag contains the given elements.
      Specified by:
        `containsAll` in interface `Collection<E>`
      Specified by:
        `containsAll` in interface `Bag<E>`
      Parameters:
        `coll` - the collection to check against
      Returns:
        `true` if the Bag contains all the collection

    - #### iterator

          public Iterator<E> iterator()

      Gets an iterator over the bag elements. Elements present in the Bag 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 `Bag<E>`
      Returns:
        the iterator

    - #### add

          public boolean add(E object)

      Adds a new element to the bag, incrementing its count in the underlying map.
      Specified by:
        `add` in interface `Collection<E>`
      Specified by:
        `add` in interface `Bag<E>`
      Parameters:
        `object` - the object to add
      Returns:
        `true` if the object was not already in the `uniqueSet`

    - #### add

          public boolean add(E object,
                    int nCopies)

      Adds a new element to the bag, incrementing its count in the map.
      Specified by:
        `add` in interface `Bag<E>`
      Parameters:
        `object` - the object to search for
        `nCopies` - the number of copies to add
      Returns:
        `true` if the object was not already in the `uniqueSet`

    - #### addAll

          public boolean addAll(Collection<? extends E> coll)

      Invokes `add(Object)` for each element in the given collection.
      Specified by:
        `addAll` in interface `Collection<E>`
      Parameters:
        `coll` - the collection to add
      Returns:
        `true` if this call changed the bag

    - #### clear

          public void clear()

      Clears the bag by clearing the underlying map.
      Specified by:
        `clear` in interface `Collection<E>`

    - #### remove

          public boolean remove(Object object)

      Removes all copies of the specified object from the bag.
      Specified by:
        `remove` in interface `Collection<E>`
      Specified by:
        `remove` in interface `Bag<E>`
      Parameters:
        `object` - the object to remove
      Returns:
        true if the bag changed

    - #### remove

          public boolean remove(Object object,
                       int nCopies)

      Removes a specified number of copies of an object from the bag.
      Specified by:
        `remove` in interface `Bag<E>`
      Parameters:
        `object` - the object to remove
        `nCopies` - the number of copies to remove
      Returns:
        true if the bag changed

    - #### removeAll

          public boolean removeAll(Collection<?> coll)

      Removes objects from the bag according to their count in the specified collection.
      Specified by:
        `removeAll` in interface `Collection<E>`
      Specified by:
        `removeAll` in interface `Bag<E>`
      Parameters:
        `coll` - the collection to use
      Returns:
        true if the bag changed

    - #### retainAll

          public boolean retainAll(Collection<?> coll)

      Remove any members of the bag that are not in the given bag, respecting cardinality.
      Specified by:
        `retainAll` in interface `Collection<E>`
      Specified by:
        `retainAll` in interface `Bag<E>`
      Parameters:
        `coll` - the collection to retain
      Returns:
        true if this call changed the collection

    - #### toArray

          public Object[] toArray()

      Returns an array of all of this bag's elements.
      Specified by:
        `toArray` in interface `Collection<E>`
      Returns:
        an array of all of this bag's elements

    - #### toArray

          public <T> T[] toArray(T[] array)

      Returns an array of all of this bag's elements. If the input array has more elements than are in the bag, trailing elements will be set to null.
      Specified by:
        `toArray` in interface `Collection<E>`
      Type Parameters:
        `T` - the type of the array elements
      Parameters:
        `array` - the array to populate
      Returns:
        an array of all of this bag'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

    - #### uniqueSet

          public Set<E> uniqueSet()

      Returns an unmodifiable view of the underlying map's key set.
      Specified by:
        `uniqueSet` in interface `Bag<E>`
      Returns:
        the set of unique elements in this bag

    - #### doWriteObject

          protected void doWriteObject(ObjectOutputStream out)
                                throws IOException

      Write the map out using a custom routine.
      Parameters:
        `out` - the output stream
      Throws:
        `IOException` - any of the usual I/O related exceptions

    - #### doReadObject

          protected void doReadObject(Map<E,AbstractMapBag.MutableInteger> map,
                          ObjectInputStream in)
                               throws IOException,
                                      ClassNotFoundException

      Read the map in using a custom routine.
      Parameters:
        `map` - the map to use
        `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

    - #### equals

          public boolean equals(Object object)

      Compares this Bag to another. This Bag equals another Bag if it contains the same number of occurrences of the same elements.
      Specified by:
        `equals` in interface `Collection<E>`
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the Bag to compare to
      Returns:
        true if equal

    - #### hashCode

          public int hashCode()

      Gets a hash code for the Bag 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)`. This hash code is compatible with the Set interface.
      Specified by:
        `hashCode` in interface `Collection<E>`
      Overrides:
        `hashCode` in class `Object`
      Returns:
        the hash code of the Bag

    - #### toString

          public String toString()

      Implement a toString() method suitable for debugging.
      Overrides:
        `toString` in class `Object`
      Returns:
        a debugging toString

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