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
extendsIterable
, it is not a general-purposeIterable
as it supports only a singleIterator
; invoking theiterator
method to obtain a second or subsequent iterator throwsIllegalStateException
.
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.