Интерфейс 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 выводится раскрытие сущности, но исправление пространств имён не выполняется. Полученный вывод будет допустим в качестве внешней сущности.
Если параметру "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 после завершения сериализации.

Для гарантии возможности сериализации данных во всех кодировках, которые должны поддерживаться всеми анализаторами XML, реализации обязаны поддерживать кодировки "UTF-8", "UTF-16", "UTF-16BE" и "UTF-16LE". При кодировке UTF-8 факт сериализации маркера порядка байтов, а также порядок байтов (от старшего к младшему или от младшего к старшему) зависят от реализации. При кодировке UTF-16 порядок байтов (от старшего к младшему или от младшего к старшему) зависит от реализации, однако для выходных данных, не являющихся символами, например LSOutput.byteStream или LSOutput.systemId, должен создаваться маркер порядка байтов. Если маркер порядка байтов не создан, выдаётся предупреждение "byte-order-mark-needed". При кодировке UTF-16LE или UTF-16BE выходные данные имеют порядок байтов от старшего к младшему (UTF-16BE) или от младшего к старшему (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 или текстовое объявление. В сериализованном объявлении XML указываются версия (Document.xmlVersion, если документ относится к уровню 3 и версия не равна null; в противном случае используется значение "1.0") и выходная кодировка (подробные сведения о том, как определить выходную кодировку, см. в LSSerializer.write).
false: [обязательный] Не сериализовать объявления XML и текста. Если это приведёт к проблемам (например, если сериализованные данные имеют версию XML, отличную от [XML 1.0], или для повторного разбора сериализованных данных потребуется кодировка), выдать предупреждение "xml-declaration-needed".

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".
Реализация отвечает за связывание сериализованных данных с соответствующим типом носителя.
При записи в URI HTTP выполняется запрос 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 с помощью параметра "error-handler".

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 с помощью параметра "error-handler".

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