Save This Page
Home » commons-collections-3.2.1-src » org.apache.commons » collections » map » [javadoc | source]
org.apache.commons.collections.map
abstract public class: AbstractTestMap [javadoc | source]
java.lang.Object
   junit.framework.TestCase
      org.apache.commons.collections.BulkTest
         org.apache.commons.collections.AbstractTestObject
            org.apache.commons.collections.map.AbstractTestMap

All Implemented Interfaces:
    Cloneable

Direct Known Subclasses:
    TestTransformedSortedMap, TestLazyMap, TestUnmodifiableBidiMap, TestStaticBucketMap, TestCaseInsensitiveMap, TestListOrderedMap2, TestHeadMap, TestSubMap, TestHashedMap, TestUnmodifiableMap, AbstractTestOrderedMap, TestTransformedMap, TestPredicatedSortedMap, TestSingletonMap, TestCompositeMap, TestReferenceMap, AbstractTestIterableMap, TestTreeBidiMap, TestLRUMap, TestUnmodifiableSortedBidiMap, TestListOrderedMap, TestFixedSizeMap, TestInverseBidiMap, AbstractTestSortedBidiMap, TestDualTreeBidiMap, TestFlat3Map, TestViewMap, TestPredicatedMap, TestDualHashBidiMap, TestAbstractOrderedBidiMapDecorator, AbstractTestSortedMap, TestUnmodifiableOrderedMap, TestMultiKeyMap, TestLinkedMap, TestFixedSizeSortedMap, TestUnmodifiableSortedMap, TestDualTreeBidiMap2, TestReferenceIdentityMap, TestTailMap, TestLazySortedMap, AbstractTestOrderedBidiMap, AbstractTestBidiMap, TestUnmodifiableOrderedBidiMap

Abstract test class for java.util.Map methods and contracts.

The forces at work here are similar to those in AbstractTestCollection . If your class implements the full Map interface, including optional operations, simply extend this class, and implement the #makeEmptyMap() method.

On the other hand, if your map implementation is weird, you may have to override one or more of the other protected methods. They're described below.

Entry Population Methods

Override these methods if your map requires special entries:

Supported Operation Methods

Override these methods if your map doesn't support certain operations:

Fixture Methods

For tests on modification operations (puts and removes), fixtures are used to verify that that operation results in correct state for the map and its collection views. Basically, the modification is performed against your map implementation, and an identical modification is performed against a confirmed map implementation. A confirmed map implementation is something like java.util.HashMap, which is known to conform exactly to the Map contract. After the modification takes place on both your map implementation and the confirmed map implementation, the two maps are compared to see if their state is identical. The comparison also compares the collection views to make sure they're still the same.

The upshot of all that is that any test that modifies the map in any way will verify that all of the map's state is still correct, including the state of its collection views. So for instance if a key is removed by the map's key set's iterator, then the entry set is checked to make sure the key/value pair no longer appears.

The #map field holds an instance of your collection implementation. The #entrySet , #keySet and #values fields hold that map's collection views. And the #confirmed field holds an instance of the confirmed collection implementation. The #resetEmpty() and #resetFull() methods set these fields to empty or full maps, so that tests can proceed from a known state.

After a modification operation to both #map and #confirmed , the #verify() method is invoked to compare the results. The #verify method calls separate methods to verify the map and its three collection views (#verifyMap , #verifyEntrySet , #verifyKeySet , and #verifyValues ). You may want to override one of the verification methodsto perform additional verifications. For instance, TestDoubleOrderedMap would want override its #verifyValues() method to verify that the values are unique and in ascending order.

Other Notes

If your Map fails one of these tests by design, you may still use this base set of cases. Simply override the test case (method) your map fails and/or the methods that define the assumptions used by the test cases. For example, if your map does not allow duplicate values, override #isAllowDuplicateValues() and have it return false

Nested Class Summary:
public class  AbstractTestMap.TestMapEntrySet   
public class  AbstractTestMap.TestMapKeySet   
public class  AbstractTestMap.TestMapValues   
Field Summary
protected  Map map    Map created by reset(). 
protected  Set entrySet    Entry set of map created by reset(). 
protected  Set keySet    Key set of map created by reset(). 
protected  Collection values    Values collection of map created by reset(). 
protected  Map confirmed    HashMap created by reset(). 
Fields inherited from org.apache.commons.collections.AbstractTestObject:
COLLECTIONS_MAJOR_VERSION
Fields inherited from org.apache.commons.collections.BulkTest:
verboseName
Constructor:
 public AbstractTestMap(String testName) 
    JUnit constructor.
    Parameters:
    testName - the test name
