Hi.
IterableOnce was kept purposely minimal so that external libraries may easily be interoperable with the standard collection library, but do not depend on its APIs. For some time, I assumed that it also meant that it will be kept binary compatible for much longer than the collection framework itself - after all, it has only two methods which seem unintrusive. However, it returns an Iterator, and the latter extends IterableOnceOps, which has a boat load of methods, and likely doesn’t come with binary compatibility guarantees stronger than the rest of the collection library. A collection implementing IterableOnce therefore has to implement also its own Iterator (unless it is able to just depend on the implementations already provided by the library, which is unlikely if it does not wish to integrate deeper by extending some more specific collection interface). This will make it binary incompatible as soon as IterableOnceOps becomes binary incompatible (I assume here that Iteratoritself won’t break the compatibility, as it was kept purposely minimal.
I am still educating myself on binary compatibility - it is a huge topic, dependent on JVM implementations - but I wonder about the intent of the authors in that matter. It also seems to me that having some GenericIterator extends IterableOnce supertype of Iterator, which defines only next and hasNext, and using it instead of Iterator in IterableOnce would be a good idea to adopt for the collection library in the future, as it would solve this problem with little to no effort and maintainance burden.