Пакет javax.xml.xpath

Предоставляет нейтральную по отношению к объектной модели API для оценки выражений XPath и доступа к среде вычислений.

API XPath поддерживает язык путей XML (XPath) версии 1.0

• 1. Обзор XPath
• 2. Выражения XPath
• 3. Типы данных XPath
  • 3.1 Типы QName
  • 3.2 Типы Class
  • 3.3 Типы Enum
• 4. Контекст XPath
• 5. Использование API XPath

1. Обзор XPath

Язык XPath предоставляет простой и лаконичный синтаксис для выбора узлов в документе XML. XPath также предоставляет правила для преобразования узла в дереве модели объектов XML (DOM) в булевое значение, значение double или строковое значение. XPath — это определённый W3C язык и официальная рекомендация W3C; W3C предоставляет спецификацию языка путей XML (XPath) версии 1.0.

XPath появился в 1999 году как дополнение к языкам XSLT и XPointer, но в последнее время стал популярен как отдельный язык, так как одно выражение XPath может заменить много строк кода API DOM.

2. Выражения XPath

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

Вот пример простого выражения XPath:

/foo/bar

Этот пример выберет элемент <bar> в документе XML, например, таком:

<foo>
    <bar/>
</foo>

Выражение /foo/bar является примером пути к местоположению. Хотя пути к местоположению XPath напоминают пути к файлам в стиле Unix, важное отличие заключается в том, что выражения XPath возвращают все узлы, соответствующие выражению. Таким образом, все три элемента <bar> в следующем документе будут выбраны выражением /foo/bar:

<foo>
    <bar/>
    <bar/>
    <bar/>
</foo>

Специальный оператор пути к местоположению //, выбирает узлы на любой глубине в документе XML. Следующий пример выбирает все элементы <bar> независимо от их расположения в документе:

//bar

Оператор подстановки *, выбирает все узлы элементов. Следующий пример выбирает все дочерние элементы элемента <foo>:

/foo/*

Помимо узлов элементов, пути к местоположению XPath могут также адресовать атрибуты, текстовые узлы, узлы комментариев и узлы инструкций обработки. В следующей таблице приведены примеры путей к местоположению для каждого из этих типов узлов:

Путь к местоположению	Описание
/foo/bar/@id	Выбирает атрибут id элемента <bar>
/foo/bar/text()	Выбирает текстовые узлы элемента <bar>. Различия между экранированными и не экранированными данными символов не делается.
/foo/bar/comment()	Выбирает все узлы комментариев, содержащиеся в элементе <bar> .
/foo/bar/processing-instruction()	Выбирает все узлы инструкций обработки, содержащиеся в элементе <bar> .

Предикаты позволяют уточнить узлы, выбранные путем к местоположению XPath. Предикаты имеют вид [expression]. Следующий пример выбирает все элементы <foo>, содержащие атрибут include со значением true:

//foo[@include='true']

Предикаты могут быть добавлены друг к другу, чтобы дополнительно уточнить выражение, например:

//foo[@include='true'][@mode='bar']

3. Типы данных XPath

Хотя выражения XPath выбирают узлы в документе XML, API XPath позволяет объединить выбранные узлы в один из следующих типов данных:

• Boolean
• Number
• String

3.1 Типы QName

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

• XPathConstants.NODESET
• XPathConstants.NODE
• XPathConstants.STRING
• XPathConstants.BOOLEAN
• XPathConstants.NUMBER

Тип возвращаемого значения задаётся параметром QName в вызове метода, используемого для оценки выражения, который представляет собой вызов методов XPathExpression.evalute(...) или XPath.evaluate(...).

При запросе типа возврата Boolean, возвращается Boolean.TRUE, если выбрано один или несколько узлов; в противном случае возвращается Boolean.FALSE.

Тип возвращаемого значения String является удобством для извлечения символьных данных из текстового узла, атрибутного узла, узла комментария или узла инструкции обработки. При использовании с узлом элемента возвращается значение дочерних текстовых узлов.

Тип возвращаемого значения Number пытается объединить текст узла в тип данных double.

3.2 Типы Class

Помимо типов QName, API XPath поддерживает использование типов Class через методы XPathExpression.evaluteExpression(...) или XPath.evaluateExpression(...). Типы данных XPath сопоставляются с типами Class следующим образом:

• Boolean -- Boolean.class
• Number -- Number.class
• String -- String.class
• Nodeset -- XPathNodes.class
• Node -- Node.class

Из подтипов Number поддерживаются только Double, Integer и Long.

3.3 Типы Enum

Типы Enum определены в XPathEvaluationResult.XPathResultType, которые предоставляют сопоставления между типами QName и Class, указанными выше. Результат оценки выражения с использованием методов XPathExpression.evaluteExpression(...) или XPath.evaluateExpression(...) будет одного из этих типов.

4. Контекст XPath

Пути к местоположению XPath могут быть относительными к конкретному узлу в документе, известному как context. Контекст состоит из:

• узла (узел контекста)
• пары целых положительных чисел (позиция контекста и размер контекста)
• набора связываний переменных
• библиотеки функций
• набора объявлений пространств имён, действующих для выражения

Это дерево документа XML, представленное в виде иерархии узлов, например, Node в реализации JDK.

5. Использование API XPath

Рассмотрим следующий XML-документ:

<widgets>
<widget>
<manufacturer/>
<dimensions/>
</widget>
</widgets>

Элемент <widget> можно выбрать с помощью следующего процесса:

// parse the XML as a W3C Document
DocumentBuilder builder = DocumentBuilderFactory.newInstance().newDocumentBuilder();
Document document = builder.parse(new File("/widgets.xml"));

//Get an XPath object and evaluate the expression
XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "/widgets/widget";
Node widgetNode = (Node) xpath.evaluate(expression, document, XPathConstants.NODE);

//or using the evaluateExpression method
Node widgetNode = xpath.evaluateExpression(expression, document, Node.class);

Ссылаясь на элемент <widget>, можно записать относительное выражение XPath для выбора дочернего элемента <manufacturer>:

XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "manufacturer";
Node manufacturerNode = (Node) xpath.evaluate(expression, widgetNode, XPathConstants.NODE);

//or using the evaluateExpression method
Node manufacturerNode = xpath.evaluateExpression(expression, widgetNode, Node.class);

В приведенном выше примере XML-файл считывается в DOM Document перед передачей в API XPath. Следующий код демонстрирует использование InputSource, оставляя обработку ему:

XPath xpath = XPathFactory.newInstance().newXPath();
String expression = "/widgets/widget";
InputSource inputSource = new InputSource("widgets.xml");
NodeList nodes = (NodeList) xpath.evaluate(expression, inputSource, XPathConstants.NODESET);

//or using the evaluateExpression method
XPathNodes nodes = xpath.evaluate(expression, inputSource, XPathNodes.class);

В приведенных выше случаях тип ожидаемых результатов известен. В случае, когда тип результата неизвестен или может быть любым, можно использовать XPathEvaluationResult для определения типа возвращаемого значения. Следующий код демонстрирует использование:

XPathEvaluationResult<?> result = xpath.evaluateExpression(expression, document);
switch (result.type()) {
    case NODESET:
        XPathNodes nodes = (XPathNodes)result.value();
        ...
        break;
}

Тип данных XPath 1.0 Number определяется как double. Однако спецификация XPath также предоставляет функции, возвращающие тип Integer. Для облегчения таких операций API XPath позволяет использовать Integer и Long в методе evaluateExpression, например, в следующем коде:

int count = xpath.evaluate("count(/widgets/widget)", document, Integer.class);