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