changeset 8377:9f8bfdd99129

8024704: Improve API documentation of ClassLoader and ServiceLoader with respect to enumeration of resources. Reviewed-by: alanb, psandoz, mchung
author dfuchs
date Mon, 14 Oct 2013 10:42:36 +0200
parents fb202a8e83c9
children 077237e4613f
files src/share/classes/java/lang/ClassLoader.java src/share/classes/java/util/ServiceLoader.java
diffstat 2 files changed, 17 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/lang/ClassLoader.java	Sun Oct 13 21:10:33 2013 -0700
+++ b/src/share/classes/java/lang/ClassLoader.java	Mon Oct 14 10:42:36 2013 +0200
@@ -1061,6 +1061,10 @@
      * built-in to the virtual machine is searched.  That failing, this method
      * will invoke {@link #findResource(String)} to find the resource.  </p>
      *
+     * @apiNote When overriding this method it is recommended that an
+     * implementation ensures that any delegation is consistent with the {@link
+     * #getResources(java.lang.String) getResources(String)} method.
+     *
      * @param  name
      *         The resource name
      *
@@ -1094,6 +1098,13 @@
      * <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 Enumeration's
+     * {@code nextElement} method is the same resource that the
+     * {@code getResource(String)} method would return.
+     *
      * @param  name
      *         The resource name
      *
--- a/src/share/classes/java/util/ServiceLoader.java	Sun Oct 13 21:10:33 2013 -0700
+++ b/src/share/classes/java/util/ServiceLoader.java	Mon Oct 14 10:42:36 2013 +0200
@@ -453,6 +453,12 @@
      * Invoking its {@link java.util.Iterator#remove() remove} method will
      * cause an {@link UnsupportedOperationException} to be thrown.
      *
+     * @implNote When adding providers to the cache, the {@link #iterator
+     * Iterator} processes resources in the order that the {@link
+     * java.lang.ClassLoader#getResources(java.lang.String)
+     * ClassLoader.getResources(String)} method finds the service configuration
+     * files.
+     *
      * @return  An iterator that lazily loads providers for this loader's
      *          service
      */