Интерфейс XPathExpression

public interface XPathExpression

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

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

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

С тех пор:: 1.5
См. также:: XML Path Language (XPath) Version 1.0, Expressions

Методы

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

Возвращает:

Результат оценки выражения.

Исключения:

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.

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

Стандартная реализация в 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.

С момента:

evaluateExpression

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

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

evaluateExpression(source, XPathEvaluationResult.class);

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

Стандартная реализация в XPath API эквивалентна:

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

Параметры:

source - InputSource документа, по которому будет производиться вычисление.

Возвращаемое значение:

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

Исключения:

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

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

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

С момента:

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