From a953097a8960cd0013fa28ddc7ee54277a82fb67 Mon Sep 17 00:00:00 2001 From: Joe Wang Date: Thu, 5 Mar 2015 17:18:19 -0800 Subject: [PATCH] 8049378: Examine references to ${java.home}/lib in JAXP Reviewed-by: lancea, alanb --- .../share/classes/javax/xml/XMLConstants.java | 26 ++++--- .../javax/xml/datatype/DatatypeFactory.java | 54 ++++++++------ .../xml/parsers/DocumentBuilderFactory.java | 71 ++++++++++--------- .../javax/xml/parsers/SAXParserFactory.java | 54 ++++++++------ .../javax/xml/stream/XMLEventFactory.java | 62 +++++++++++----- .../javax/xml/stream/XMLInputFactory.java | 59 +++++++++++---- .../javax/xml/stream/XMLOutputFactory.java | 63 +++++++++++----- .../xml/transform/TransformerFactory.java | 67 +++++++++-------- .../javax/xml/validation/SchemaFactory.java | 30 +++++--- .../classes/javax/xml/xpath/XPathFactory.java | 71 +++++++++++-------- 10 files changed, 356 insertions(+), 201 deletions(-) diff --git a/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java b/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java index 4cb5800200d..cca303c5d66 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/XMLConstants.java @@ -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 @@ public final class XMLConstants { *

* *

- * ${JAVA_HOME}/conf/jaxp.properties: 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. + * jaxp.properties: 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. *

* *

@@ -314,9 +316,11 @@ public final class XMLConstants { *

* *

- * ${JAVA_HOME}/conf/jaxp.properties: 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. + * jaxp.properties: 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 *

@@ -380,9 +384,11 @@ public final class XMLConstants { *

* *

- * ${JAVA_HOME}/conf/jaxp.properties: 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. + * jaxp.properties: 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 */ diff --git a/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java index de6050ac4e8..d3afb25888e 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/datatype/DatatypeFactory.java @@ -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.Matcher; import java.util.regex.Pattern; /** - *

Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects.

- * - *

A new instance of the DatatypeFactory is created through the {@link #newInstance()} method - * that uses the following implementation resolution mechanisms to determine an implementation:

+ * Factory that creates new javax.xml.datatype Objects that map XML to/from Java Objects. + *

+ * 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: + *

*

    *
  1. - * If the system property specified by {@link #DATATYPEFACTORY_PROPERTY}, "javax.xml.datatype.DatatypeFactory", + * 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}. *
    2. *
  2. - * If the file ${JAVA_HOME}/conf/jaxp.properties exists, it is loaded in a {@link java.util.Properties} Object. - * The Properties Object is then queried for the property as documented in the prior step - * and processed as documented in the prior step. + *

    + * 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. + *

    + * 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. *

    3. *
  3. - * Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt + *

    + * 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 @@ import java.util.regex.Pattern; * to attempt to load the service. If the context class * loader is null, the {@linkplain * ClassLoader#getSystemClassLoader() system class loader} will be used. - *
    + *

    * 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. *

    4. *
  4. - * The final mechanism is to attempt to instantiate the Class specified by + *

    + * 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}. *

    5. @@ -79,7 +91,7 @@ public abstract class DatatypeFactory { /** *

    Default property name as defined in JSR 206: Java(TM) API for XML Processing (JAXP) 1.3.

    * - *

    Default value is javax.xml.datatype.DatatypeFactory.

    + *

    Default value is {@code javax.xml.datatype.DatatypeFactory}.

    */ public static final String DATATYPEFACTORY_PROPERTY = // We use a String constant here, rather than calling @@ -120,18 +132,18 @@ public abstract class DatatypeFactory { /** *

    Protected constructor to prevent instantiation outside of package.

    * - *

    Use {@link #newInstance()} to create a DatatypeFactory.

    + *

    Use {@link #newInstance()} to create a {@code DatatypeFactory}.

    */ protected DatatypeFactory() { } /** - *

    Obtain a new instance of a DatatypeFactory.

    + *

    Obtain a new instance of a {@code DatatypeFactory}.

    * *

    The implementation resolution mechanisms are defined in this * Class's documentation.

    * - * @return New instance of a DatatypeFactory + * @return New instance of a {@code DatatypeFactory} * * @throws DatatypeConfigurationException If the implementation is not * available or cannot be instantiated. @@ -149,12 +161,12 @@ public abstract class DatatypeFactory { } /** - *

    Obtain a new instance of a DatatypeFactory from class name. + *

    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.

    * - *

    Once an application has obtained a reference to a DatatypeFactory + *

    Once an application has obtained a reference to a {@code DatatypeFactory} * it can use the factory to configure and obtain datatype instances.

    * * @@ -168,12 +180,12 @@ public abstract class DatatypeFactory { * java -Djaxp.debug=1 YourProgram .... * * - * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.datatype.DatatypeFactory. + * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.datatype.DatatypeFactory}. * * @param classLoader ClassLoader used to load the factory class. If null * current Thread's context classLoader is used to load the factory class. * - * @return New instance of a DatatypeFactory + * @return New instance of a {@code DatatypeFactory} * * @throws DatatypeConfigurationException if factoryClassName is null, or * the factory class cannot be loaded, instantiated. diff --git a/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java index 62bd3bd27c0..c500869cd7f 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/parsers/DocumentBuilderFactory.java @@ -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 @@ public abstract class DocumentBuilderFactory { /** * Obtain a new instance of a - * DocumentBuilderFactory. 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 DocumentBuilderFactory implementation class to + * the {@code DocumentBuilderFactory} implementation class to * load: + *

    *

    * + *

    * Once an application has obtained a reference to a - * DocumentBuilderFactory it can use the factory to + * {@code DocumentBuilderFactory} it can use the factory to * configure and obtain parser instances. * * *

    Tip for Trouble-shooting

    - *

    Setting the jaxp.debug system property will cause + *

    + * Setting the {@code jaxp.debug} system property will cause * this method to print a lot of debug messages - * to System.err about what it is doing and where it is looking at.

    + * to {@code System.err} about what it is doing and where it is looking at. * - *

    If you have problems loading {@link DocumentBuilder}s, try:

    + *

    + * If you have problems loading {@link DocumentBuilder}s, try: * 

          * java -Djaxp.debug=1 YourProgram ....
      *
    * - * @return New instance of a DocumentBuilderFactory + * @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 @@ public abstract class DocumentBuilderFactory { } /** - *

    Obtain a new instance of a DocumentBuilderFactory from class name. + *

    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.

    + * should be loaded. * - *

    Once an application has obtained a reference to a DocumentBuilderFactory - * it can use the factory to configure and obtain parser instances.

    + *

    Once an application has obtained a reference to a {@code DocumentBuilderFactory} + * it can use the factory to configure and obtain parser instances. * * *

    Tip for Trouble-shooting

    - *

    Setting the jaxp.debug system property will cause + *

    Setting the {@code jaxp.debug} system property will cause * this method to print a lot of debug messages - * to System.err about what it is doing and where it is looking at.

    + * to {@code System.err} about what it is doing and where it is looking at.

    * *

    If you have problems try:

    * 
          * java -Djaxp.debug=1 YourProgram ....
      *
    * - * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.parsers.DocumentBuilderFactory. + * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.DocumentBuilderFactory}. * * @param classLoader ClassLoader used to load the factory class. If null * current Thread's context classLoader is used to load the factory class. * - * @return New instance of a DocumentBuilderFactory + * @return New instance of a {@code DocumentBuilderFactory} * * @throws FactoryConfigurationError if factoryClassName is null, or * the factory class cannot be loaded, instantiated. @@ -406,14 +413,14 @@ public abstract class DocumentBuilderFactory { throws IllegalArgumentException; /** - *

    Set a feature for this DocumentBuilderFactory and DocumentBuilders created by this factory.

    + *

    Set a feature for this {@code DocumentBuilderFactory} and DocumentBuilders created by this factory.

    * *

    * Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. - * A {@link ParserConfigurationException} is thrown if this DocumentBuilderFactory or the + * A {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the * DocumentBuilders it creates cannot support the feature. - * It is possible for a DocumentBuilderFactory 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. *

    * *

    @@ -436,7 +443,7 @@ public abstract class DocumentBuilderFactory { * @param name Feature name. * @param value Is feature state true or false. * - * @throws ParserConfigurationException if this DocumentBuilderFactory or the DocumentBuilders + * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} or the DocumentBuilders * it creates cannot support this feature. * @throws NullPointerException If the name parameter is null. * @since 1.5 @@ -450,16 +457,16 @@ public abstract class DocumentBuilderFactory { *

    * Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. - * An {@link ParserConfigurationException} is thrown if this DocumentBuilderFactory or the + * An {@link ParserConfigurationException} is thrown if this {@code DocumentBuilderFactory} or the * DocumentBuilders it creates cannot support the feature. - * It is possible for an DocumentBuilderFactory 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. *

    * * @param name Feature name. * * @return State of the named feature. * - * @throws ParserConfigurationException if this DocumentBuilderFactory + * @throws ParserConfigurationException if this {@code DocumentBuilderFactory} * or the DocumentBuilders it creates cannot support this feature. * @since 1.5 */ diff --git a/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java index f2e9120a02f..1160a62edf4 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/parsers/SAXParserFactory.java @@ -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 @@ public abstract class SAXParserFactory { } /** - * Obtain a new instance of a SAXParserFactory. 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 SAXParserFactory implementation class to + * the {@code SAXParserFactory} implementation class to * load: + *

    *

    * + *

    * Once an application has obtained a reference to a - * SAXParserFactory it can use the factory to + * {@code SAXParserFactory} it can use the factory to * configure and obtain parser instances. * * * *

    Tip for Trouble-shooting

    - *

    Setting the jaxp.debug system property will cause + *

    + * Setting the {@code jaxp.debug} system property will cause * this method to print a lot of debug messages - * to System.err about what it is doing and where it is looking at.

    + * to {@code System.err} about what it is doing and where it is looking at. * - *

    If you have problems loading {@link SAXParser}s, try:

    + *

    + * If you have problems loading {@link SAXParser}s, try: * 

          * java -Djaxp.debug=1 YourProgram ....
      *
    @@ -131,31 +138,32 @@ public abstract class SAXParserFactory { } /** - *

    Obtain a new instance of a SAXParserFactory from class name. + *

    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.

    * - *

    Once an application has obtained a reference to a SAXParserFactory + *

    Once an application has obtained a reference to a {@code SAXParserFactory} * it can use the factory to configure and obtain parser instances.

    * * *

    Tip for Trouble-shooting

    - *

    Setting the jaxp.debug system property will cause + *

    Setting the {@code jaxp.debug} system property will cause * this method to print a lot of debug messages - * to System.err about what it is doing and where it is looking at.

    + * to {@code System.err} about what it is doing and where it is looking at.

    * - *

    If you have problems, try:

    + *

    + * If you have problems, try: * 

          * java -Djaxp.debug=1 YourProgram ....
      *
    * - * @param factoryClassName fully qualified factory class name that provides implementation of javax.xml.parsers.SAXParserFactory. + * @param factoryClassName fully qualified factory class name that provides implementation of {@code javax.xml.parsers.SAXParserFactory}. * * @param classLoader ClassLoader used to load the factory class. If null * current Thread's context classLoader is used to load the factory class. * - * @return New instance of a SAXParserFactory + * @return New instance of a {@code SAXParserFactory} * * @throws FactoryConfigurationError if factoryClassName is null, or * the factory class cannot be loaded, instantiated. diff --git a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java index 548feeb272a..fc14bc620bc 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLEventFactory.java @@ -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 @@ public abstract class XMLEventFactory { * This static method creates a new factory instance. * This method uses the following ordered lookup procedure to determine * the XMLEventFactory implementation class to load: - *

    + *

    *

    *

    * 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 @@ public abstract class XMLEventFactory { *

    * This method uses the following ordered lookup procedure to determine * the XMLEventFactory implementation class to load: - *

    + *

    *

    @@ -179,7 +210,6 @@ public abstract class XMLEventFactory { * newInstance(String factoryId, ClassLoader classLoader)} method. * No changes in behavior are defined by this replacement method relative * to the deprecated method. - *

    * * @apiNote The parameter factoryId defined here is inconsistent with that * of other JAXP factories where the first parameter is fully qualified diff --git a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java index 20af7a052b2..90030378467 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLInputFactory.java @@ -68,7 +68,7 @@ import javax.xml.transform.Source; * * * @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 @@ public abstract class XMLInputFactory { *

    * *

    @@ -233,20 +245,36 @@ public abstract class XMLInputFactory { *

    * This method uses the following ordered lookup procedure to determine * the XMLInputFactory implementation class to load: - *

    + *

    *

    @@ -269,7 +298,7 @@ public abstract class XMLInputFactory { * newInstance(String factoryId, ClassLoader classLoader)} method. * No changes in behavior are defined by this replacement method relative * to the deprecated method. - *

    + * * * @apiNote The parameter factoryId defined here is inconsistent with that * of other JAXP factories where the first parameter is fully qualified diff --git a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java index e875ac2c277..4524a4e8315 100644 --- a/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java +++ b/jaxp/src/java.xml/share/classes/javax/xml/stream/XMLOutputFactory.java @@ -102,7 +102,7 @@ import javax.xml.transform.Result; * namespace URI of the element or attribute using that prefix.

    * * @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 @@ public abstract class XMLOutputFactory { * This static method creates a new factory instance. This method uses the * following ordered lookup procedure to determine the XMLOutputFactory * implementation class to load: - *

    + *

    *