changeset 704:cb455de08da8

8049378: Examine references to ${java.home}/lib in JAXP Reviewed-by: lancea, alanb
author joehw
date Thu, 05 Mar 2015 17:18:19 -0800
parents 542c0c855ad4
children 2a460ce60ed4
files src/java.xml/share/classes/javax/xml/XMLConstants.java src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java
diffstat 10 files changed, 356 insertions(+), 201 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.xml/share/classes/javax/xml/XMLConstants.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/XMLConstants.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -247,9 +247,11 @@
          * </p>
          *
          * <p>
-         * <b>${JAVA_HOME}/conf/jaxp.properties:</b> This configuration file is in standard
-         * {@link java.util.Properties} format. If the file exists and the system property is specified,
-         * its value will be used to override the default of the property.
+         * <b>jaxp.properties:</b> This configuration file is in standard
+         * {@link java.util.Properties} format and typically located in the {@code conf}
+         * directory of the Java installation. If the file exists and the system
+         * property is specified, its value will be used to override the default
+         * of the property.
          * </p>
          *
          * <p>
@@ -314,9 +316,11 @@
          * </p>
          *
          * <p>
-         * <b>${JAVA_HOME}/conf/jaxp.properties:</b> This configuration file is in standard
-         * java.util.Properties format. If the file exists and the system property is specified,
-         * its value will be used to override the default of the property.
+         * <b>jaxp.properties:</b> This configuration file is in standard
+         * {@link java.util.Properties} format and typically located in the {@code conf}
+         * directory of the Java installation. If the file exists and the system
+         * property is specified, its value will be used to override the default
+         * of the property.
          *
          * @since 1.7
          * </p>
@@ -380,9 +384,11 @@
          * </p>
          *
          * <p>
-         * <b>${JAVA_HOME}/conf/jaxp.properties: </b> This configuration file is in standard
-         * java.util.Properties format. If the file exists and the system property is specified,
-         * its value will be used to override the default of the property.
+         * <b>jaxp.properties:</b> This configuration file is in standard
+         * {@link java.util.Properties} format and typically located in the {@code conf}
+         * directory of the Java installation. If the file exists and the system
+         * property is specified, its value will be used to override the default
+         * of the property.
          *
          * @since 1.7
          */
--- a/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,23 +32,34 @@
 import java.util.regex.Pattern;
 
 /**
- * <p>Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.</p>
- *
- * <p>A new instance of the <code>DatatypeFactory</code> is created through the {@link #newInstance()} method
- * that uses the following implementation resolution mechanisms to determine an implementation:</p>
+ * Factory that creates new <code>javax.xml.datatype</code> <code>Object</code>s that map XML to/from Java <code>Object</code>s.
+ * <p>
+ * A new instance of the {@code DatatypeFactory} is created through the {@link #newInstance()} method
+ * that uses the following implementation resolution mechanisms to determine an implementation:
+ * <p>
  * <ol>
  *    <li>
- *      If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "<code>javax.xml.datatype.DatatypeFactory</code>",
+ *      If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "{@code javax.xml.datatype.DatatypeFactory}",
  *      exists, a class with the name of the property value is instantiated.
  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  *    </li>
  *    <li>
- *      If the file ${JAVA_HOME}/conf/jaxp.properties exists, it is loaded in a {@link java.util.Properties} <code>Object</code>.
- *      The <code>Properties</code> <code>Object </code> is then queried for the property as documented in the prior step
- *      and processed as documented in the prior step.
+ *      <p>
+ *      Use the configuration file "jaxp.properties". The file is in standard
+ *      {@link java.util.Properties} format and typically located in the
+ *      {@code conf} directory of the Java installation. It contains the fully qualified
+ *      name of the implementation class with the key being the system property
+ *      defined above.
+ *      <p>
+ *      The jaxp.properties file is read only once by the JAXP implementation
+ *      and its values are then cached for future use.  If the file does not exist
+ *      when the first attempt is made to read from it, no further attempts are
+ *      made to check for its existence.  It is not possible to change the value
+ *      of any property in jaxp.properties after it has been read for the first time.
  *    </li>
  *    <li>
- *     Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
+ *     <p>
+ *     Use the service-provider loading facility, 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
@@ -56,13 +67,14 @@
  *     to attempt to load the service. If the context class
  *     loader is null, the {@linkplain
  *     ClassLoader#getSystemClassLoader() system class loader} will be used.
- *     <br>
+ *     <p>
  *     In case of {@link java.util.ServiceConfigurationError service
- *     configuration error} a {@link javax.xml.datatype.DatatypeConfigurationException}
+ *     configuration error}, a {@link javax.xml.datatype.DatatypeConfigurationException}
  *     will be thrown.
  *    </li>
  *    <li>
- *      The final mechanism is to attempt to instantiate the <code>Class</code> specified by
+ *      <p>
+ *      The final mechanism is to attempt to instantiate the {@code Class} specified by
  *      {@link #DATATYPEFACTORY_IMPLEMENTATION_CLASS}.
  *      Any Exception thrown during the instantiation process is wrapped as a {@link DatatypeConfigurationException}.
  *    </li>
@@ -79,7 +91,7 @@
     /**
      * <p>Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.</p>
      *
-     * <p>Default value is <code>javax.xml.datatype.DatatypeFactory</code>.</p>
+     * <p>Default value is {@code javax.xml.datatype.DatatypeFactory}.</p>
      */
     public static final String DATATYPEFACTORY_PROPERTY =
             // We use a String constant here, rather than calling
