Pure generators: stream bindings

[Mike Duigou]

On Sep 14 2012, at 08:39 , Aleksey Shipilev wrote:

> Hi guys,
> 
> I'm trying to figure the way to construct my own generator which will
> produce the stream of scalar values. There is lack of the documentation
> for the expected behavior of Streams. Some of the behavior can be
> inferred from the common sense, but I will still ask for guidance here.
> 
> 1. Are Streams traversable once?

Only once.

> If so, what is expected behavior for
> multiple Stream.iterator() calls?

It will return the same iterator instance. (Much like Socket.getInputStream())

> Should it prohibit returning new
> iterator (odd) after first one is being served?

Yes.

> Should it return the
> same iterator over and over again(odd)?

Yes, and not actually too odd.

> Should it return new iterator,
> but bind to the Stream state (dirty, but ok)?

This is possible but probably wasteful.

> 
> 2. The connection between StreamAccessor.into() and
> StreamAccessor.iterator(). In the Stream case, should we allow into()
> after single iterator() is called?

Yes. The idea is that the iterator can be used to peel off some elements before sink() is called.

> If so, should we synchronize
> "iterator" and "into" positions?

Yes. There should be only one "traversal state" per stream.

> If not, what is the exceptional
> contract for into()? Throwing ISE?
> 
> 3. The connection between StreamAccessor.iterator() and
> StreamAccessor.spliterator(). Are we allowing getting the iterator once
> we requested spliterator?

No. This should be an ISE.

> Acquiring spliterator after iterator is
> prohibited in JavaDoc at the moment. What about vice versa?

Also illegal.

> 
> 4. The connection between StreamAccessor.iterator() and
> spliterator().iterator().

StreamAccessor.iterator() is illegal after StreamAccessor.spliterator() so only the Spliterator.iterator() is valid.

> Considering we are allowed to get the iterator
> and spliterator at the same time (3), does it extend to spliterator's
> iterator? Do we need to update their states at the same time (e.g.
> next() in one iterator should make the element in question unavailable
> in another iterator)?

Should be an ISE to attempt to use both.

> 
> The lesson I learned from this is, there is for having a couple of
> standard generators in order to highlight these issues, and also to
> comply with the "rule of three".

Thank you for pointing out some of the documentation holes. I've made a few improvements to the docs in this area recently but this feedback gives us good indication of what the most confusing/poorly described points are.

Mike