Class AbstractTestMap
- java.lang.Object
-
- junit.framework.Assert
-
- junit.framework.TestCase
-
- org.apache.commons.collections.BulkTest
-
- org.apache.commons.collections.AbstractTestObject
-
- org.apache.commons.collections.map.AbstractTestMap
-
- All Implemented Interfaces:
java.lang.Cloneable
,junit.framework.Test
- Direct Known Subclasses:
AbstractTestBidiMap
,AbstractTestIterableMap
,AbstractTestSortedMap
public abstract class AbstractTestMap extends AbstractTestObject
Abstract test class forMap
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 themakeEmptyMap()
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 MethodsOverride these methods if your map doesn't support certain operations:
-
isPutAddSupported()
-
isPutChangeSupported()
-
isSetValueSupported()
-
isRemoveSupported()
-
isGetStructuralModify()
-
isAllowDuplicateValues()
-
isAllowNullKey()
-
isAllowNullValue()
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 theMap
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. TheentrySet
,keySet
andvalues
fields hold that map's collection views. And theconfirmed
field holds an instance of the confirmed collection implementation. TheresetEmpty()
andresetFull()
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
andconfirmed
, theverify()
method is invoked to compare the results. Theverify()
method calls separate methods to verify the map and its three collection views (verifyMap()
,verifyEntrySet()
,verifyKeySet()
, andverifyValues()
). You may want to override one of the verification methodsto perform additional verifications. For instance, TestDoubleOrderedMap would want override itsverifyValues()
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, overrideisAllowDuplicateValues()
and have it returnfalse
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description class
AbstractTestMap.TestMapEntrySet
class
AbstractTestMap.TestMapKeySet
class
AbstractTestMap.TestMapValues
-
Field Summary
Fields Modifier and Type Field Description protected java.util.Map
confirmed
HashMap created by reset().protected java.util.Set
entrySet
Entry set of map created by reset().protected java.util.Set
keySet
Key set of map created by reset().protected java.util.Map
map
Map created by reset().protected java.util.Collection
values
Values collection of map created by reset().-
Fields inherited from class org.apache.commons.collections.AbstractTestObject
COLLECTIONS_MAJOR_VERSION
-
-
Constructor Summary
Constructors Constructor Description AbstractTestMap(java.lang.String testName)
JUnit constructor.
-
Method Summary
All Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description void
addSampleMappings(java.util.Map m)
Helper method to add all the mappings described bygetSampleKeys()
andgetSampleValues()
.BulkTest
bulkTestMapEntrySet()
Bulk testMap.entrySet()
.BulkTest
bulkTestMapKeySet()
Bulk testMap.keySet()
.BulkTest
bulkTestMapValues()
Bulk testMap.values()
.java.util.Map.Entry
cloneMapEntry(java.util.Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.java.lang.String
getCompatibilityVersion()
Gets the compatability version, needed for package access.java.lang.Object[]
getNewSampleValues()
Returns a the set of values that can be used to replace the values returned fromgetSampleValues()
.java.lang.Object[]
getOtherKeys()
java.lang.Object[]
getOtherNonNullStringElements()
Returns a list of string elements suitable for return bygetOtherKeys()
orgetOtherValues()
.java.lang.Object[]
getOtherValues()
java.lang.Object[]
getSampleKeys()
Returns the set of keys in the mappings used to test the map.java.lang.Object[]
getSampleValues()
Returns the set of values in the mappings used to test the map.boolean
isAllowDuplicateValues()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
supports duplicate values.boolean
isAllowNullKey()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
supports null keys.boolean
isAllowNullValue()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
supports null values.boolean
isGetStructuralModify()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
can cause structural modification on a get().boolean
isPutAddSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support theput
andputAll
operations adding new mappings.boolean
isPutChangeSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support theput
andputAll
operations changing existing mappings.boolean
isRemoveSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support theremove
andclear
operations.boolean
isSetValueSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support thesetValue
operation on entrySet entries.boolean
isSubMapViewsSerializable()
Returns whether the sub map views of SortedMap are serializable.java.util.Map
makeConfirmedMap()
Override to return a map other than HashMap as the confirmed map.abstract java.util.Map
makeEmptyMap()
Return a new, emptyMap
to be used for testing.java.util.Map
makeFullMap()
Return a new, populated map.java.lang.Object
makeObject()
Implements the superclass method to return the map to be tested.void
resetEmpty()
void
resetFull()
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 theMap.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 theMap.keySet()
collection is backed by the underlying map for clear().void
testKeySetRemoveChangesMap()
Tests that theMap.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()
TestsMap.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 theMap.values()
collection is backed by the underlying map for clear().void
testValuesRemoveChangesMap()
Tests that theMap.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()
void
verifyEntrySet()
void
verifyKeySet()
void
verifyMap()
void
verifyValues()
-
Methods inherited from class org.apache.commons.collections.AbstractTestObject
getCanonicalEmptyCollectionName, getCanonicalFullCollectionName, isEqualsCheckable, isTestSerialization, readExternalFormFromBytes, readExternalFormFromDisk, skipSerializedCanonicalTests, supportsEmptyCollections, supportsFullCollections, testCanonicalEmptyCollectionExists, testCanonicalFullCollectionExists, testEqualsNull, testObjectEqualsSelf, testObjectHashCodeEqualsContract, testObjectHashCodeEqualsSelfHashCode, testSerializeDeserializeThenCompare, testSimpleSerialization, writeExternalFormToBytes, writeExternalFormToDisk
-
Methods inherited from class org.apache.commons.collections.BulkTest
clone, ignoredTests, makeSuite, toString
-
Methods inherited from class junit.framework.TestCase
assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertFalse, assertFalse, assertNotNull, assertNotNull, assertNotSame, assertNotSame, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, countTestCases, createResult, fail, fail, failNotEquals, failNotSame, failSame, format, getName, run, run, runBare, runTest, setName, setUp
-
-
-
-
Field Detail
-
map
protected java.util.Map map
Map created by reset().
-
entrySet
protected java.util.Set entrySet
Entry set of map created by reset().
-
keySet
protected java.util.Set keySet
Key set of map created by reset().
-
values
protected java.util.Collection values
Values collection of map created by reset().
-
confirmed
protected java.util.Map confirmed
HashMap created by reset().
-
-
Method Detail
-
isPutAddSupported
public boolean isPutAddSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support theput
andputAll
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 bymakeEmptyMap()
andmakeFullMap()
support theput
andputAll
operations changing existing mappings.Default implementation returns true. Override if your collection class does not support put changing.
-
isSetValueSupported
public boolean isSetValueSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support thesetValue
operation on entrySet entries.Default implementation returns isPutChangeSupported(). Override if your collection class does not support setValue but does support put changing.
-
isRemoveSupported
public boolean isRemoveSupported()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
support theremove
andclear
operations.Default implementation returns true. Override if your collection class does not support removal operations.
-
isGetStructuralModify
public boolean isGetStructuralModify()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
can cause structural modification on a get(). The example is LRUMap.Default implementation returns false. Override if your map class structurally modifies on get.
-
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
-
isAllowNullKey
public boolean isAllowNullKey()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
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 bymakeEmptyMap()
andmakeFullMap()
supports null values.Default implementation returns true. Override if your collection class does not support null values.
-
isAllowDuplicateValues
public boolean isAllowDuplicateValues()
Returns true if the maps produced bymakeEmptyMap()
andmakeFullMap()
supports duplicate values.Default implementation returns true. Override if your collection class does not support duplicate values.
-
getSampleKeys
public java.lang.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 asgetSampleValues()
and all array elements must be different. The default implementation constructs a set of String keys, and includes a single null key ifisAllowNullKey()
returnstrue
.
-
getOtherKeys
public java.lang.Object[] getOtherKeys()
-
getOtherValues
public java.lang.Object[] getOtherValues()
-
getOtherNonNullStringElements
public java.lang.Object[] getOtherNonNullStringElements()
Returns a list of string elements suitable for return bygetOtherKeys()
orgetOtherValues()
.Override getOtherElements to returnthe results of this method if your collection does not support heterogenous elements or the null element.
-
getSampleValues
public java.lang.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 asgetSampleKeys()
. The default implementation constructs a set of String values and includes a single null value ifisAllowNullValue()
returnstrue
, and includes two values that are the same ifisAllowDuplicateValues()
returnstrue
.
-
getNewSampleValues
public java.lang.Object[] getNewSampleValues()
Returns a the set of values that can be used to replace the values returned fromgetSampleValues()
. This method must return an array with the same length asgetSampleValues()
. The values returned from this method should not be the same as those returned fromgetSampleValues()
. The default implementation constructs a set of String values and includes a single null value ifisAllowNullValue()
returnstrue
, and includes two values that are the same ifisAllowDuplicateValues()
returnstrue
.
-
addSampleMappings
public void addSampleMappings(java.util.Map m)
Helper method to add all the mappings described bygetSampleKeys()
andgetSampleValues()
.
-
makeEmptyMap
public abstract java.util.Map makeEmptyMap()
Return a new, emptyMap
to be used for testing.- Returns:
- the map to be tested
-
makeFullMap
public java.util.Map makeFullMap()
Return a new, populated map. The mappings in the map should match the keys and values returned fromgetSampleKeys()
andgetSampleValues()
. The default implementation uses makeEmptyMap() and callsaddSampleMappings(java.util.Map)
to add all the mappings to the map.- Returns:
- the map to be tested
-
makeObject
public java.lang.Object makeObject()
Implements the superclass method to return the map to be tested.- Specified by:
makeObject
in classAbstractTestObject
- Returns:
- the map to be tested
-
makeConfirmedMap
public java.util.Map makeConfirmedMap()
Override to return a map other than HashMap as the confirmed map.- Returns:
- a map that is known to be valid
-
cloneMapEntry
public java.util.Map.Entry cloneMapEntry(java.util.Map.Entry entry)
Creates a new Map Entry that is independent of the first and the map.
-
getCompatibilityVersion
public java.lang.String getCompatibilityVersion()
Gets the compatability version, needed for package access.- Overrides:
getCompatibilityVersion
in classAbstractTestObject
- Returns:
- The version, or
null
if this object shouldn't be tested for compatibility with previous versions.
-
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.
-
testMakeMap
public void testMakeMap()
Test to ensure that makeEmptyMap and makeFull returns a new non-null map with each invocation.
-
testMapIsEmpty
public void testMapIsEmpty()
Tests Map.isEmpty()
-
testMapSize
public void testMapSize()
Tests Map.size()
-
testMapClear
public void testMapClear()
TestsMap.clear()
. If the mapisRemoveSupported()
can add and remove elements}, thenMap.size()
andMap.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()
-
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.
-
testEmptyMapCompatibility
public void testEmptyMapCompatibility() throws java.lang.Exception
Compare the current serialized form of the Map against the canonical version in CVS.- Throws:
java.lang.Exception
-
testFullMapCompatibility
public void testFullMapCompatibility() throws java.lang.Exception
Compare the current serialized form of the Map against the canonical version in CVS.- Throws:
java.lang.Exception
-
testMapPut
public void testMapPut()
Tests Map.put(Object, Object)
-
testMapPutNullKey
public void testMapPutNullKey()
Tests Map.put(null, value)
-
testMapPutNullValue
public void testMapPutNullValue()
Tests Map.put(null, value)
-
testMapPutAll
public void testMapPutAll()
Tests Map.putAll(map)
-
testMapRemove
public void testMapRemove()
Tests Map.remove(Object)
-
testValuesClearChangesMap
public void testValuesClearChangesMap()
Tests that theMap.values()
collection is backed by the underlying map for clear().
-
testKeySetClearChangesMap
public void testKeySetClearChangesMap()
Tests that theMap.keySet()
collection is backed by the underlying map for clear().
-
testEntrySetClearChangesMap
public void testEntrySetClearChangesMap()
Tests that theMap.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()
-
testValuesRemoveChangesMap
public void testValuesRemoveChangesMap()
Tests that theMap.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.
-
testKeySetRemoveChangesMap
public void testKeySetRemoveChangesMap()
Tests that theMap.keySet()
set is backed by the underlying map by removing from the keySet set and testing if the key was removed from the map.
-
bulkTestMapEntrySet
public BulkTest bulkTestMapEntrySet()
Bulk testMap.entrySet()
. This method runs through all of the tests inAbstractTestSet
. After modification operations,verify()
is invoked to ensure that the map and the other collection views are still valid.- Returns:
- a
AbstractTestSet
instance for testing the map's entry set
-
bulkTestMapKeySet
public BulkTest bulkTestMapKeySet()
Bulk testMap.keySet()
. This method runs through all of the tests inAbstractTestSet
. After modification operations,verify()
is invoked to ensure that the map and the other collection views are still valid.- Returns:
- a
AbstractTestSet
instance for testing the map's key set
-
bulkTestMapValues
public BulkTest bulkTestMapValues()
Bulk testMap.values()
. This method runs through all of the tests inAbstractTestCollection
. After modification operations,verify()
is invoked to ensure that the map and the other collection views are still valid.- Returns:
- a
AbstractTestCollection
instance for testing the map's values collection
-
resetEmpty
public void resetEmpty()
-
resetFull
public void resetFull()
-
verify
public void verify()
Verifies thatmap
is still equal toconfirmed
. 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. Anequals
test is done on the maps and their collection views; their size andisEmpty
results are compared; their hashCodes are compared; andcontainsAll
tests are run on the collection views.
-
verifyMap
public void verifyMap()
-
verifyEntrySet
public void verifyEntrySet()
-
verifyKeySet
public void verifyKeySet()
-
verifyValues
public void verifyValues()
-
tearDown
public void tearDown() throws java.lang.Exception
Erases any leftover instance variables by setting them to null.- Overrides:
tearDown
in classjunit.framework.TestCase
- Throws:
java.lang.Exception
-
-