@@ -120,18 +132,18 @@
     /**
      * <p>Protected constructor to prevent instantiation outside of package.</p>
      *
-     * <p>Use {@link #newInstance()} to create a <code>DatatypeFactory</code>.</p>
+     * <p>Use {@link #newInstance()} to create a {@code DatatypeFactory}.</p>
      */
     protected DatatypeFactory() {
     }
 
     /**
-     * <p>Obtain a new instance of a <code>DatatypeFactory</code>.</p>
+     * <p>Obtain a new instance of a {@code DatatypeFactory}.</p>
      *
      * <p>The implementation resolution mechanisms are <a href="#DatatypeFactory.newInstance">defined</a> in this
      * <code>Class</code>'s documentation.</p>
      *
-     * @return New instance of a <code>DatatypeFactory</code>
+     * @return New instance of a {@code DatatypeFactory}
      *
      * @throws DatatypeConfigurationException If the implementation is not
      *   available or cannot be instantiated.
@@ -149,12 +161,12 @@
     }
 
     /**
-     * <p>Obtain a new instance of a <code>DatatypeFactory</code> from class name.
+     * <p>Obtain a new instance of a {@code DatatypeFactory} from class name.
      * This function is useful when there are multiple providers in the classpath.
      * It gives more control to the application as it can specify which provider
      * should be loaded.</p>
      *
-     * <p>Once an application has obtained a reference to a <code>DatatypeFactory</code>
+     * <p>Once an application has obtained a reference to a {@code DatatypeFactory}
      * it can use the factory to configure and obtain datatype instances.</P>
      *
      *
@@ -168,12 +180,12 @@
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
      *
-     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.datatype.DatatypeFactory</code>.
+     * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.datatype.DatatypeFactory}.
      *
      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
      *
-     * @return New instance of a <code>DatatypeFactory</code>
+     * @return New instance of a {@code DatatypeFactory}
      *
      * @throws DatatypeConfigurationException if <code>factoryClassName</code> is <code>null</code>, or
      *                                   the factory class cannot be loaded, instantiated.
--- a/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -55,31 +55,34 @@
 
     /**
      * Obtain a new instance of a
-     * <code>DocumentBuilderFactory</code>. This static method creates
+     * {@code DocumentBuilderFactory}. This static method creates
      * a new factory instance.
      * This method uses the following ordered lookup procedure to determine
-     * the <code>DocumentBuilderFactory</code> implementation class to
+     * the {@code DocumentBuilderFactory} implementation class to
      * load:
+     * <p>
      * <ul>
      * <li>
-     * Use the <code>javax.xml.parsers.DocumentBuilderFactory</code> system
+     * Use the {@code javax.xml.parsers.DocumentBuilderFactory} system
      * property.
      * </li>
      * <li>
-     * Use the properties file "conf/jaxp.properties" in the JRE directory.
-     * This configuration file is in standard <code>java.util.Properties
-     * </code> format and contains the fully qualified name of the
-     * implementation class with the key being the system property defined
-     * above.
-     *
+     * <p>
+     * Use the configuration file "jaxp.properties". The file is in standard
+     * {@link java.util.Properties} format and typically located in the
+     * {@code conf} directory of the Java installation. It contains the fully qualified
+     * name of the implementation class with the key being the system property
+     * defined above.
+     * <p>
      * The jaxp.properties file is read only once by the JAXP implementation
-     * and it's values are then cached for future use.  If the file does not exist
+     * and its values are then cached for future use.  If the file does not exist
      * when the first attempt is made to read from it, no further attempts are
      * made to check for its existence.  It is not possible to change the value
      * of any property in jaxp.properties after it has been read for the first time.
      * </li>
      * <li>
-     * Uses the service-provider loading facilities, defined by the
+     * <p>
+     * Use the service-provider loading facility, 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}:
@@ -90,26 +93,30 @@
      * ClassLoader#getSystemClassLoader() system class loader} will be used.
      * </li>
      * <li>
+     * <p>
      * Otherwise, the system-default implementation is returned.
      * </li>
      * </ul>
      *
+     * <p>
      * Once an application has obtained a reference to a
-     * <code>DocumentBuilderFactory</code> it can use the factory to
+     * {@code DocumentBuilderFactory} it can use the factory to
      * configure and obtain parser instances.
      *
      *
      * <h2>Tip for Trouble-shooting</h2>
-     * <p>Setting the <code>jaxp.debug</code> system property will cause
+     * <p>
+     * Setting the {@code jaxp.debug} system property will cause
      * this method to print a lot of debug messages
-     * to <code>System.err</code> about what it is doing and where it is looking at.</p>
+     * to {@code System.err} about what it is doing and where it is looking at.
      *
-     * <p> If you have problems loading {@link DocumentBuilder}s, try:</p>
+     * <p>
+     * If you have problems loading {@link DocumentBuilder}s, try:
      * <pre>
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
      *
-     * @return New instance of a <code>DocumentBuilderFactory</code>
+     * @return New instance of a {@code DocumentBuilderFactory}
      *
      * @throws FactoryConfigurationError in case of {@linkplain
      * java.util.ServiceConfigurationError service configuration error} or if
@@ -124,31 +131,31 @@
     }
 
     /**
-     * <p>Obtain a new instance of a <code>DocumentBuilderFactory</code> from class name.
+     * <p>Obtain a new instance of a {@code DocumentBuilderFactory} from class name.
      * This function is useful when there are multiple providers in the classpath.
      * It gives more control to the application as it can specify which provider
-     * should be loaded.</p>
+     * should be loaded.
      *
-     * <p>Once an application has obtained a reference to a <code>DocumentBuilderFactory</code>
-     * it can use the factory to configure and obtain parser instances.</p>
+     * <p>Once an application has obtained a reference to a {@code DocumentBuilderFactory}
+     * it can use the factory to configure and obtain parser instances.
      *
      *
      * <h2>Tip for Trouble-shooting</h2>
-     * <p>Setting the <code>jaxp.debug</code> system property will cause
+     * <p>Setting the {@code jaxp.debug} system property will cause
      * this method to print a lot of debug messages
-     * to <code>System.err</code> about what it is doing and where it is looking at.</p>
+     * to {@code System.err} about what it is doing and where it is looking at.</p>
      *
      * <p> If you have problems try:</p>
      * <pre>
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
      *
-     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.DocumentBuilderFactory</code>.
+     * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.DocumentBuilderFactory}.
      *
      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
      *
-     * @return New instance of a <code>DocumentBuilderFactory</code>
+     * @return New instance of a {@code DocumentBuilderFactory}
      *
      * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
      *                                   the factory class cannot be loaded, instantiated.
@@ -406,14 +413,14 @@
                 throws IllegalArgumentException;
 
     /**
-     * <p>Set a feature for this <code>DocumentBuilderFactory</code> and <code>DocumentBuilder</code>s created by this factory.</p>
+     * <p>Set a feature for this {@code DocumentBuilderFactory} and <code>DocumentBuilder</code>s created by this factory.</p>
      *
      * <p>
      * Feature names are fully qualified {@link java.net.URI}s.
      * Implementations may define their own features.
-     * A {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
+     * A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
      * <code>DocumentBuilder</code>s it creates cannot support the feature.
-     * It is possible for a <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
+     * It is possible for a {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
      * </p>
      *
      * <p>
@@ -436,7 +443,7 @@
      * @param name Feature name.
      * @param value Is feature state <code>true</code> or <code>false</code>.
      *
-     * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code> or the <code>DocumentBuilder</code>s
+     * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the <code>DocumentBuilder</code>s
      *   it creates cannot support this feature.
      * @throws NullPointerException If the <code>name</code> parameter is null.
      * @since 1.5
@@ -450,16 +457,16 @@
      * <p>
      * Feature names are fully qualified {@link java.net.URI}s.
      * Implementations may define their own features.
-     * An {@link ParserConfigurationException} is thrown if this <code>DocumentBuilderFactory</code> or the
+     * An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the
      * <code>DocumentBuilder</code>s it creates cannot support the feature.
-     * It is possible for an <code>DocumentBuilderFactory</code> to expose a feature value but be unable to change its state.
+     * It is possible for an {@code DocumentBuilderFactory} to expose a feature value but be unable to change its state.
      * </p>
      *
      * @param name Feature name.
      *
      * @return State of the named feature.
      *
-     * @throws ParserConfigurationException if this <code>DocumentBuilderFactory</code>
+     * @throws ParserConfigurationException if this {@code DocumentBuilderFactory}
      *   or the <code>DocumentBuilder</code>s it creates cannot support this feature.
      * @since 1.5
      */
