Module  java.xml
软件包  javax.xml.xpath

Interface XPath


  • public interface XPath
    XPath提供对XPath评估环境和表达式的访问。 XPath评估受下表中描述的因素的影响。 Evaluation of XPath Expressions Factor Behavior context The type of the context is implementation-dependent. If the value is null, the operation must have no dependency on the context, otherwise an XPathExpressionException will be thrown. For the purposes of evaluating XPath expressions, a DocumentFragment is treated like a Document node. variables If the expression contains a variable reference, its value will be found through the XPathVariableResolver set with setXPathVariableResolver(XPathVariableResolver resolver). An XPathExpressionException is raised if the variable resolver is undefined or the resolver returns null for the variable. The value of a variable must be immutable through the course of any single evaluation. functions If the expression contains a function reference, the function will be found through the XPathFunctionResolver set with setXPathFunctionResolver(XPathFunctionResolver resolver). An XPathExpressionException is raised if the function resolver is undefined or the function resolver returns null for the function. QNames QNames in the expression are resolved against the XPath namespace context set with setNamespaceContext(NamespaceContext nsContext). result This result of evaluating an expression is converted to an instance of the desired return type. Valid return types are defined in XPathConstants. Conversion to the return type follows XPath conversion rules.

    XPath对象不是线程安全的，不可重入。 换句话说，应用程序有责任确保在任何给定时间从多个线程中不使用一个XPath对象，而在调用evaluate方法时，应用程序可能不会递归调用evaluate方法。

    从以下版本开始：
    1.5
    另请参见：
    XML Path Language (XPath) Version 1.0

    • 方法详细信息

      • setXPathVariableResolver

        void setXPathVariableResolver​(XPathVariableResolver resolver)
        建立变量解析器。

        一个NullPointerException如果抛出resolver为null 。

        参数
        resolver - 可变 resolver器。
        异常
        NullPointerException - 如果 resolver是 null 。

      • getXPathVariableResolver

        XPathVariableResolver getXPathVariableResolver​()
        返回当前变量解析器。

        null返回的无变量解析器是有效的。

        结果
        当前变量解算器。

      • setXPathFunctionResolver

        void setXPathFunctionResolver​(XPathFunctionResolver resolver)
        建立一个函数解析器。

        一个NullPointerException如果抛出resolver为null 。

        参数
        resolver - XPath函数解析器。
        异常
        NullPointerException - 如果 resolver是 null 。

      • getXPathFunctionResolver

        XPathFunctionResolver getXPathFunctionResolver​()
        返回当前函数解析器。

        null返回无功能解析器有效。

        结果
        当前功能解析器。

      • setNamespaceContext

        void setNamespaceContext​(NamespaceContext nsContext)
        建立命名空间上下文。

        一个NullPointerException如果抛出nsContext为null 。

        参数
        nsContext - 要使用的命名空间上下文。
        异常
        NullPointerException - 如果 nsContext是 null 。

      • getNamespaceContext

        NamespaceContext getNamespaceContext​()
        返回当前命名空间上下文。

        null返回的没有命名空间上下文是有效的。

        结果
        当前命名空间上下文。

      • evaluate

        Object evaluate​(String expression,
                Object item,
                QName returnType)
         throws XPathExpressionException
        在指定的上下文中评估一个XPath表达式，并将结果作为指定的类型返回。

        有关上下文项目评估，变量，函数和QName分辨率和返回类型转换，请参见Evaluation of XPath Expressions 。

        参数item表示将运行XPath表达式的上下文。 上下文的类型取决于实现。 如果值为null ，则操作必须与上下文无关，否则将抛出XPathExpressionException异常。

        Implementation Note:
        上下文的类型通常为Node 。
        参数
        expression - XPath表达式。
        item - 将评估XPath表达式的上下文。
        returnType - 预期由XPath表达式返回的结果类型。
        结果
        评估XPath表达式的结果为 Object的 returnType 。
        异常
        XPathExpressionException - 如果不能评估 expression 。
        IllegalArgumentException -如果returnType不在定义的类型的一个XPathConstants （ NUMBER ， STRING ， BOOLEAN ， NODE或NODESET ）。
        NullPointerException - 如果 expression or returnType是 null 。

      • evaluateExpression

        default <T> T evaluateExpression​(String expression,
                                 Object item,
                                 Class<T> type)
                          throws XPathExpressionException
        评估指定上下文中的XPath表达式，并返回结果，并使用class type指定的类型

        参数item表示将运行XPath表达式的上下文。 上下文的类型取决于实现。 如果值为null ，则操作必须与上下文无关，否则将抛出XPathExpressionException异常。

        实现要求：
        XPath API中的默认实现相当于： 
           (T)evaluate(expression, item, XPathEvaluationResult.XPathResultType.getQNameType(type));
        由于evaluate方法不支持ANY类型，因此指定XPathEvaluationResult类型将导致IllegalArgumentException。 任何支持ANY类型的实现都必须覆盖此方法。
        Implementation Note:
        上下文的类型通常为Node 。
        参数类型
        T - 由XPath表达式返回的类类型。
        参数
        expression - XPath表达式。
        item - XPath表达式的上下文将被评估。
        type - 预期由XPath表达式返回的类类型。
        结果
        表达式的评估结果。
        异常
        XPathExpressionException - 如果表达式无法评估。
        IllegalArgumentException - 如果type不是与XPathEvaluationResult.XPathResultType中定义的类型对应的类型，或者XPathEvaluationResult被指定为类型，但是支持ANY类型的实现不可用。
        NullPointerException - 如果 expression or type是 null 。
        从以下版本开始：
        9

      • evaluateExpression

        default XPathEvaluationResult<?> evaluateExpression​(String expression,
                                                    Object item)
                                             throws XPathExpressionException
        评估指定上下文中的XPath表达式。 这相当于打电话evaluateExpression(String expression, Object item, Class type) ，类型为XPathEvaluationResult ： 
           evaluateExpression(expression, item, XPathEvaluationResult.class);

        参数item表示将运行XPath表达式的上下文。 上下文的类型取决于实现。 如果值为null ，操作必须与上下文无关，否则将抛出XPathExpressionException异常。

        实现要求：
        XPath API中的默认实现相当于： 
           evaluateExpression(expression, item, XPathEvaluationResult.class);
        由于evaluate方法不支持ANY类型，因此此方法的默认实现将始终会引发IllegalArgumentException。 因此，支持ANY类型的任何实现必须覆盖此方法。
        Implementation Note:
        上下文的类型通常为Node 。
        参数
        expression - XPath表达式。
        item - 将评估XPath表达式的上下文。
        结果
        表达式的评估结果。
        异常
        XPathExpressionException - 如果表达式无法评估。
        IllegalArgumentException - 如果该方法的实现不支持 ANY类型。
        NullPointerException - 如果 expression是 null 。
        从以下版本开始：
        9

      • evaluateExpression

        default <T> T evaluateExpression​(String expression,
                                 InputSource source,
                                 Class<T> type)
                          throws XPathExpressionException
        在指定的source的上下文中评估XPath表达式，并返回指定的结果。

        此方法构建InputSource的数据模型，并在生成的文档对象上调用evaluateExpression(String expression, Object item, Class type) 。 数据模型通常为Document

        实现要求：
        XPath API中的默认实现相当于： 
           (T)evaluate(expression, source, XPathEvaluationResult.XPathResultType.getQNameType(type));
        由于evaluate方法不支持ANY类型，因此指定XPathEvaluationResult作为该类型会导致IllegalArgumentException。 任何支持ANY类型的实现都必须覆盖此方法。
        参数类型
        T - XPath表达式返回的类类型。
        参数
        expression - XPath表达式。
        source - 要评估的文档的输入源。
        type - 预期由XPath表达式返回的类类型。
        结果
        表达式的评估结果。
        异常
        XPathExpressionException - 如果表达式无法评估。
        IllegalArgumentException - 如果type不是与XPathResultType中定义的类型对应的类型，或者XPathEvaluationResult被指定为类型，但是支持ANY类型的实现不可用。
        NullPointerException - 如果 expression, source or type是 null 。
        从以下版本开始：
        9