Пакет 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) в логическое, двойное или строковое значение. 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.evaluate(...) или XPath.evaluate(...).

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

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

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

3.2 Типы Class

В дополнение к типам QName API XPath поддерживает использование типов Class через методы XPathExpression.evaluateExpression(...) или 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.evaluateExpression(...) или XPath.evaluateExpression(...) будет одного из этих типов.

Обратите внимание на различия между отображениями Enum и QName:

• NUMBER
  Отображение Enum для NUMBER поддерживает Double, Integer и Long.
  
  
• NODESET
  Отображение Enum для NODESET — XPathNodes, а не NodeList в отображении QName.

4. Контекст XPath

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

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

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

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 перед передачей в API XPath. Следующий код демонстрирует использование InputSource, оставляя обработку за реализацией XPath:

     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.evaluateExpression(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.evaluateExpression("count(/widgets/widget)", document, Integer.class);