--- a/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -59,31 +59,34 @@
     }
 
     /**
-     * Obtain a new instance of a <code>SAXParserFactory</code>. This
+     * Obtain a new instance of a {@code SAXParserFactory}. This
      * static method creates a new factory instance
      * This method uses the following ordered lookup procedure to determine
-     * the <code>SAXParserFactory</code> implementation class to
+     * the {@code SAXParserFactory} implementation class to
      * load:
+     * <p>
      * <ul>
      * <li>
-     * Use the <code>javax.xml.parsers.SAXParserFactory</code> system
+     * Use the {@code javax.xml.parsers.SAXParserFactory} system
      * property.
      * </li>
      * <li>
-     * Use the properties file "conf/jaxp.properties" in the JRE directory.
-     * This configuration file is in standard <code>java.util.Properties
-     * </code> format and contains the fully qualified name of the
-     * implementation class with the key being the system property defined
-     * above.
-     *
+     * <p>
+     * Use the configuration file "jaxp.properties". The file is in standard
+     * {@link java.util.Properties} format and typically located in the
+     * {@code conf} directory of the Java installation. It contains the fully qualified
+     * name of the implementation class with the key being the system property
+     * defined above.
+     * <p>
      * The jaxp.properties file is read only once by the JAXP implementation
-     * and it's values are then cached for future use.  If the file does not exist
+     * and its values are then cached for future use.  If the file does not exist
      * when the first attempt is made to read from it, no further attempts are
      * made to check for its existence.  It is not possible to change the value
      * of any property in jaxp.properties after it has been read for the first time.
      * </li>
      * <li>
-     * Use the service-provider loading facilities, defined by the
+     * <p>
+     * Use the service-provider loading facility, 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}:
@@ -94,22 +97,26 @@
      * ClassLoader#getSystemClassLoader() system class loader} will be used.
      * </li>
      * <li>
+     * <p>
      * Otherwise the system-default implementation is returned.
      * </li>
      * </ul>
      *
+     * <p>
      * Once an application has obtained a reference to a
-     * <code>SAXParserFactory</code> it can use the factory to
+     * {@code SAXParserFactory} it can use the factory to
      * configure and obtain parser instances.
      *
      *
      *
      * <h2>Tip for Trouble-shooting</h2>
-     * <p>Setting the <code>jaxp.debug</code> system property will cause
+     * <p>
+     * Setting the {@code jaxp.debug} system property will cause
      * this method to print a lot of debug messages
-     * to <code>System.err</code> about what it is doing and where it is looking at.</p>
+     * to {@code System.err} about what it is doing and where it is looking at.
      *
-     * <p> If you have problems loading {@link SAXParser}s, try:</p>
+     * <p>
+     * If you have problems loading {@link SAXParser}s, try:
      * <pre>
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
@@ -131,31 +138,32 @@
     }
 
     /**
-     * <p>Obtain a new instance of a <code>SAXParserFactory</code> from class name.
+     * <p>Obtain a new instance of a {@code SAXParserFactory} from class name.
      * This function is useful when there are multiple providers in the classpath.
      * It gives more control to the application as it can specify which provider
      * should be loaded.</p>
      *
-     * <p>Once an application has obtained a reference to a <code>SAXParserFactory</code>
+     * <p>Once an application has obtained a reference to a {@code SAXParserFactory}
      * it can use the factory to configure and obtain parser instances.</p>
      *
      *
      * <h2>Tip for Trouble-shooting</h2>
-     * <p>Setting the <code>jaxp.debug</code> system property will cause
+     * <p>Setting the {@code jaxp.debug} system property will cause
      * this method to print a lot of debug messages
-     * to <code>System.err</code> about what it is doing and where it is looking at.</p>
+     * to {@code System.err} about what it is doing and where it is looking at.</p>
      *
-     * <p> If you have problems, try:</p>
+     * <p>
+     * If you have problems, try:
      * <pre>
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
      *
-     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.parsers.SAXParserFactory</code>.
+     * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.SAXParserFactory}.
      *
      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
      *
-     * @return New instance of a <code>SAXParserFactory</code>
+     * @return New instance of a {@code SAXParserFactory}
      *
      * @throws FactoryConfigurationError if <code>factoryClassName</code> is <code>null</code>, or
      *                                   the factory class cannot be loaded, instantiated.
--- a/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -23,7 +23,7 @@
  */
 
 /*
- * Copyright (c) 2009, 2013, by Oracle Corporation. All Rights Reserved.
+ * Copyright (c) 2009, 2015, by Oracle Corporation. All Rights Reserved.
  */
 
 package javax.xml.stream;
