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