Пакет 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(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 пространства имён в фигурных скобках ({}), за которым следует локальное имя. Если URI у qname равен null, строковый объект содержит только локальное имя. Приложение может безопасно проверить, что URI не равен null, проверив, является ли первый символ имени символом '{'.

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

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

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

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

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

Исключения и сообщения об ошибках

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

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

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

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

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

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