Интерфейс LSSerializer

public interface LSSerializer

Объект LSSerializer предоставляет API для сериализации (записи) документа DOM в XML. Данные XML записываются в строку или в поток вывода. Любые изменения или корректировки, внесенные во время сериализации, влияют только на сериализованные данные. Объект Document и его потомки никогда не изменяются операцией сериализации.

При сериализации данных 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 выводят расширение сущности, но корректировка пространств имён не выполняется. Результат будет валиден как внешняя сущность.
• Если параметр " сущностей" установлен в true, узлы EntityReference сериализуются как ссылка на сущность вида "&entityName;" в выводе. Дочерние узлы (расширение) ссылки на сущность игнорируются. Если параметр " сущностей" установлен в 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 Level 3.

Методы

getDomConfig

DOMConfiguration getDomConfig()

Объект DOMConfiguration, используемый LSSerializer при сериализации узла DOM.
В дополнение к параметрам, распознаваемым интерфейсом DOMConfiguration, определенным в [DOM Level 3 Core], объекты DOMConfiguration для LSSerializer добавляют или изменяют следующие параметры:

"canonical-form"

true

[необязательно] Записывает документ в соответствии с правилами, указанными в [Canonical XML]. В дополнение к поведению, описанному в "canonical-form" [DOM Level 3 Core], установка этого параметра в значение true установит параметры "format-pretty-print", "discard-default-content" и "xml-declaration" в значение false. Установка любого из этих параметров в значение true установит этот параметр в значение false. Сериализация документа XML 1.1, когда "canonical-form" имеет значение true, вызовет ошибку fatal error.

false

[обязательно] (по умолчанию) Не канонизировать вывод.

"discard-default-content"

true

[обязательно] (по умолчанию) Использует атрибут Attr.specified, чтобы определить, какие атрибуты следует отбросить. Обратите внимание, что некоторые реализации могут использовать любую доступную информацию (например, схему XML, DTD, атрибут Attr.specified, и т. д.) для определения атрибутов и содержимого, которые следует отбросить, если этот параметр установлен в значение true.

false

[обязательно] Сохранить все атрибуты и всё содержимое.

"format-pretty-print"

true

[необязательно] Форматирование вывода путем добавления пробелов для создания красивого, отступающего, удобочитаемого формата. Точная форма преобразований не указана в этом спецификации. Красивое форматирование изменяет содержимое документа и может повлиять на его валидность, валидирующие реализации должны сохранить валидность.

false

[обязательно] (по умолчанию) Не форматировать результат.

"ignore-unknown-character-denormalizations"

true

[обязательно] (по умолчанию) Если при проверке полной нормализации, когда поддерживается [XML 1.1], встречается символ, для которого невозможно определить свойства нормализации, то выводится предупреждение "unknown-character-denormalization" (вместо вывода ошибки, если этот параметр не задан), и игнорируются любые возможные денормализации, вызванные этими символами.

false

[необязательно] Вывести ошибку fatal error, если встречается символ, для которого процессор не может определить свойства нормализации.

"normalize-characters"

Этот параметр эквивалентен параметру, определенному DOMConfiguration в [DOM Level 3 Core]. В отличие от Core, значение по умолчанию для этого параметра — true. Хотя реализации DOM не обязаны поддерживать полную нормализацию символов в документе в соответствии с приложением E [XML 1.1], этот параметр должен быть активирован по умолчанию, если поддерживается.

"xml-declaration"

true

[обязательно] (по умолчанию) Если сериализуется узел Document, Element, или Entity, должна быть включена декларация XML или текстовая декларация. Версия (Document.xmlVersion, если документ — документ уровня 3 и версия не null, в противном случае используется значение "1.0"), и кодировка вывода (см. LSSerializer.write для получения информации о том, как найти кодировку вывода) указаны в сериализованной декларации XML.

false

[обязательно] Не сериализовать декларации XML и текста. Выдать предупреждение "xml-declaration-needed" , если это вызовет проблемы (т. е. сериализованные данные имеют другую версию XML, кроме [XML 1.0], или потребуется кодировка, чтобы перепарсить сериализованные данные).

getNewLine

String getNewLine()

Последовательность символов конца строки, которые будут использоваться в выводимом XML. Поддерживается любая строка, но XML обрабатывает только определенный набор последовательностей символов как конец строки (См. раздел 2.11, "Обработка конца строки" в [XML 1.0], если сериализуемое содержимое XML 1.0, или раздел 2.11, "Обработка конца строки" в [XML 1.1], если сериализуемое содержимое XML 1.1). Использование других последовательностей символов, отличных от рекомендуемых, может привести к тому, что документ будет не сериализуемым или не будет правильно сформирован.
При получении значение по умолчанию этого атрибута — специфичная для реализации последовательность символов конца строки по умолчанию. Реализации DOM должны выбрать значение по умолчанию, соответствующее общепринятой конвенции для текстовых файлов в используемой среде. Реализации должны выбрать последовательность по умолчанию, соответствующую одной из разрешенных XML 1.0 или XML 1.1 в зависимости от сериализуемого содержимого. Установка этого атрибута в значение null сбросит его значение до значения по умолчанию.

setNewLine

