Пакет javax.xml.transform

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

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

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

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

Определение входных и выходных данных

Этот API определяет два интерфейсных объекта, называемые Source и Result. Для передачи объектов Source и Result в интерфейсы необходимо использовать конкретные классы. Три конкретных представления определены для каждого из этих объектов: StreamSource и StreamResult, 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, независимо от того, установлено ли оно приложением или по умолчанию реализацией процессора. По умолчанию реализация, предоставляемая процессором, сообщает все предупреждения и ошибки System.err и не выбрасывает никаких Exception. Приложениям настоятельно рекомендуется регистрировать и использовать ErrorListener для обеспечения правильного поведения предупреждений и ошибок.

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