Java Doc for TestCollection.java in  » Ajax » GWT » org » apache » commons » collections » Java Source Code / Java DocumentationJava Source Code and Java Documentation

You should create a concrete subclass of this class to test any custom Collection implementation. At minimum, you'll have to implement the TestCollection.makeCollection() method. You might want to override some of the additional protected 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):

• TestCollection.getFullElements()
• TestCollection.getOtherElements()

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

• TestCollection.isAddSuppoted()
• TestCollection.isRemoveSupported()
• TestCollection.areEqualElementsDistinguishable()

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 TestCollection.collection field holds an instance of your collection implementation; the TestCollection.confirmed field holds an instance of the confirmed collection implementation. The TestCollection.resetEmpty() and TestCollection.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 TestCollection.collection and TestCollection.confirmed , the TestCollection.verify() method is invoked to compare the results. You may want to override TestCollection.verify() to perform additional verifications. For instance, when testing the collection views of a map, TestMap would override TestCollection.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:

• TestCollection.makeConfirmedCollection()
• TestCollection.makeConfirmedFullCollection()

If you're extending TestList , TestSet , or TestBag , 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. For instance, the TestCollection.testIteratorFailFast() method is provided since most collections have fail-fast iterators; however, that's not strictly required by the collection contract, so you may want to override that method to do nothing.

author:
   Rodney Waldhoff
author:
   Paul Jack
author:
   Michael A. Smith
version:
   $Id: TestCollection.java,v 1.9.2.1 2004/05/22 12:14:05 scolebourne Exp $

Default implementation returns true.

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.

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

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