## org.apache.commons.collections.bag
Class AbstractMapBag

    java.lang.Object
      org.apache.commons.collections.bag.AbstractMapBag

All Implemented Interfaces:
  Bag, Collection

Direct Known Subclasses:
  HashBag, TreeBag

public abstract class AbstractMapBag
extends Object
implements Bag

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:
  Commons Collections 3.0 (previously DefaultMapBag v2.0)
Version:
  $Revision: 1.15 $ $Date: 2004/05/15 12:27:04 $
Author:
  Chuck Burdick, Michael A. Smith, Stephen Colebourne, Janek Bogucki

Nested Class Summary
`protected static class` `AbstractMapBag.MutableInteger` Mutable integer class for storing the data.

Constructor Summary
`protected` `AbstractMapBag()` Constructor needed for subclass serialisation.
`protected` `AbstractMapBag(Map map)` Constructor that assigns the specified Map as the backing store.

Method Summary
`boolean` `add(Object object)` Adds a new element to the bag, incrementing its count in the underlying map.
`boolean` `add(Object object, int nCopies)` Adds a new element to the bag, incrementing its count in the map.
`boolean` `addAll(Collection 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 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` `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` `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.
`Object[]` `toArray(Object[] array)` Returns an array of all of this bag's elements.
`String` `toString()` Implement a toString() method suitable for debugging.
`Set` `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 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 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 `Bag`
  Returns:
    current size of the bag

### isEmpty

    public boolean isEmpty()

  Returns true if the underlying map is empty.

  Specified by:
    `isEmpty` in interface `Collection`
  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`
  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`
  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 `Bag`
  Parameters:
    `coll` - the collection to check against
  Returns:
    `true` if the Bag contains all the collection

### iterator

    public Iterator 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 `Bag`
  Returns:
    the iterator

### add

    public boolean add(Object object)

  Adds a new element to the bag, incrementing its count in the underlying map.

  Specified by:
    `add` in interface `Bag`
  Parameters:
    `object` - the object to add
  Returns:
    `true` if the object was not already in the `uniqueSet`

### add

    public boolean add(Object object,
                       int nCopies)

  Adds a new element to the bag, incrementing its count in the map.

  Specified by:
    `add` in interface `Bag`
  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 coll)

  Invokes `add(Object)` for each element in the given collection.

  Specified by:
    `addAll` in interface `Collection`
  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`

### remove

    public boolean remove(Object object)

  Removes all copies of the specified object from the bag.

  Specified by:
    `remove` in interface `Bag`
  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`
  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 `Bag`
  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 `Bag`
  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`
  Returns:
    an array of all of this bag's elements

### toArray

    public Object[] toArray(Object[] array)

  Returns an array of all of this bag's elements.

  Specified by:
    `toArray` in interface `Collection`
  Parameters:
    `array` - the array to populate
  Returns:
    an array of all of this bag's elements

### uniqueSet

    public Set uniqueSet()

  Returns an unmodifiable view of the underlying map's key set.

  Specified by:
    `uniqueSet` in interface `Bag`
  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`

### doReadObject

    protected void doReadObject(Map 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`
    `ClassNotFoundException`

### 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`
  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`
  Returns:
    the hash code of the Bag

### toString

    public String toString()

  Implement a toString() method suitable for debugging.

  Returns:
    a debugging toString

Copyright © 2001-2005 Apache Software Foundation. All Rights Reserved.