src/javax/xml/xpath/XPathFactory.java

@@ -43,10 +43,11 @@
  * even from the same thread.
  *
  * @author  <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
  * @author  <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
  *
+ * @version $Revision: 1.7 $, $Date: 2010-11-01 04:36:14 $
  * @since 1.5
  */
 public abstract class XPathFactory {
 
 

@@ -119,18 +120,24 @@
     *   <li>
     *     ${java.home}/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for.
     *     If present, the value is processed just like above.
     *   </li>
     *   <li>
-    *     The class loader is asked for service provider provider-configuration files matching <code>javax.xml.xpath.XPathFactory</code>
-    *     in the resource directory META-INF/services.
-    *     See the JAR File Specification for file format and parsing rules.
+    *     Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt 
+    *     to locate and load an implementation of the service. 
     *     Each potential service provider is required to implement the method:
     *     <pre>
     *       {@link #isObjectModelSupported(String objectModel)}
     *     </pre>
-    *     The first service provider found in class loader order that supports the specified object model is returned.
+    *      A service provider is deemed as valid if it supports the specified object model.
+    *  
+    *  <p>In case of multiple providers, the first non-default implementation shall be 
+    *  instantiated and returned.  The default implementation is returned if it is 
+    *  the only one found by the service loader.</p>
+    *  <p>
+    *  If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, 
+    *  the error will be wrapped in a {@link javax.xml.xpath.XPathFactoryConfigurationException}.</p>
     *   </li>
     *   <li>
     *     Platform default <code>XPathFactory</code> is located in a platform specific way.
     *     There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}.
     *   </li>

@@ -150,11 +157,12 @@
     *   <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM,
     *   the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
     *
     * @return Instance of an <code>XPathFactory</code>.
     *
-    * @throws XPathFactoryConfigurationException If the specified object model is unavailable.
+    * @throws XPathFactoryConfigurationException If the specified object model is unavailable, or
+    *                   if a misconfigured provider is encountered
     * @throws NullPointerException If <code>uri</code> is <code>null</code>.
         * @throws IllegalArgumentException If <code>uri</code> is <code>null</code>
     *   or <code>uri.length() == 0</code>.
     */
     public static final XPathFactory newInstance(final String uri)