關於多次使用，是否有Iterable接口的正式合同？

Question

由於Java 5，我們有新的java.lang.Iterable類型，可以在foreach循環就這樣使用：

for (Object element : iterable); 

的Iterable合同沒有具體的可迭代的處理之前其iterator()方法是否可以調用一次以上。也就是說，目前尚不清楚下面是否可以預期到的所有Iterables工作：

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

例如，一個Iterator包裝實現不能用兩次：

​​

對於大多數Iterables，這是無關緊要，因爲它們實際上是改裝後的Collection API類型，例如List,Set，它們已經爲其iterator()方法定義了明確的合同。

我的問題是：我的OneShotIterable實施違反了一些我忽略的合同嗎？換句話說，Iterable的用戶會期望它是可重用的嗎？如果有，是否有Java 5專家組的「官方」建議如何處理這種「一次性」Iterables（例如，在第二次調用時拋出IllegalStateException）？

Answer 1

我可以在標準庫中找到的一個先例是DirectoryStream接口。

及其Javadoc中包含以下通路（強調他們的）：

雖然DirectoryStream延伸Iterable，它不是一個通用的Iterable，因爲它僅支持單個Iterator;調用iterator方法來獲取第二個或後續的迭代器拋出IllegalStateException。

對我來說，這意味着兩兩件事：（！甚至兼）

• 上Iterable隱含契約是你應該能夠重複多次
• 一黑體字文檔中的警告以及拋出IllegalStateException可能是處理您自己的類/接口中的不合規性的最佳方式。

Answer 2

不是一個真正的回答我的問題，但是Apache Commons Collections中已經在其IteratorUtils類解決了這個問題：

• IteratorUtils.asIterable(Iterator)
• IteratorUtils.asMultipleUseIterable(Iterator)

兩者都是爲IteratorIterable類型的工廠方法。上述區別表明，在包裝Iterables時必須注意。