Method from org.apache.commons.collections.map.AbstractTestMap Summary:
addSampleMappings,   bulkTestMapEntrySet,   bulkTestMapKeySet,   bulkTestMapValues,   cloneMapEntry,   getCompatibilityVersion,   getNewSampleValues,   getOtherKeys,   getOtherNonNullStringElements,   getOtherValues,   getSampleKeys,   getSampleValues,   isAllowDuplicateValues,   isAllowNullKey,   isAllowNullValue,   isGetStructuralModify,   isPutAddSupported,   isPutChangeSupported,   isRemoveSupported,   isSetValueSupported,   isSubMapViewsSerializable,   makeConfirmedMap,   makeEmptyMap,   makeFullMap,   makeObject,   resetEmpty,   resetFull,   tearDown,   testEmptyMapCompatibility,   testEntrySetClearChangesMap,   testEntrySetContains1,   testEntrySetContains2,   testEntrySetContains3,   testEntrySetRemove1,   testEntrySetRemove2,   testEntrySetRemove3,   testFullMapCompatibility,   testKeySetClearChangesMap,   testKeySetRemoveChangesMap,   testMakeMap,   testMapClear,   testMapContainsKey,   testMapContainsValue,   testMapEquals,   testMapGet,   testMapHashCode,   testMapIsEmpty,   testMapPut,   testMapPutAll,   testMapPutNullKey,   testMapPutNullValue,   testMapRemove,   testMapSize,   testMapToString,   testSampleMappings,   testValuesClearChangesMap,   testValuesRemoveChangesMap,   verify,   verifyEntrySet,   verifyKeySet,   verifyMap,   verifyValues
Methods from org.apache.commons.collections.AbstractTestObject:
getCanonicalEmptyCollectionName,   getCanonicalFullCollectionName,   getCompatibilityVersion,   isEqualsCheckable,   isTestSerialization,   makeObject,   readExternalFormFromBytes,   readExternalFormFromDisk,   skipSerializedCanonicalTests,   supportsEmptyCollections,   supportsFullCollections,   testCanonicalEmptyCollectionExists,   testCanonicalFullCollectionExists,   testEqualsNull,   testObjectEqualsSelf,   testObjectHashCodeEqualsContract,   testObjectHashCodeEqualsSelfHashCode,   testSerializeDeserializeThenCompare,   testSimpleSerialization,   writeExternalFormToBytes,   writeExternalFormToDisk
Methods from org.apache.commons.collections.BulkTest:
clone,   ignoredSimpleTests,   makeSuite,   toString
Methods from java.lang.Object:
equals,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from org.apache.commons.collections.map.AbstractTestMap Detail:
 public  void addSampleMappings(Map m) 
 public BulkTest bulkTestMapEntrySet() 
    Bulk test Map#entrySet() . This method runs through all of the tests in AbstractTestSet . After modification operations, #verify() is invoked to ensure that the map and the other collection views are still valid.
 public BulkTest bulkTestMapKeySet() 
    Bulk test Map#keySet() . This method runs through all of the tests in AbstractTestSet . After modification operations, #verify() is invoked to ensure that the map and the other collection views are still valid.
 public BulkTest bulkTestMapValues() 
    Bulk test Map#values() . This method runs through all of the tests in AbstractTestCollection . After modification operations, #verify() is invoked to ensure that the map and the other collection views are still valid.
 public Map.Entry cloneMapEntry(Map.Entry entry) 
    Creates a new Map Entry that is independent of the first and the map.
 public String getCompatibilityVersion() 
    Gets the compatability version, needed for package access.
 public Object[] getNewSampleValues() 
    Returns a the set of values that can be used to replace the values returned from #getSampleValues() . This method must return an array with the same length as #getSampleValues() . The values returned from this method should not be the same as those returned from #getSampleValues() . The default implementation constructs a set of String values and includes a single null value if #isAllowNullValue() returns true, and includes two values that are the same if #isAllowDuplicateValues() returns true.
 public Object[] getOtherKeys() 
 public Object[] getOtherNonNullStringElements() 
    Returns a list of string elements suitable for return by #getOtherKeys() or #getOtherValues .

    Override getOtherElements to returnthe results of this method if your collection does not support heterogenous elements or the null element.

 public Object[] getOtherValues() 
 public Object[] getSampleKeys() 
    Returns the set of keys in the mappings used to test the map. This method must return an array with the same length as #getSampleValues() and all array elements must be different. The default implementation constructs a set of String keys, and includes a single null key if #isAllowNullKey() returns true.
 public Object[] getSampleValues() 
    Returns the set of values in the mappings used to test the map. This method must return an array with the same length as #getSampleKeys() . The default implementation constructs a set of String values and includes a single null value if #isAllowNullValue() returns true, and includes two values that are the same if #isAllowDuplicateValues() returns true.
 public boolean isAllowDuplicateValues() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() supports duplicate values.

    Default implementation returns true. Override if your collection class does not support duplicate values.

 public boolean isAllowNullKey() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() supports null keys.

    Default implementation returns true. Override if your collection class does not support null keys.

 public boolean isAllowNullValue() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() supports null values.

    Default implementation returns true. Override if your collection class does not support null values.

 public boolean isGetStructuralModify() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() can cause structural modification on a get(). The example is LRUMap.

    Default implementation returns false. Override if your map class structurally modifies on get.

 public boolean isPutAddSupported() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() support the put and putAll operations adding new mappings.

    Default implementation returns true. Override if your collection class does not support put adding.

 public boolean isPutChangeSupported() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() support the put and putAll operations changing existing mappings.

    Default implementation returns true. Override if your collection class does not support put changing.

 public boolean isRemoveSupported() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() support the remove and clear operations.

    Default implementation returns true. Override if your collection class does not support removal operations.

 public boolean isSetValueSupported() 
    Returns true if the maps produced by #makeEmptyMap() and #makeFullMap() support the setValue operation on entrySet entries.

    Default implementation returns isPutChangeSupported(). Override if your collection class does not support setValue but does support put changing.

 public boolean isSubMapViewsSerializable() 
    Returns whether the sub map views of SortedMap are serializable. If the class being tested is based around a TreeMap then you should override and return false as TreeMap has a bug in deserialization.
 public Map makeConfirmedMap() 
    Override to return a map other than HashMap as the confirmed map.
 abstract public Map makeEmptyMap()
    Return a new, empty Map to be used for testing.
 public Map makeFullMap() 
 public Object makeObject() 
    Implements the superclass method to return the map to be tested.
 public  void resetEmpty() 
 public  void resetFull() 
 public  void tearDown() throws Exception 
    Erases any leftover instance variables by setting them to null.
 public  void testEmptyMapCompatibility() throws Exception 
    Compare the current serialized form of the Map against the canonical version in CVS.
 public  void testEntrySetClearChangesMap() 
    Tests that the Map#entrySet() collection is backed by the underlying map for clear().
 public  void testEntrySetContains1() 
 public  void testEntrySetContains2() 
 public  void testEntrySetContains3() 
 public  void testEntrySetRemove1() 
 public  void testEntrySetRemove2() 
 public  void testEntrySetRemove3() 
 public  void testFullMapCompatibility() throws Exception 
    Compare the current serialized form of the Map against the canonical version in CVS.
 public  void testKeySetClearChangesMap() 
    Tests that the Map#keySet collection is backed by the underlying map for clear().
 public  void testKeySetRemoveChangesMap() 
    Tests that the Map#keySet set is backed by the underlying map by removing from the keySet set and testing if the key was removed from the map.
 public  void testMakeMap() 
    Test to ensure that makeEmptyMap and makeFull returns a new non-null map with each invocation.
 public  void testMapClear() 
    Tests Map#clear() . If the map #isRemoveSupported() can add and remove elements}, then Map#size() and Map#isEmpty() are used to ensure that map has no elements after a call to clear. If the map does not support adding and removing elements, this method checks to ensure clear throws an UnsupportedOperationException.
 public  void testMapContainsKey() 
    Tests Map.containsKey(Object) by verifying it returns false for all sample keys on a map created using an empty map and returns true for all sample keys returned on a full map.
 public  void testMapContainsValue() 
    Tests Map.containsValue(Object) by verifying it returns false for all sample values on an empty map and returns true for all sample values on a full map.
 public  void testMapEquals() 
    Tests Map.equals(Object)
 public  void testMapGet() 
    Tests Map.get(Object)
 public  void testMapHashCode() 
    Tests Map.hashCode()
 public  void testMapIsEmpty() 
    Tests Map.isEmpty()
 public  void testMapPut() 
    Tests Map.put(Object, Object)
 public  void testMapPutAll() 
    Tests Map.putAll(map)
 public  void testMapPutNullKey() 
    Tests Map.put(null, value)
 public  void testMapPutNullValue() 
    Tests Map.put(null, value)
 public  void testMapRemove() 
    Tests Map.remove(Object)
 public  void testMapSize() 
    Tests Map.size()
 public  void testMapToString() 
    Tests Map.toString(). Since the format of the string returned by the toString() method is not defined in the Map interface, there is no common way to test the results of the toString() method. Thereforce, it is encouraged that Map implementations override this test with one that checks the format matches any format defined in its API. This default implementation just verifies that the toString() method does not return null.
 public  void testSampleMappings() 
    Test to ensure the test setup is working properly. This method checks to ensure that the getSampleKeys and getSampleValues methods are returning results that look appropriate. That is, they both return a non-null array of equal length. The keys array must not have any duplicate values, and may only contain a (single) null key if isNullKeySupported() returns true. The values array must only have a null value if useNullValue() is true and may only have duplicate values if isAllowDuplicateValues() returns true.
 public  void testValuesClearChangesMap() 
    Tests that the Map#values collection is backed by the underlying map for clear().
 public  void testValuesRemoveChangesMap() 
    Tests that the Map#values collection is backed by the underlying map by removing from the values collection and testing if the value was removed from the map.

    We should really test the "vice versa" case--that values removed from the map are removed from the values collection--also, but that's a more difficult test to construct (lacking a "removeValue" method.)

    See bug 9573.

 public  void verify() 
    Verifies that #map is still equal to #confirmed . This method checks that the map is equal to the HashMap, and that the map's collection views are still equal to the HashMap's collection views. An equals test is done on the maps and their collection views; their size and isEmpty results are compared; their hashCodes are compared; and containsAll tests are run on the collection views.
 public  void verifyEntrySet() 
 public  void verifyKeySet() 
 public  void verifyMap() 
 public  void verifyValues()