diff -r 82cd31c5d6ca -r 534054ee6062 jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java --- a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java Wed Jul 05 20:23:32 2017 +0200 +++ b/jaxp/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: - *
+ **
+ * 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. + * + *
+ * 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. + * + *
+ * 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. *
+ * 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. *
* Otherwise, the system-default implementation is returned. *
* Once an application has obtained a reference to a XMLEventFactory it * can use the factory to configure and obtain stream instances. - *
** 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. - *
+ * * @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 @@ ** This method uses the following ordered lookup procedure to determine * the XMLEventFactory implementation class to load: - *
+ **
+ * 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. + * + *
+ * 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. + * + *
+ * 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. *
* 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. *
* Otherwise, throws a {@link FactoryConfigurationError}. *