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...