@@ -70,19 +70,34 @@
    * This static method creates a new factory instance.
    * This method uses the following ordered lookup procedure to determine
    * the XMLEventFactory implementation class to load:
-   * </p>
+   * <p>
    * <ul>
    * <li>
    *   Use the javax.xml.stream.XMLEventFactory system property.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the system property defined above.
+   *   <p>
+   *   Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   {@code conf} directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>
+   *   The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
-   *   Use the service-provider loading facilities, defined by the
+   *   <p>
+   *   Use the service-provider loading facility, 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}:
@@ -93,18 +108,18 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
+   *   <p>
    *   Otherwise, the system-default implementation is returned.
    * </li>
    * </ul>
    * <p>
    *   Once an application has obtained a reference to a XMLEventFactory it
    *   can use the factory to configure and obtain stream instances.
-   * </p>
    * <p>
    *   Note that this is a new method that replaces the deprecated newInstance() method.
    *     No changes in behavior are defined by this replacement method relative to
    *     the deprecated method.
-   * </p>
+   *
    * @throws FactoryConfigurationError in case of {@linkplain
    *   java.util.ServiceConfigurationError service configuration error} or if
    *   the implementation is not available or cannot be instantiated.
@@ -143,20 +158,35 @@
    * <p>
    * This method uses the following ordered lookup procedure to determine
    * the XMLEventFactory implementation class to load:
-   * </p>
+   * <p>
    * <ul>
    * <li>
    *   Use the value of the system property identified by {@code factoryId}.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the given {@code factoryId}.
+   *   <p>
+   *   Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   conf directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>
+   *   The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
+   *   <p>
    *   If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
-   *   use the service-provider loading facilities, defined by the
+   *   use the service-provider loading facility, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to {@linkplain
    *   java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
    *   an implementation of the service using the specified {@code ClassLoader}.
@@ -169,6 +199,7 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
+   *   <p>
    *   Otherwise, throws a {@link FactoryConfigurationError}.
    * </li>
    * </ul>
@@ -179,7 +210,6 @@
    *   newInstance(String factoryId, ClassLoader classLoader)} method.
    * No changes in behavior are defined by this replacement method relative
    * 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
--- a/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -68,7 +68,7 @@
  *
  *
  * @version 1.2
- * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
+ * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
  * @see XMLOutputFactory
  * @see XMLEventReader
  * @see XMLStreamReader
@@ -163,16 +163,28 @@
    * </p>
    * <ul>
    * <li>
-   *   Use the javax.xml.stream.XMLInputFactory system property.
+   *   <p>Use the javax.xml.stream.XMLInputFactory system property.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the system property defined above.
+   *   <p>Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   {@code conf} directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
-   *   Use the service-provider loading facilities, defined by the
+   *   <p>Use the service-provider loading facility, 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}:
@@ -183,7 +195,7 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
-   * Otherwise, the system-default implementation is returned.
+   * <p>Otherwise, the system-default implementation is returned.
    * </li>
    * </ul>
    * <p>
