Should I be exposing Stream on my interface?

Question

If I am writing .NET code I would often expose IEnumerable<T> where-ever it could possibly make sense. Maybe it was down to LINQ and the fact you could use foreach, but it felt "right" to do it.

private List<String> _myList;

public IEnumerable<String> MyList
{
    get { return _myList; }
}

Now I am writing Java 8 code and I am debating whether I should be exposing Stream<T> where possible in the same way? Maybe its because I have to call Collection.stream() and it feels like it is "doing work", but it doesn't feel right?

private Collection<String> myCollection;

public Stream<String> getStuff() {
    return myCollection.stream();
}

Is Stream<T> meant to be exposed on an interface in the same way that IEnumerable<T> might be?

If you return a collection, the caller can stream it... or not. If you return a stream, it does create extra work (as in CPU time) to turn it into a collection. So unless it makes no sense to do anything else than "iterating" over the returned collection once and be done with it, in which case a stream would be just fine, I would return a collection as it gives more flexibility. — assylias, Nov 27 '14 at 22:40
@assylias - I guess the reason I was asking is that I disagree with the fact that you have to call `.stream()` in order to get access to the functional query operators, I think the Stream interface should have been added to Collection, but I guess that isn't the Java way... — Cheetah, Nov 28 '14 at 07:52
Brian Goetz has already posted a pretty thorough answer to a similar question: http://stackoverflow.com/a/24679745/1441122 — Stuart Marks, Nov 29 '14 at 00:47

score 5 · Accepted Answer · answered Nov 28 '14 at 09:39

You are asking the wrong question. After all, it isn’t hard to support both, e.g.

Collection<Foo> getStuff();
default Stream<Foo> stuff() {
    return getStuff().stream();
}

so code using your interface doesn’t need an explicit stream() call, while implementors of the interface don’t need to bother with it as well.

As you are always exposing a Stream support whether via Collection.stream() or explicitly, the question is whether you want to expose the Collection. While it is cheap to provide a Stream for a Collection back-end it might turn out to be expensive to collect a Collection from a Stream.

So an interface exposing both ways suggests that they are equally usable while for an implementation not using a Collection back-end one of these methods might be way more expensive than the other.

So if you are sure that all implementations, including future ones, will always use (or have to support) a Collection it might be useful to expose it though the API as Collections support certain operations which Stream doesn’t. That’s especially true if you support modification of the underlying data via the exposed Collection.

Otherwise, supporting Stream access only might be the better choice. This gives implementations the freedom to have other back-ends than a Collection. However, that also implies that this API does not support Java versions prior to Java 8.

I think the thing that has made it "click" for me is the modification point. I will expose `Stream` - thank you! (I don't support pre-Java 8). (I do understand your point about collecting from a stream) — Cheetah, Nov 28 '14 at 09:51

score 0 · Answer 2 · answered Nov 28 '14 at 04:21

Whether or not you want to be a Stream yourself, primarily depends on whether you're truly a Stream with the corresponding powers, i.e. support parallelization (not all Streams do, but it's one of the many benefits of Streams, and it's an important one). Normally I'd rather be a Collection and let myself be Streamed by the corresponding API calls.

The getStuff() method, returning Stream<String> from myCollection.stream() looks right to me.

score 0 · Answer 3 · answered Jun 28 '19 at 00:09

Avoid Stream where possible in interfaces.

Streams may * be finite or infinite * be sequential or parallel * be ordered or non-ordered * need closing or not

Neither the implementors of an interface nor the clients of the interface can know which of these characteristics should (not) apply or which they need to guard against.

Choosing the most flexible return type in an interface just means that clients have the full burden of guarding against all possibilities. It is generally much more useful in an interface to restrict the returned datatype so that implementors know what assumptions they can rely one (for the same reason returning Collection itself is not very useful in most cases, it is more useful to return List, Set, Iterable, InputStream to indicate rights and duties of clients when consuming the data).

And when you need to change the characteristics of the returned data, change the interface,b break your clients intentionally, so that they can update their algorithms to the changed situation.

That's much more useful than to say: "My method returns a Stream, so now I can return an infinite stream instead of a finite one, and the client code still compiles, how wonderful!". It is not wonderful, it is a horrible source of bugs to do that. Client code should NOT continue to compile with such drastic changes, so using datatypes that are explicit about finity, parallelity, orderedness and duty to close() is a much better choice.

Think like this: If remaining flexible was so great, then all interfaces that in Java7 return List or Set or Queue would be returning Iterable instead, to remain flexible in what datatype to actually return. But this is not what most interfaces do returning a Collection instead tells clients they can safely rely on a size() method, and returning a Set means they can safely rely on non-duplication, as an example. Being specific and restrictive in interfaces is not a sin, it is a virtue.

Should I be exposing Stream on my interface?

3 Answers3

Linked