org.apache.commons.collections.collection
Class AbstractTestCollection

java.lang.Object
  extended byjunit.framework.Assert
      extended byjunit.framework.TestCase
          extended byorg.apache.commons.collections.BulkTest
              extended byorg.apache.commons.collections.AbstractTestObject
                  extended byorg.apache.commons.collections.collection.AbstractTestCollection
All Implemented Interfaces:
java.lang.Cloneable, junit.framework.Test
Direct Known Subclasses:
AbstractTestList, AbstractTestMap.TestMapValues, AbstractTestSet

public abstract class AbstractTestCollection
extends AbstractTestObject

Abstract test class for Collection methods and contracts.

You should create a concrete subclass of this class to test any custom Collection implementation. At minimum, you'll have to implement the makeCollection() method. You might want to override some of the additional public methods as well:

Element Population Methods

Override these if your collection restricts what kind of elements are allowed (for instance, if null is not permitted):

Supported Operation Methods

Override these if your collection doesn't support certain operations:

Fixture Methods

Fixtures are used to verify that the the operation results in correct state for the collection. Basically, the operation is performed against your collection implementation, and an identical operation is performed against a confirmed collection implementation. A confirmed collection implementation is something like java.util.ArrayList, which is known to conform exactly to its collection interface's contract. After the operation takes place on both your collection implementation and the confirmed collection implementation, the two collections are compared to see if their state is identical. The comparison is usually much more involved than a simple equals test. This verification is used to ensure proper modifications are made along with ensuring that the collection does not change when read-only modifications are made.

The collection field holds an instance of your collection implementation; the confirmed field holds an instance of the confirmed collection implementation. The resetEmpty() and resetFull() methods set these fields to empty or full collections, so that tests can proceed from a known state.

After a modification operation to both collection and confirmed, the verify() method is invoked to compare the results. You may want to override verify() to perform additional verifications. For instance, when testing the collection views of a map, AbstractTestMap would override verify() to make sure the map is changed after the collection view is changed.

If you're extending this class directly, you will have to provide implementations for the following:

Those methods should provide a confirmed collection implementation that's compatible with your collection implementation.

If you're extending AbstractTestList, AbstractTestSet, or AbstractTestBag, you probably don't have to worry about the above methods, because those three classes already override the methods to provide standard JDK confirmed collections.

Other notes

If your Collection fails one of these tests by design, you may still use this base set of cases. Simply override the test case (method) your Collection fails.


Field Summary
 java.util.Collection collection
          A collection instance that will be used for testing.
 java.util.Collection confirmed
          Confirmed collection.
 
Fields inherited from class org.apache.commons.collections.AbstractTestObject
COLLECTIONS_MAJOR_VERSION
 
Constructor Summary
AbstractTestCollection(java.lang.String testName)
          JUnit constructor.
 
Method Summary
 boolean areEqualElementsDistinguishable()
          Specifies whether equal elements in the collection are, in fact, distinguishable with information not readily available.
 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.Object[] getFullElements()
          Returns an array of objects that are contained in a collection produced by makeFullCollection().
 java.lang.Object[] getFullNonNullElements()
          Returns a list of elements suitable for return by getFullElements().
 java.lang.Object[] getFullNonNullStringElements()
          Returns a list of string elements suitable for return by getFullElements().
 java.lang.Object[] getOtherElements()
          Returns an array of elements that are not contained in a full collection.
 java.lang.Object[] getOtherNonNullElements()
          Returns the default list of objects returned by getOtherElements().
 java.lang.Object[] getOtherNonNullStringElements()
          Returns a list of string elements suitable for return by getOtherElements().
 boolean isAddSupported()
          Returns true if the collections produced by makeCollection() and makeFullCollection() support the add and addAll operations.
 boolean isEqualsCheckable()
          Returns true to indicate that the collection supports equals() comparisons.
 boolean isFailFastSupported()
          Returns true to indicate that the collection supports fail fast iterators.
 boolean isNullSupported()
          Returns true to indicate that the collection supports holding null.
 boolean isRemoveSupported()
          Returns true if the collections produced by makeCollection() and makeFullCollection() support the remove, removeAll, retainAll, clear and iterator().remove() methods.
abstract  java.util.Collection makeCollection()
          Return a new, empty Collection to be used for testing.
abstract  java.util.Collection makeConfirmedCollection()
          Returns a confirmed empty collection.
