Java > Open Source Codes > org > apache > commons > collections > list > AbstractTestList


1 /*
2  * Copyright 2001-2004 The Apache Software Foundation
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 package org.apache.commons.collections.list;
17
18 import java.io.IOException ;
19 import java.io.Serializable ;
20 import java.lang.reflect.InvocationTargetException ;
21 import java.lang.reflect.Method ;
22 import java.util.AbstractCollection ;
23 import java.util.ArrayList ;
24 import java.util.Arrays ;
25 import java.util.Collection ;
26 import java.util.Collections ;
27 import java.util.ConcurrentModificationException ;
28 import java.util.Iterator ;
29 import java.util.List ;
30 import java.util.ListIterator ;
31 import java.util.NoSuchElementException ;
32
33 import org.apache.commons.collections.BulkTest;
34 import org.apache.commons.collections.collection.AbstractTestCollection;
35 import org.apache.commons.collections.iterators.AbstractTestListIterator;
36
37 /**
38  * Abstract test class for {@link java.util.List} methods and contracts.
39  * <p>
40  * To use, simply extend this class, and implement
41  * the {@link #makeEmptyList} method.
42  * <p>
43  * If your {@link List} fails one of these tests by design,
44  * you may still use this base set of cases. Simply override the
45  * test case (method) your {@link List} fails or override one of the
46  * protected methods from AbstractTestCollection.
47  *
48  * @version $Revision: 1.9 $ $Date: 2004/05/31 22:39:20 $
49  *
50  * @author Rodney Waldhoff
51  * @author Paul Jack
52  * @author Stephen Colebourne
53  * @author Neil O'Toole
54  */
55 public abstract class AbstractTestList extends AbstractTestCollection {
56
57     /**
58      * JUnit constructor.
59      *
60      * @param testName the test class name
61      */
62     public AbstractTestList(String testName) {
63         super(testName);
64     }
65
66     //-----------------------------------------------------------------------
67 /**
68      * Returns true if the collections produced by
69      * {@link #makeCollection()} and {@link #makeFullCollection()}
70      * support the <code>set operation.<p>
71      * Default implementation returns true. Override if your collection
72      * class does not support set.
73      */
74     public boolean isSetSupported() {
75         return true;
76     }
77
78     //-----------------------------------------------------------------------
79 /**
80      * Verifies that the test list implementation matches the confirmed list
81      * implementation.
82      */
83     public void verify() {
84         super.verify();
85
86         List list1 = getList();
87         List list2 = getConfirmedList();
88
89         assertEquals("List should equal confirmed", list1, list2);
90         assertEquals("Confirmed should equal list", list2, list1);
91
92         assertEquals("Hash codes should be equal", list1.hashCode(), list2.hashCode());
93
94         int i = 0;
95         Iterator iterator1 = list1.iterator();
96         Iterator iterator2 = list2.iterator();
97         Object [] array = list1.toArray();
98         while (iterator2.hasNext()) {
99             assertTrue("List iterator should have next", iterator1.hasNext());
100             Object o1 = iterator1.next();
101             Object o2 = iterator2.next();
102             assertEquals("Iterator elements should be equal", o1, o2);
103             o2 = list1.get(i);
104             assertEquals("get should return correct element", o1, o2);
105             o2 = array[i];
106             assertEquals("toArray should have correct element", o1, o2);
107             i++;
108         }
109     }
110
111     //-----------------------------------------------------------------------
112 /**
113      * List equals method is defined.
114      */
115     public boolean isEqualsCheckable() {
116         return true;
117     }
118
119     /**
120      * Returns an empty {@link ArrayList}.
121      */
122     public Collection makeConfirmedCollection() {
123         ArrayList list = new ArrayList ();
124         return list;
125     }
126
127     /**
128      * Returns a full {@link ArrayList}.
129      */
130     public Collection makeConfirmedFullCollection() {
131         ArrayList list = new ArrayList ();
132         list.addAll(Arrays.asList(getFullElements()));
133         return list;
134     }
135
136     /**
137      * Return a new, empty {@link List} to be used for testing.
138      *
139      * @return an empty list for testing.
140      */
141     public abstract List makeEmptyList();
142
143     /**
144      * Return a new, full {@link List} to be used for testing.
145      *
146      * @return a full list for testing
147      */
148     public List makeFullList() {
149         // only works if list supports optional "addAll(Collection)"
150 List list = makeEmptyList();
151         list.addAll(Arrays.asList(getFullElements()));
152         return list;
153     }
154
155     /**
156      * Returns {@link #makeEmptyList()}.
157      *
158      * @return an empty list to be used for testing
159      */
160     public final Collection makeCollection() {
161         return makeEmptyList();
162     }
163
164     /**
165      * Returns {@link #makeFullList()}.
166      *
167      * @return a full list to be used for testing
168      */
169     public final Collection makeFullCollection() {
170         return makeFullList();
171     }
172
173     //-----------------------------------------------------------------------
174 /**
175      * Returns the {@link #collection} field cast to a {@link List}.
176      *
177      * @return the collection field as a List
178      */
179     public List getList() {
180         return (List ) collection;
181     }
182
183     /**
184      * Returns the {@link #confirmed} field cast to a {@link List}.
185      *
186      * @return the confirmed field as a List
187      */
188     public List getConfirmedList() {
189         return (List ) confirmed;
190     }
191
192     //-----------------------------------------------------------------------
193 /**
194      * Tests bounds checking for {@link List#add(int, Object)} on an
195      * empty list.
196      */
197     public void testListAddByIndexBoundsChecking() {
198         if (!isAddSupported()) {
199             return;
200         }
201
202         List list;
203         Object element = getOtherElements()[0];
204
205         try {
206             list = makeEmptyList();
207             list.add(Integer.MIN_VALUE, element);
208             fail("List.add should throw IndexOutOfBoundsException [Integer.MIN_VALUE]");
209         } catch (IndexOutOfBoundsException e) {
210             // expected
211 }
212
213         try {
214             list = makeEmptyList();
215             list.add(-1, element);
216             fail("List.add should throw IndexOutOfBoundsException [-1]");
217         } catch (IndexOutOfBoundsException e) {
218             // expected
219 }
220
221         try {
222             list = makeEmptyList();
223             list.add(1, element);
224             fail("List.add should throw IndexOutOfBoundsException [1]");
225         } catch (IndexOutOfBoundsException e) {
226             // expected
227 }
228
229         try {
230             list = makeEmptyList();
231             list.add(Integer.MAX_VALUE, element);
232             fail("List.add should throw IndexOutOfBoundsException [Integer.MAX_VALUE]");
233         } catch (IndexOutOfBoundsException e) {
234             // expected
235 }
236     }
237
238     /**
239      * Tests bounds checking for {@link List#add(int, Object)} on a
240      * full list.
241      */
242     public void testListAddByIndexBoundsChecking2() {
243         if (!isAddSupported()) {
244             return;
245         }
246
247         List list;
248         Object element = getOtherElements()[0];
249
250         try {
251             list = makeFullList();
252             list.add(Integer.MIN_VALUE, element);
253             fail("List.add should throw IndexOutOfBoundsException [Integer.MIN_VALUE]");
254         } catch (IndexOutOfBoundsException e) {
255             // expected
256 }
257
258         try {
259             list = makeFullList();
260             list.add(-1, element);
261             fail("List.add should throw IndexOutOfBoundsException [-1]");
262         } catch (IndexOutOfBoundsException e) {
263             // expected
264 }
265
266         try {
267             list = makeFullList();
268             list.add(list.size() + 1, element);
269             fail("List.add should throw IndexOutOfBoundsException [size + 1]");
270         } catch (IndexOutOfBoundsException e) {
271             // expected
272 }
273
274         try {
275             list = makeFullList();
276             list.add(Integer.MAX_VALUE, element);
277             fail("List.add should throw IndexOutOfBoundsException [Integer.MAX_VALUE]");
278         } catch (IndexOutOfBoundsException e) {
279             // expected
280 }
281     }
282
283     /**
284      * Tests {@link List#add(int,Object)}.
285      */
286     public void testListAddByIndex() {
287         if (!isAddSupported()) {
288             return;
289         }
290
291         Object element = getOtherElements()[0];
292         int max = getFullElements().length;
293
294         for (int i = 0; i <= max; i++) {
295             resetFull();
296             ((List ) collection).add(i, element);
297             ((List ) confirmed).add(i, element);
298             verify();
299         }
300     }
301
302     /**
303      * Tests {@link List#equals(Object)}.
304      */
305     public void testListEquals() {
306         resetEmpty();
307         List list = getList();
308         assertEquals("Empty lists should be equal", true, list.equals(confirmed));
309         verify();
310         assertEquals("Empty list should equal self", true, list.equals(list));
311         verify();
312
313         List list2 = Arrays.asList(getFullElements());
314         assertEquals("Empty list shouldn't equal full", false, list.equals(list2));
315         verify();
316
317         list2 = Arrays.asList(getOtherElements());
318         assertEquals("Empty list shouldn't equal other", false, list.equals(list2));
319         verify();
320
321         resetFull();
322         list = getList();
323         assertEquals("Full lists should be equal", true, list.equals(confirmed));
324         verify();
325         assertEquals("Full list should equal self", true, list.equals(list));
326         verify();
327
328         list2 = makeEmptyList();
329         assertEquals("Full list shouldn't equal empty", false, list.equals(list2));
330         verify();
331
332         list2 = Arrays.asList(getOtherElements());
333         assertEquals("Full list shouldn't equal other", false, list.equals(list2));
334         verify();
335
336         list2 = Arrays.asList(getFullElements());
337         if (list2.size() < 2 && isAddSupported()) {
338             // main list is only size 1, so lets add other elements to get a better list
339 list.addAll(Arrays.asList(getOtherElements()));
340             confirmed.addAll(Arrays.asList(getOtherElements()));
341             list2 = new ArrayList (list2);
342             list2.addAll(Arrays.asList(getOtherElements()));
343         }
344         if (list2.size() > 1) {
345             Collections.reverse(list2);
346             assertEquals(
347                 "Full list shouldn't equal full list with same elements but different order",
348                 false, list.equals(list2));
349             verify();
350         }
351
352         resetFull();
353         list = getList();
354         assertEquals("List shouldn't equal String", false, list.equals(""));
355         verify();
356
357         final List listForC = Arrays.asList(getFullElements());
358         Collection c = new AbstractCollection () {
359             public int size() {
360                 return listForC.size();
361             }
362
363             public Iterator iterator() {
364                 return listForC.iterator();
365             }
366         };
367
368         assertEquals("List shouldn't equal nonlist with same elements in same order", false, list.equals(c));
369         verify();
370     }
371
372     /**
373      * Tests {@link List#hashCode()}.
374      */
375     public void testListHashCode() {
376         resetEmpty();
377         int hash1 = collection.hashCode();
378         int hash2 = confirmed.hashCode();
379         assertEquals("Empty lists should have equal hashCodes", hash1, hash2);
380         verify();
381
382         resetFull();
383         hash1 = collection.hashCode();
384         hash2 = confirmed.hashCode();
385         assertEquals("Full lists should have equal hashCodes", hash1, hash2);
386         verify();
387     }
388
389     /**
390      * Tests {@link List#get(int)}.
391      */
392     public void testListGetByIndex() {
393         resetFull();
394         List list = getList();
395         Object [] elements = getFullElements();
396         for (int i = 0; i < elements.length; i++) {
397             assertEquals("List should contain correct elements", elements[i], list.get(i));
398             verify();
399         }
400     }
401
402     /**
403      * Tests bounds checking for {@link List#get(int)} on an
404      * empty list.
405      */
406     public void testListGetByIndexBoundsChecking() {
407         List list = makeEmptyList();
408
409         try {
410             list.get(Integer.MIN_VALUE);
411             fail("List.get should throw IndexOutOfBoundsException [Integer.MIN_VALUE]");
412         } catch (IndexOutOfBoundsException e) {
413             // expected
414 }
415
416         try {
417             list.get(-1);
418             fail("List.get should throw IndexOutOfBoundsException [-1]");
419         } catch (IndexOutOfBoundsException e) {
420             // expected
421 }
422
423         try {
424             list.get(0);
425             fail("List.get should throw IndexOutOfBoundsException [0]");
426         } catch (IndexOutOfBoundsException e) {
427             // expected
428 }
429
430         try {
431             list.get(1);
432             fail("List.get should throw IndexOutOfBoundsException [1]");
433         } catch (IndexOutOfBoundsException e) {
434             // expected
435 }
436
437         try {
438             list.get(Integer.MAX_VALUE);
439             fail("List.get should throw IndexOutOfBoundsException [Integer.MAX_VALUE]");
440         } catch (IndexOutOfBoundsException e) {
441             // expected
442 }
443     }
444
445     /**
446      * Tests bounds checking for {@link List#get(int)} on a
447      * full list.
448      */
449     public void testListGetByIndexBoundsChecking2() {
450         List list = makeFullList();
451
452         try {
453             list.get(Integer.MIN_VALUE);
454             fail("List.get should throw IndexOutOfBoundsException [Integer.MIN_VALUE]");
455         } catch (IndexOutOfBoundsException e) {
456             // expected
457 }
458
459         try {
460             list.get(-1);
461             fail("List.get should throw IndexOutOfBoundsException [-1]");
462         } catch (IndexOutOfBoundsException e) {
463             // expected
464 }
465
466         try {
467             list.get(getFullElements().length);
468             fail("List.get should throw IndexOutOfBoundsException [size]");
469         } catch (IndexOutOfBoundsException e) {
470             // expected
471 }
472
473         try {
474             list.get(Integer.MAX_VALUE);
475             fail("List.get should throw IndexOutOfBoundsException [Integer.MAX_VALUE]");
476         } catch (IndexOutOfBoundsException e) {
477             // expected
478 }
479     }
480
481     /**
482      * Tests {@link List#indexOf}.
483      */
484     public void testListIndexOf() {
485         resetFull();
486         List list1 = getList();
487         List list2 = getConfirmedList();
488
489         Iterator iterator = list2.iterator();
490         while (iterator.hasNext()) {
491             Object element = iterator.next();
492             assertEquals("indexOf should return correct result",
493                 list1.indexOf(element), list2.indexOf(element));
494             verify();
495         }
496
497         Object [] other = getOtherElements();
498         for (int i = 0; i < other.length; i++) {
499             assertEquals("indexOf should return -1 for nonexistent element",
500                 list1.indexOf(other[i]), -1);
501             verify();
502         }
503     }
504
505     /**
506      * Tests {@link List#lastIndexOf}.
507      */
508     public void testListLastIndexOf() {
509         resetFull();
510         List list1 = getList();
511         List list2 = getConfirmedList();
512
513         Iterator iterator = list2.iterator();
514         while (iterator.hasNext()) {
515             Object element = iterator.next();
516             assertEquals("lastIndexOf should return correct result",
517               list1.lastIndexOf(element), list2.lastIndexOf(element));
518             verify();
519         }
520
521         Object [] other = getOtherElements();
522         for (int i = 0; i < other.length; i++) {
523             assertEquals("lastIndexOf should return -1 for nonexistent " +
524               "element", list1.lastIndexOf(other[i]), -1);
525             verify();
526         }
527     }
528
529     /**
530      * Tests bounds checking for {@link List#set(int,Object)} on an
531      * empty list.
532      */
533     public void testListSetByIndexBoundsChecking() {
534         if (!isSetSupported()) {
535             return;
536         }
537
538         List list = makeEmptyList();
539         Object element = getOtherElements()[0];
540
541         try {
542             list.set(Integer.MIN_VALUE, element);
543             fail("List.set should throw IndexOutOfBoundsException [Integer.MIN_VALUE]");
544         } catch (IndexOutOfBoundsException e) {
545             // expected
546 }
547
548         try {
549             list.set(-1, element);
550             fail("List.set should throw IndexOutOfBoundsException [-1]");
551         } catch (IndexOutOfBoundsException e) {
552             // expected
553 }
554
555         try {
556             list.set(0, element);
557             fail("List.set should throw IndexOutOfBoundsException [0]");
558         } catch (IndexOutOfBoundsException e) {
559             // expected
560 }
561
562         try {
563             list.set(1, element);
564             fail("List.set should throw IndexOutOfBoundsException [1]");
565         } catch (IndexOutOfBoundsException e) {
566             // expected
567 }
568
569         try {
570             list.set(Integer.MAX_VALUE, element);
571             fail("List.set should throw IndexOutOfBoundsException [Integer.MAX_VALUE]");
572         } catch (IndexOutOfBoundsException e) {
573             // expected
574 }
575     }
576
577
578     /**
579      * Tests bounds checking for {@link List#set(int,Object)} on a
580      * full list.
581      */
582     public void testListSetByIndexBoundsChecking2() {
583         if (!isSetSupported()) return;
584
585         List list = makeFullList();
586         Object element = getOtherElements()[0];
587
588         try {
589             list.set(Integer.MIN_VALUE, element);
590             fail("List.set should throw IndexOutOfBoundsException " +
591               "[Integer.MIN_VALUE]");
592         } catch(IndexOutOfBoundsException e) {
593             // expected
594 }
595
596         try {
597             list.set(-1, element);
598             fail("List.set should throw IndexOutOfBoundsException [-1]");
599         } catch(IndexOutOfBoundsException e) {
600             // expected
601 }
602
603         try {
604             list.set(getFullElements().length, element);
605             fail("List.set should throw IndexOutOfBoundsException [size]");
606         } catch(IndexOutOfBoundsException e) {
607             // expected
608 }
609
610         try {
611             list.set(Integer.MAX_VALUE, element);
612             fail("List.set should throw IndexOutOfBoundsException " +
613               "[Integer.MAX_VALUE]");
614         } catch(IndexOutOfBoundsException e) {
615             // expected
616 }
617     }
618
619
620     /**
621      * Test {@link List#set(int,Object)}.
622      */
623     public void testListSetByIndex() {
624         if (!isSetSupported()) return;
625
626         resetFull();
627         Object [] elements = getFullElements();
628         Object [] other = getOtherElements();
629
630         for (int i = 0; i < elements.length; i++) {
631             Object n = other[i % other.length];
632             Object v = ((List )collection).set(i, n);
633             assertEquals("Set should return correct element", elements[i], v);
634             ((List )confirmed).set(i, n);
635             verify();
636         }
637     }
638
639
640     /**
641      * If {@link #isSetSupported()} returns false, tests that set operation
642      * raises <Code>UnsupportedOperationException.
643      */
644     public void testUnsupportedSet() {
645         if (isSetSupported()) return;
646         
647         resetFull();
648         try {
649             ((List ) collection).set(0, new Object ());
650             fail("Emtpy collection should not support set.");
651         } catch (UnsupportedOperationException e) {
652             // expected
653 }
654         // make sure things didn't change even if the expected exception was
655 // thrown.
656 verify();
657     }
658     
659
660     /**
661      * Tests bounds checking for {@link List#remove(int)} on an
662      * empty list.
663      */
664     public void testListRemoveByIndexBoundsChecking() {
665         if (!isRemoveSupported()) return;
666
667         List list = makeEmptyList();
668
669         try {
670             list.remove(Integer.MIN_VALUE);
671             fail("List.remove should throw IndexOutOfBoundsException " +
672               "[Integer.MIN_VALUE]");
673         } catch(IndexOutOfBoundsException e) {
674             // expected
675 }
676
677         try {
678             list.remove(-1);
679             fail("List.remove should throw IndexOutOfBoundsException [-1]");
680         } catch(IndexOutOfBoundsException e) {
681             // expected
682 }
683
684         try {
685             list.remove(0);
686             fail("List.remove should throw IndexOutOfBoundsException [0]");
687         } catch(IndexOutOfBoundsException e) {
688             // expected
689 }
690
691         try {
692             list.remove(1);
693             fail("List.remove should throw IndexOutOfBoundsException [1]");
694         } catch(IndexOutOfBoundsException e) {
695             // expected
696 }
697
698         try {
699             list.remove(Integer.MAX_VALUE);
700             fail("List.remove should throw IndexOutOfBoundsException " +
701               "[Integer.MAX_VALUE]");
702         } catch(IndexOutOfBoundsException e) {
703             // expected
704 }
705     }
706
707
708     /**
709      * Tests bounds checking for {@link List#remove(int)} on a
710      * full list.
711      */
712     public void testListRemoveByIndexBoundsChecking2() {
713         if (!isRemoveSupported()) return;
714
715         List list = makeFullList();
716
717         try {
718             list.remove(Integer.MIN_VALUE);
719             fail("List.remove should throw IndexOutOfBoundsException " +
720               "[Integer.MIN_VALUE]");
721         } catch(IndexOutOfBoundsException e) {
722             // expected
723 }
724
725         try {
726             list.remove(-1);
727             fail("List.remove should throw IndexOutOfBoundsException [-1]");
728         } catch(IndexOutOfBoundsException e) {
729             // expected
730 }
731
732         try {
733             list.remove(getFullElements().length);
734             fail("List.remove should throw IndexOutOfBoundsException [size]");
735         } catch(IndexOutOfBoundsException e) {
736             // expected
737 }
738
739         try {
740             list.remove(Integer.MAX_VALUE);
741             fail("List.remove should throw IndexOutOfBoundsException " +
742               "[Integer.MAX_VALUE]");
743         } catch(IndexOutOfBoundsException e) {
744             // expected
745 }
746     }
747
748
749     /**
750      * Tests {@link List#remove(int)}.
751      */
752     public void testListRemoveByIndex() {
753         if (!isRemoveSupported()) return;
754
755         int max = getFullElements().length;
756         for (int i = 0; i < max; i++) {
757             resetFull();
758             Object o1 = ((List )collection).remove(i);
759             Object o2 = ((List )confirmed).remove(i);
760             assertEquals("remove should return correct element", o1, o2);
761             verify();
762         }
763     }
764
765
766     /**
767      * Tests the read-only bits of {@link List#listIterator()}.
768      */
769     public void testListListIterator() {
770         resetFull();
771         forwardTest(getList().listIterator(), 0);
772         backwardTest(getList().listIterator(), 0);
773     }
774
775
776     /**
777      * Tests the read-only bits of {@link List#listIterator(int)}.
778      */
779     public void testListListIteratorByIndex() {
780         resetFull();
781         try {
782             getList().listIterator(-1);
783         } catch (IndexOutOfBoundsException ex) {}
784         resetFull();
785         try {
786             getList().listIterator(getList().size() + 1);
787         } catch (IndexOutOfBoundsException ex) {}
788         resetFull();
789         for (int i = 0; i <= confirmed.size(); i++) {
790             forwardTest(getList().listIterator(i), i);
791             backwardTest(getList().listIterator(i), i);
792         }
793         resetFull();
794         for (int i = 0; i <= confirmed.size(); i++) {
795             backwardTest(getList().listIterator(i), i);
796         }
797     }
798
799     /**
800      * Tests remove on list iterator is correct.
801      */
802     public void testListListIteratorPreviousRemove() {
803         if (isRemoveSupported() == false) return;
804         resetFull();
805         ListIterator it = getList().listIterator();
806         Object zero = it.next();
807         Object one = it.next();
808         Object two = it.next();
809         Object two2 = it.previous();
810         Object one2 = it.previous();
811         assertSame(one, one2);
812         assertSame(two, two2);
813         assertSame(zero, getList().get(0));
814         assertSame(one, getList().get(1));
815         assertSame(two, getList().get(2));
816         it.remove();
817         assertSame(zero, getList().get(0));
818         assertSame(two, getList().get(1));
819     }
820
821     /**
822      * Traverses to the end of the given iterator.
823      *
824      * @param iter the iterator to traverse
825      * @param i the starting index
826      */
827     private void forwardTest(ListIterator iter, int i) {
828         List list = getList();
829         int max = getFullElements().length;
830
831         while (i < max) {
832             assertTrue("Iterator should have next", iter.hasNext());
833             assertEquals("Iterator.nextIndex should work",
834               iter.nextIndex(), i);
835             assertEquals("Iterator.previousIndex should work",
836               iter.previousIndex(), i - 1);
837             Object o = iter.next();
838             assertEquals("Iterator returned correct element", list.get(i), o);
839             i++;
840         }
841
842         assertTrue("Iterator shouldn't have next", !iter.hasNext());
843         assertEquals("nextIndex should be size", iter.nextIndex(), max);
844         assertEquals("previousIndex should be size - 1",
845           iter.previousIndex(), max - 1);
846
847         try {
848             iter.next();
849             fail("Exhausted iterator should raise NoSuchElement");
850         } catch (NoSuchElementException e) {
851             // expected
852 }
853     }
854
855
856     /**
857      * Traverses to the beginning of the given iterator.
858      *
859      * @param iter the iterator to traverse
860  &