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
addSampleMappings
public void addSampleMappings(Map m)
bulkTestMapEntrySet
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.
- a
AbstractTestSet
instance for testing the map's entry set
bulkTestMapKeySet
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.
- a
AbstractTestSet
instance for testing the map's key set
bulkTestMapValues
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.
- 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.
makeConfirmedMap
public Map makeConfirmedMap()
Override to return a map other than HashMap as the confirmed map.
- a map that is known to be valid
makeEmptyMap
public abstract Map makeEmptyMap()
Return a new, empty Map
to be used for testing.
makeFullMap
public Map makeFullMap()
makeObject
public Object makeObject()
Implements the superclass method to return 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()
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.
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()