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 * <p>The value you pass to the parameter {@code steps} should be greater than the length of your 054 * iterator, so that this class can check that your iterator behaves correctly when it is exhausted. 055 * 056 * <p>For example, to test {@link java.util.Collections#unmodifiableList(java.util.List) 057 * Collections.unmodifiableList}'s iterator: 058 * 059 * <pre>{@code 060 * List<String> expectedElements = 061 * Arrays.asList("a", "b", "c", "d", "e"); 062 * List<String> actualElements = 063 * Collections.unmodifiableList( 064 * Arrays.asList("a", "b", "c", "d", "e")); 065 * IteratorTester<String> iteratorTester = 066 * new IteratorTester<String>( 067 * 6, 068 * IteratorFeature.UNMODIFIABLE, 069 * expectedElements, 070 * IteratorTester.KnownOrder.KNOWN_ORDER) { 071 * @Override 072 * protected Iterator<String> newTargetIterator() { 073 * return actualElements.iterator(); 074 * } 075 * }; 076 * iteratorTester.test(); 077 * iteratorTester.testForEachRemaining(); 078 * }</pre> 079 * 080 * <p><b>Note</b>: It is necessary to use {@code IteratorTester.KnownOrder} as shown above, rather 081 * than {@code KnownOrder} directly, because otherwise the code cannot be compiled. 082 * 083 * @author Kevin Bourrillion 084 * @author Chris Povirk 085 */ 086@GwtCompatible 087public abstract class IteratorTester<E> extends AbstractIteratorTester<E, Iterator<E>> { 088 /** 089 * Creates an IteratorTester. 090 * 091 * @param steps how many operations to test for each tested pair of iterators 092 * @param features the features supported by the iterator 093 */ 094 protected IteratorTester( 095 int steps, 096 Iterable<? extends IteratorFeature> features, 097 Iterable<E> expectedElements, 098 KnownOrder knownOrder) { 099 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}