Интерфейс XPathExpression

public interface XPathExpression

XPathExpression предоставляет доступ к скомпилированным выражениям XPath. На вычисление XPath влияют факторы, описанные в следующей таблице.

Вычисление выражений XPath
Фактор	Поведение
контекст	Тип контекста зависит от реализации. Если значение равно null, операция не должна зависеть от контекста; в противном случае будет выброшено исключение XPathExpressionException. При вычислении выражений XPath узел DocumentFragment рассматривается как узел Document.
переменные	Если выражение содержит ссылку на переменную, её значение будет получено через `XPathVariableResolver`. Исключение `XPathExpressionException` возникает, если обработчик переменных не определён или возвращает `null` для переменной. Значение переменной должно оставаться неизменным в течение одного вычисления.
функции	Если выражение содержит ссылку на функцию, функция будет найдена через `XPathFunctionResolver`. Исключение `XPathExpressionException` возникает, если обработчик функций не определён или возвращает `null` для функции.
QName	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)`	Вычисляет скомпилированное выражение XPath в контексте указанного `InputSource` и возвращает результат в виде `String`.
`Object`	`evaluate(InputSource source, QName returnType)`	Вычисляет скомпилированное выражение XPath в контексте указанного `InputSource` и возвращает результат в виде значения указанного типа.
`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.

Примечание к реализации:: Типом контекста обычно является Node.
Параметры:: item — контекст, в котором будет вычисляться выражение XPath.
Возвращает:: Результат вычисления выражения XPath в виде String.
Исключения:: XPathExpressionException — если выражение не удаётся вычислить.

evaluate

Object evaluate(InputSource source, QName returnType) throws XPathExpressionException

Вычисляет скомпилированное выражение XPath в контексте указанного InputSource и возвращает результат в виде значения указанного типа.

Этот метод строит модель данных для InputSource и вызывает evaluate(Object item, QName returnType) для полученного объекта документа.

Если 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

Вычисляет скомпилированное выражение XPath в контексте указанного InputSource и возвращает результат в виде String.

Этот метод вызывает evaluate(InputSource source, QName returnType) с returnType, равным XPathConstants.STRING.

Если 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.

Требования к реализации:

Реализация по умолчанию в API XPath эквивалентна следующей:

    (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.

Начиная с:

evaluateExpression

default XPathEvaluationResult<?> evaluateExpression(Object item) throws XPathExpressionException

Вычисляет скомпилированное выражение XPath в указанном контексте. Эквивалентно вызову evaluateExpression(Object item, Class type) с типом XPathEvaluationResult:

    evaluateExpression(item, XPathEvaluationResult.class);

Требования к реализации:

Реализация по умолчанию в API XPath эквивалентна следующей:

    evaluateExpression(item, XPathEvaluationResult.class);

Поскольку метод evaluate не поддерживает тип ANY, реализация этого метода по умолчанию всегда будет выбрасывать IllegalArgumentException. Поэтому любая реализация, поддерживающая тип ANY, должна переопределить этот метод.

Примечание к реализации:

Типом контекста обычно является Node.

Параметры:

item — контекст, в котором будет вычисляться выражение XPath.

Возвращает:

Результат вычисления выражения.

Исключения:

XPathExpressionException — если выражение не удаётся вычислить.

IllegalArgumentException — если реализация этого метода не поддерживает тип ANY.

Начиная с:

evaluateExpression

default <T> T evaluateExpression(InputSource source, Class<T> type) throws XPathExpressionException

Вычисляет скомпилированное выражение XPath в указанном контексте и возвращает результат с типом, заданным с помощью class type

Этот метод строит модель данных для InputSource и вызывает evaluateExpression(Object item, Class type) для полученного объекта документа.

По умолчанию моделью данных JDK является Document.

Требования к реализации:

Реализация по умолчанию в API XPath эквивалентна следующей:

          (T)evaluate(source, XPathEvaluationResult.XPathResultType.getQNameType(type));

Параметры типа:

T — тип класса, возвращаемого выражением XPath.

Параметры:

source — InputSource документа, для которого выполняется вычисление.

Возвращает:

Результат вычисления выражения.

Исключения:

XPathExpressionException — если выражение не удаётся вычислить.

NullPointerException — если source or type равно null.

Начиная с:

evaluateExpression

default XPathEvaluationResult<?> evaluateExpression(InputSource source) throws XPathExpressionException

Вычисляет скомпилированное выражение XPath в указанном контексте. Эквивалентно вызову evaluateExpression(InputSource source, Class type) с типом XPathEvaluationResult:

    evaluateExpression(source, XPathEvaluationResult.class);

Требования к реализации:

Реализация по умолчанию в API XPath эквивалентна следующей:

    (XPathEvaluationResult)evaluateExpression(source, XPathEvaluationResult.class);

Параметры:

source — InputSource документа, для которого выполняется вычисление.

Возвращает:

Результат вычисления выражения.

Исключения:

XPathExpressionException — если выражение не удаётся вычислить.

IllegalArgumentException — если реализация этого метода не поддерживает тип ANY.

NullPointerException — если source равно null.

Начиная с:

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/xpath/XPathExpression.html