Is there any official contract for the Iterable interface with respect to multiple usage?

One precedent that I could find in the standard library is the DirectoryStream interface.

Its Javadoc contains the following passage (emphasis theirs):

While DirectoryStream extends Iterable, it is not a general-purpose Iterable as it supports only a single Iterator; invoking the iterator method to obtain a second or subsequent iterator throws IllegalStateException.

To me, this suggests two things:

  • The implied contract on Iterable is that you're supposed to be able to iterate more than once (perhaps even concurrently!)
  • A boldface warning in the documentation coupled with throwing IllegalStateException is probably the best way to handle non-compliance in your own classes/interfaces.

Tags:

Java

Iterable