abstract  java.util.Collection makeConfirmedFullCollection()
          Returns a confirmed full collection.
 java.util.Collection makeFullCollection()
          Returns a full collection to be used for testing.
 java.lang.Object makeObject()
          Returns an empty collection for Object tests.
 void resetEmpty()
          Resets the collection and confirmed fields to empty collections.
 void resetFull()
          Resets the collection and confirmed fields to full collections.
 void testCollectionAdd()
          Tests Collection.add(Object).
 void testCollectionAddAll()
          Tests Collection.addAll(Collection).
 void testCollectionClear()
          Test Collection.clear().
 void testCollectionContains()
          Tests Collection.contains(Object).
 void testCollectionContainsAll()
          Tests Collection.containsAll(Collection).
 void testCollectionIsEmpty()
          Tests Collection.isEmpty().
 void testCollectionIterator()
          Tests the read-only functionality of Collection.iterator().
 void testCollectionIteratorFailFast()
          Tests that the collection's iterator is fail-fast.
 void testCollectionIteratorRemove()
          Tests removals from Collection.iterator().
 void testCollectionRemove()
          Tests Collection.remove(Object).
 void testCollectionRemoveAll()
          Tests Collection.removeAll(Collection).
 void testCollectionRetainAll()
          Tests Collection.retainAll(Collection).
 void testCollectionSize()
          Tests Collection.size().
 void testCollectionToArray()
          Tests Collection.toArray().
 void testCollectionToArray2()
          Tests Collection.toArray(Object[]).
 void testCollectionToString()
          Tests toString on a collection.
 void testSerializeDeserializeThenCompare()
           
 void testUnsupportedAdd()
          If isAddSupported() returns false, tests that add operations raise UnsupportedOperationException.
 void testUnsupportedRemove()
          If isRemoveSupported() returns false, tests to see that remove operations raise an UnsupportedOperationException.
 void verify()
          Verifies that collection and confirmed have identical state.
 
Methods inherited from class org.apache.commons.collections.AbstractTestObject
getCanonicalEmptyCollectionName, getCanonicalFullCollectionName, getCompatibilityVersion, isTestSerialization, readExternalFormFromBytes, readExternalFormFromDisk, skipSerializedCanonicalTests, supportsEmptyCollections, supportsFullCollections, testCanonicalEmptyCollectionExists, testCanonicalFullCollectionExists, testEqualsNull, testObjectEqualsSelf, testObjectHashCodeEqualsContract, testObjectHashCodeEqualsSelfHashCode, testSimpleSerialization, writeExternalFormToBytes, writeExternalFormToDisk
 
Methods inherited from class org.apache.commons.collections.BulkTest
clone, ignoredTests, makeSuite, toString
 
Methods inherited from class junit.framework.TestCase
countTestCases, createResult, getName, run, run, runBare, runTest, setName, setUp, tearDown
 
Methods inherited from class junit.framework.Assert
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, fail, fail, failNotEquals, failNotSame, failSame
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

collection

public java.util.Collection collection
A collection instance that will be used for testing.


confirmed

public java.util.Collection confirmed
Confirmed collection. This is an instance of a collection that is confirmed to conform exactly to the java.util.Collection contract. Modification operations are tested by performing a mod on your collection, performing the exact same mod on an equivalent confirmed collection, and then calling verify() to make sure your collection still matches the confirmed collection.

Constructor Detail

AbstractTestCollection

public AbstractTestCollection(java.lang.String testName)
JUnit constructor.

Parameters:
testName - the test class name
Method Detail

areEqualElementsDistinguishable

public boolean areEqualElementsDistinguishable()
Specifies whether equal elements in the collection are, in fact, distinguishable with information not readily available. That is, if a particular value is to be removed from the collection, then there is one and only one value that can be removed, even if there are other elements which are equal to it.

In most collection cases, elements are not distinguishable (equal is equal), thus this method defaults to return false. In some cases, however, they are. For example, the collection returned from the map's values() collection view are backed by the map, so while there may be two values that are equal, their associated keys are not. Since the keys are distinguishable, the values are.

This flag is used to skip some verifications for iterator.remove() where it is impossible to perform an equivalent modification on the confirmed collection because it is not possible to determine which value in the confirmed collection to actually remove. Tests that override the default (i.e. where equal elements are distinguishable), should provide additional tests on iterator.remove() to make sure the proper elements are removed when remove() is called on the iterator.


isAddSupported

public boolean isAddSupported()
Returns true if the collections produced by makeCollection() and makeFullCollection() support the add and addAll operations.

Default implementation returns true. Override if your collection class does not support add or addAll.


isRemoveSupported

public boolean isRemoveSupported()
Returns true if the collections produced by makeCollection() and makeFullCollection() support the remove, removeAll, retainAll, clear and iterator().remove() methods. Default implementation returns true. Override if your collection class does not support removal operations.


isNullSupported

public boolean isNullSupported()
Returns true to indicate that the collection supports holding null. The default implementation returns true;


isFailFastSupported

public boolean isFailFastSupported()
Returns true to indicate that the collection supports fail fast iterators. The default implementation returns true;


isEqualsCheckable

public boolean isEqualsCheckable()
Returns true to indicate that the collection supports equals() comparisons. This implementation returns false;

Overrides:
isEqualsCheckable in class AbstractTestObject

verify

public void verify()
Verifies that collection and confirmed have identical state.


resetEmpty

