IteratorTester.java revision 7dd252788645e940eada959bdde927426e2531c9
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 17package com.google.common.collect.testing; 18 19import com.google.common.annotations.GwtCompatible; 20 21import java.util.Collections; 22import 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 * 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 * <p>This class is GWT compatible. 61 * 62 * @author Kevin Bourrillion 63 * @author Chris Povirk 64 */ 65@GwtCompatible 66public abstract class IteratorTester<E> extends 67 AbstractIteratorTester<E, Iterator<E>> { 68 /** 69 * Creates an IteratorTester. 70 * 71 * @param steps how many operations to test for each tested pair of iterators 72 * @param features the features supported by the iterator 73 */ 74 protected IteratorTester(int steps, 75 Iterable<? extends IteratorFeature> features, 76 Iterable<E> expectedElements, KnownOrder knownOrder) { 77 super(steps, Collections.<E>singleton(null), features, expectedElements, 78 knownOrder, 0); 79 } 80 81 @Override 82 protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { 83 return iteratorStimuli(); 84 } 85} 86