模块 java.xml
包 javax.xml.xpath

接口 XPathExpression

public interface XPathExpression
XPathExpression 提供对已编译 XPath 表达式的访问。 XPath 评估受下表中描述的因素影响。
XPath 表达式的评估
因素 行为
context 上下文的类型是依赖于实现的。如果值为 null，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。为了评估 XPath 表达式，将 DocumentFragment 视为文档节点。
变量 如果表达式包含一个变量引用，它的值将通过 XPathVariableResolver 找到。如果变量解析器未定义或解析器为变量返回 null，则会引发 XPathExpressionException 。在任何单个评估过程中，变量的值必须是不可变的。
功能 如果表达式包含函数引用，则将通过 XPathFunctionResolver 找到该函数。如果函数解析器未定义或函数解析器为函数返回 null，则会引发 XPathExpressionException 。
QNames 表达式中的 QName 根据 XPath 命名空间上下文进行解析。
结果 计算表达式的结果将转换为所需返回类型的实例。 XPathConstants 中定义了有效的返回类型。转换为返回类型遵循 XPath 转换规则。

XPath 表达式不是线程安全的，也不是可重入的。换句话说，应用程序有责任确保在任何给定时间不从多个线程使用一个 XPathExpression 对象，并且在调用 evaluate 方法时，应用程序不得递归调用 evaluate 方法。