public void resetEmpty()
Resets the collection and confirmed fields to empty collections. Invoke this method before performing a modification test.


resetFull

public void resetFull()
Resets the collection and confirmed fields to full collections. Invoke this method before performing a modification test.


makeConfirmedCollection

public abstract java.util.Collection makeConfirmedCollection()
Returns a confirmed empty collection. For instance, an ArrayList for lists or a HashSet for sets.

Returns:
a confirmed empty collection

makeConfirmedFullCollection

public abstract java.util.Collection makeConfirmedFullCollection()
Returns a confirmed full collection. For instance, an ArrayList for lists or a HashSet for sets. The returned collection should contain the elements returned by getFullElements().

Returns:
a confirmed full collection

makeCollection

public abstract java.util.Collection makeCollection()
Return a new, empty Collection to be used for testing.


makeFullCollection

public java.util.Collection makeFullCollection()
Returns a full collection to be used for testing. The collection returned by this method should contain every element returned by getFullElements(). The default implementation, in fact, simply invokes addAll on an empty collection with the results of getFullElements(). Override this default if your collection doesn't support addAll.


makeObject

public java.lang.Object makeObject()
Returns an empty collection for Object tests.

Specified by:
makeObject in class AbstractTestObject
Returns:
the object to test

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.


getFullElements

public java.lang.Object[] getFullElements()
Returns an array of objects that are contained in a collection produced by makeFullCollection(). Every element in the returned array must be an element in a full collection.

The default implementation returns a heterogenous array of objects with some duplicates. null is added if allowed. Override if you require specific testing elements. Note that if you override makeFullCollection(), you must override this method to reflect the contents of a full collection.


getOtherElements

public java.lang.Object[] getOtherElements()
Returns an array of elements that are not contained in a full collection. Every element in the returned array must not exist in a collection returned by makeFullCollection(). The default implementation returns a heterogenous array of elements without null. Note that some of the tests add these elements to an empty or full collection, so if your collection restricts certain kinds of elements, you should override this method.


getFullNonNullElements

public java.lang.Object[] getFullNonNullElements()
Returns a list of elements suitable for return by getFullElements(). The array returned by this method does not include null, but does include a variety of objects of different types. Override getFullElements to return the results of this method if your collection does not support the null element.


getOtherNonNullElements

public java.lang.Object[] getOtherNonNullElements()
Returns the default list of objects returned by getOtherElements(). Includes many objects of different types.


getFullNonNullStringElements

public java.lang.Object[] getFullNonNullStringElements()
Returns a list of string elements suitable for return by getFullElements(). Override getFullElements to return the results of this method if your collection does not support heterogenous elements or the null element.


getOtherNonNullStringElements

public java.lang.Object[] getOtherNonNullStringElements()
Returns a list of string elements suitable for return by getOtherElements(). Override getOtherElements to return the results of this method if your collection does not support heterogenous elements or the null element.


testCollectionAdd

public void testCollectionAdd()
Tests Collection.add(Object).


testCollectionAddAll

public void testCollectionAddAll()
Tests Collection.addAll(Collection).


testUnsupportedAdd

public void testUnsupportedAdd()
If isAddSupported() returns false, tests that add operations raise UnsupportedOperationException.


testCollectionClear

public void testCollectionClear()
Test Collection.clear().


testCollectionContains

public void testCollectionContains()
Tests Collection.contains(Object).


testCollectionContainsAll

public void testCollectionContainsAll()
Tests Collection.containsAll(Collection).


testCollectionIsEmpty

public void testCollectionIsEmpty()
Tests Collection.isEmpty().


testCollectionIterator

public void testCollectionIterator()
Tests the read-only functionality of Collection.iterator().


testCollectionIteratorRemove

public void testCollectionIteratorRemove()
Tests removals from Collection.iterator().


testCollectionRemove

public void testCollectionRemove()
Tests Collection.remove(Object).


testCollectionRemoveAll

public void testCollectionRemoveAll()
Tests Collection.removeAll(Collection).


testCollectionRetainAll

public void testCollectionRetainAll()
Tests Collection.retainAll(Collection).


testCollectionSize

public void testCollectionSize()
Tests Collection.size().


testCollectionToArray

public void testCollectionToArray()
Tests Collection.toArray().


testCollectionToArray2

public void testCollectionToArray2()
Tests Collection.toArray(Object[]).


testCollectionToString

public void testCollectionToString()
Tests toString on a collection.


testUnsupportedRemove

public void testUnsupportedRemove()
If isRemoveSupported() returns false, tests to see that remove operations raise an UnsupportedOperationException.


testCollectionIteratorFailFast

public void testCollectionIteratorFailFast()
Tests that the collection's iterator is fail-fast.


testSerializeDeserializeThenCompare

public void testSerializeDeserializeThenCompare()
                                         throws java.lang.Exception
Overrides:
testSerializeDeserializeThenCompare in class AbstractTestObject
Throws:
java.lang.Exception


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