Интерфейс XPathExpression

public interface XPathExpression

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

Вычисление выражений XPath
Фактор	Поведение
контекст	Тип контекста зависит от реализации. Если значение равно null, операция не должна зависеть от контекста, в противном случае будет выброшено исключение XPathExpressionException. Для целей вычисления выражений XPath, DocumentFragment обрабатывается как узел Document.
переменные	Если выражение содержит ссылку на переменную, её значение будет найдено через `XPathVariableResolver`. Исключение `XPathExpressionException` будет выброшено, если разрешитель переменной не определён или разрешитель возвращает `null` для переменной. Значение переменной должно быть неизменным в течение любого отдельного вычисления.
функции	Если выражение содержит ссылку на функцию, функция будет найдена через `XPathFunctionResolver`. Исключение `XPathExpressionException` будет выброшено, если разрешитель функций не определён или разрешитель возвращает `null` для функции.
QNames	QNames в выражении разрешаются относительно контекста пространства имён XPath.
результат	Результат вычисления выражения преобразуется в экземпляр желаемого типа возвращаемого значения. Допустимые типы возвращаемых значений определены в `XPathConstants`. Преобразование в тип возвращаемого значения следует правилам преобразования XPath.

Выражение XPath не является потокобезопасным и не рекурсивным. Другими словами, приложение несёт ответственность за обеспечение того, чтобы один объект XPathExpression не использовался более чем из одной нити в любой данный момент времени, и в то время как вызывается метод evaluate, приложения не могут рекурсивно вызывать метод evaluate.

Since:

1.5

See Also:

Краткое описание методов

Модификатор и тип	Метод	Описание
`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 в указанном контексте и вернуть результат в указанном типе.

См. Вычисление выражений XPath для оценки элемента контекста, разрешения переменных, функций и QName, а также преобразования типов возвращаемых значений.

Параметр item представляет контекст, в котором будет выполняться выражение XPath. Тип контекста зависит от реализации. Если значение равно null, операция не должна зависеть от контекста, в противном случае будет выброшено исключение XPathExpressionException.

Примечание реализации:: Тип контекста обычно Node.
Параметры:: item - Контекст, в котором будет вычисляться выражение XPath.; returnType - Тип результата, ожидаемый от выражения XPath.
Возвращает:: Результат вычисления выражения и преобразования результата к типу 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 - Источник документа, над которым необходимо выполнить вычисление.; returnType - Желаемый тип возвращаемого значения.
Возвращает:: Результат вычисления выражения и преобразования результата к типу 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 - Источник документа, над которым необходимо выполнить вычисление.
Возвращает:: Результат вычисления выражения и преобразования результата к типу 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 - Ожидаемый тип возвращаемого значения, должен быть одним из типов, описанных в разделе 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));

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

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

T - Тип класса, который будет возвращён выражением XPath.

Параметры:

source - InputSource документа для оценки.

type - Тип класса, ожидаемый в качестве возвращаемого результата выражения XPath, должен быть одним из типов, описанных в разделе 3.2 Типы классов в обзоре пакета.

Возвращает:

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

Исключения:

XPathExpressionException - Если выражение не может быть вычислено.

IllegalArgumentException - Если type не относится к типам, соответствующим типам, определённым в XPathResultType, или если XPathEvaluationResult задан как тип, но реализация, поддерживающая тип ANY, недоступна.

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);

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

Параметры:

source - InputSource документа для оценки.

Возвращает:

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

Исключения:

XPathExpressionException - Если выражение не может быть вычислено.

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

NullPointerException - Если source является null.

С:

© 1993, 2023, 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/21/docs/api/java.xml/javax/xml/xpath/XPathExpression.html