Keel 2.1RC2

org.apache.commons.collections
Class TestMap

java.lang.Object
  extended byjunit.framework.Assert
      extended byjunit.framework.TestCase
          extended byorg.apache.commons.collections.BulkTest
              extended byorg.apache.commons.collections.TestObject
                  extended byorg.apache.commons.collections.TestMap
All Implemented Interfaces:
java.lang.Cloneable, junit.framework.Test
Direct Known Subclasses:
TestBeanMap, TestDoubleOrderedMap, TestFastHashMap, TestMultiHashMap, TestProxyMap, TestReferenceMap, TestSequencedHashMap, TestStaticBucketMap, TestTreeMap

public abstract class TestMap
extends TestObject

Tests base Map methods and contracts.

The forces at work here are similar to those in TestCollection. 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 implemenation is wierd, 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(), {@link verifyEntrySet()}, {@link verifyKeySet()}, and {@link verifyValues()}). You may want to override one of the verification methodsto perform additional verifications. For instance, {@link TestDoubleOrderedMap} would want override its {@link #verifyValues()} method to verify that the values are unique and in ascending order.

Other Notes

If your {@link Map} fails one of these tests by design, you may still use this base set of cases. Simply override the test case (method) your {@link 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 {@link #useDuplicateValues()} and have it return false

Version:
$Id: TestMap.java,v 1.20 2002/10/13 13:55:35 scolebourne Exp $
Author:
Michael Smith, Rodney Waldhoff, Paul Jack

Nested Class Summary
(package private)  class TestMap.TestMapEntrySet
           
(package private)  class TestMap.TestMapKeySet
           
(package private)  class TestMap.TestMapValues
           
 
Field Summary
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.TestObject
COLLECTIONS_MAJOR_VERSION
 
Fields inherited from class org.apache.commons.collections.BulkTest
verboseName
 
Fields inherited from class junit.framework.TestCase
 
Constructor Summary
TestMap(java.lang.String testName)
           
 
Method Summary
protected  void addSampleMappings(java.util.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().
protected  java.lang.Object[] getNewSampleValues()
          Returns a the set of values that can be used to replace the values returned from getSampleValues().
protected  java.lang.Object[] getOtherKeys()
           
protected  java.lang.Object[] getOtherValues()
           
protected  java.lang.Object[] getSampleKeys()
          Returns the set of keys in the mappings used to test the map.
protected  java.lang.Object[] getSampleValues()
          Returns the set of values in the mappings used to test the map.
protected  boolean isAddRemoveModifiable()
          Override if your map does not allow add/remove modifications.
protected  boolean isChangeable()
          Override if your map allows its mappings to be changed to new values.
protected abstract  java.util.Map makeEmptyMap()
          Return a new, empty Map to be used for testing.
private  java.util.Map.Entry[] makeEntryArray(java.lang.Object[] keys, java.lang.Object[] values)
          Utility methods to create an array of Map.Entry objects out of the given key and value arrays.
protected  java.util.Map makeFullMap()
          Return a new, populated map.
 java.lang.Object makeObject()
          Return a new, empty Object to used for testing.
protected  void resetEmpty()
          Resets the map, entrySet, keySet, values and confirmed fields to empty.
protected  void resetFull()
          Resets the map, entrySet, keySet, values and confirmed fields to full.
protected  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 testFullMapCompatibility()
          Compare the current serialized form of the Map against the canonical version in CVS.
 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(Collection)
 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.
protected  boolean useDuplicateValues()
          Override if your map does not allow duplicate values.
protected  boolean useNullKey()
          Override if your map does not allow a null key.
protected  boolean useNullValue()
          Override if your map does not allow null values.
protected  void verify()
          Verifies that map is still equal to confirmed.
protected  void verifyEntrySet()
           
protected  void verifyKeySet()
           
protected  void verifyMap()
           
protected  void verifyValues()
           
private  void views()
          Resets the collection view fields.
 
Methods inherited from class org.apache.commons.collections.TestObject
getCanonicalEmptyCollectionName, getCanonicalFullCollectionName, getCompatibilityVersion, readExternalFormFromBytes, readExternalFormFromDisk, supportsEmptyCollections, supportsFullCollections, testCanonicalEmptyCollectionExists, testCanonicalFullCollectionExists, testObjectEqualsSelf, testObjectHashCodeEqualsContract, testObjectHashCodeEqualsSelfHashCode, testSimpleSerialization, writeExternalFormToBytes, writeExternalFormToDisk
 
Methods inherited from class org.apache.commons.collections.BulkTest
clone, ignoredSimpleTests, makeSuite, toString
 
Methods inherited from class junit.framework.TestCase
countTestCases, createResult, getName, name, run, run, runBare, runTest, setName, setUp
 
Methods inherited from class junit.framework.Assert
assert, assert, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertEquals, assertNotNull, assertNotNull, assertNull, assertNull, assertSame, assertSame, assertTrue, assertTrue, fail, fail
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

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().

Constructor Detail

TestMap

public TestMap(java.lang.String testName)
Method Detail

useNullKey

protected boolean useNullKey()
Override if your map does not allow a null key. The default implementation returns true


useNullValue

protected boolean useNullValue()
Override if your map does not allow null values. The default implementation returns true.


useDuplicateValues

protected boolean useDuplicateValues()
Override if your map does not allow duplicate values. The default implementation returns true.


isChangeable

protected boolean isChangeable()
Override if your map allows its mappings to be changed to new values. The default implementation returns true.


isAddRemoveModifiable

protected boolean isAddRemoveModifiable()
Override if your map does not allow add/remove modifications. The default implementation returns true.


getSampleKeys

protected 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 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 useNullKey() returns true.


getOtherKeys

protected java.lang.Object[] getOtherKeys()

getOtherValues

protected java.lang.Object[] getOtherValues()

getSampleValues

protected 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 as getSampleKeys(). The default implementation contructs a set of String values and includes a single null value if useNullValue() returns true, and includes two values that are the same if useDuplicateValues() returns true.


getNewSampleValues

protected java.lang.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 useNullValue() returns true, and includes two values that are the same if useDuplicateValues() returns true.


addSampleMappings

protected void addSampleMappings(java.util.Map m)
Helper method to add all the mappings described by getSampleKeys() and getSampleValues().


makeEmptyMap

protected abstract java.util.Map makeEmptyMap()
Return a new, empty Map to be used for testing.


makeFullMap

protected java.util.Map makeFullMap()
Return a new, populated map. The mappings in the map should match the keys and values returned from getSampleKeys() and getSampleValues(). The default implementation uses makeEmptyMap() and calls #addSampleMappings() to add all the mappings to the map.


makeObject

public java.lang.Object makeObject()
Description copied from class: TestObject
Return a new, empty Object to used for testing.

Specified by:
makeObject in class TestObject

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 useNullKey() returns true. The values array must only have a null value if useNullValue() is true and may only have duplicate values if useDuplicateValues() 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()
Tests Map.clear(). If the map 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()


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.io.IOException,
                                      java.lang.ClassNotFoundException
Compare the current serialized form of the Map against the canonical version in CVS.

Throws:
java.io.IOException
java.lang.ClassNotFoundException

testFullMapCompatibility

public void testFullMapCompatibility()
                              throws java.io.IOException,
                                     java.lang.ClassNotFoundException
Compare the current serialized form of the Map against the canonical version in CVS.

Throws:
java.io.IOException
java.lang.ClassNotFoundException

testMapPut

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


testMapPutAll

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


testMapRemove

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


makeEntryArray

private java.util.Map.Entry[] makeEntryArray(java.lang.Object[] keys,
                                             java.lang.Object[] values)
Utility methods to create an array of Map.Entry objects out of the given key and value arrays.

Parameters:
keys - the array of keys
values - the array of values
Returns:
an array of Map.Entry of those keys to those values

bulkTestMapEntrySet

public BulkTest bulkTestMapEntrySet()
Bulk test Map.entrySet(). This method runs through all of the tests in TestSet. After modification operations, verify() is invoked to ensure that the map and the other collection views are still valid.

Returns:
a TestSet 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 TestSet. After modification operations, verify() is invoked to ensure that the map and the other collection views are still valid.

Returns:
a TestSet 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 TestCollection. After modification operations, verify() is invoked to ensure that the map and the other collection views are still valid.

Returns:
a TestCollection instance for testing the map's values collection

resetEmpty

protected void resetEmpty()
Resets the map, entrySet, keySet, values and confirmed fields to empty.


resetFull

protected void resetFull()
Resets the map, entrySet, keySet, values and confirmed fields to full.


views

private void views()
Resets the collection view fields.


verify

protected 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.


verifyMap

protected void verifyMap()

verifyEntrySet

protected void verifyEntrySet()

verifyKeySet

protected void verifyKeySet()

verifyValues

protected void verifyValues()

tearDown

protected void tearDown()
Erases any leftover instance variables by setting them to null.


Keel 2.1RC2

Please see keelframework.org for information about new Keel releases.