@@ -233,20 +245,36 @@
    * <p>
    * This method uses the following ordered lookup procedure to determine
    * the XMLInputFactory implementation class to load:
-   * </p>
+   * <p>
    * <ul>
    * <li>
+   *   <p>
    *   Use the value of the system property identified by {@code factoryId}.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the given {@code factoryId}.
+   *   <p>
+   *   Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   {@code conf} directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>
+   *   The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
+   *   <p>
    *   If {@code factoryId} is "javax.xml.stream.XMLInputFactory",
-   *   use the service-provider loading facilities, defined by the
+   *   use the service-provider loading facility, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to {@linkplain
    *   java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
    *   an implementation of the service using the specified {@code ClassLoader}.
@@ -259,6 +287,7 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
+   *   <p>
    *   Otherwise, throws a {@link FactoryConfigurationError}.
    * </li>
    * </ul>
@@ -269,7 +298,7 @@
    *   newInstance(String factoryId, ClassLoader classLoader)} method.
    * No changes in behavior are defined by this replacement method relative
    * 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
--- a/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -102,7 +102,7 @@
  * namespace URI of the element or attribute using that prefix.</p>
  *
  * @version 1.2
- * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
+ * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
  * @see XMLInputFactory
  * @see XMLEventWriter
  * @see XMLStreamWriter
@@ -136,19 +136,34 @@
    * This static method creates a new factory instance. This method uses the
    * following ordered lookup procedure to determine the XMLOutputFactory
    * implementation class to load:
-   * </p>
+   * <p>
    * <ul>
    * <li>
    *   Use the javax.xml.stream.XMLOutputFactory system property.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the system property defined above.
+   *   <p>
+   *   Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   {@code conf} directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>
+   *   The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
-   *   Use the service-provider loading facilities, defined by the
+   *   <p>
+   *   Use the service-provider loading facility, 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}:
@@ -159,17 +174,17 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
+   *   <p>
    *   Otherwise, the system-default implementation is returned.
    * </li>
    * <p>
    * Once an application has obtained a reference to a XMLOutputFactory it
    * can use the factory to configure and obtain stream instances.
-   * </p>
    * <p>
    * Note that this is a new method that replaces the deprecated newInstance() method.
    *   No changes in behavior are defined by this replacement method relative to the
    *   deprecated method.
-   * </p>
+   *
    * @throws FactoryConfigurationError in case of {@linkplain
    *   java.util.ServiceConfigurationError service configuration error} or if
    *   the implementation is not available or cannot be instantiated.
@@ -207,20 +222,35 @@
    * <p>
    * This method uses the following ordered lookup procedure to determine
    * the XMLOutputFactory implementation class to load:
-   * </p>
+   * <p>
    * <ul>
    * <li>
    *   Use the value of the system property identified by {@code factoryId}.
    * </li>
    * <li>
-   *   Use the properties file "lib/stax.properties" in the JRE directory.
-   *     This configuration file is in standard java.util.Properties format
-   *     and contains the fully qualified name of the implementation class
-   *     with the key being the given {@code factoryId}.
+   *   <p>
+   *   Use the configuration file "stax.properties". The file is in standard
+   *   {@link java.util.Properties} format and typically located in the
+   *   {@code conf} directory of the Java installation. It contains the fully qualified
+   *   name of the implementation class with the key being the system property
+   *   defined above.
+   *
+   *   <p>
+   *   The stax.properties file is read only once by the implementation
+   *   and its values are then cached for future use.  If the file does not exist
+   *   when the first attempt is made to read from it, no further attempts are
+   *   made to check for its existence.  It is not possible to change the value
+   *   of any property in stax.properties after it has been read for the first time.
+   *
+   *   <p>
+   *   Use the jaxp configuration file "jaxp.properties". The file is in the same
+   *   format as stax.properties and will only be read if stax.properties does
+   *   not exist.
    * </li>
    * <li>
+   *   <p>
    *   If {@code factoryId} is "javax.xml.stream.XMLOutputFactory",
-   *   use the service-provider loading facilities, defined by the
+   *   use the service-provider loading facility, defined by the
    *   {@link java.util.ServiceLoader} class, to attempt to {@linkplain
    *   java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
    *   an implementation of the service using the specified {@code ClassLoader}.
@@ -233,6 +263,7 @@
    *   ClassLoader#getSystemClassLoader() system class loader} will be used.
    * </li>
    * <li>
+   *   <p>
    *   Otherwise, throws a {@link FactoryConfigurationError}.
    * </li>
    * </ul>
@@ -246,7 +277,7 @@
    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)
    *   newInstance(String factoryId, ClassLoader classLoader)} method.
    *   The original method was incorrectly defined to return XMLInputFactory.
-   * </p>
+   *
    *
    * @param factoryId             Name of the factory to find, same as
    *                              a property name
--- a/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -33,7 +33,7 @@
  * <p>The system property that determines which Factory implementation
  * to create is named <code>"javax.xml.transform.TransformerFactory"</code>.
  * This property names a concrete subclass of the
- * <code>TransformerFactory</code> abstract class. If the property is not
+ * {@code TransformerFactory} abstract class. If the property is not
  * defined, a platform default is be used.</p>
  *
  * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
