RFR: JDK-8161230 - Create java.util.stream.Stream from Iterator / Enumeration

[Patrick Reinhart]

Hi Paul,

I was quit busy lately and this comes a bit late, I guess you do not have less work ;-)

On 15.07.2016 17:10, Paul Sandoz wrote:
>> When I understand you correctly here we should concentrate on the public
>> methods naming firstly? I initially was not sure, what a proper naming
>> for the steams method was. It seem to me reasonable the way Stuart pointed
>> them out on his first comment to name them something like this:
>> 
>> Stream<URL> resources(String name)
>> Stream<URL> systemResources(String name)
>> 
>> 
>> Yes.
I have a first proposal for the new methods and their documentation to start with the discussion about the actual API without the implementation jet:


    /**
     * Finds all the resources with the given name. A resource is some data
     * (images, audio, text, etc) that can be accessed by class code in a way
     * that is independent of the location of the code.
     *
     * Resources in a named module are private to that module. This method does
     * not find resources in named modules.
     *
     * <p>The name of a resource is a <tt>/</tt>-separated path name that
     * identifies the resource.
     *
     * <p> The search order is described in the documentation for {@link
     * #getResource(String)}.  </p>
     *
     * @apiNote When overriding this method it is recommended that an
     * implementation ensures that any delegation is consistent with the {@link
     * #getResource(java.lang.String) getResource(String)} method. This should
     * ensure that the first element returned by the stream is the same 
     * resource that the {@code getResource(String)} method would return.
     *
     * @param  name
     *         The resource name
     *
     * @return  An stream of {@link java.net.URL <tt>URL</tt>} objects for
     *          the resource.  If no resources could  be found, the stream
     *          will be empty.  Resources that the class loader doesn't have
     *          access to will not be in the stream.
     *
     * @throws  IOException
     *          If I/O errors occur
     *
     * @see  #findResources(String)
     *
     * @since  1.9
     */
    public Stream<URL> resources(String name) throws IOException {
        // to be implemented later
    }


    /**
     * Finds all resources of the specified name from the search path used to
     * load classes.  The resources thus found are returned as an
     * {@link java.util.stream.Stream <tt>Stream</tt>} of {@link
     * java.net.URL <tt>URL</tt>} objects.
     *
     * Resources in a named module are private to that module. This method does
     * not find resources in named modules.
     *
     * <p> The search order is described in the documentation for {@link
     * #getSystemResource(String)}.  </p>
     *
     * @param  name
     *         The resource name
     *
     * @return  An stream of resource {@link java.net.URL <tt>URL</tt>}
     *          objects
     *
     * @throws  IOException
     *          If I/O errors occur

     * @since  1.9
     */
    public static Stream<URL> systemResources(String name) throws IOException {
        // to be implemented later
    }


>> Has anyone a better naming suggestion? For me those names would fit so
>> far. If we look into the stream characteristics I would suggest that it
>> has a unknown size and is immutable in both cases. Maybe the entries are
>> also distinct, but there I'm not sure.
>> 
> I would expect the URLs to be distinct, but that might not be consistent with URL.equals i.e. i don’t trust URL handlers :-) therefore i would be wary of including the DISTINCT characteristic.
> 
> Paul.

So, I was right to no be completely sure about the DISTINCT :-) - then I would go for NONNULL and IMMUTABLE characteristics to start with...