自从：
1.5
参见：

  • 方法总结

    修饰符和类型
    方法
    描述
    String
    evaluate(Object item)
    在指定上下文中计算已编译的 XPath 表达式并将结果作为 String 返回。
    Object
    evaluate(Object item, QName returnType)
    在指定上下文中计算已编译的 XPath 表达式，并将结果作为指定类型返回。
    String
    evaluate(InputSource source)
    在指定的 InputSource 上下文中计算已编译的 XPath 表达式，并将结果作为 String 返回。
    Object
    evaluate(InputSource source, QName returnType)
    在指定的 InputSource 上下文中计算已编译的 XPath 表达式，并将结果作为指定类型返回。
    default XPathEvaluationResult<?>
    evaluateExpression(Object item)
    在指定的上下文中计算已编译的 XPath 表达式。
    default <T> T
    evaluateExpression(Object item, Class<T> type)
    在指定的上下文中计算已编译的 XPath 表达式，并返回具有通过 class type 指定的类型的结果。
    default XPathEvaluationResult<?>
    evaluateExpression(InputSource source)
    在指定的上下文中计算已编译的 XPath 表达式。
    default <T> T
    evaluateExpression(InputSource source, Class<T> type)
    在指定的上下文中计算已编译的 XPath 表达式，并返回具有通过 class type 指定的类型的结果

  • 方法详情

    • evaluate

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

      有关上下文项评估、变量、函数和 QName 解析以及返回类型转换的信息，请参见 XPath 表达式的评估。

      参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

      实现注意事项：
      上下文的类型通常是 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 解析以及返回类型转换的信息，请参见 XPath 表达式的评估。

      参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

      实现注意事项：
      上下文的类型通常是 Node 。
      参数：
      item - 将在其中计算 XPath 表达式的上下文。
      返回：
      将 XPath 表达式计算为 String 的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。

    • evaluate

      Object  evaluate(InputSource  source, QName  returnType) throws XPathExpressionException
      在指定的 InputSource 上下文中计算已编译的 XPath 表达式，并将结果作为指定类型返回。

      此方法为 InputSource 构建数据模型并在生成的文档对象上调用 evaluate(Object item, QName returnType) 。

      有关上下文项评估、变量、函数和 QName 解析以及返回类型转换的信息，请参见 XPath 表达式的评估。

      如果 returnType 不是 XPathConstants 中定义的类型之一，则抛出 IllegalArgumentException。

      如果 source 或 returnType 是 null ，则抛出 NullPointerException。

      参数：
      source - 要评估的文档的 InputSource。
      returnType - 所需的返回类型。
      返回：
      Object 是计算表达式并将结果转换为 returnType 的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。
      IllegalArgumentException - 如果 returnType 不是 XPathConstants 中定义的类型之一。
      NullPointerException - 如果 source or returnType 是 null。

    • evaluate

      String  evaluate(InputSource  source) throws XPathExpressionException
      在指定的 InputSource 上下文中计算已编译的 XPath 表达式，并将结果作为 String 返回。

      此方法使用 XPathConstants.STRING 的 returnType 调用 evaluate(InputSource source, QName returnType) 。

      有关上下文项评估、变量、函数和 QName 解析以及返回类型转换的信息，请参见 XPath 表达式的评估。

      如果 source 是 null，则抛出 NullPointerException。

      参数：
      source - 要评估的文档的 InputSource。
      返回：
      String 是计算表达式并将结果转换为 String 的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。
      NullPointerException - 如果 source 是 null。

    • 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 类型的实现都必须覆盖此方法。
      实现注意事项：
      上下文的类型通常是 Node 。
      类型参数：
      T - XPath 表达式将返回的类类型。
      参数：
      item - 将在其中计算 XPath 表达式的上下文。
      type - XPath 表达式预期返回的类类型必须是包摘要中 3.2 类类型 部分中描述的类型之一。
      返回：
      计算表达式的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。
      IllegalArgumentException - 如果 type 不是与 XPathResultType 中定义的类型相对应的类型，或者 XPathEvaluationResult 被指定为该类型但支持 ANY 类型的实现不可用。
      NullPointerException - 如果 type 是 null。
      自从：
      9

    • evaluateExpression

      default XPathEvaluationResult <?> evaluateExpression(Object  item) throws XPathExpressionException
      在指定的上下文中计算已编译的 XPath 表达式。这相当于调用类型为 XPathEvaluationResult 的 evaluateExpression(Object item, Class type) : 
       
   evaluateExpression(item, XPathEvaluationResult.class);

      参数 item 代表 XPath 表达式将被操作的上下文。上下文的类型是依赖于实现的。如果值为 null ，则操作必须不依赖于上下文，否则将抛出 XPathExpressionException。

      实现要求：
      XPath API 中的默认实现等效于： 
       
   evaluateExpression(item, XPathEvaluationResult.class);
      由于evaluate 方法不支持ANY 类型，因此此方法的默认实现将始终抛出 IllegalArgumentException。因此，任何支持 ANY 类型的实现都必须覆盖此方法。
      实现注意事项：
      上下文的类型通常是 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 表达式预期返回的类类型必须是包摘要中 3.2 类类型 部分中描述的类型之一。
      返回：
      计算表达式的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。
      IllegalArgumentException - 如果 type 不是与 XPathResultType 中定义的类型相对应的类型，或者 XPathEvaluationResult 被指定为该类型但支持 ANY 类型的实现不可用。
      NullPointerException - 如果 source or type 是 null。
      自从：
      9

    • evaluateExpression

      default XPathEvaluationResult <?> evaluateExpression(InputSource  source) throws XPathExpressionException
      在指定的上下文中计算已编译的 XPath 表达式。这相当于调用类型为 XPathEvaluationResult 的 evaluateExpression(InputSource source, Class type) : 
       
   evaluateExpression(source, XPathEvaluationResult.class);
      实现要求：
      XPath API 中的默认实现等效于： 
       
   (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class);
      由于 evaluate 方法不支持 ANY 类型，因此此方法的默认实现将始终抛出 IllegalArgumentException。因此，任何支持 ANY 类型的实现都必须覆盖此方法。
      参数：
      source - 要评估的文档的 InputSource。
      返回：
      计算表达式的结果。
      抛出：
      XPathExpressionException - 如果无法计算表达式。
      IllegalArgumentException - 如果此方法的实现不支持 ANY 类型。
      NullPointerException - 如果 source 是 null。
      自从：
      9