8261673: Move javadoc for the lookup mechanism to module-info
Reviewed-by: lancea, naoto, iris
This commit is contained in:
Joe Wang
parent
7b6efd3b86
commit
289d48ae32
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2000, 2021, 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
|
||||
@ -139,53 +139,14 @@ public abstract class DocumentBuilderFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Obtain a new instance of a
|
||||
* {@code DocumentBuilderFactory}. This static method creates
|
||||
* a new factory instance.
|
||||
* This method uses the following ordered lookup procedure to determine
|
||||
* the {@code DocumentBuilderFactory} implementation class to
|
||||
* load:
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the {@code javax.xml.parsers.DocumentBuilderFactory} system
|
||||
* property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@linkplain #newDefaultInstance() system-default}
|
||||
* implementation is returned.
|
||||
* </li>
|
||||
* </ul>
|
||||
* Obtains a new instance of a {@code DocumentBuilderFactory}.
|
||||
* This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code DocumentBuilderFactory} implementation class to load.
|
||||
*
|
||||
* <p>
|
||||
* Once an application has obtained a reference to a
|
||||
* {@code DocumentBuilderFactory} it can use the factory to
|
||||
* {@code DocumentBuilderFactory}, it can use the factory to
|
||||
* configure and obtain parser instances.
|
||||
*
|
||||
*
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2000, 2021, 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
|
||||
@ -145,52 +145,14 @@ public abstract class SAXParserFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* 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} implementation class to
|
||||
* load:
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the {@code javax.xml.parsers.SAXParserFactory} system
|
||||
* property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@linkplain #newDefaultInstance() system-default}
|
||||
* implementation is returned.
|
||||
* </li>
|
||||
* </ul>
|
||||
* Obtains a new instance of a {@code SAXParserFactory}.
|
||||
* This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code SAXParserFactory} implementation class to load.
|
||||
*
|
||||
* <p>
|
||||
* Once an application has obtained a reference to a
|
||||
* {@code SAXParserFactory} it can use the factory to
|
||||
* {@code SAXParserFactory}, it can use the factory to
|
||||
* configure and obtain parser instances.
|
||||
*
|
||||
*
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2009, 2021, 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
|
||||
@ -81,56 +81,12 @@ public abstract class XMLEventFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new instance of the factory.
|
||||
* Creates a new instance of the factory. This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code XMLEventFactory} implementation class to load.
|
||||
* <p>
|
||||
* This static method creates a new factory instance.
|
||||
* This method uses the following ordered lookup procedure to determine
|
||||
* the XMLEventFactory implementation class to load:
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the javax.xml.stream.XMLEventFactory system property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* 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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@linkplain #newDefaultFactory() 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.
|
||||
* Once an application has obtained a reference to a {@code XMLEventFactory}, it
|
||||
* can use the factory to configure and obtain stream instances.
|
||||
*
|
||||
* @return an instance of the {@code XMLEventFactory}
|
||||
* @throws FactoryConfigurationError in case of {@linkplain
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2009, 2021, 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
|
||||
@ -167,53 +167,12 @@ public abstract class XMLInputFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new instance of the factory.
|
||||
* Creates a new instance of the factory. This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code XMLInputFactory} implementation class to load.
|
||||
* <p>
|
||||
* This static method creates a new factory instance.
|
||||
* This method uses the following ordered lookup procedure to determine
|
||||
* the XMLInputFactory implementation class to load:
|
||||
*
|
||||
* <ul>
|
||||
* <li>
|
||||
* <p>Use the javax.xml.stream.XMLInputFactory system property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>Otherwise, the {@linkplain #newDefaultFactory() system-default}
|
||||
* implementation is returned.
|
||||
* </li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* Once an application has obtained a reference to a XMLInputFactory it
|
||||
* can use the factory to configure and obtain stream instances.
|
||||
* Once an application has obtained a reference to a {@code XMLInputFactory}, it
|
||||
* can use the factory to configure and obtain stream instances.
|
||||
*
|
||||
* @return an instance of the {@code XMLInputFactory}
|
||||
* @throws FactoryConfigurationError in case of {@linkplain
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2009, 2021, 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
|
||||
@ -144,55 +144,11 @@ public abstract class XMLOutputFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Create a new instance of the factory.
|
||||
* Creates a new instance of the factory. This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code XMLOutputFactory} implementation class to load.
|
||||
* <p>
|
||||
* This static method creates a new factory instance. This method uses the
|
||||
* following ordered lookup procedure to determine the XMLOutputFactory
|
||||
* implementation class to load:
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the javax.xml.stream.XMLOutputFactory system property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* 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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@linkplain #newDefaultFactory() system-default}
|
||||
* implementation is returned.
|
||||
* </li>
|
||||
* </ul>
|
||||
* <p>
|
||||
* Once an application has obtained a reference to a XMLOutputFactory it
|
||||
* Once an application has obtained a reference to a {@code XMLOutputFactory}, it
|
||||
* can use the factory to configure and obtain stream instances.
|
||||
*
|
||||
* @return an instance of the {@code XMLOutputFactory}
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2000, 2021, 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
|
||||
@ -66,52 +66,12 @@ public abstract class TransformerFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* 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:
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the {@code javax.xml.transform.TransformerFactory} system
|
||||
* property.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@linkplain #newDefaultInstance() system-default}
|
||||
* implementation is returned.
|
||||
* </li>
|
||||
* </ul>
|
||||
*
|
||||
* Obtains a new instance of a {@code TransformerFactory}. This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine the {@code TransformerFactory} implementation class to load.
|
||||
* <p>
|
||||
* Once an application has obtained a reference to a
|
||||
* {@code TransformerFactory} it can use the factory to configure
|
||||
* {@code TransformerFactory}, it can use the factory to configure
|
||||
* and obtain transformer instances.
|
||||
*
|
||||
* @return new TransformerFactory instance, never null.
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2021, 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
|
||||
@ -143,68 +143,11 @@ public abstract class SchemaFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* Lookup an implementation of the {@code SchemaFactory} that supports the specified
|
||||
* schema language and return it.
|
||||
*
|
||||
* <p>To find a {@code SchemaFactory} object for a given schema language,
|
||||
* this method looks the following places in the following order
|
||||
* where "the class loader" refers to the context class loader:
|
||||
* <ol>
|
||||
* <li>
|
||||
* <p>
|
||||
* If the system property
|
||||
* {@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
|
||||
* create a new instance of this class by using the class loader,
|
||||
* and returns it if it is successfully created.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* <br>
|
||||
* Each potential service provider is required to implement the method
|
||||
* {@link #isSchemaLanguageSupported(String schemaLanguage)}.
|
||||
* <br>
|
||||
* The first service provider found that supports the specified schema
|
||||
* language is returned.
|
||||
* <br>
|
||||
* In case of {@link java.util.ServiceConfigurationError} a
|
||||
* {@link SchemaFactoryConfigurationError} will be thrown.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Platform default {@code SchemaFactory} is located
|
||||
* in an implementation specific way. There must be a
|
||||
* {@linkplain #newDefaultInstance() platform default}
|
||||
* {@code SchemaFactory} for W3C XML Schema.
|
||||
* </li>
|
||||
* </ol>
|
||||
*
|
||||
* <p>If everything fails, {@link IllegalArgumentException} will be thrown.
|
||||
* Obtains a new instance of a {@code SchemaFactory} that supports
|
||||
* the specified schema language. This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine and load the {@code SchemaFactory} implementation that supports
|
||||
* the specified schema language.
|
||||
*
|
||||
* <h4>Tip for Trouble-shooting:</h4>
|
||||
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
/*
|
||||
* Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 2003, 2021, 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
|
||||
@ -122,62 +122,11 @@ public abstract class XPathFactory {
|
||||
}
|
||||
|
||||
/**
|
||||
* <p>Get a new {@code XPathFactory} instance using the specified object model.</p>
|
||||
*
|
||||
* <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>
|
||||
* <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>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
* <br>
|
||||
* Each potential service provider is required to implement the method
|
||||
* {@link #isObjectModelSupported(String objectModel)}.
|
||||
* The first service provider found that supports the specified object
|
||||
* model is returned.
|
||||
* <br>
|
||||
* In case of {@link java.util.ServiceConfigurationError} an
|
||||
* {@link XPathFactoryConfigurationException} will be thrown.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Platform default {@code XPathFactory} is located in a platform
|
||||
* specific way.
|
||||
* There must be a {@linkplain #newDefaultInstance() platform default}
|
||||
* {@code XPathFactory} for the W3C DOM, i.e.
|
||||
* {@link #DEFAULT_OBJECT_MODEL_URI}.
|
||||
* </li>
|
||||
* </ol>
|
||||
* <p>If everything fails, an {@code XPathFactoryConfigurationException} will be thrown.
|
||||
* Obtains a new {@code XPathFactory} instance using the specified object model.
|
||||
* This method uses the
|
||||
* <a href="../../../module-summary.html#LookupMechanism">JAXP Lookup Mechanism</a>
|
||||
* to determine and load the {@code XPathFactory} implementation that supports
|
||||
* the specified object model.
|
||||
*
|
||||
* <p>Tip for Trouble-shooting:
|
||||
* <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed.
|
||||
|
||||
@ -27,6 +27,199 @@
|
||||
* Defines the Java API for XML Processing (JAXP), the Streaming API for XML (StAX),
|
||||
* the Simple API for XML (SAX), and the W3C Document Object Model (DOM) API.
|
||||
*
|
||||
* <h2 id="LookupMechanism">JAXP Lookup Mechanism</h2>
|
||||
* JAXP defines an ordered lookup procedure to determine the implementation class
|
||||
* to load for the JAXP factories. Factories that support the mechanism are listed
|
||||
* in the table below along with the method, System Property name, Configuration
|
||||
* File, and System Default method to be used in the procedure.
|
||||
*
|
||||
* <table class="plain" id="Factories">
|
||||
* <caption>JAXP Factories</caption>
|
||||
* <thead>
|
||||
* <tr>
|
||||
* <th scope="col">Factory</th>
|
||||
* <th scope="col">Method</th>
|
||||
* <th scope="col">System Property Name</th>
|
||||
* <th scope="col">Configuration File</th>
|
||||
* <th scope="col">System Default</th>
|
||||
* </tr>
|
||||
* </thead>
|
||||
*
|
||||
* <tbody>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="DOM">
|
||||
* {@link javax.xml.parsers.DocumentBuilderFactory DocumentBuilderFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.parsers.DocumentBuilderFactory#newInstance() newInstance()}</td>
|
||||
* <td>{@code javax.xml.parsers.DocumentBuilderFactory}</td>
|
||||
* <td><a href="#JaxpProperties">jaxp.properties</a></td>
|
||||
* <td>{@link javax.xml.parsers.DocumentBuilderFactory#newDefaultInstance() newDefaultInstance()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="SAX">
|
||||
* {@link javax.xml.parsers.SAXParserFactory SAXParserFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.parsers.SAXParserFactory#newInstance() newInstance()}</td>
|
||||
* <td>{@code javax.xml.parsers.SAXParserFactory}</td>
|
||||
* <td><a href="#JaxpProperties">jaxp.properties</a></td>
|
||||
* <td>{@link javax.xml.parsers.SAXParserFactory#newDefaultInstance() newDefaultInstance()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="StAXEvent">
|
||||
* {@link javax.xml.stream.XMLEventFactory XMLEventFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.stream.XMLEventFactory#newFactory() newFactory()}</td>
|
||||
* <td>{@code javax.xml.stream.XMLEventFactory}</td>
|
||||
* <td>
|
||||
* <a href="#StAXProperties">stax.properties</a> and then
|
||||
* <a href="#JaxpProperties">jaxp.properties</a>
|
||||
* </td>
|
||||
* <td>{@link javax.xml.stream.XMLEventFactory#newDefaultFactory() newDefaultFactory()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="StAXInput">
|
||||
* {@link javax.xml.stream.XMLInputFactory XMLInputFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.stream.XMLInputFactory#newFactory() newFactory()}</td>
|
||||
* <td>{@code javax.xml.stream.XMLInputFactory}</td>
|
||||
* <td>
|
||||
* <a href="#StAXProperties">stax.properties</a> and then
|
||||
* <a href="#JaxpProperties">jaxp.properties</a>
|
||||
* </td>
|
||||
* <td>{@link javax.xml.stream.XMLInputFactory#newDefaultFactory() newDefaultFactory()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="StAXOutput">
|
||||
* {@link javax.xml.stream.XMLOutputFactory XMLOutputFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.stream.XMLOutputFactory#newFactory() newFactory()}</td>
|
||||
* <td>{@code javax.xml.stream.XMLOutputFactory}</td>
|
||||
* <td>
|
||||
* <a href="#StAXProperties">stax.properties</a> and then
|
||||
* <a href="#JaxpProperties">jaxp.properties</a>
|
||||
* </td>
|
||||
* <td>{@link javax.xml.stream.XMLOutputFactory#newDefaultFactory() newDefaultFactory()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="XSLT">
|
||||
* {@link javax.xml.transform.TransformerFactory TransformerFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.transform.TransformerFactory#newInstance() newInstance()}</td>
|
||||
* <td>{@code javax.xml.transform.TransformerFactory}</td>
|
||||
* <td><a href="#JaxpProperties">jaxp.properties</a></td>
|
||||
* <td>{@link javax.xml.transform.TransformerFactory#newDefaultInstance() newDefaultInstance()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="Validation">
|
||||
* {@link javax.xml.validation.SchemaFactory SchemaFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.validation.SchemaFactory#newInstance(java.lang.String) newInstance(schemaLanguage)}</td>
|
||||
* <td>{@code javax.xml.validation.SchemaFactory:}<i>schemaLanguage</i>[1]</td>
|
||||
* <td><a href="#JaxpProperties">jaxp.properties</a></td>
|
||||
* <td>{@link javax.xml.validation.SchemaFactory#newDefaultInstance() newDefaultInstance()}</td>
|
||||
* </tr>
|
||||
* <tr>
|
||||
* <th scope="row" style="font-weight:normal" id="XPath">
|
||||
* {@link javax.xml.xpath.XPathFactory XPathFactory}
|
||||
* </th>
|
||||
* <td>{@link javax.xml.xpath.XPathFactory#newInstance(java.lang.String) newInstance(uri)}</td>
|
||||
* <td>{@link javax.xml.xpath.XPathFactory#DEFAULT_PROPERTY_NAME DEFAULT_PROPERTY_NAME} + ":uri"[2]</td>
|
||||
* <td><a href="#JaxpProperties">jaxp.properties</a></td>
|
||||
* <td>{@link javax.xml.xpath.XPathFactory#newDefaultInstance() newDefaultInstance()}</td>
|
||||
* </tr>
|
||||
* </tbody>
|
||||
* </table>
|
||||
*
|
||||
* <b>[1]</b> where <i>schemaLanguage</i> is the parameter to the
|
||||
* {@link javax.xml.validation.SchemaFactory#newInstance(java.lang.String) newInstance(schemaLanguage)}
|
||||
* method.
|
||||
* <p>
|
||||
* <b>[2]</b> where <i>uri</i> is the parameter to the
|
||||
* {@link javax.xml.xpath.XPathFactory#newInstance(java.lang.String) newInstance(uri)}
|
||||
* method.
|
||||
*
|
||||
* <h3 id="JaxpProperties">jaxp.properties</h3>
|
||||
* {@code jaxp.properties} is a configuration file 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 name
|
||||
* defined in <a href="#Factories">the table</a> above.
|
||||
* <p>
|
||||
* The {@code jaxp.properties} file is read only once by the implementation and
|
||||
* the 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 after it has been read for the first time.
|
||||
*
|
||||
* <h3 id="StAXProperties">stax.properties</h3>
|
||||
* {@code stax.properties} is a configuration file that functions the same as
|
||||
* {@code jaxp.properties} except that it is only used by StAX factory lookup.
|
||||
*
|
||||
* <h3 id="LookupProcedure">Lookup Procedure</h3>
|
||||
* The <a href="#Factories">JAXP Factories</a> follow the procedure described
|
||||
* below in order to locate and load the implementation class:
|
||||
*
|
||||
* <ul>
|
||||
* <li>
|
||||
* Use the system property as described in column System Property of the table
|
||||
* <a href="#Factories">JAXP Factories</a> above.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Use the configuration file <a href="#JaxpProperties">jaxp.properties</a> as
|
||||
* indicated in the table <a href="#Factories">JAXP Factories</a>. For StAX,
|
||||
* if <a href="#StAXProperties">stax.properties</a> exists, the factories will
|
||||
* first attempt to read from it instead of <a href="#JaxpProperties">jaxp.properties</a>.
|
||||
* </li>
|
||||
* <li>
|
||||
* <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
|
||||
* java.lang.Thread#getContextClassLoader() current thread's context class loader}
|
||||
* to attempt to load the service. If the context class
|
||||
* loader is null, the {@linkplain
|
||||
* ClassLoader#getSystemClassLoader() system class loader} will be used.
|
||||
*
|
||||
* <h3>{@link javax.xml.validation.SchemaFactory SchemaFactory}</h3>
|
||||
* In case of the {@link javax.xml.validation.SchemaFactory SchemaFactory},
|
||||
* each potential service provider is required to implement the method
|
||||
* {@link javax.xml.validation.SchemaFactory#isSchemaLanguageSupported(java.lang.String)
|
||||
* isSchemaLanguageSupported(String schemaLanguage)}.
|
||||
* The first service provider found that supports the specified schema language
|
||||
* is returned.
|
||||
*
|
||||
* <h3>{@link javax.xml.xpath.XPathFactory XPathFactory}</h3>
|
||||
* In case of the {@link javax.xml.xpath.XPathFactory XPathFactory},
|
||||
* each potential service provider is required to implement the method
|
||||
* {@link javax.xml.xpath.XPathFactory#isObjectModelSupported(String objectModel)
|
||||
* isObjectModelSupported(String objectModel)}.
|
||||
* The first service provider found that supports the specified object model is
|
||||
* returned.
|
||||
* </li>
|
||||
* <li>
|
||||
* <p>
|
||||
* Otherwise, the {@code system-default} implementation is returned, which is
|
||||
* equivalent to calling the {@code newDefaultInstance() or newDefaultFactory()}
|
||||
* method as shown in column System Default of the table
|
||||
* <a href="#Factories">JAXP Factories</a> above.
|
||||
*
|
||||
* <h3>{@link javax.xml.validation.SchemaFactory SchemaFactory}</h3>
|
||||
* In case of the {@link javax.xml.validation.SchemaFactory SchemaFactory},
|
||||
* there must be a {@linkplain javax.xml.validation.SchemaFactory#newDefaultInstance()
|
||||
* platform default} {@code SchemaFactory} for W3C XML Schema.
|
||||
*
|
||||
* <h3>{@link javax.xml.xpath.XPathFactory XPathFactory}</h3>
|
||||
* In case of the {@link javax.xml.xpath.XPathFactory XPathFactory},
|
||||
* there must be a
|
||||
* {@linkplain javax.xml.xpath.XPathFactory#newDefaultInstance() platform default}
|
||||
* {@code XPathFactory} for the W3C DOM, i.e.
|
||||
* {@link javax.xml.xpath.XPathFactory#DEFAULT_OBJECT_MODEL_URI DEFAULT_OBJECT_MODEL_URI}.
|
||||
* </li>
|
||||
* </ul>
|
||||
*
|
||||
* @implNote
|
||||
* <h2>Implementation Specific Features and Properties</h2>
|
||||
*
|
||||
@ -79,15 +272,12 @@
|
||||
* to the creation of a processor and may be cleared afterwards.
|
||||
*
|
||||
* <h3>jaxp.properties</h3>
|
||||
* A system property can be specified in the {@code jaxp.properties} file to
|
||||
* set the behavior for all invocations of the JDK. The format is
|
||||
* A system property can be specified in the <a href="#JaxpProperties">jaxp.properties</a>
|
||||
* file to set the behavior for all invocations of the JDK. The format is
|
||||
* {@code system-property-name=value}. For example:
|
||||
* <pre>
|
||||
* {@code jdk.xml.isStandalone=true}
|
||||
* </pre>
|
||||
* <p>
|
||||
* For details about the JAXP configuration file {@code jaxp.properties}, refer to
|
||||
* {@link javax.xml.parsers.SAXParserFactory#newInstance() SAXParserFactory#newInstance}.
|
||||
*
|
||||
* <h3 id="ScopeAndOrder">Scope and Order</h3>
|
||||
* The {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user