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