void setNewLine(String newLine)

Последовательность символов конца строки, которые будут использоваться в выводимом XML. Поддерживается любая строка, но XML обрабатывает только определенный набор последовательностей символов как конец строки (См. раздел 2.11, "Обработка конца строки" в [XML 1.0], если сериализуемое содержимое XML 1.0, или раздел 2.11, "Обработка конца строки" в [XML 1.1], если сериализуемое содержимое XML 1.1). Использование других последовательностей символов, отличных от рекомендуемых, может привести к тому, что документ будет не сериализуемым или не будет правильно сформирован.
При получении значение по умолчанию этого атрибута — специфичная для реализации последовательность символов конца строки по умолчанию. Реализации DOM должны выбрать значение по умолчанию, соответствующее общепринятой конвенции для текстовых файлов в используемой среде. Реализации должны выбрать последовательность по умолчанию, соответствующую одной из разрешенных XML 1.0 или XML 1.1 в зависимости от сериализуемого содержимого. Установка этого атрибута в значение null сбросит его значение до значения по умолчанию.

getFilter

LSSerializerFilter getFilter()

Если приложение предоставляет фильтр, сериализатор вызовет фильтр перед сериализацией каждого узла. Реализация фильтра может выбрать удаление узла из потока или прервать сериализацию досрочно.
Фильтр вызывается после применения операций, запрошенных параметрами DOMConfiguration. Например, секции CDATA не будут переданы фильтру, если "cdata-sections" установлен в значение false.

setFilter

void setFilter(LSSerializerFilter filter)

Если приложение предоставляет фильтр, сериализатор вызовет фильтр перед сериализацией каждого узла. Реализация фильтра может выбрать удаление узла из потока или прервать сериализацию досрочно.
Фильтр вызывается после применения операций, запрошенных параметрами DOMConfiguration. Например, секции CDATA не будут переданы фильтру, если "cdata-sections" установлен в значение false.

write

boolean write(Node nodeArg,
              LSOutput destination)
       throws LSException

Сериализует указанный узел, как описано выше в общем описании интерфейса LSSerializer. Вывод записывается в предоставленный LSOutput.
При записи в LSOutput, кодировка определяется по информации о кодировке, доступной через LSOutput и записываемый элемент (или его документ-владелец) в таком порядке:

1. LSOutput.encoding,
2. Document.inputEncoding,
3. Document.xmlEncoding.

Если кодировка не доступна через вышеперечисленные свойства, используется кодировка по умолчанию "UTF-8". Если указанная кодировка не поддерживается, возникает ошибка "unsupported-encoding" fatal error.
Если вывод не указан в LSOutput, возникает ошибка "no-output-specified" fatal error.
Реализация отвечает за присвоение соответствующего типа носителя сериализованным данным.
При записи в HTTP URI выполняется HTTP PUT. При записи в другие типы URI механизм записи данных в URI зависит от реализации.

Параметры:

nodeArg - Узел для сериализации.

destination - Назначение для сериализованного DOM.

Возвращает:

Возвращает true , если node был успешно сериализован. Возвращает false в случае остановки обычной обработки, но реализация продолжала сериализацию документа; результат сериализации затем зависит от реализации.

Вызывает:

LSException - SERIALIZE_ERR: Возникает, если LSSerializer не смог сериализовать узел. Приложения DOM должны прикрепить обработчик ошибок DOMErrorHandler с помощью параметра "error-handler", если они хотят получить подробную информацию об ошибке.

writeToURI

boolean writeToURI(Node nodeArg,
                   String uri)
            throws LSException

Удобный метод, который действует так, как будто LSSerializer.write был вызван с LSOutput без указания кодировки и LSOutput.systemId установлен на аргумент uri.

Параметры:

nodeArg - Узел для сериализации.

uri - URI для записи.

Возвращает:

Возвращает true если node был успешно сериализован. Возвращает false в случае, если обычная обработка была остановлена, но реализация продолжила сериализацию документа; результат сериализации зависит от реализации.

Исключения:

LSException - SERIALIZE_ERR: Возникает, если LSSerializer не смог сериализовать узел. Приложения DOM должны прикрепить обработчик ошибок DOMErrorHandler с помощью параметра " обработчик ошибок", если они хотят получить подробности об ошибке.

writeToString

String writeToString(Node nodeArg)
              throws DOMException,
                     LSException

Сериализуйте указанный узел, как описано выше в общем описании интерфейса LSSerializer. Вывод записывается в DOMString, который возвращается вызывающей стороне. Используемый кодировка — кодировка типа DOMString, т. е. UTF-16. Обратите внимание, что в объекте DOMString не генерируется маркер порядка байтов.

Параметры:

nodeArg - Узел для сериализации.

Возвращает:

Возвращает сериализованные данные.

Исключения:

DOMException - DOMSTRING_SIZE_ERR: Возникает, если результирующая строка слишком длинная для размещения в DOMString.

LSException - SERIALIZE_ERR: Возникает, если LSSerializer не смог сериализовать узел. Приложения DOM должны прикрепить обработчик ошибок DOMErrorHandler с помощью параметра " обработчик ошибок", если они хотят получить подробности об ошибке.