https://openjdk.java.net/ 
/*
 * Copyright (c) 2003, 2017, 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
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.xml.xpath;

import com.sun.org.apache.xpath.internal.jaxp.XPathFactoryImpl;
import jdk.xml.internal.SecuritySupport;


An XPathFactory instance can be used to create XPath objects.


See newInstance(String uri) for lookup mechanism.


The XPathFactory class is not thread-safe. In other words, it is the application's responsibility to ensure that at most one thread is using a XPathFactory object at any given moment. Implementations are encouraged to mark methods as synchronized to protect themselves from broken clients.

XPathFactory is not re-entrant. While one of the newInstance methods is being invoked, applications
may not attempt to recursively invoke a newInstance method,
even from the same thread.

Author: Norman Walsh,  Jeff Suttor
Since:1.5
/**
 * <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>
 *
 * <p>The {@link XPathFactory} class is not thread-safe. In other words,
 * it is the application's responsibility to ensure that at most
 * one thread is using a {@link XPathFactory} object at any
 * given moment. Implementations are encouraged to mark methods
 * as <code>synchronized</code> to protect themselves from broken clients.
 *
 * <p>{@link XPathFactory} is not re-entrant. While one of the
 * <code>newInstance</code> methods is being invoked, applications
 * may not attempt to recursively invoke a <code>newInstance</code> method,
 * even from the same thread.
 *
 * @author  Norman Walsh
 * @author  Jeff Suttor
 *
 * @since 1.5
 */
public abstract class XPathFactory {


    
The default property name according to the JAXP spec.


/**
     * <p>The default property name according to the JAXP spec.</p>
     */
    public static final String DEFAULT_PROPERTY_NAME = "javax.xml.xpath.XPathFactory";

    
Default Object Model URI.


/**
     * <p>Default Object Model URI.</p>
     */
    public static final String DEFAULT_OBJECT_MODEL_URI = "http://java.sun.com/jaxp/xpath/dom";

    
Protected constructor as newInstance() or newInstance(String uri) or newInstance(String uri, String factoryClassName, ClassLoader classLoader) should be used to create a new instance of an XPathFactory.


/**
     * <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}.</p>
     */
    protected XPathFactory() {
    }

    
Creates a new instance of the XPathFactory builtin system-default implementation. 
Implementation Requirements:The XPathFactory builtin system-default implementation is only required to support the default object model, the W3C DOM, but may support additional object models.
Returns:A new instance of the XPathFactory builtin system-default implementation.
Since:9
/**
     * Creates a new instance of the {@code XPathFactory} builtin
     * system-default implementation.
     *
     * @implSpec The {@code XPathFactory} builtin
     * system-default implementation is only required to support the
     * {@link #DEFAULT_OBJECT_MODEL_URI default object model}, the
     * {@linkplain org.w3c.dom W3C DOM}, but may support additional
     * object models.
     *
     * @return A new instance of the {@code XPathFactory} builtin
     *         system-default implementation.
     *
     * @since 9
     */
    public static XPathFactory newDefaultInstance() {
        return new XPathFactoryImpl();
    }

    
Get a new XPathFactory instance using the default object model, DEFAULT_OBJECT_MODEL_URI, the W3C DOM.


This method is functionally equivalent to:


  newInstance(DEFAULT_OBJECT_MODEL_URI)



Since the implementation for the W3C DOM is always available, this method will never fail.


Throws:
  • RuntimeException – When there is a failure in creating an XPathFactory for the default object model.
Returns:Instance of an XPathFactory.
/**
     * <p>Get a new {@code XPathFactory} instance using the default object model,
     * {@link #DEFAULT_OBJECT_MODEL_URI},
     * the W3C DOM.</p>
     *
     * <p>This method is functionally equivalent to:</p>
     * <pre>
     *   newInstance(DEFAULT_OBJECT_MODEL_URI)
     * </pre>
     *
     * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p>
     *
     * @return Instance of an {@code XPathFactory}.
     *
     * @throws RuntimeException When there is a failure in creating an
     *   {@code XPathFactory} for the default object model.
     */
    public static XPathFactory newInstance() {

        try {
            return newInstance(DEFAULT_OBJECT_MODEL_URI);
        } catch (XPathFactoryConfigurationException e) {
            throw new RuntimeException(
                    "XPathFactory#newInstance() failed to create an XPathFactory for the default object model: "
                    + DEFAULT_OBJECT_MODEL_URI
                    + " with the XPathFactoryConfigurationException: "
                    + e.getMessage(), e
            );
        }
    }

    
Get a new XPathFactory instance using the specified object model.


To find a XPathFactory object, this method looks the following places in the following order where "the class loader" refers to the context class loader:


    
  
  1. 
    
     If the system property 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. 
    2. 
  
  2. 
    
     Use the configuration file "jaxp.properties". The file is in standard Properties format and typically located in the conf directory of the Java installation. It contains the fully qualified name of the implementation class with the key being the system property defined above. 
    
