Пакет 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 должен быть пригоден для использования преобразователем, как указано в его реализованных функциях.