I think these snippets of code show that it's not a trivial task to implement an iterator that satisfies the Java Iterator contract. I don't see why we should require users to do so since we don't mention it in the docs and we illustrate what looks like an implicit contract in section 7.1.1, i.e.
1. The framework calls the CAS Multiplier's process method, passing it an input CAS. The process method returns, but may hold on to a reference to the input CAS. 2. The framework then calls the CAS Multiplier's hasNext method. The CAS Multiplier should return true from this method if it intends to output one or more new CASes (for instance, segments of this CAS), and false if not. 3. If hasNext returned true, the framework will call the CAS Multiplier's next method. The CAS Multiplier creates a new CAS (we will see how in a moment), populates it, and returns it from the hasNext method. 4. Steps 2 and 3 continue until hasNext returns false. Also I don't think Java iterators are allowed to throw exceptions in hasNext and ours do. I don't see how restricting our use of the user's CAS Multiplier iterator to a single hasNext could cause trouble in existing implementations, or violates any contract. We have an implicit (compatibility) contract with Collection Readers since the CPE calls their hasNext only once, so if a user puts their CR in an aggregate and UIMA treats it as a CAS Multiplier, it may not work as expected with the current consecutive hasNext calls. Finally, I may be naive but I can see no technical objection to making the implementation of the CasIterator support a more forgiving and efficient interface to user code, especially since the code changes may be simpler than the documentation changes. - Burn