@@ -51,31 +51,36 @@
 
 
     /**
-     * <p>Obtain a new instance of a <code>TransformerFactory</code>.
-     * This static method creates a new factory instance.</p>
-     * <p>This method uses the following ordered lookup procedure to determine
-     * the <code>TransformerFactory</code> implementation class to
-     * load:</p>
+     * <p>
+     * Obtain a new instance of a {@code TransformerFactory}.
+     * This static method creates a new factory instance.
+     * <p>
+     * This method uses the following ordered lookup procedure to determine
+     * the {@code TransformerFactory} implementation class to
+     * load:
+     * <p>
      * <ul>
      * <li>
-     * Use the <code>javax.xml.transform.TransformerFactory</code> system
+     * Use the {@code javax.xml.transform.TransformerFactory} system
      * property.
      * </li>
      * <li>
-     * Use the properties file "conf/jaxp.properties" in the JRE directory.
-     * This configuration file is in standard <code>java.util.Properties
-     * </code> format and contains the fully qualified name of the
-     * implementation class with the key being the system property defined
-     * above.
-     * <br>
+     * <p>
+     * Use the configuration file "jaxp.properties". The file is in standard
+     * {@link java.util.Properties} format and typically located in the
+     * {@code conf} directory of the Java installation. It contains the fully qualified
+     * name of the implementation class with the key being the system property
+     * defined above.
+     * <p>
      * The jaxp.properties file is read only once by the JAXP implementation
-     * and it's values are then cached for future use.  If the file does not exist
+     * and its values are then cached for future use.  If the file does not exist
      * when the first attempt is made to read from it, no further attempts are
      * made to check for its existence.  It is not possible to change the value
      * of any property in jaxp.properties after it has been read for the first time.
      * </li>
      * <li>
-     *   Use the service-provider loading facilities, defined by the
+     * <p>
+     * Use the service-provider loading facility, 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}:
@@ -86,13 +91,15 @@
      *   ClassLoader#getSystemClassLoader() system class loader} will be used.
      * </li>
      * <li>
+     * <p>
      *   Otherwise, the system-default implementation is returned.
      * </li>
      * </ul>
      *
-     * <p>Once an application has obtained a reference to a <code>
-     * TransformerFactory</code> it can use the factory to configure
-     * and obtain transformer instances.</p>
+     * <p>
+     * Once an application has obtained a reference to a
+     * {@code TransformerFactory} it can use the factory to configure
+     * and obtain transformer instances.
      *
      * @return new TransformerFactory instance, never null.
      *
@@ -111,13 +118,13 @@
     }
 
     /**
-     * <p>Obtain a new instance of a <code>TransformerFactory</code> from factory class name.
+     * <p>Obtain a new instance of a {@code TransformerFactory} from factory class name.
      * This function is useful when there are multiple providers in the classpath.
      * It gives more control to the application as it can specify which provider
      * should be loaded.</p>
      *
-     * <p>Once an application has obtained a reference to a <code>
-     * TransformerFactory</code> it can use the factory to configure
+     * <p>Once an application has obtained a reference to a
+     * {@code TransformerFactory} it can use the factory to configure
      * and obtain transformer instances.</p>
      *
      * <h2>Tip for Trouble-shooting</h2>
@@ -130,7 +137,7 @@
      * java -Djaxp.debug=1 YourProgram ....
      * </pre>
      *
-     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.transform.TransformerFactory</code>.
+     * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.transform.TransformerFactory}.
      *
      * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code>
      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
@@ -232,7 +239,7 @@
      * @param charset The value of the charset attribute to match.  May be null.
      *
      * @return A <code>Source</code> <code>Object</code> suitable for passing
-     *   to the <code>TransformerFactory</code>.
+     *   to the {@code TransformerFactory}.
      *
      * @throws TransformerConfigurationException An <code>Exception</code>
      *   is thrown if an error occurings during parsing of the
@@ -268,15 +275,15 @@
     //======= CONFIGURATION METHODS =======
 
         /**
-         * <p>Set a feature for this <code>TransformerFactory</code> and <code>Transformer</code>s
+         * <p>Set a feature for this {@code TransformerFactory} and <code>Transformer</code>s
          * or <code>Template</code>s created by this factory.</p>
          *
          * <p>
          * Feature names are fully qualified {@link java.net.URI}s.
          * Implementations may define their own features.
-         * An {@link TransformerConfigurationException} is thrown if this <code>TransformerFactory</code> or the
+         * An {@link TransformerConfigurationException} is thrown if this {@code TransformerFactory} or the
          * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
-         * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state.
+         * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
          * </p>
          *
          * <p>All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
@@ -299,7 +306,7 @@
          * @param name Feature name.
          * @param value Is feature state <code>true</code> or <code>false</code>.
          *
-         * @throws TransformerConfigurationException if this <code>TransformerFactory</code>
+         * @throws TransformerConfigurationException if this {@code TransformerFactory}
          *   or the <code>Transformer</code>s or <code>Template</code>s it creates cannot support this feature.
      * @throws NullPointerException If the <code>name</code> parameter is null.
          */
@@ -312,9 +319,9 @@
          * <p>
          * Feature names are fully qualified {@link java.net.URI}s.
          * Implementations may define their own features.
-         * <code>false</code> is returned if this <code>TransformerFactory</code> or the
+         * <code>false</code> is returned if this {@code TransformerFactory} or the
          * <code>Transformer</code>s or <code>Template</code>s it creates cannot support the feature.
-         * It is possible for an <code>TransformerFactory</code> to expose a feature value but be unable to change its state.
+         * It is possible for an {@code TransformerFactory} to expose a feature value but be unable to change its state.
          * </p>
          *
          * @param name Feature name.
