xsl:result-document

Используется для направления вывода на вторичное место назначения вывода.

Доступен в XSLT 2.0 и более поздних версиях. Доступно во всех редакциях Saxon.

• Категория: инструкция
• Содержимое: sequence-constructor
• Допустимые родительские элементы: любой элемент XSLT, модель содержимого которого - sequence-constructor; любой литеральный элемент результата

Атрибуты

format?

{ eqname }

Если присутствует, то указывает имя элемента xsl:output, который описывает формат сериализации для данного выходного документа; если отсутствует, то используется неименованное объявление xsl:output.

href?

{ uri }

URI для результирующего документа. Если это относительный URI, он интерпретируется относительно базового выходного URI. Базовый выходной URI - это системный идентификатор объекта результата, указанный в качестве назначения для преобразования, или, если вы используете командную строку, значение флага -o. Если атрибут href опущен, документ записывается в местоположение, определенное базовым URI вывода: это работает только в том случае, если все выходные данные, созданные таблицей стилей, находятся в области действия инструкции xsl:result-document.

Если базовый выходной URI неизвестен, а заданный href не является абсолютным, то это приводит к ошибке.

Базовый выходной URI должен быть доступным для записи местом. Обычно это URI, использующий схему "file:". Однако Saxon пытается открыть соединение, какая бы схема URI ни использовалась, и поэтому он должен работать с любым URI, где Java VM имеет возможность открыть записываемое соединение. Пользователи сообщали об успешном использовании URI "ftp:" и "mailto:".

Если установлен параметр конфигурации Feature.ALLOW-EXTERNAL-FUNCTIONS, то в целях безопасности использование инструкции xsl:result-document с атрибутом href запрещено.

validation?

"strict" | "lax" | "preserve" | "strip"

Требуется Saxon-PE или Saxon-EE.

type?

eqname

Определяет, что происходит с любыми аннотациями типов на узлах элементов или атрибутов. Требуется Saxon-PE или Saxon-EE.

method?

{ "xml" | "html" | "xhtml" | "text" | "json" | "adaptive" | eqname }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

allow-duplicate-names?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

build-tree?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

byte-order-mark?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

cdata-section-elements?

{ eqnames }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

doctype-public?

{ string }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

doctype-system?

{ string }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

encoding?

{ string }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

escape-uri-attributes?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

html-version?

{ decimal }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

include-content-type?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

indent?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

item-separator?

{ string }

Недоступно в XSLT.

json-node-output-method?

{ "xml" | "html" | "xhtml" | "text" | eqname }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

media-type?

{ string }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

normalization-form?

{ "NFC" | "NFD" | "NFKC" | "NFKD" | "fully-normalized" | "none" | nmtoken }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

omit-xml-declaration?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

parameter-document?

{ uri }

Новое в XSLT 3.0. Не реализовано в Saxon 9.7. Позволяет настраивать сериализацию во внешнем документе.

standalone?

{ boolean | "omit" }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

suppress-indentation?

{ eqnames }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

undeclare-prefixes?

{ boolean }

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

use-character-maps?

eqnames

Атрибут сериализации, для получения дополнительной информации см. раздел Подробности.

output-version?

{ nmtoken }

Переопределяет атрибут version, указанный в определении вывода. Атрибут сериализации, более подробную информацию смотрите в разделе Подробности.

saxon:asynchronous?

boolean

По умолчанию для Saxon-EE используется yes, что заставляет инструкцию оцениваться в отдельном потоке, если есть свободный поток (максимальное количество используемых потоков настраивается с помощью Feature.RESULT_DOCUMENT_THREADS). Используйте no для подавления многопоточности. Асинхронная обработка xsl:result-document автоматически подавляется, если включена трассировка (с помощью TraceListener). Подробности см. в saxon:asynchronous и примечаниях ниже.

Заметки по реализации Saxon

Начиная с версии Saxon 9.5, инструкция xsl:result-document в Saxon-EE является асинхронной. То есть код для вывода результирующего документа выполняется в отдельном потоке, параллельно с другими процессами. Максимальное количество потоков, используемых инструкциями xsl:result-document, ограничено параметром конфигурации Feature.RESULT_DOCUMENT_THREADS, который по умолчанию равен количеству процессоров, доступных Java VM; установка этого параметра в ноль или единицу подавляет многопоточность. Установка Feature.ALLOW_MULTITHREADING в false имеет тот же эффект. (Это может быть полезно при отладке, поскольку в противном случае вывод xsl:message и fn:trace() может быть очень запутанным).

