8207690: Parsing API for classpath and similar path strings

[Alan Bateman]

On 11/09/2018 17:04, Stephen Colebourne wrote:
> :
> This is a broader question for new methods in the JDK, not just this
> one. I don't think anyone has come up with a "style guide" for when to
> use Stream returning as opposed to list-returning methods.
>
> What I can say is that I think List is the better fit here, because:
> - the result is not large
> - the result may well be stored somewhere (method should guarantee
> result is immutable)
> - a List is simpler conceptually than Stream as a result type (eg.
> serial vs parallel)
>
> Personally, I only tend to return Stream if I the particular method is
> returning a very large data set.
>
There are several discussion points around this aspect of API design. 
One of the most important questions to ask is whether a stream or 
collection is more useful to the caller. For the API under discussion 
then we have several examples in the JDK that process the class path or 
module path. One example involves mapping the elements of the class path 
to file URLs and into an array to create a URLClassLoader. Another maps 
the elements to Path objects and into an array to create a ModuleFinder. 
Another maps the elements to Path objects and performs an action on each 
element. Stuart brings up the empty path case which, depending on 
context, may need to be filtered. The examples so far iterate over the 
elements once and an intermediate/cached collection isn't needed. On the 
other hand, I think Roger's main use-case is representing the value of 
the java.class.path property as a List<Path> which will may involve 
caching an unmodifiable list.

-Alan