Pure generators: stream bindings

[Aleksey Shipilev]

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? If so, what is expected behavior for
multiple Stream.iterator() calls? Should it prohibit returning new
iterator (odd) after first one is being served? Should it return the
same iterator over and over again(odd)? Should it return new iterator,
but bind to the Stream state (dirty, but ok)?

2. The connection between StreamAccessor.into() and
StreamAccessor.iterator(). In the Stream case, should we allow into()
after single iterator() is called? If so, should we synchronize
"iterator" and "into" positions? 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? Acquiring spliterator after iterator is
prohibited in JavaDoc at the moment. What about vice versa?

4. The connection between StreamAccessor.iterator() and
spliterator().iterator(). 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)?

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". The candidates which are important to
implement for performance testing are:
 - {Int,Long}Stream: emits the integer numbers in [$from, $to)
 - DoubleStream: emits the real numbers in [$from, $to) with $step


Thanks,
Aleksey.