svn commit: r1065563 - /incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java

[jo...@apache.org]

Author: joern
Date: Mon Jan 31 11:24:54 2011
New Revision: 1065563

URL: http://svn.apache.org/viewvc?rev=1065563&view=rev
Log:
OPENNLP-99 JavaDoc explains now the design decision why ObjectStream does not implement java.util.Iterator. Thanks to Steven Bethard for contribution it.

Modified:
    incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java

Modified: incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java
URL: http://svn.apache.org/viewvc/incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java?rev=1065563&r1=1065562&r2=1065563&view=diff
==============================================================================
--- incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java (original)
+++ incubator/opennlp/trunk/opennlp-tools/src/main/java/opennlp/tools/util/ObjectStream.java Mon Jan 31 11:24:54 2011
@@ -23,6 +23,23 @@ import java.io.ObjectStreamException;
 
 /**
  * Reads <code>Object</code>s from a stream.
+ * <p>
+ * Design Decision:<br>
+ * This interface provides a means for iterating over the
+ * objects in a stream, it does not implement {@link java.util.Iterator} or
+ * {@link Iterable} because:
+ * <ul>
+ * <li>{@link java.util.Iterator#next()} and
+ * {@link java.util.Iterator#hasNext()} are declared as throwing no checked
+ * exceptions. Thus the {@link IOException}s thrown by {@link #read()} would
+ * have to be wrapped in {@link RuntimeException}s, and the compiler would be
+ * unable to force users of this code to catch such exceptions.</li>
+ * <li>Implementing {@link Iterable} would mean either silently calling
+ * {@link #reset()} to guarantee that all items were always seen on each
+ * iteration, or documenting that the Iterable only iterates over the remaining
+ * elements of the ObjectStream. In either case, users not reading the
+ * documentation carefully might run into unexpected behavior.</li>
+ * </ul>
  * 
  * @see ObjectStreamException
  */