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

Interface XPathExpression


  • public interface XPathExpression
    XPathExpression提供对编译的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. 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. 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. 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表达式不是线程安全的，不可重入。 换句话说，应用程序有责任确保在任何给定时间从多个线程中使用一个2708606942661对象，而在调用evaluate方法时，应用程序可能不递归调用evaluate方法。

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

    • 方法详细信息

      • evaluate

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

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

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

        Implementation Note:
        上下文的类型通常为Node 。
        参数
        item - 将评估XPath表达式的上下文。
        returnType - 预期由XPath表达式返回的结果类型。
        结果
        Object是评估表达式并将结果转换为 returnType的结果。
        异常
        XPathExpressionException - 如果表达式无法评估。
        IllegalArgumentException -如果returnType不在定义的类型之一XPathConstants 。
        NullPointerException - 如果 returnType是 null 。

      • evaluate

        String evaluate​(Object item)
         throws XPathExpressionException
        在指定上下文中评估编译的XPath表达式，并将结果作为String返回。

        该方法调用evaluate(Object item, QName returnType) ，其中returnType为XPathConstants.STRING 。

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

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

        Implementation Note:
        上下文的类型通常为Node 。
        参数
        item - 将评估XPath表达式的上下文。
        结果
        将XPath表达式评估为 String 。
        异常
        XPathExpressionException - 如果表达式无法评估。

      • evaluateExpression

        default <T> T evaluateExpression​(Object item,
                                 Class<T> type)
                          throws XPathExpressionException
        评估在指定的上下文中编译的XPath表达式，并返回结果与通过class type指定的类型。

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

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

      • evaluateExpression

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

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

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

      • evaluateExpression

        default <T> T evaluateExpression​(InputSource source,
                                 Class<T> type)
                          throws XPathExpressionException
        评估在指定上下文中编译的XPath表达式，并返回结果，其类型通过class type指定

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

        默认情况下，JDK的数据模型为Document 。

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