Пакет javax.xml.transform

Определяет общие API для обработки инструкций преобразования и выполнения преобразования из источника в результат. Эти интерфейсы не зависят от стандартов SAX или DOM и стараются по возможности не делать предположений о деталях источника и результата преобразования. Это достигается за счет определения интерфейсов Source и Result.

Для предоставления конкретных классов пользователю API определяет специализации интерфейсов на корневом уровне. Эти интерфейсы находятся в javax.xml.transform.sax, javax.xml.transform.dom, javax.xml.transform.stax и javax.xml.transform.stream.

Создание объектов

API позволяет создать объект TransformerFactory с помощью статической функции TransformerFactory.newInstance().

Указание входов и выходов

Этот API определяет два интерфейсных объекта, называемые Source и Result. Для передачи объектов Source и Result в интерфейсы необходимо использовать конкретные классы. Ниже приведены конкретные представления для каждого из этих объектов: StreamSource и StreamResult, StAXSource и StAXResult, а также SAXSource и SAXResult, и DOMSource и DOMResult. Каждый из этих объектов определяет строку FEATURE (в формате URL), которую можно передать в TransformerFactory.getFeature(java.lang.String), чтобы узнать, поддерживается ли данный тип объекта Source или Result. Например, чтобы проверить, поддерживается ли DOMSource и StreamResult, можно выполнить следующее тестирование.

 
 TransformerFactory tfactory = TransformerFactory.newInstance();
 if (tfactory.getFeature(DOMSource.FEATURE) &&
     tfactory.getFeature(StreamResult.FEATURE)) {
     ...
 }
 
 

Представление квалифицированных имен

Пространства имен представляют собой проблему при работе с XML-объектами. Квалифицированные имена появляются в XML-разметке как префиксные имена. Но сами префиксы не являются идентификаторами. Скорее, это URI, к которым они контекстуально сопоставляются, являются идентификаторами. Поэтому, передавая квалифицированное имя, например, "xyz:foo", между Java-программами, необходимо предоставить способ сопоставления "xyz" со пространством имен.

Одним из решений является создание объекта "QName", который содержит URI пространства имен, а также префикс и локальное имя, но это не всегда оптимальное решение, например, когда вы хотите использовать уникальные строки в качестве ключей в объекте словаря. Отсутствие строкового представления также затрудняет указание идентификатора пространства имен за пределами контекста XML-документа.

Для передачи значений пространства имен в преобразования, например, при установке свойства или параметра для объекта Transformer, этот стандарт определяет, что параметр строки "qname" должен передаваться как строка из двух частей: URI пространства имен в фигурных скобках ({}), за которым следует локальное имя. Если у qname нет URI, то строковый объект содержит только локальное имя. Приложение может безопасно проверить наличие URI, проверив, является ли первый символ имени символом '{'.

Например, если URI и локальное имя были получены из элемента, определенного с помощью <xyz:foo xmlns:xyz="http://xyz.foo.com/yada/baz.html"/>, то квалифицированное имя будет "{http://xyz.foo.com/yada/baz.html}foo". Обратите внимание, что префикс теряется.

Сериализация дерева результатов

Сериализацию дерева результатов в поток можно контролировать с помощью методов Transformer.setOutputProperties(java.util.Properties) и Transformer.setOutputProperty(java.lang.String, java.lang.String). Эти свойства применяются только к результатам потока, они не влияют на результаты DOM-дерева или потока событий SAX.

Строки, соответствующие спецификации XSLT для атрибутов xsl:output, могут быть использованы из класса OutputKeys. Также можно указать другие строки. Если преобразователь не распознает ключ вывода, выбрасывается IllegalArgumentException, если имя ключа не является квалифицированным по пространству имен. Имена ключей вывода, квалифицированные по пространству имен, всегда разрешены, хотя некоторые реализации могут их игнорировать.

Если требуется только простое преобразование источника в результат, то TransformerFactory предоставляет метод TransformerFactory.newTransformer() без аргументов. Этот метод создает преобразователь, который эффективно копирует источник в результат. Этот метод можно использовать для создания DOM из событий SAX или для создания потока XML или HTML из DOM или событий SAX.

Исключения и обработка ошибок

API преобразования выбрасывает три типа специализированных исключений. TransformerFactoryConfigurationError аналогичен FactoryConfigurationError и выбрасывается при наличии проблемы конфигурации в TransformerFactory. Обычно эта ошибка возникает, когда класс фабрики преобразований, указанный системной переменной "javax.xml.transform.TransformerFactory", не найден или не может быть создан.

TransformerConfigurationException может быть вызван, если по какой-либо причине преобразователь не может быть создан. TransformerConfigurationException может быть выброшен, если в инструкциях преобразования есть синтаксическая ошибка, например, при вызове TransformerFactory.newTransformer(javax.xml.transform.Source).

TransformerException — общее исключение, возникающее во время преобразования. Исключение преобразователя может обернуть другое исключение, и если вызовятся любые из методов TransformerException.printStackTrace(), будет выведен список стековых следов, начиная с последнего. Исключение преобразователя также предоставляет объект SourceLocator, который указывает, где в дереве источника или инструкциях преобразования произошла ошибка. TransformerException.getMessageAndLocation() можно вызвать для получения сообщения об ошибке с информацией о расположении, а TransformerException.getLocationAsString() можно вызвать для получения только строки расположения.

Предупреждения и ошибки преобразования отправляются в ErrorListener, в этом случае приложение может решить, сообщить об ошибке или предупреждении, и может решить выбросить Exception для некритической ошибки. ErrorListener можно установить с помощью TransformerFactory.setErrorListener(javax.xml.transform.ErrorListener) для сообщения об ошибках, связанных с синтаксическими ошибками в инструкциях преобразования, или с помощью Transformer.setErrorListener(javax.xml.transform.ErrorListener) для отчета об ошибках, возникающих во время преобразования. ErrorListener в обоих объектах всегда будет допустимым и не-null, независимо от того, устанавливается ли оно приложением или по умолчанию, предоставляемой процессором.

Разрешение URI в рамках преобразования

API предоставляет способ разрешения URI, на которые ссылаются инструкции шаблона или в процессе преобразования вызывающим приложением. Это можно сделать, создав класс, реализующий интерфейс URIResolver с его единственным методом URIResolver.resolve(java.lang.String, java.lang.String), и использовать этот класс для установки разрешения URI для инструкций преобразования или преобразования с помощью TransformerFactory.setURIResolver(javax.xml.transform.URIResolver) или Transformer.setURIResolver(javax.xml.transform.URIResolver). Метод URIResolver.resolve принимает два строковых аргумента: URI, найденный в инструкциях шаблона или сгенерированный в процессе преобразования, и базовый URI, относительно которого первый аргумент будет сделан абсолютным, если абсолютный URI требуется. Возвращаемый объект Source должен быть пригоден для использования преобразователем, как указано в его реализованных функциях.