| 1 |
/* |
| 2 |
* Copyright (C) 2007 The Guava Authors |
| 3 |
* |
| 4 |
* Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
* you may not use this file except in compliance with the License. |
| 6 |
* You may obtain a copy of the License at |
| 7 |
* |
| 8 |
* http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
* |
| 10 |
* Unless required by applicable law or agreed to in writing, software |
| 11 |
* distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
* See the License for the specific language governing permissions and |
| 14 |
* limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
package com.google.common.collect.testing; |
| 18 |
|
| 19 |
import com.google.common.annotations.GwtCompatible; |
| 20 |
import java.util.Collections; |
| 21 |
import java.util.Iterator; |
| 22 |
|
| 23 |
/** |
| 24 |
* A utility for testing an Iterator implementation by comparing its behavior to that of a "known |
| 25 |
* good" reference implementation. In order to accomplish this, it's important to test a great |
| 26 |
* variety of sequences of the {@link Iterator#next}, {@link Iterator#hasNext} and {@link |
| 27 |
* Iterator#remove} operations. This utility takes the brute-force approach of trying <i>all</i> |
| 28 |
* possible sequences of these operations, up to a given number of steps. So, if the caller |
| 29 |
* specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are actually performed. |
| 30 |
* |
| 31 |
* <p>For instance, if <i>steps</i> is 5, one example sequence that will be tested is: |
| 32 |
* |
| 33 |
* <ol> |
| 34 |
* <li>remove(); |
| 35 |
* <li>hasNext() |
| 36 |
* <li>hasNext(); |
| 37 |
* <li>remove(); |
| 38 |
* <li>next(); |
| 39 |
* </ol> |
| 40 |
* |
| 41 |
* <p>This particular order of operations may be unrealistic, and testing all 3^5 of them may be |
| 42 |
* thought of as overkill; however, it's difficult to determine which proper subset of this massive |
| 43 |
* set would be sufficient to expose any possible bug. Brute force is simpler. |
| 44 |
* |
| 45 |
* <p>To use this class the concrete subclass must implement the {@link |
| 46 |
* IteratorTester#newTargetIterator()} method. This is because it's impossible to test an Iterator |
| 47 |
* without changing its state, so the tester needs a steady supply of fresh Iterators. |
| 48 |
* |
| 49 |
* <p>If your iterator supports modification through {@code remove()}, you may wish to override the |
| 50 |
* verify() method, which is called <em>after</em> each sequence and is guaranteed to be called |
| 51 |
* using the latest values obtained from {@link IteratorTester#newTargetIterator()}. |
| 52 |
* |
| 53 |
* <p>The value you pass to the parameter {@code steps} should be greater than the length of your |
| 54 |
* iterator, so that this class can check that your iterator behaves correctly when it is exhausted. |
| 55 |
* |
| 56 |
* <p>For example, to test {@link java.util.Collections#unmodifiableList(java.util.List) |
| 57 |
* Collections.unmodifiableList}'s iterator: |
| 58 |
* |
| 59 |
* <pre>{@code |
| 60 |
* List<String> expectedElements = |
| 61 |
* Arrays.asList("a", "b", "c", "d", "e"); |
| 62 |
* List<String> actualElements = |
| 63 |
* Collections.unmodifiableList( |
| 64 |
* Arrays.asList("a", "b", "c", "d", "e")); |
| 65 |
* IteratorTester<String> iteratorTester = |
| 66 |
* new IteratorTester<String>( |
| 67 |
* 6, |
| 68 |
* IteratorFeature.UNMODIFIABLE, |
| 69 |
* expectedElements, |
| 70 |
* IteratorTester.KnownOrder.KNOWN_ORDER) { |
| 71 |
* @Override |
| 72 |
* protected Iterator<String> newTargetIterator() { |
| 73 |
* return actualElements.iterator(); |
| 74 |
* } |
| 75 |
* }; |
| 76 |
* iteratorTester.test(); |
| 77 |
* iteratorTester.testForEachRemaining(); |
| 78 |
* }</pre> |
| 79 |
* |
| 80 |
* <p><b>Note</b>: It is necessary to use {@code IteratorTester.KnownOrder} as shown above, rather |
| 81 |
* than {@code KnownOrder} directly, because otherwise the code cannot be compiled. |
| 82 |
* |
| 83 |
* @author Kevin Bourrillion |
| 84 |
* @author Chris Povirk |
| 85 |
*/ |
| 86 |
@GwtCompatible |
| 87 |
public abstract class IteratorTester<E> extends AbstractIteratorTester<E, Iterator<E>> { |
| 88 |
/** |
| 89 |
* Creates an IteratorTester. |
| 90 |
* |
| 91 |
* @param steps how many operations to test for each tested pair of iterators |
| 92 |
* @param features the features supported by the iterator |
| 93 |
*/ |
| 94 |
protected IteratorTester( |
| 95 |
int steps, |
| 96 |
Iterable<? extends IteratorFeature> features, |
| 97 |
Iterable<E> expectedElements, |
| 98 |
KnownOrder knownOrder) { |
| 99 |
super(steps, Collections.<E>singleton(null), features, expectedElements, knownOrder, 0); |
| 100 |
} |
| 101 |
|
| 102 |
@Override |
| 103 |
protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { |
| 104 |
return iteratorStimuli(); |
| 105 |
} |
| 106 |
} |