    The 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. 
    
     Use the service-provider loading facility, defined by the ServiceLoader class, to attempt to locate and load an implementation of the service using the default loading mechanism: the service-provider loading facility will use the current thread's context class loader to attempt to load the service. If the context class loader is null, the system class loader will be used. 
     Each potential service provider is required to implement the method isObjectModelSupported(String objectModel). The first service provider found that supports the specified object model is returned. 
     In case of ServiceConfigurationError an XPathFactoryConfigurationException will be thrown. 
    4. 
  
  4. 
    
     Platform default XPathFactory is located in a platform specific way. There must be a platform default XPathFactory for the W3C DOM, i.e. DEFAULT_OBJECT_MODEL_URI. 
    5. 



If everything fails, an XPathFactoryConfigurationException will be thrown. 
Tip for Trouble-shooting:

See Properties.load(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: 
  http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory



Params:
  • uri – Identifies the underlying object model. The specification only defines the URI DEFAULT_OBJECT_MODEL_URI, http://java.sun.com/jaxp/xpath/dom for the W3C DOM,
  the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
Throws:
Returns:Instance of an 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.
    *
    * <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:
    * <pre>
    *   http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory
    * </pre>
    *
    * @param uri Identifies the underlying object model.
    *   The specification only defines the URI {@link #DEFAULT_OBJECT_MODEL_URI},
    *   <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}.
    *
    * @throws XPathFactoryConfigurationException If the specified object model
    *      is unavailable, or if there is a configuration error.
    * @throws NullPointerException If <code>uri</code> is <code>null</code>.
    * @throws IllegalArgumentException If <code>uri</code> is <code>null</code>
    *   or <code>uri.length() == 0</code>.
    */
    public static XPathFactory newInstance(final String uri)
        throws XPathFactoryConfigurationException {

        if (uri == null) {
            throw new NullPointerException(
                    "XPathFactory#newInstance(String uri) cannot be called with uri == null");
        }

        if (uri.length() == 0) {
            throw new IllegalArgumentException(
                    "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"");
        }

        ClassLoader classLoader = SecuritySupport.getContextClassLoader();

        if (classLoader == null) {
            //use the current class loader
            classLoader = XPathFactory.class.getClassLoader();
        }

        XPathFactory xpathFactory = new XPathFactoryFinder(classLoader).newFactory(uri);

        if (xpathFactory == null) {
            throw new XPathFactoryConfigurationException(
                    "No XPathFactory implementation found for the object model: "
                    + uri);
        }

        return xpathFactory;
    }

    
Obtain a new instance of a XPathFactory from a factory class name. 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 should be loaded.


Tip for Trouble-shooting


Setting the 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.


 If you have problems try:


java -Djaxp.debug=1 YourProgram ....



Params:
  • uri –  Identifies the underlying object model. The specification only defines the URI DEFAULT_OBJECT_MODEL_URI,http://java.sun.com/jaxp/xpath/dom
                   for the W3C DOM, the org.w3c.dom package, and implementations are free to introduce
                   other URIs for other object models.
  • factoryClassName – fully qualified factory class name that provides implementation of javax.xml.xpath.XPathFactory.
  • classLoader – ClassLoader used to load the factory class. If null
                    current Thread's context classLoader is used to load the factory class.
Throws:
See Also:
Returns:New instance of a XPathFactory
Since:1.6
/**
     * <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
     * should be loaded.</p>
     *
     *
     * <h2>Tip for Trouble-shooting</h2>
     * <p>Setting the <code>jaxp.debug</code> 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>
     *
     * <p> If you have problems try:</p>
     * <pre>
     * java -Djaxp.debug=1 YourProgram ....
     * </pre>
     *
     * @param uri         Identifies the underlying object model. The specification only defines the URI
     *                    {@link #DEFAULT_OBJECT_MODEL_URI},<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.
     *
     * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.xpath.XPathFactory</code>.
     *
     * @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 XPathFactory}
     *
     * @throws XPathFactoryConfigurationException
     *                   if <code>factoryClassName</code> is <code>null</code>, or
     *                   the factory class cannot be loaded, instantiated
     *                   or the factory class does not support the object model specified
     *                   in the <code>uri</code> parameter.
     *
     * @throws NullPointerException If <code>uri</code> is <code>null</code>.
     * @throws IllegalArgumentException If <code>uri</code> is <code>null</code>
     *          or <code>uri.length() == 0</code>.
     *
     * @see #newInstance()
     * @see #newInstance(String uri)
     *
     * @since 1.6
     */
    public static XPathFactory newInstance(String uri, String factoryClassName, ClassLoader classLoader)
        throws XPathFactoryConfigurationException{
        ClassLoader cl = classLoader;

        if (uri == null) {
            throw new NullPointerException(
                    "XPathFactory#newInstance(String uri) cannot be called with uri == null");
        }

        if (uri.length() == 0) {
            throw new IllegalArgumentException(
                    "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"");
        }

        if (cl == null) {
            cl = SecuritySupport.getContextClassLoader();
        }

        XPathFactory f = new XPathFactoryFinder(cl).createInstance(factoryClassName);

        if (f == null) {
            throw new XPathFactoryConfigurationException(
                    "No XPathFactory implementation found for the object model: "
                    + uri);
        }
        //if this factory supports the given schemalanguage return this factory else thrown exception
        if (f.isObjectModelSupported(uri)) {
            return f;
        } else {
            throw new XPathFactoryConfigurationException("Factory "
                    + factoryClassName + " doesn't support given " + uri
                    + " object model");
        }

    }

    
Is specified object model supported by this XPathFactory?


Params:
  • objectModel – Specifies the object model which the returned XPathFactory will understand.
Throws:
Returns:true if XPathFactory supports objectModel, else false.
/**
     * <p>Is specified object model supported by this {@code XPathFactory}?</p>
     *
     * @param objectModel Specifies the object model which the returned {@code XPathFactory} will understand.
     *
     * @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>.
     */
    public abstract boolean isObjectModelSupported(String objectModel);

    
Set a feature for this XPathFactory and XPaths created by this factory.


 Feature names are fully qualified URIs. Implementations may define their own features. An XPathFactoryConfigurationException is thrown if this XPathFactory or the XPaths it creates cannot support the feature. It is possible for an XPathFactory to expose a feature value but be unable to change its state. 


 All implementations are required to support the XMLConstants.FEATURE_SECURE_PROCESSING feature. When the feature is true, any reference to an external function is an error. Under these conditions, the implementation must not call the XPathFunctionResolver and must throw an XPathFunctionException. 


Params:
  • name – Feature name.
  • value – Is feature state true or false.
Throws:
/**
     * <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} or the <code>XPath</code>s
     * it creates cannot support the feature.
     * It is possible for an {@code XPathFactory} 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.
     * When the feature is <code>true</code>, any reference to  an external function is an error.
     * Under these conditions, the implementation must not call the {@link XPathFunctionResolver}
     * and must throw an {@link XPathFunctionException}.
     * </p>
     *
     * @param name Feature name.
     * @param value Is feature state <code>true</code> or <code>false</code>.
     *
     * @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>.
     */
    public abstract void setFeature(String name, boolean value)
            throws XPathFactoryConfigurationException;

    
Get the state of the named feature.


 Feature names are fully qualified URIs. Implementations may define their own features. An XPathFactoryConfigurationException is thrown if this XPathFactory or the XPaths it creates cannot support the feature. It is possible for an XPathFactory to expose a feature value but be unable to change its state. 


Params:
  • name – Feature name.
Throws:
Returns:State of the named feature.
/**
     * <p>Get the state of the named feature.</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} or the <code>XPath</code>s
     * it creates cannot support the feature.
     * It is possible for an {@code XPathFactory} to expose a feature value
     * but be unable to change its state.
     * </p>
     *
     * @param name Feature name.
     *
     * @return State of the named feature.
     *
     * @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>.
     */
    public abstract boolean getFeature(String name)
            throws XPathFactoryConfigurationException;

    
Establish a default variable resolver.


Any XPath objects constructed from this factory will use
the specified resolver by default.


A NullPointerException is thrown if resolver
is null.


Params:
  • resolver – Variable resolver.
Throws:
/**
     * <p>Establish a default variable resolver.</p>
     *
     * <p>Any <code>XPath</code> objects constructed from this factory will use
     * the specified resolver by default.</p>
     *
     * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code>
     * is <code>null</code>.</p>
     *
     * @param resolver Variable resolver.
     *
     * @throws NullPointerException If <code>resolver</code> is
     *   <code>null</code>.
     */
    public abstract void setXPathVariableResolver(XPathVariableResolver resolver);

    
Establish a default function resolver.


Any XPath objects constructed from this factory will
use the specified resolver by default.


A NullPointerException is thrown if
resolver is null.


Params:
  • resolver – XPath function resolver.
Throws:
/**
     * <p>Establish a default function resolver.</p>
     *
     * <p>Any <code>XPath</code> objects constructed from this factory will
     * use the specified resolver by default.</p>
     *
     * <p>A <code>NullPointerException</code> is thrown if
     * <code>resolver</code> is <code>null</code>.</p>
     *
     * @param resolver XPath function resolver.
     *
     * @throws NullPointerException If <code>resolver</code> is
     *   <code>null</code>.
     */
    public abstract void setXPathFunctionResolver(XPathFunctionResolver resolver);

    
Return a new XPath using the underlying object model determined when the XPathFactory was instantiated.


Returns:New instance of an XPath.
/**
    * <p>Return a new <code>XPath</code> using the underlying object
    * model determined when the {@code XPathFactory} was instantiated.</p>
    *
    * @return New instance of an <code>XPath</code>.
    */
    public abstract XPath newXPath();
}