--- a/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -132,8 +132,9 @@
      * where "the class loader" refers to the context class loader:</p>
      * <ol>
      *  <li>
+     *     <p>
      *     If the system property
-     *     <code>"javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"</code>
+     *     {@code "javax.xml.validation.SchemaFactory:<i>schemaLanguage</i>"}
      *     is present (where <i>schemaLanguage</i> is the parameter
      *     to this method), then its value is read
      *     as a class name. The method will try to
@@ -141,12 +142,22 @@
      *     and returns it if it is successfully created.
      *   </li>
      *   <li>
-     *     <code>$java.home/conf/jaxp.properties</code> 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.
+     *     <p>
+     *     Use the configuration file "jaxp.properties". The file is in standard
+     *     {@link java.util.Properties} format and typically located in the
+     *     conf directory of the Java installation. It contains the fully qualified
+     *     name of the implementation class with the key being the system property
+     *     defined above.
+     *     <p>
+     *     The jaxp.properties file is read only once by the JAXP implementation
+     *     and its values are then cached for future use.  If the file does not exist
+     *     when the first attempt is made to read from it, no further attempts are
+     *     made to check for its existence.  It is not possible to change the value
+     *     of any property in jaxp.properties after it has been read for the first time.
      *   </li>
      *   <li>
-     *   Use the service-provider loading facilities, defined by the
+     *   <p>
+     *   Use the service-provider loading facility, 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}:
@@ -166,19 +177,20 @@
      *   {@link SchemaFactoryConfigurationError} will be thrown.
      *   </li>
      *   <li>
+     *     <p>
      *     Platform default <code>SchemaFactory</code> is located
      *     in a implementation specific way. There must be a platform default
      *     <code>SchemaFactory</code> for W3C XML Schema.
      *   </li>
      * </ol>
      *
-     * <p>If everything fails, {@link IllegalArgumentException} will be thrown.</p>
+     * <p>If everything fails, {@link IllegalArgumentException} will be thrown.
      *
