Пакет javax.xml.xpath

Предоставляет API, не зависящий от объектной модели, для вычисления выражений XPath и доступа к среде вычисления.

API XPath поддерживает язык XML Path Language (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 Path Language (XPath), версия 1.0.

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

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

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

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

    /foo/bar

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

    <foo>
        <bar/>
    </foo>

Выражение /foo/bar является примером пути расположения. Хотя пути расположения XPath похожи на пути файловой системы в стиле Unix, важно то, что выражения XPath возвращают все узлы, соответствующие выражению. Таким образом, выражение /foo/bar выберет все три элемента <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
  Для NODESET в соответствии Enum используется XPathNodes, а не NodeList, используемый в соответствии QName.

4. Контекст XPath

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

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

Это дерево XML-документа, представленное иерархией узлов, например, в реализации JDK — 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 Document перед передачей 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;
    }

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

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