From f573ee1917b325703f58e89a7d7a31502cb330ed Mon Sep 17 00:00:00 2001
From: Daniel Fuchs <dfuchs@openjdk.org>
Date: Mon, 14 Oct 2013 10:42:36 +0200
Subject: [PATCH] 8024704: Improve API documentation of ClassLoader and
 ServiceLoader with respect to enumeration of resources

Reviewed-by: alanb, psandoz, mchung
---
 jdk/src/share/classes/java/lang/ClassLoader.java   | 11 +++++++++++
 jdk/src/share/classes/java/util/ServiceLoader.java |  6 ++++++
 2 files changed, 17 insertions(+)

diff --git a/jdk/src/share/classes/java/lang/ClassLoader.java b/jdk/src/share/classes/java/lang/ClassLoader.java
index c3f2aa20458..3fd927482b3 100644
--- a/jdk/src/share/classes/java/lang/ClassLoader.java
+++ b/jdk/src/share/classes/java/lang/ClassLoader.java
@@ -1061,6 +1061,10 @@ public abstract class ClassLoader {
      * 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 @@ public abstract class ClassLoader {
      * <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
      *
diff --git a/jdk/src/share/classes/java/util/ServiceLoader.java b/jdk/src/share/classes/java/util/ServiceLoader.java
index aa5c3008818..f2473a950a2 100644
--- a/jdk/src/share/classes/java/util/ServiceLoader.java
+++ b/jdk/src/share/classes/java/util/ServiceLoader.java
@@ -453,6 +453,12 @@ public final class ServiceLoader<S>
      * 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
      */