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 21 import java.util.Collections; 22 import java.util.Iterator; 23 24 /** 25 * A utility for testing an Iterator implementation by comparing its behavior to 26 * that of a "known good" reference implementation. In order to accomplish this, 27 * it's important to test a great variety of sequences of the 28 * {@link Iterator#next}, {@link Iterator#hasNext} and {@link Iterator#remove} 29 * operations. This utility takes the brute-force approach of trying <i>all</i> 30 * possible sequences of these operations, up to a given number of steps. So, if 31 * the caller specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are 32 * actually performed. 33 * 34 * <p>For instance, if <i>steps</i> is 5, one example sequence that will be 35 * tested is: 36 * 37 * <ol> 38 * <li>remove(); 39 * <li>hasNext() 40 * <li>hasNext(); 41 * <li>remove(); 42 * <li>next(); 43 * </ol> 44 * 45 * <p>This particular order of operations may be unrealistic, and testing all 3^5 46 * of them may be thought of as overkill; however, it's difficult to determine 47 * which proper subset of this massive set would be sufficient to expose any 48 * possible bug. Brute force is simpler. 49 * 50 * <p>To use this class the concrete subclass must implement the 51 * {@link IteratorTester#newTargetIterator()} method. This is because it's 52 * impossible to test an Iterator without changing its state, so the tester 53 * needs a steady supply of fresh Iterators. 54 * 55 * <p>If your iterator supports modification through {@code remove()}, you may 56 * wish to override the verify() method, which is called <em>after</em> 57 * each sequence and is guaranteed to be called using the latest values 58 * obtained from {@link IteratorTester#newTargetIterator()}. 59 * 60 * @author Kevin Bourrillion 61 * @author Chris Povirk 62 */ 63 @GwtCompatible 64 public abstract class IteratorTester<E> extends 65 AbstractIteratorTester<E, Iterator<E>> { 66 /** 67 * Creates an IteratorTester. 68 * 69 * @param steps how many operations to test for each tested pair of iterators 70 * @param features the features supported by the iterator 71 */ IteratorTester(int steps, Iterable<? extends IteratorFeature> features, Iterable<E> expectedElements, KnownOrder knownOrder)72 protected IteratorTester(int steps, 73 Iterable<? extends IteratorFeature> features, 74 Iterable<E> expectedElements, KnownOrder knownOrder) { 75 super(steps, Collections.<E>singleton(null), features, expectedElements, 76 knownOrder, 0); 77 } 78 79 @Override getStimulusValues()80 protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { 81 return iteratorStimuli(); 82 } 83 } 84