Пакет 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; спецификация Языка путей XML (XPath) Версии 1.0 размещена на сайте W3C.

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);