When writing the iterator() method in an Iterable<T> then it is important to make sure that each call will result in a fresh Iterator<T> instance containing all the necessary state for keeping track of the iteration. If the iterator is stored in the Iterable<T>, or somehow refers to iteration state stored in the Iterable<T>, then subsequent calls to iterator() can result in loops that only traverse a subset of the elements or have no effect at all.

The following example returns the same iterator on every call, and therefore causes the second loop to terminate immediately without any effect.

This second example returns a newly created iterator each time, but still relies on iteration state stored in the surrounding class, and therefore also causes the second loop to terminate immediately.

The code should instead be written like this, such that each call to iterator() correctly gives a fresh iterator that starts at the beginning.

Java Language Specification: The enhanced for statement.

Java API Specification: Interface Iterable<T>, Interface Iterator<T>, Interface DirectoryStream<T>.