--- a/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/transform/TransformerFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/validation/SchemaFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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/jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java Thu Mar 12 13:35:06 2015 -0700
+++ b/jaxp/src/java.xml/share/classes/javax/xml/xpath/XPathFactory.java Thu Mar 12 21:13:52 2015 -0700
@@ -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>.
*/