-     * <p><strong>Tip for Trouble-shooting:</strong></p>
+     * <p><strong>Tip for Trouble-shooting:</strong>
      * <p>See {@link java.util.Properties#load(java.io.InputStream)} for
      * exactly how a property file is parsed. In particular, colons ':'
      * need to be escaped in a property file, so make sure schema language
-     * URIs are properly escaped in it. For example:</p>
+     * URIs are properly escaped in it. For example:
      * <pre>
      * http\://www.w3.org/2001/XMLSchema=org.acme.foo.XSSchemaFactory
      * </pre>
--- a/src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java	Thu Mar 05 11:26:16 2015 -0800
+++ b/src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java	Thu Mar 05 17:18:19 2015 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -26,7 +26,7 @@
 package javax.xml.xpath;
 
 /**
- * <p>An <code>XPathFactory</code> instance can be used to create
+ * <p>An {@code XPathFactory} instance can be used to create
  * {@link javax.xml.xpath.XPath} objects.</p>
  *
  *<p>See {@link #newInstance(String uri)} for lookup mechanism.</p>
@@ -68,13 +68,13 @@
     /**
      * <p>Protected constructor as {@link #newInstance()} or {@link #newInstance(String uri)}
      * or {@link #newInstance(String uri, String factoryClassName, ClassLoader classLoader)}
-     * should be used to create a new instance of an <code>XPathFactory</code>.</p>
+     * should be used to create a new instance of an {@code XPathFactory}.</p>
      */
     protected XPathFactory() {
     }
 
     /**
-     * <p>Get a new <code>XPathFactory</code> instance using the default object model,
+     * <p>Get a new {@code XPathFactory} instance using the default object model,
      * {@link #DEFAULT_OBJECT_MODEL_URI},
      * the W3C DOM.</p>
      *
@@ -85,10 +85,10 @@
      *
      * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p>
      *
-     * @return Instance of an <code>XPathFactory</code>.
+     * @return Instance of an {@code XPathFactory}.
      *
      * @throws RuntimeException When there is a failure in creating an
-     *   <code>XPathFactory</code> for the default object model.
+     *   {@code XPathFactory} for the default object model.
      */
     public static XPathFactory newInstance() {
 
@@ -105,23 +105,35 @@
     }
 
     /**
-    * <p>Get a new <code>XPathFactory</code> instance using the specified object model.</p>
+    * <p>Get a new {@code XPathFactory} instance using the specified object model.</p>
     *
-    * <p>To find a <code>XPathFactory</code> object,
+    * <p>To find a {@code XPathFactory} object,
     * this method looks the following places in the following order where "the class loader" refers to the context class loader:</p>
     * <ol>
     *   <li>
+    *     <p>
     *     If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present,
     *     where uri is the parameter to this method, then its value is read as a class name.
     *     The method will try to create a new instance of this class by using the class loader,
     *     and returns it if it is successfully created.
     *   </li>
     *   <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.
+    *     <p>
+    *     Use the configuration file "jaxp.properties". The file is in standard
+    *     {@link java.util.Properties} format and typically located in the
+    *     conf directory of the Java installation. It contains the fully qualified
+    *     name of the implementation class with the key being the system property
+    *     defined above.
+    *     <p>
+    *     The jaxp.properties file is read only once by the JAXP implementation
+    *     and its values are then cached for future use.  If the file does not exist
+    *     when the first attempt is made to read from it, no further attempts are
+    *     made to check for its existence.  It is not possible to change the value
+    *     of any property in jaxp.properties after it has been read for the first time.
     *   </li>
     *   <li>
-    *     Use the service-provider loading facilities, defined by the
+    *     <p>
+    *     Use the service-provider loading facility, 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}:
@@ -140,16 +152,17 @@
     *     {@link XPathFactoryConfigurationException} will be thrown.
     *   </li>
     *   <li>
-    *     Platform default <code>XPathFactory</code> is located in a platform specific way.
+    *     <p>
+    *     Platform default {@code XPathFactory} 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>
     * </ol>
-    * <p>If everything fails, an <code>XPathFactoryConfigurationException</code> will be thrown.</p>
+    * <p>If everything fails, an {@code XPathFactoryConfigurationException} will be thrown.
     *
-    * <p>Tip for Trouble-shooting:</p>
+    * <p>Tip for Trouble-shooting:
     * <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed.
     * In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it.
-    * For example:</p>
+    * For example:
     * <pre>
     *   http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory
     * </pre>
@@ -159,7 +172,7 @@
     *   <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>.
+    * @return Instance of an {@code XPathFactory}.
     *
     * @throws XPathFactoryConfigurationException If the specified object model
     *      is unavailable, or if there is a configuration error.
@@ -199,7 +212,7 @@
     }
 
     /**
-     * <p>Obtain a new instance of a <code>XPathFactory</code> from a factory class name. <code>XPathFactory</code>
+     * <p>Obtain a new instance of a {@code XPathFactory} from a factory class name. {@code XPathFactory}
      * is returned if specified factory class supports the specified object model.
      * This function is useful when there are multiple providers in the classpath.
      * It gives more control to the application as it can specify which provider
@@ -227,7 +240,7 @@
      *                     current <code>Thread</code>'s context classLoader is used to load the factory class.
      *
      *
-     * @return New instance of a <code>XPathFactory</code>
+     * @return New instance of a {@code XPathFactory}
      *
      * @throws XPathFactoryConfigurationException
      *                   if <code>factoryClassName</code> is <code>null</code>, or
@@ -281,11 +294,11 @@
     }
 
     /**
-     * <p>Is specified object model supported by this <code>XPathFactory</code>?</p>
+     * <p>Is specified object model supported by this {@code XPathFactory}?</p>
      *
-     * @param objectModel Specifies the object model which the returned <code>XPathFactory</code> will understand.
+     * @param objectModel Specifies the object model which the returned {@code XPathFactory} will understand.
      *
-     * @return <code>true</code> if <code>XPathFactory</code> supports <code>objectModel</code>, else <code>false</code>.
+     * @return <code>true</code> if {@code XPathFactory} supports <code>objectModel</code>, else <code>false</code>.
      *
      * @throws NullPointerException If <code>objectModel</code> is <code>null</code>.
      * @throws IllegalArgumentException If <code>objectModel.length() == 0</code>.
@@ -293,16 +306,16 @@
     public abstract boolean isObjectModelSupported(String objectModel);
 
     /**
-     * <p>Set a feature for this <code>XPathFactory</code> and
+     * <p>Set a feature for this {@code XPathFactory} and
      * <code>XPath</code>s created by this factory.</p>
      *
      * <p>
      * Feature names are fully qualified {@link java.net.URI}s.
      * Implementations may define their own features.
      * An {@link XPathFactoryConfigurationException} is thrown if this
-     * <code>XPathFactory</code> or the <code>XPath</code>s
+     * {@code XPathFactory} or the <code>XPath</code>s
      * it creates cannot support the feature.
-     * It is possible for an <code>XPathFactory</code> to expose a feature value
+     * It is possible for an {@code XPathFactory} to expose a feature value
      * but be unable to change its state.
      * </p>
      *
@@ -316,7 +329,7 @@
      * @param name Feature name.
      * @param value Is feature state <code>true</code> or <code>false</code>.
      *
-     * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s
+     * @throws XPathFactoryConfigurationException if this {@code XPathFactory} or the <code>XPath</code>s
      *   it creates cannot support this feature.
      * @throws NullPointerException if <code>name</code> is <code>null</code>.
      */
@@ -330,9 +343,9 @@
      * Feature names are fully qualified {@link java.net.URI}s.
      * Implementations may define their own features.
      * An {@link XPathFactoryConfigurationException} is thrown if this
-     * <code>XPathFactory</code> or the <code>XPath</code>s
+     * {@code XPathFactory} or the <code>XPath</code>s
      * it creates cannot support the feature.
-     * It is possible for an <code>XPathFactory</code> to expose a feature value
+     * It is possible for an {@code XPathFactory} to expose a feature value
      * but be unable to change its state.
      * </p>
      *
@@ -341,7 +354,7 @@
      * @return State of the named feature.
      *
      * @throws XPathFactoryConfigurationException if this
-     *   <code>XPathFactory</code> or the <code>XPath</code>s
+     *   {@code XPathFactory} or the <code>XPath</code>s
      *   it creates cannot support this feature.
      * @throws NullPointerException if <code>name</code> is <code>null</code>.
      */
@@ -382,7 +395,7 @@
 
     /**
     * <p>Return a new <code>XPath</code> using the underlying object
-    * model determined when the <code>XPathFactory</code> was instantiated.</p>
+    * model determined when the {@code XPathFactory} was instantiated.</p>
     *
     * @return New instance of an <code>XPath</code>.
     */