001/* 002 * Copyright (C) 2007 The Guava Authors 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package com.google.common.collect.testing; 018 019import com.google.common.annotations.GwtCompatible; 020import java.util.Collections; 021import java.util.Iterator; 022 023/** 024 * A utility for testing an Iterator implementation by comparing its behavior to that of a "known 025 * good" reference implementation. In order to accomplish this, it's important to test a great 026 * variety of sequences of the {@link Iterator#next}, {@link Iterator#hasNext} and {@link 027 * Iterator#remove} operations. This utility takes the brute-force approach of trying <i>all</i> 028 * possible sequences of these operations, up to a given number of steps. So, if the caller 029 * specifies to use <i>n</i> steps, a total of <i>3^n</i> tests are actually performed. 030 * 031 * <p>For instance, if <i>steps</i> is 5, one example sequence that will be tested is: 032 * 033 * <ol> 034 * <li>remove(); 035 * <li>hasNext() 036 * <li>hasNext(); 037 * <li>remove(); 038 * <li>next(); 039 * </ol> 040 * 041 * <p>This particular order of operations may be unrealistic, and testing all 3^5 of them may be 042 * thought of as overkill; however, it's difficult to determine which proper subset of this massive 043 * set would be sufficient to expose any possible bug. Brute force is simpler. 044 * 045 * <p>To use this class the concrete subclass must implement the {@link 046 * IteratorTester#newTargetIterator()} method. This is because it's impossible to test an Iterator 047 * without changing its state, so the tester needs a steady supply of fresh Iterators. 048 * 049 * <p>If your iterator supports modification through {@code remove()}, you may wish to override the 050 * verify() method, which is called <em>after</em> each sequence and is guaranteed to be called 051 * using the latest values obtained from {@link IteratorTester#newTargetIterator()}. 052 * 053 * @author Kevin Bourrillion 054 * @author Chris Povirk 055 */ 056@GwtCompatible 057public abstract class IteratorTester<E> extends AbstractIteratorTester<E, Iterator<E>> { 058 /** 059 * Creates an IteratorTester. 060 * 061 * @param steps how many operations to test for each tested pair of iterators 062 * @param features the features supported by the iterator 063 */ 064 protected IteratorTester( 065 int steps, 066 Iterable<? extends IteratorFeature> features, 067 Iterable<E> expectedElements, 068 KnownOrder knownOrder) { 069 super(steps, Collections.<E>singleton(null), features, expectedElements, knownOrder, 0); 070 } 071 072 @Override 073 protected final Iterable<Stimulus<E, Iterator<E>>> getStimulusValues() { 074 return iteratorStimuli(); 075 } 076}