Интерфейс XPath

public interface XPath

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

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

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

Since:

1.5

See Also:

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

Модификатор и тип	Метод	Описание
`XPathExpression`	`compile(String expression)`	Компилирует выражение XPath для последующей оценки.
`String`	`evaluate(String expression, Object item)`	Вычисляет выражение XPath в указанном контексте и возвращает результат как `String`.
`Object`	`evaluate(String expression, Object item, QName returnType)`	Вычисляет выражение `XPath` в указанном контексте и возвращает результат как указанный тип.
`String`	`evaluate(String expression, InputSource source)`	Вычисляет выражение XPath в контексте указанного `InputSource` и возвращает результат как `String`.
`Object`	`evaluate(String expression, InputSource source, QName returnType)`	Вычисляет выражение XPath в контексте указанного `InputSource` и возвращает результат как указанный тип.
`default XPathEvaluationResult<?>`	`evaluateExpression(String expression, Object item)`	Вычисляет выражение XPath в указанном контексте.
`default <T> T`	`evaluateExpression(String expression, Object item, Class<T> type)`	Вычисляет выражение XPath в указанном контексте и возвращает результат с типом, указанным через `class type`
`default XPathEvaluationResult<?>`	`evaluateExpression(String expression, InputSource source)`	Вычисляет выражение XPath в указанном контексте.
`default <T> T`	`evaluateExpression(String expression, InputSource source, Class<T> type)`	Вычисляет выражение XPath в контексте указанного `source` и возвращает результат как указанный.
`NamespaceContext`	`getNamespaceContext()`	Возвращает текущий контекст пространства имен.
`XPathFunctionResolver`	`getXPathFunctionResolver()`	Возвращает текущего решателя функций.
`XPathVariableResolver`	`getXPathVariableResolver()`	Возвращает текущего решателя переменных.
`void`	`reset()`	Сбрасывает этот `XPath` в исходную конфигурацию.
`void`	`setNamespaceContext(NamespaceContext nsContext)`	Устанавливает контекст пространства имен.
`void`	`setXPathFunctionResolver(XPathFunctionResolver resolver)`	Устанавливает решатель функций.
`void`	`setXPathVariableResolver(XPathVariableResolver resolver)`	Устанавливает решатель переменных.

Подробное описание методов

reset

void reset()

Сбросить данное XPath до его исходной конфигурации.

XPath сбрасывается до состояния, в котором он был создан с помощью XPathFactory.newXPath(). reset() предназначен для повторного использования существующих XPath, экономя ресурсы, связанные с созданием новых XPath.

Сброшенное XPath не гарантирует, что у него будут те же XPathFunctionResolver, XPathVariableResolver или NamespaceContext Object, например, Object.equals(Object obj). Гарантируется, что у него будут функционально эквивалентные XPathFunctionResolver, XPathVariableResolver и NamespaceContext.

setXPathVariableResolver

void setXPathVariableResolver(XPathVariableResolver resolver)

Установить разрешитель переменных.

Выбрасывается NullPointerException, если resolver является null.

Параметры:: resolver - Разрешитель переменных.
Исключения:: NullPointerException - Если resolver является null.

getXPathVariableResolver

XPathVariableResolver getXPathVariableResolver()

Возвращает текущего разрешителя переменных.

Возвращает null, если разрешитель переменных не установлен.

Возвращает:: Текущий разрешитель переменных.

setXPathFunctionResolver

void setXPathFunctionResolver(XPathFunctionResolver resolver)

Установить разрешитель функций.

Выбрасывается NullPointerException, если resolver является null.

Параметры:: resolver - Разрешитель функций XPath.
Исключения:: NullPointerException - Если resolver является null.

getXPathFunctionResolver

XPathFunctionResolver getXPathFunctionResolver()

Возвращает текущего разрешителя функций.

Возвращает null если разрешитель функций не установлен.

Возвращает:: Текущий разрешитель функций.

setNamespaceContext

void setNamespaceContext(NamespaceContext nsContext)

Установить контекст имен пространств.

Выбрасывается NullPointerException, если nsContext является null.

Параметры:: nsContext - Контекст имен пространств для использования.
Исключения:: NullPointerException - Если nsContext является null.

getNamespaceContext

NamespaceContext getNamespaceContext()

Возвращает текущий контекст имен пространств.

