# HG changeset patch
# User joehw
# Date 1386145032 28800
# Node ID 65d2e8e1d666780a783ed4b88ff00de8d789e7cb
# Parent  87b743b2263cc53955266411b7797b365a0fb050
8027973: Error in the documentation for newFactory method of the javax.xml.stream factories
Reviewed-by: alanb, dfuchs, lancea, rriggs

diff -r 87b743b2263c -r 65d2e8e1d666 jaxp/src/javax/xml/stream/FactoryFinder.java
--- a/jaxp/src/javax/xml/stream/FactoryFinder.java	Wed Jul 05 19:24:47 2017 +0200
+++ b/jaxp/src/javax/xml/stream/FactoryFinder.java	Wed Dec 04 00:17:12 2013 -0800
@@ -262,9 +262,7 @@
             }
             if (systemProp != null) {
                 dPrint("found system property, value=" + systemProp);
-                // There's a bug here - because 'cl' is ignored.
-                // This will be handled separately.
-                return newInstance(type, systemProp, null, true);
+                return newInstance(type, systemProp, cl, true);
             }
         }
         catch (SecurityException se) {
@@ -303,9 +301,7 @@
 
             if (factoryClassName != null) {
                 dPrint("found in " + configFile + " value=" + factoryClassName);
-                // There's a bug here - because 'cl' is ignored.
-                // This will be handled separately.
-                return newInstance(type, factoryClassName, null, true);
+                return newInstance(type, factoryClassName, cl, true);
             }
         }
         catch (Exception ex) {
@@ -314,7 +310,7 @@
 
         if (type.getName().equals(factoryId)) {
             // Try Jar Service Provider Mechanism
-            final T provider = findServiceProvider(type);
+            final T provider = findServiceProvider(type, cl);
             if (provider != null) {
                 return provider;
             }
@@ -340,12 +336,18 @@
      *
      * @return instance of provider class if found or null
      */
-    private static <T> T findServiceProvider(final Class<T> type) {
+    private static <T> T findServiceProvider(final Class<T> type, final ClassLoader cl) {
         try {
             return AccessController.doPrivileged(new PrivilegedAction<T>() {
                 @Override
                 public T run() {
-                    final ServiceLoader<T> serviceLoader = ServiceLoader.load(type);
+                    final ServiceLoader<T> serviceLoader;
+                    if (cl == null) {
+                        //the current thread's context class loader
+                        serviceLoader = ServiceLoader.load(type);
+                    } else {
+                        serviceLoader = ServiceLoader.load(type, cl);
+                    }
                     final Iterator<T> iterator = serviceLoader.iterator();
                     if (iterator.hasNext()) {
                         return iterator.next();
diff -r 87b743b2263c -r 65d2e8e1d666 jaxp/src/javax/xml/stream/XMLEventFactory.java
--- a/jaxp/src/javax/xml/stream/XMLEventFactory.java	Wed Jul 05 19:24:47 2017 +0200
+++ b/jaxp/src/javax/xml/stream/XMLEventFactory.java	Wed Dec 04 00:17:12 2013 -0800
@@ -158,9 +158,10 @@
    *   If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
    *   use the service-provider loading facilities, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
-   *   implementation of the service using the {@linkplain
-   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
-   *   the service-provider loading facility will use the {@linkplain
+   *   implementation of the service using the specified {@code ClassLoader}.
+   *   If {@code classLoader} is null, the {@linkplain
+   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
+   *   That is, the service-provider loading facility will use the {@linkplain
    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
    *   to attempt to load the service. If the context class
    *   loader is null, the {@linkplain
@@ -179,6 +180,10 @@
    * to the deprecated method.
    * </p>
    *
+   * @apiNote The parameter factoryId defined here is inconsistent with that
+   * of other JAXP factories where the first parameter is fully qualified
+   * factory class name that provides implementation of the factory.
+   *
    * @param factoryId             Name of the factory to find, same as
    *                              a property name
    * @param classLoader           classLoader to use
diff -r 87b743b2263c -r 65d2e8e1d666 jaxp/src/javax/xml/stream/XMLInputFactory.java
--- a/jaxp/src/javax/xml/stream/XMLInputFactory.java	Wed Jul 05 19:24:47 2017 +0200
+++ b/jaxp/src/javax/xml/stream/XMLInputFactory.java	Wed Dec 04 00:17:12 2013 -0800
@@ -248,9 +248,10 @@
    *   If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
    *   use the service-provider loading facilities, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
-   *   implementation of the service using the {@linkplain
-   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
-   *   the service-provider loading facility will use the {@linkplain
+   *   implementation of the service using the specified {@code ClassLoader}.
+   *   If {@code classLoader} is null, the {@linkplain
+   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
+   *   That is, the service-provider loading facility will use the {@linkplain
    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
    *   to attempt to load the service. If the context class
    *   loader is null, the {@linkplain
@@ -269,6 +270,10 @@
    * to the deprecated method.
    * </p>
    *
+   * @apiNote The parameter factoryId defined here is inconsistent with that
+   * of other JAXP factories where the first parameter is fully qualified
+   * factory class name that provides implementation of the factory.
+   *
    * @param factoryId             Name of the factory to find, same as
    *                              a property name
    * @param classLoader           classLoader to use
diff -r 87b743b2263c -r 65d2e8e1d666 jaxp/src/javax/xml/stream/XMLOutputFactory.java
--- a/jaxp/src/javax/xml/stream/XMLOutputFactory.java	Wed Jul 05 19:24:47 2017 +0200
+++ b/jaxp/src/javax/xml/stream/XMLOutputFactory.java	Wed Dec 04 00:17:12 2013 -0800
@@ -222,9 +222,10 @@
    *   If {@code factoryId} is "javax.xml.stream.XMLOutputFactory",
    *   use the service-provider loading facilities, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an
-   *   implementation of the service using the {@linkplain
-   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
-   *   the service-provider loading facility will use the {@linkplain
+   *   implementation of the service using the specified {@code ClassLoader}.
+   *   If {@code classLoader} is null, the {@linkplain
+   *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
+   *   That is, the service-provider loading facility will use the {@linkplain
    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}
    *   to attempt to load the service. If the context class
    *   loader is null, the {@linkplain
@@ -235,6 +236,10 @@
    * </li>
    * </ul>
    *
+   * @apiNote The parameter factoryId defined here is inconsistent with that
+   * of other JAXP factories where the first parameter is fully qualified
+   * factory class name that provides implementation of the factory.
+   *
    * <p>
    * Note that this is a new method that replaces the deprecated
    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)