Интерфейс LSSerializer

Во время сериализации XML-данных выполняется корректировка пространства имён, как определено в [DOM Level 3 Core], Приложение B. [DOM Level 2 Core] допускает пустые строки в качестве реального URI пространства имен. Если namespaceURI Node является пустой строкой, сериализация будет обрабатывать их как null, игнорируя префикс, если таковой имеется.

LSSerializer принимает любой тип узла для сериализации. Для узлов типа Document или Entity, при возможности, будет создан корректный XML (корректность гарантируется, если документ или сущность получены из операции разбора и не изменены с момента создания). Сериализованный вывод для этих типов узлов представляет собой либо XML-документ, либо внешнюю XML-сущность, и является приемлемым вводом для XML-парсера. Для всех других типов узлов сериализованная форма зависит от реализации.

Внутри Document, DocumentFragment или Entity, подлежащих сериализации, Nodes обрабатываются следующим образом

• Узлы Document записываются, включая объявление XML (если параметр "xml-declaration" не установлен в значение false) и подмножество DTD, если оно существует в DOM. Запись узла Document сериализует весь документ.
• Узлы Entity, когда записываются напрямую LSSerializer.write, выводит расширение сущности, но корректировка пространства имён не выполняется. Результативный вывод будет корректным как внешняя сущность.
• Если параметр "entities" установлен в значение true, узлы EntityReference сериализуются как ссылка на сущность вида " &entityName;" в выводе. Дочерние узлы (расширение) ссылки на сущность игнорируются. Если параметр "entities" установлен в значение false, сериализуются только дочерние узлы ссылки на сущность. Узлы EntityReference без дочерних узлов (без соответствующего узла Entity или соответствующие узлы Entity без дочерних узлов) всегда сериализуются.
• Узлы CDATAsections, содержащие символы контента, которые невозможно представить в указанной кодировке вывода, обрабатываются в соответствии с параметром "split-cdata-sections". Если параметр установлен в значение true, CDATAsections разделяются, а непредставимые символы сериализуются в виде числовых ссылок на символы в обычном содержимом. Точное расположение и количество разделов не указано. Если параметр установлен в значение false, непредставимые символы в CDATAsection сообщаются как "wf-invalid-character" ошибки, если параметр "well-formed" установлен в значение true. Ошибка необрабатываема — нет механизма для предоставления альтернативных символов и продолжения сериализации.
• Узлы DocumentFragment сериализуются путём сериализации дочерних узлов фрагмента документа в порядке их появления во фрагменте документа.
• Все другие типы узлов (Element, Text и т.д.) сериализуются в соответствующую XML-форму.

Примечание: Сериализация Node не всегда генерирует корректный XML-документ, т.е. LSParser может генерировать фатальные ошибки при парсинге полученной сериализации.

В текстовом содержимом документа (вне разметки) любые символы, которые нельзя представить непосредственно, заменяются ссылками на символы. Вхождения '<' и '&' заменяются предопределёнными сущностями &lt; и &amp;. Другие предопределённые сущности (&gt;, &apos; и &quot;) могут не использоваться, за исключением случаев необходимости (например, использование &gt; в таких случаях, как ']]>'). Любые символы, которые нельзя непосредственно представить в кодировке вывода, сериализуются как числовые ссылки на символы (и поскольку стандарты кодировки символов обычно используют шестнадцатеричные представления символов, рекомендуется использовать шестнадцатеричное представление при сериализации ссылок на символы).

Для возможности использования одинарных и двойных кавычек в значениях атрибутов символ апострофа (') может быть представлен как "&apos;", а символ двойной кавычки (") — как "&quot;". Символы новой строки и другие символы, которые нельзя непосредственно представить в значениях атрибутов в кодировке вывода, сериализуются как числовые ссылки на символы.

Внутри разметки, но вне атрибутов, любое вхождение символа, который нельзя представить в кодировке вывода, сообщается как фатальная ошибка DOMError. Примером может служить сериализация элемента <LaCañada/> с encoding="us-ascii". Это приведёт к генерации ошибки DOMError "wf-invalid-character-in-node-name" (как предложено в "well-formed").

По запросу путём установки параметра "normalize-characters" на LSSerializer в значение true выполняется нормализация символов в соответствии с определением полностью нормализованных символов, включённых в приложение E [XML 1.1] во всех данных, подлежащих сериализации, как в разметке, так и в текстовом содержимом. Процесс нормализации символов влияет только на данные при их записи; он не изменяет представление документа DOM после завершения сериализации.

Реализации должны поддерживать кодировки "UTF-8", "UTF-16", "UTF-16BE" и "UTF-16LE", чтобы гарантировать, что данные можно сериализовать во всех кодировках, которые должны поддерживаться всеми XML-парсерами. При кодировке UTF-8, сериализация символа порядка байтов, или является ли вывод big-endian или little-endian, зависит от реализации. При кодировке UTF-16, является ли вывод big-endian или little-endian, зависит от реализации, но маркер порядка байтов должен быть сгенерирован для выводов, не являющихся символами, таких как LSOutput.byteStream или LSOutput.systemId. Если маркер порядка байтов не сгенерирован, выдаётся предупреждение "byte-order-mark-needed". При кодировке UTF-16LE или UTF-16BE, вывод представляет собой big-endian (UTF-16BE) или little-endian (UTF-16LE), и маркер порядка байтов не генерируется. Во всех случаях объявление кодировки, если оно сгенерировано, будет соответствовать кодировке, использованной при сериализации (например, encoding="UTF-16" будет отображаться, если была запрошена UTF-16).

Пространства имён корректируются во время сериализации; процесс сериализации проверяет, что объявления пространств имён, префиксы пространств имён и URI пространства имён, связанные с элементами и атрибутами, согласованы. Если обнаружены несоответствия, сериализованная форма документа будет изменена, чтобы устранить их. Метод, используемый для корректировки пространства имён при сериализации документа, — это алгоритм, определённый в Приложении B.1, "Нормализация пространства имён", [DOM Level 3 Core].

При сериализации документа параметр "discard-default-content" управляет тем, сериализуются ли не указанные данные.

Во время сериализации ошибки и предупреждения сообщаются приложению через обработчик ошибок (параметр "error-handler" LSSerializer.domConfig). Данный документ не пытается определить все возможные ошибки и предупреждения, которые могут возникнуть при сериализации узла DOM, но некоторые распространённые случаи ошибок и предупреждений определены. Типы ( DOMError.type) ошибок и предупреждений, определённые в этом спецификации, следующие:

"no-output-specified" [fatal]

Возникает при записи в LSOutput, если в LSOutput не указан вывод.

"unbound-prefix-in-entity-reference" [fatal]

Возникает, если параметр конфигурации "namespaces" установлен в значение true и к сущности, текст замены которой содержит несвязанные префиксы пространства имён, обращаются в месте, где нет связей для префиксов пространства имён.

"unsupported-encoding" [fatal]

Возникает при обнаружении неподдерживаемой кодировки.

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

См. также Спецификацию загрузки и сохранения документа (DOM) уровня 3.