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

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

All Implemented Interfaces:
  java.lang.Iterable, java.util.Collection, Bag

Direct Known Subclasses:
  HashBag, TreeBag

    public abstract class AbstractMapBag

extends java.lang.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: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Chuck Burdick, Michael A. Smith, Stephen Colebourne, Janek Bogucki, Steve Clark

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(java.util.Map map)` Constructor that assigns the specified Map as the backing store.

Method Summary
`boolean` `add(java.lang.Object object)` Adds a new element to the bag, incrementing its count in the underlying map.
`boolean` `add(java.lang.Object object, int nCopies)` Adds a new element to the bag, incrementing its count in the map.
`boolean` `addAll(java.util.Collection coll)` Invokes `add(Object)` for each element in the given collection.
`void` `clear()` Clears the bag by clearing the underlying map.
`boolean` `contains(java.lang.Object object)` Determines if the bag contains the given element by checking if the underlying map contains the element as a key.
`boolean` `containsAll(java.util.Collection coll)` Determines if the bag contains the given elements.
`protected void` `doReadObject(java.util.Map map, java.io.ObjectInputStream in)` Read the map in using a custom routine.
`protected void` `doWriteObject(java.io.ObjectOutputStream out)` Write the map out using a custom routine.
`boolean` `equals(java.lang.Object object)` Compares this Bag to another.
`int` `getCount(java.lang.Object object)` Returns the number of occurrence of the given element in this bag by looking up its count in the underlying map.
`protected java.util.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.
`java.util.Iterator` `iterator()` Gets an iterator over the bag elements.
`boolean` `remove(java.lang.Object object)` Removes all copies of the specified object from the bag.
`boolean` `remove(java.lang.Object object, int nCopies)` Removes a specified number of copies of an object from the bag.
`boolean` `removeAll(java.util.Collection coll)` Removes objects from the bag according to their count in the specified collection.
`boolean` `retainAll(java.util.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.
`java.lang.Object[]` `toArray()` Returns an array of all of this bag's elements.
`java.lang.Object[]` `toArray(java.lang.Object[] array)` Returns an array of all of this bag's elements.
`java.lang.String` `toString()` Implement a toString() method suitable for debugging.
`java.util.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(java.util.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 java.util.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 `java.util.Collection`
  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 `java.util.Collection`
  Returns:
    true if bag is empty

### getCount

    public int getCount(java.lang.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(java.lang.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 `java.util.Collection`
  Parameters:
    `object` - the object to search for
  Returns:
    true if the bag contains the given element

### containsAll

    public boolean containsAll(java.util.Collection coll)

  Determines if the bag contains the given elements.

  Specified by:
    `containsAll` in interface `java.util.Collection`
  Specified by:
    `containsAll` in interface `Bag`
  Parameters:
    `coll` - the collection to check against
  Returns:
    `true` if the Bag contains all the collection

### iterator

    public java.util.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 `java.lang.Iterable`
  Specified by:
    `iterator` in interface `java.util.Collection`
  Specified by:
    `iterator` in interface `Bag`
  Returns:
    the iterator

### add

    public boolean add(java.lang.Object object)

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

  Specified by:
    `add` in interface `java.util.Collection`
  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(java.lang.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(java.util.Collection coll)

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

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

### remove

    public boolean remove(java.lang.Object object)

  Removes all copies of the specified object from the bag.

  Specified by:
    `remove` in interface `java.util.Collection`
  Specified by:
    `remove` in interface `Bag`
  Parameters:
    `object` - the object to remove
  Returns:
    true if the bag changed

### remove

    public boolean remove(java.lang.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(java.util.Collection coll)

  Removes objects from the bag according to their count in the specified collection.

  Specified by:
    `removeAll` in interface `java.util.Collection`
  Specified by:
    `removeAll` in interface `Bag`
  Parameters:
    `coll` - the collection to use
  Returns:
    true if the bag changed

### retainAll

    public boolean retainAll(java.util.Collection coll)

  Remove any members of the bag that are not in the given bag, respecting cardinality.

  Specified by:
    `retainAll` in interface `java.util.Collection`
  Specified by:
    `retainAll` in interface `Bag`
  Parameters:
    `coll` - the collection to retain
  Returns:
    true if this call changed the collection

### toArray

    public java.lang.Object[] toArray()

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

  Specified by:
    `toArray` in interface `java.util.Collection`
  Returns:
    an array of all of this bag's elements

### toArray

    public java.lang.Object[] toArray(java.lang.Object[] array)

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

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

### uniqueSet

    public java.util.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(java.io.ObjectOutputStream out)
                          throws java.io.IOException

  Write the map out using a custom routine.

  Parameters:
    `out` - the output stream
  Throws:
    `java.io.IOException`

### doReadObject

    protected void doReadObject(java.util.Map map,
                                java.io.ObjectInputStream in)
                         throws java.io.IOException,
                                java.lang.ClassNotFoundException

  Read the map in using a custom routine.

  Parameters:
    `map` - the map to use
    `in` - the input stream
  Throws:
    `java.io.IOException`
    `java.lang.ClassNotFoundException`

### equals

    public boolean equals(java.lang.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 `java.util.Collection`
  Overrides:
    `equals` in class `java.lang.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 `java.util.Collection`
  Overrides:
    `hashCode` in class `java.lang.Object`
  Returns:
    the hash code of the Bag

### toString

    public java.lang.String toString()

  Implement a toString() method suitable for debugging.

  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    a debugging toString

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.