Асинхронность также потенциально может вызвать проблемы, если код вызывает функции расширения, которые имеют побочные эффекты. Поэтому при необходимости многопоточность можно контролировать с помощью атрибута saxon:asynchronous инструкции xsl:result-document: используйте saxon:asynchronous="no" для подавления многопоточности. Асинхронная обработка xsl:result-document автоматически подавляется, если включена трассировка (с помощью TraceListener).

Инструкция xsl:result-document может также принимать параметр сериализации расширения saxon:indent-spaces. Этот атрибут может быть AVT, так что значения могут быть определены во время выполнения. Любые значения, указанные в инструкции xsl:result-document, переопределяют значения, указанные в объявлении xsl:output.

Новый атрибут XSLT 3.0 parameter-document впервые реализован в Saxon 9.8.

В Saxon 9.9 есть изменение в том, как обрабатывается инструкция xsl:result-document без атрибута href. В предыдущих выпусках Saxon пытался повторно использовать поток вывода, созданный для первичного вывода трансформации. Новые опции XSLT 3.0 (такие как необработанный вывод) делают это сложным и, возможно, несоответствующим требованиям. Поэтому новая модель заключается в том, что атрибут href просто устанавливается по умолчанию на базовый выходной URI, а в остальном обрабатывается так же, как и любой другой вызов xsl:result-document. Это означает, что если не указан базовый выходной URI, то в этом случае произойдет сбой. Это также означает, что если используется пользовательский преобразователь результирующего документа, он будет вызван для обработки этого случая с базовым выходным URI, предоставленным в качестве аргумента URI. Для получения дополнительной информации см. раздел Разрешение URI выходных файлов.

Подробности

Элемент xsl:result-document был введен в XSLT 2.0, заменив предыдущий элемент расширения saxon6:output (который был восстановлен в Saxon 9.9 как синоним xsl:result-document, поскольку устаревшие таблицы стилей все еще используют его).

Назначение результирующего документа может быть изменено программно, как описано в разделе Разрешение URI выходных файлов. В других случаях документ сериализуется и записывается в файл, идентифицированный URI в атрибуте href, разрешенный, если он является относительным по отношению к базовому выходному URI для трансформации (который по умолчанию является местом назначения основного выходного документа). Место назначения должно использовать схему URI file:/. Любой предыдущий файл в этом месте перезаписывается. Если преобразование завершается с динамической ошибкой, содержимое всех выходных файлов не определяется (не предпринимается попыток вернуть их в исходное состояние).

Атрибуты сериализации method, allow-duplicate-names, build-tree, byte-order-mark, cdata-section-elements, doctype-public, doctype-system, encoding, escape-uri-attributes, html-version, include-content-type, indent, item-separator, json-node-output-method, media-type, normalization-form, omit-xml-declaration, standalone, uppress-indentation, undeclare-prefixes, use-character-maps и output-version могут быть использованы для переопределения атрибутов, определенных в определении вывода. Полные определения этих атрибутов см. в документации к соответствующему элементу xsl:output.

За исключением use-character-maps, любой из этих атрибутов сериализации может быть AVT, так что значения могут быть определены во время выполнения. Для любого из этих атрибутов, который присутствует в инструкции xsl:result-document, эффективное значение атрибута переопределяет или дополняет соответствующее значение из определения вывода. В случае cdata-section-elements и uppress-indentation, значение параметра сериализации является объединением расширенных имен элементов, названных в этой инструкции, и элементов, названных в выбранном определении вывода. В случае use-character-maps, карты символов, на которые ссылается эта инструкция, дополняют и имеют приоритет над картами, определенными в определении вывода. Во всех остальных случаях приоритет имеют значения атрибутов сериализации в инструкции xsl:result-document.

Примеры

В следующем примере тело предисловия направляется в файл под названием preface.html (с префиксом в виде константы, задающей имя каталога). Затем вывод возвращается к предыдущему месту назначения, где вставляется гиперссылка HTML на вновь созданный файл.

<xsl:template match="preface">
    <xsl:result-document href="{$dir}/preface.html" method="html">
        <html><body bgcolor="#00eeee"><center>
            <xsl:apply-templates/>
        </center><hr/></body></html>
    </xsl:result-document>
    <a href="{$dir}/preface.html">Preface</a>
</xsl:template>

Ссылки

• XSLT 2.0 Specification
• XSLT 3.0 Specification
• Saxon

См. также

• xsl:output

Комментарии