Интерфейс XPathExpression

public interface XPathExpression

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

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

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

Since:

1.5

See Also:

XML Path Language (XPath) Version 1.0, Выражения

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

Модификатор и тип	Метод	Описание
`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 - Источник InputSource документа для вычисления.; 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 - Источник InputSource документа для вычисления.
Возвращает:: Результат вычисления выражения и преобразования результата в String.
Исключение:: XPathExpressionException - Если выражение не может быть вычислено.; NullPointerException - Если source равно null.

evaluateExpression

default <T> T evaluateExpression(Object item, Class<T> type) throws XPathExpressionException

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

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

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

По умолчанию в 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));

Поскольку метод 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, 2021, 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/17/docs/api/java.xml/javax/xml/xpath/XPathExpression.html