org.apache.commons.collections.map

Class AbstractTestMap


public abstract class AbstractTestMap
extends AbstractTestObject

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

class
AbstractTestMap.TestMapEntrySet
class
AbstractTestMap.TestMapKeySet
class
AbstractTestMap.TestMapValues

Field Summary

protected Map
confirmed
HashMap created by reset().
protected Set
entrySet
Entry set of map created by reset().
protected Set
keySet
Key set of map created by reset().
protected Map
map
Map created by reset().
protected Collection
values
Values collection of map created by reset().

Constructor Summary

AbstractTestMap(String testName)
JUnit constructor.

Method Summary

void
addSampleMappings(Map m)
Helper method to add all the mappings described by getSampleKeys() and getSampleValues().
BulkTest
bulkTestMapEntrySet()
Bulk test Map.entrySet().
BulkTest
bulkTestMapKeySet()
Bulk test Map.keySet().
BulkTest
bulkTestMapValues()
Bulk test Map.values().
Map.Entry
cloneMapEntry(Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.
String
getCompatibilityVersion()
Gets the compatability version, needed for package access.
Object[]
getNewSampleValues()
Returns a the set of values that can be used to replace the values returned from getSampleValues().
Object[]
getOtherKeys()
Object[]
getOtherNonNullStringElements()
Returns a list of string elements suitable for return by getOtherKeys() or getOtherValues().
Object[]
getOtherValues()
Object[]
getSampleKeys()
Returns the set of keys in the mappings used to test the map.
Object[]
getSampleValues()
Returns the set of values in the mappings used to test the map.
boolean
isAllowDuplicateValues()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() supports duplicate values.
boolean
isAllowNullKey()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() supports null keys.
boolean
isAllowNullValue()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() supports null values.
boolean
isGetStructuralModify()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() can cause structural modification on a get().
boolean
isPutAddSupported()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() support the put and putAll operations adding new mappings.
boolean
isPutChangeSupported()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() support the put and putAll operations changing existing mappings.
boolean
isRemoveSupported()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() support the remove and clear operations.
boolean
isSetValueSupported()
Returns true if the maps produced by makeEmptyMap() and makeFullMap() support the setValue operation on entrySet entries.
boolean
isSubMapViewsSerializable()
Returns whether the sub map views of SortedMap are serializable.
Map
makeConfirmedMap()
Override to return a map other than HashMap as the confirmed map.
abstract Map
makeEmptyMap()
Return a new, empty Map to be used for testing.
Map
makeFullMap()
Return a new, populated map.
Object
makeObject()
Implements the superclass method to return the map to be tested.
void
resetEmpty()
Resets the map, entrySet, keySet, values and confirmed fields to empty.
void
resetFull()
Resets the map, entrySet, keySet, values and confirmed fields to full.
void
tearDown()
Erases any leftover instance variables by setting them to null.
void
testEmptyMapCompatibility()
Compare the current serialized form of the Map against the canonical version in CVS.
void
testEntrySetClearChangesMap()
Tests that the Map.entrySet() collection is backed by the underlying map for clear().
void
testEntrySetContains1()
void
testEntrySetContains2()
void
testEntrySetContains3()
void
testEntrySetRemove1()
void
testEntrySetRemove2()
void
testEntrySetRemove3()
void
testFullMapCompatibility()
Compare the current serialized form of the Map against the canonical version in CVS.
void
testKeySetClearChangesMap()
Tests that the Map.keySet collection is backed by the underlying map for clear().
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.
void
testMakeMap()
Test to ensure that makeEmptyMap and makeFull returns a new non-null map with each invocation.
void
testMapClear()
Tests Map.clear().
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.
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.
void
testMapEquals()
Tests Map.equals(Object)
void
testMapGet()
Tests Map.get(Object)
void
testMapHashCode()
Tests Map.hashCode()
void
testMapIsEmpty()
Tests Map.isEmpty()
void
testMapPut()
Tests Map.put(Object, Object)
void
testMapPutAll()
Tests Map.putAll(map)
void
testMapPutNullKey()
Tests Map.put(null, value)
void
testMapPutNullValue()
Tests Map.put(null, value)
void
testMapRemove()
Tests Map.remove(Object)
void
testMapSize()
Tests Map.size()
void
testMapToString()
Tests Map.toString().
void
testSampleMappings()
Test to ensure the test setup is working properly.
void
testValuesClearChangesMap()
Tests that the Map.values collection is backed by the underlying map for clear().
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.
void
verify()
Verifies that map is still equal to confirmed.
void
verifyEntrySet()
void
verifyKeySet()
void
verifyMap()
void
verifyValues()

Field Details

confirmed

protected Map confirmed
HashMap created by reset().

entrySet

protected Set entrySet
Entry set of map created by reset().

keySet

protected Set keySet
Key set of map created by reset().

map

protected Map map
Map created by reset().

values

protected Collection values
Values collection of map created by reset().

Constructor Details

AbstractTestMap

public AbstractTestMap(String testName)
JUnit constructor.
Parameters:
testName - the test name

Method Details

addSampleMappings

public void addSampleMappings(Map m)

bulkTestMapEntrySet

public BulkTest bulkTestMapEntrySet()
Returns:
a AbstractTestSet instance for testing the map's entry set

bulkTestMapKeySet

public BulkTest bulkTestMapKeySet()
Returns:
a AbstractTestSet instance for testing the map's key set

bulkTestMapValues

public BulkTest bulkTestMapValues()
Returns:
a AbstractTestCollection instance for testing the map's values collection

cloneMapEntry

public Map.Entry cloneMapEntry(Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.

getCompatibilityVersion

public String getCompatibilityVersion()
Gets the compatability version, needed for package access.

getNewSampleValues

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.

getOtherKeys

public Object[] getOtherKeys()

getOtherNonNullStringElements

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.


getOtherValues

public Object[] getOtherValues()

getSampleKeys

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.

getSampleValues

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.

isAllowDuplicateValues

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.


isAllowNullKey

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.


isAllowNullValue

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.


isGetStructuralModify

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.


isPutAddSupported

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.


isPutChangeSupported

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.


isRemoveSupported

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.


isSetValueSupported

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.


isSubMapViewsSerializable

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.
Returns:
false

makeConfirmedMap

public Map makeConfirmedMap()
Override to return a map other than HashMap as the confirmed map.
Returns:
a map that is known to be valid

makeEmptyMap

public abstract Map makeEmptyMap()
Return a new, empty Map to be used for testing.
Returns:
the map to be tested

makeFullMap

public Map makeFullMap()
Returns:
the map to be tested

makeObject

public Object makeObject()
Implements the superclass method to return the map to be tested.
Returns:
the map to be tested

resetEmpty

public void resetEmpty()

resetFull

public void resetFull()

tearDown

public void tearDown()
            throws Exception
Erases any leftover instance variables by setting them to null.

testEmptyMapCompatibility

public void testEmptyMapCompatibility()
            throws Exception
Compare the current serialized form of the Map against the canonical version in CVS.

testEntrySetClearChangesMap

public void testEntrySetClearChangesMap()
Tests that the Map.entrySet() collection is backed by the underlying map for clear().

testEntrySetContains1

public void testEntrySetContains1()

testEntrySetContains2

public void testEntrySetContains2()

testEntrySetContains3

public void testEntrySetContains3()

testEntrySetRemove1

public void testEntrySetRemove1()

testEntrySetRemove2

public void testEntrySetRemove2()

testEntrySetRemove3

public void testEntrySetRemove3()

testFullMapCompatibility

public void testFullMapCompatibility()
            throws Exception
Compare the current serialized form of the Map against the canonical version in CVS.

testKeySetClearChangesMap

public void testKeySetClearChangesMap()
Tests that the Map.keySet collection is backed by the underlying map for clear().

testKeySetRemoveChangesMap

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.

testMakeMap

public void testMakeMap()
Test to ensure that makeEmptyMap and makeFull returns a new non-null map with each invocation.

testMapClear

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.

testMapContainsKey

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.

testMapContainsValue

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.

testMapEquals

public void testMapEquals()
Tests Map.equals(Object)

testMapGet

public void testMapGet()
Tests Map.get(Object)

testMapHashCode

public void testMapHashCode()
Tests Map.hashCode()

testMapIsEmpty

public void testMapIsEmpty()
Tests Map.isEmpty()

testMapPut

public void testMapPut()
Tests Map.put(Object, Object)

testMapPutAll

public void testMapPutAll()
Tests Map.putAll(map)

testMapPutNullKey

public void testMapPutNullKey()
Tests Map.put(null, value)

testMapPutNullValue

public void testMapPutNullValue()
Tests Map.put(null, value)

testMapRemove

public void testMapRemove()
Tests Map.remove(Object)

testMapSize

public void testMapSize()
Tests Map.size()

testMapToString

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.

testSampleMappings

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.

testValuesClearChangesMap

public void testValuesClearChangesMap()
Tests that the Map.values collection is backed by the underlying map for clear().

testValuesRemoveChangesMap

public void testValuesRemoveChangesMap()

verify

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.

verifyEntrySet

public void verifyEntrySet()

verifyKeySet

public void verifyKeySet()

verifyMap

public void verifyMap()

verifyValues

public void verifyValues()

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