java - Iterable 接口(interface)是否有任何关于多次使用的官方契约(Contract)？

Question

从 Java 5 开始，我们有了新的 java.lang.Iterable可以在 foreach 循环中使用的类型:

for (Object element : iterable);

Iterable契约(Contract)未指定其是否iterator()在处理 Iterable 之前可以多次调用方法。即，不清楚以下内容是否适用于所有 Iterables:

for (Object element : iterable);
for (Object element : iterable);

例如，Iterator 包装实现不能使用两次:

public class OneShotIterable<T> implements Iterable<T> {
    private final Iterator<T> it;

    public OneShotIterable(Iterator<T> it) {
        this.it = it;
    }

    @Override
    public Iterator<T> iterator() {
        return it;
    }
}

对于大多数Iterables，这是无关紧要的，因为它们实际上是 retrofit 的Collection API 类型，例如List、Set，它他们的 iterator() 方法已经有了明确定义的契约。

我的问题是:我的 OneShotIterable 实现是否违反了我忽略的某些约定？换句话说，Iterable 的用户会期望它是可重用的吗？如果是这样，Java 5 专家组是否有关于如何处理此类“一次性”Iterables 的“官方”建议(例如，在第二次调用时抛出 IllegalStateException) ？

Answer 1

我可以在标准库中找到的一个先例是 DirectoryStream界面。

它的 Javadoc 包含以下段落(强调他们的):

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.

对我来说，这表明两件事:

• Iterable 上的隐含合约是你应该能够迭代不止一次(甚至可能同时进行!)
• 文档中的粗体 警告以及抛出 IllegalStateException可能是处理您自己的类/接口(interface)中的不合规行为的最佳方式。