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

С момента:: 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] . В отличие от Core, значение по умолчанию для этого параметра равно true. Хотя DOM-реализации не обязаны поддерживать полную нормализацию символов в документе в соответствии с приложением E [XML 1.1], этот параметр должен быть активирован по умолчанию, если он поддерживается.

"xml-declaration"

true: [обязательно] (по умолчанию) Если сериализуется узел Document, Element, или Entity, должна быть включена декларация XML или текст декларации. Версия (Document.xmlVersion если документ является документом Level 3 и версия не пустая, в противном случае используется значение "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.

Parameters:: nodeArg - Узел для сериализации.; uri - URI для записи.
Returns:: Возвращает true, если node был успешно сериализован. Возвращает false, если обычная обработка была остановлена, но реализация продолжала сериализацию документа; результат сериализации зависит от реализации.
Throws:: LSException - SERIALIZE_ERR: Вызвано, если LSSerializer не смог сериализовать узел. Приложения DOM должны прикрепить DOMErrorHandler используя параметр "обработчик ошибок", если они хотят получить подробности об ошибке.

writeToString

String writeToString(Node nodeArg) throws DOMException, LSException

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

Parameters:: nodeArg - Узел для сериализации.
Returns:: Возвращает сериализованные данные.
Throws:: DOMException - DOMSTRING_SIZE_ERR: Вызвано, если полученная строка слишком длинная, чтобы поместиться в DOMString.; LSException - SERIALIZE_ERR: Вызвано, если LSSerializer не смог сериализовать узел. Приложения DOM должны прикрепить DOMErrorHandler используя параметр "обработчик ошибок", если они хотят получить подробности об ошибке.

© 1993, 2023, 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/21/docs/api/java.xml/org/w3c/dom/ls/LSSerializer.html