Интерфейс 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, нормализация символов выполняется в соответствии с определением полностью нормализованных символов, включённых в приложение Е [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]

Возникает, если встречается неподдерживаемая кодировка.

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

См. также Спецификацию загрузки и сохранения (Load and Save) Объектной модели документа (DOM) уровня 3.