Пакет 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 Path Language (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.evalute(...) или 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. Контекст состоит из:

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

Это дерево документа 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 перед передачей в 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);