Module java.xml
Package javax.xml.xpath

Interface XPathExpression

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

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

自版本:
1.5
参见:

  • Method Summary

    Modifier and Type
    Method
    Description
    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指定返回结果的类型。

  • Method Details

    • evaluate

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

      查看XPath表达式的评估以获取上下文项评估、变量、函数和QName解析以及返回类型转换的信息。

      参数item表示XPath表达式将在其上操作的上下文。上下文的类型取决于实现。如果值为null，则操作不得依赖于上下文，否则将抛出XPathExpressionException异常。

      实现注意:
      上下文的类型通常为Node。
      参数:
      item - 要在其中评估XPath表达式的上下文。
      returnType - 期望由XPath表达式返回的结果类型。
      返回:
      评估表达式并将结果转换为returnType的Object。
      抛出:
      XPathExpressionException - 如果无法评估表达式。
      IllegalArgumentException - 如果returnType不是在XPathConstants中定义的类型之一。
      NullPointerException - 如果returnType为null。

    • evaluate

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

      此方法使用returnType为XPathConstants.STRING调用evaluate(Object item, QName returnType)。

      查看XPath表达式的评估以获取上下文项评估、变量、函数和QName解析以及返回类型转换的信息。

      参数item表示XPath表达式将在其上操作的上下文。上下文的类型取决于实现。如果值为null，则操作不得依赖于上下文，否则将抛出XPathExpressionException异常。

      实现注意:
      上下文的类型通常为Node。
      参数:
      item - 要在其中评估XPath表达式的上下文。
      返回:
      作为String评估XPath表达式的结果。
      抛出:
      XPathExpressionException - 如果无法评估表达式。

    • evaluate

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

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

      查看XPath表达式的评估以获取上下文项评估、变量、函数和QName解析以及返回类型转换的信息。

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

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

      参数:
      source - 要在其上评估文档的InputSource。
      returnType - 期望返回的结果类型。
      返回:
      评估表达式并将结果转换为returnType的Object。
      抛出:
      XPathExpressionException - 如果无法评估表达式。
      IllegalArgumentException - 如果returnType不是在XPathConstants中定义的类型之一。
      NullPointerException - 如果source或returnType为null。

    • evaluate

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

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

      查看XPath表达式的评估以获取上下文项评估、变量、函数和QName解析以及返回类型转换的信息。

      如果source为null，则会抛出NullPointerException。

      参数:
      source - 要在其上评估文档的InputSource。
      返回:
      作为String评估XPath表达式的结果。
      抛出:
      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或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