Возвращает null если контекст имен пространств не установлен.

Возвращает:: Текущий контекст имен пространств.

compile

XPathExpression compile(String expression) throws XPathExpressionException

Компилирует выражение XPath для последующего вычисления.

Если expression содержит какие-либо XPathFunction, они должны быть доступны через XPathFunctionResolver. Будет выброшено исключение XPathExpressionException, если XPathFunction не может быть решен с помощью XPathFunctionResolver.

Если expression содержит какие-либо переменные, то XPathVariableResolver, действующий во время компиляции, будет использоваться для их разрешения.

Параметры:: expression - Выражение XPath.
Возвращает:: Скомпилированное выражение XPath.
Исключения:: XPathExpressionException - Если expression не может быть скомпилировано.; NullPointerException - Если expression является null.

evaluate

Object evaluate(String expression, Object item, QName returnType) throws XPathExpressionException

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

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

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

Примечание реализации:: Тип контекста обычно Node.
Параметры:: expression - Выражение XPath.; item - Контекст, в котором будет вычисляться выражение XPath.; returnType - Тип результата, который ожидается вернуть выражением XPath.
Возвращает:: Результат вычисления выражения XPath в виде Object типа returnType.
Исключения:: XPathExpressionException - Если expression не может быть вычислено.; IllegalArgumentException - Если returnType не является одним из типов, определённых в XPathConstants ( NUMBER, STRING, BOOLEAN, NODE или NODESET).; NullPointerException - Если expression or returnType является null.

evaluate

String evaluate(String expression, Object item) throws XPathExpressionException

Вычислить выражение XPath в указанном контексте и вернуть результат как String.

Этот метод вызывает evaluate(String expression, Object item, QName returnType) с типом результата XPathConstants.STRING.

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

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

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

evaluate

Object evaluate(String expression, InputSource source, QName returnType) throws XPathExpressionException

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

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

Параметры:: expression - Выражение XPath.; source - Источник входных данных документа, по которому выполняется вычисление.; returnType - Требуемый тип возвращаемого значения.
Возвращает:: Результат, содержащий результат вычисления выражения.
Исключения:: XPathExpressionException - Если выражение не может быть вычислено.; IllegalArgumentException - Если returnType не является одним из типов, определённых в XPathConstants.; NullPointerException - Если expression, source or returnType является null.

evaluate

String evaluate(String expression, InputSource source) throws XPathExpressionException

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

Этот метод вызывает evaluate(String expression, InputSource source, QName returnType) с типом результата XPathConstants.STRING.

Параметры:: expression - Выражение XPath.; source - Источник входных данных документа, по которому выполняется вычисление.
Возвращает:: Результат вычисления выражения и преобразования результата к типу String.
Исключения:: XPathExpressionException - Если выражение не может быть вычислено.; NullPointerException - Если expression or source является null.

evaluateExpression

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

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

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

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

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

 
     (T)evaluate(expression, item,
           XPathEvaluationResult.XPathResultType.getQNameType(type));

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

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

Тип контекста обычно Node.

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

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

Параметры:

expression - Выражение XPath.

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

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

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

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

Исключения:

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

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

NullPointerException - Если expression or type равно null.

С тех пор как:

evaluateExpression

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

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

 
     evaluateExpression(expression, item, XPathEvaluationResult.class);

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

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

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

 
     evaluateExpression(expression, item, XPathEvaluationResult.class);

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

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

Тип контекста обычно Node.

Параметры:

expression - Выражение XPath.

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

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

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

Исключения:

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

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

NullPointerException - Если expression равно null.

С тех пор как:

evaluateExpression

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

Вычислить выражение XPath в контексте указанного source и вернуть результат в соответствии с требованиями.

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

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

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

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

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

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

Параметры:

expression - Выражение XPath.

source - Источник входных данных документа для вычисления.

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

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

Исключения:

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

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

NullPointerException - Если expression, source or type равно null.

С тех пор как:

evaluateExpression

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

 
     evaluateExpression(expression, item, XPathEvaluationResult.class);

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

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

 
     evaluateExpression(expression, source, XPathEvaluationResult.class);

Параметры:

expression - Выражение XPath.

source - Источник входных данных документа для вычисления.

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

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

Исключения:

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

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

NullPointerException - Если expression or 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/XPath.html