Интерфейс LSSerializer

public interface LSSerializer

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

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

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

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

Внутри разметки, но вне атрибутов, любое вхождение символа, который не может быть представлен в кодировке вывода, регистрируется как фатальная ошибка 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, но некоторые общие случаи ошибок и предупреждений определены.

"no-output-specified" [fatal]: Возникает при записи в LSOutput при отсутствии указанного вывода в LSOutput.
"unbound-prefix-in-entity-reference" [fatal]: Возникает, если параметр конфигурации "namespaces" установлен в значение true и к сущности, текст замены которой содержит не связанные префиксы пространств имён, ссылаются в местоположении, где нет привязок для префиксов пространств имён.
"unsupported-encoding" [fatal]: Возникает, если встречается неподдерживаемая кодировка.

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

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

С:: 1.5

Методы

Модификатор и тип	Метод	Описание
`DOMConfiguration`	`getDomConfig()`	Объект `DOMConfiguration`, используемый в `LSSerializer` при сериализации узла DOM.
`LSSerializerFilter`	`getFilter()`	Если приложение предоставляет фильтр, сериализатор вызовет этот фильтр перед сериализацией каждого узла.
`String`	`getNewLine()`	Последовательность символов конца строки, которая должна использоваться в выводимом XML.
`void`	`setFilter(LSSerializerFilter filter)`	Если приложение предоставляет фильтр, сериализатор вызовет этот фильтр перед сериализацией каждого узла.
`void`	`setNewLine(String newLine)`	Последовательность символов конца строки, которая должна использоваться в выводимом XML.
`boolean`	`write(Node nodeArg, LSOutput destination)`	Сериализация указанного узла, как описано выше в общем описании интерфейса `LSSerializer`.
`String`	`writeToString(Node nodeArg)`	Сериализация указанного узла, как описано выше в общем описании интерфейса `LSSerializer`.
`boolean`	`writeToURI(Node nodeArg, String uri)`	Удобный метод, который действует так, как будто `LSSerializer.write` был вызван с `LSOutput` без указанного кодирования и `LSOutput.systemId` установлено на аргумент `uri`.

Методы

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, вызовет ошибку.
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: [необязательно] Сообщить об ошибке, если встречается символ, для которого процессор не может определить свойства нормализации.

"normalize-characters"

Этот параметр эквивалентен параметру, определённому DOMConfiguration в [DOM Level 3 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)

getFilter

LSSerializerFilter getFilter()

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

setFilter

void setFilter(LSSerializerFilter filter)

write

boolean write(Node nodeArg,
              LSOutput destination)
       throws LSException

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

LSOutput.encoding,
Document.inputEncoding,
Document.xmlEncoding.

Если кодировка не найдена, будет использована кодировка по умолчанию "UTF-8". Если указанная кодировка не поддерживается, генерируется ошибка "unsupported-encoding".
Если выход не указан в LSOutput, генерируется ошибка "no-output-specified".
Реализация отвечает за ассоциацию соответствующего типа носителя с сериализованными данными.
При записи в 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 с использованием параметра «обработчик ошибок», если они хотят получить подробности об ошибке.

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/org/w3c/dom/ls/LSSerializer.html