org.w3c.dom.ls

Интерфейсный LSSerializer

public interface LSSerializer

A LSSerializer обеспечивает API для того, чтобы он сериализировал выписывание документа ДОМА в XML. Данные XML пишутся строке или потоку вывода. Любые изменения или fixups, сделанный во время сериализации, влияют только на сериализированные данные. Document возразите и его дочерние элементы никогда не изменяются работой сериализации.

Во время сериализации данных XML пространство имен fixup делается как определено в [ДОМ Левель 3 Ядра], Приложение B. [ДОМ Левель, которого 2 Ядра] позволяют пустым строкам как реальному URI пространства имен. Если namespaceURI из a Node пустая строка, сериализация обработает их как null, игнорирование префикса, если любой.

LSSerializer принимает любой тип узла для сериализации. Для узлов типа Document или Entity, правильно построенный XML будет создаваться, когда возможный (отмеченность гарантируется, если документ или объект прибудут из работы синтаксического анализа и будут неизменны, так как это создавалось). Сериализированный вывод для этих, которые вводит узел, или как XML-документ или как Внешний XML Объект, соответственно, и является приемлемым вводом для синтаксического анализатора XML. Для всех других типов узлов сериализированная форма является зависящей от реализации.

В пределах a Document, DocumentFragment, или Entity быть сериализированным, Nodes обрабатываются следующим образом

• Document узлы пишутся, включая объявление XML (если параметры "xml-объявление" не устанавливаются к false) и подмножество DTD, если Вы существуете в ДОМЕ. Запись a Document узел сериализирует весь документ.
• Entity узлы, когда записано непосредственно LSSerializer.write, выводит расширение объекта, но никакое пространство имен fixup не делается. Получающийся вывод будет допустим как внешний объект.
• Если параметры "объекты" устанавливаются к true, EntityReference узлы сериализируются как ссылка на сущность формы" &entityName;"в выводе. Игнорируются дочерние узлы (расширение) ссылки на сущность. Если параметры "объекты" устанавливаются к false, только дочерние элементы ссылки на сущность сериализируются. EntityReference узлы без дочерних элементов (никакое соответствие Entity узел или соответствие Entity у узлов нет никаких дочерних элементов), всегда сериализируются.
• CDATAsections содержа символы контента, которые не могут быть представлены в указанном выходном кодировании, обрабатывается согласно "split-cdata-sections" параметру. Если параметры устанавливаются к true, CDATAsections разделяются, и непредставимые символы сериализируются как ссылки цифры в обычном контенте. Точная позиция и число разделений не определяются. Если параметры устанавливаются к false, непредставимые символы в a CDATAsection сообщаются как "wf-invalid-character" ошибки, если "правильно построенные" параметры устанавливаются к true. Ошибка не восстанавливаема - нет никакого механизма для того, чтобы предоставить альтернативные символы и продолжаться с сериализацией.
• DocumentFragment узлы сериализируются, сериализируя дочерние элементы фрагмента документа в порядке, они появляются во фрагменте документа.
• Все другие типы узла (Элемент, текст, и т.д.) сериализируются к их соответствующей исходной форме XML.

Отметьте: сериализация a Node не всегда генерирует правильно построенный XML-документ, то есть a LSParser мог бы бросить фатальные ошибки, анализируя получающуюся сериализацию.

В пределах символьных данных документа (за пределами разметки), любые символы, которые не могут быть представлены непосредственно, заменяются символьными ссылками. Возникновения' <' и '&' заменяются предопределенными объектами &lt; и &amp;. Другие предопределенные объекты (&gt; &apos; и &quot;) не мог бы использоваться, кроме где необходимый (например, использующий &gt; в случаях такой как']]>'). Любые символы, которые не могут быть представлены непосредственно в выходной кодировке символов, сериализируются как ссылки цифры (и так как стандарты кодировки символов обычно используют шестнадцатеричные представления символов, используя шестнадцатеричное представление, когда сериализация символьных ссылок поощряется).

Позволить значениям атрибута содержать и одинарные и двойные кавычки, апостроф или символ одинарной кавычки (') может быть представлено как "&apos;", и символ двойной кавычки (") как "&quot;". Новые знаки строки и другие символы, которые не могут быть представлены непосредственно в значениях атрибута в выходной кодировке символов, сериализируются как ссылка цифры.

В пределах разметки, но за пределами атрибутов, о любом возникновении символа, который не может быть представлен в выходной кодировке символов, сообщают как a DOMError фатальная ошибка. Пример сериализировал бы элемент <LaCañada/> с encoding="us-ascii". Это закончится с генерацией a DOMError "wf-invalid-character-in-node-name" (как предложено в "правильно построенном").

Когда требующийся, устанавливая параметр "нормализовать-символы" на LSSerializer к истине символьная нормализация выполняется согласно определению полностью нормализованных символов, включенных в приложение E [XML 1.1] на всех данных, которые будут сериализированы, и разметка и символьные данные. Символьный процесс нормализации влияет только на данные, как это пишется; это не изменяет представление DOM документа после того, как сериализация завершилась.

Реализации обязаны поддерживать кодировки "UTF-8", "UTF-16", "UTF-16BE", и "UTF-16LE", чтобы гарантировать, что данные сериализуемы во всех кодировках, которые обязаны поддерживаться всеми синтаксическими анализаторами XML. То, когда кодирование является UTF-8, сериализируется ли метка порядка байтов, или если вывод с обратным порядком байтов или с прямым порядком байтов, является зависящим от реализации. Когда кодирование является UTF-16, с обратным порядком байтов ли вывод, или с прямым порядком байтов является зависящим от реализации, но Порядок байтов, Марк должен быть сгенерирован для невыводов символов, такой как LSOutput.byteStream или LSOutput.systemId. Если Порядок байтов, Марк не сгенерирован, метка порядка байтов, нуждался в предупреждении, сообщается. Когда кодирование является UTF-16LE или UTF-16BE, вывод является обратным порядком байтов (UTF-16BE) или прямым порядком байтов (UTF-16LE) и Порядком байтов, который Марк не быть сгенерированным. Во всех случаях объявление кодирования, если сгенерировано, будет соответствовать кодированию, используемому во время сериализации (например. encoding="UTF-16" появится, если UTF-16 требовали).

Пространства имен ремонтируются во время сериализации, процесс сериализации проверит, что объявления пространства имен, префиксы пространства имен и URI пространства имен, связанный с элементами и атрибутами, являются непротиворечивыми. Если несогласованности будут найдены, то сериализированная форма документа будет изменена, чтобы удалить их. Метод, используемый для того, чтобы сделать пространство имен fixup, сериализируя документ, является алгоритмом, определенным в Приложении B.1, "Нормализация пространства имен", из [ДОМ Левель 3 Ядра].

Сериализируя документ, параметр "контент по умолчанию отбрасывания" управляет, сериализируются ли неуказанные данные.

Сериализируя, об ошибках и предупреждениях сообщают приложению через обработчик ошибок (LSSerializer.domConfig's параметр "обработчика ошибок"). Эта спецификация никоим образом не пытается определить все возможные ошибки и предупреждения, которые могут произойти, сериализируя узел ДОМА, но некоторую распространенную ошибку и предупреждая, что случаи определяются. Типы ( DOMError.type) из ошибок и предупреждений, определенных этой спецификацией:

"no-output-specified" [fatal]

Повышенный при записи в a LSOutput если никакой вывод не определяется в LSOutput.

"unbound-prefix-in-entity-reference" [fatal]

Повышенный, если параметр конфигурации "пространства имен" устанавливается в true и на объект, заменяющий текст которого содержит несвязанные префиксы пространства имен, ссылаются в расположении, где нет никакой привязки для префиксов пространства имен.

"unsupported-encoding" [fatal]

Повышенный, если с неподдерживаемым кодированием встречаются.

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

См. также Объектную модель документа (ДОМ) Загрузка Уровня 3 и Сохраните Спецификацию.

Сводка метода

Методы

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

Деталь метода

getDomConfig

DOMConfiguration getDomConfig()

DOMConfiguration объект, используемый LSSerializer сериализируя узел ДОМА.
В дополнение к параметрам, распознанным интерфейсом DOMConfiguration, определенным в [ДОМ Левель 3 Ядра], DOMConfiguration объекты для LSSerializer добавляет, или изменяет, следующие параметры:

"canonical-form"

true

[дополнительные] Записи документ согласно правилам, определенным в [Канонический XML]. В дополнение к поведению, описанному в "канонической форме" [ДОМ Левель 3 Ядра], устанавливая эти параметры к true установит параметры "структурная распечатка программы формата", "контент по умолчанию отбрасывания", и "xml-объявление", к false. Установка одного из тех параметров к true установит эти параметры к false. Сериализация документа XML 1.1, когда "каноническая форма" 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] поддерживается, с символом встречаются, для которого свойства нормализации не могут быть определены, затем повысить a "unknown-character-denormalization" предупреждение (вместо того, чтобы повысить ошибку, если эти параметры не устанавливаются) и игнорирует любые возможные денормализации, вызванные этими символами.

false

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

"normalize-characters"

Этот параметр эквивалентен тому, определенному DOMConfiguration в [ДОМ Левель 3 Ядра]. В отличие от этого в Ядре, значение по умолчанию для этого параметра true. В то время как реализации ДОМА не обязаны поддерживать полностью нормализование символов в документе согласно приложению E [XML 1.1], этот параметр должен быть активирован по умолчанию если поддерживающийся.

"xml-declaration"

true

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

false

[требуемый] не сериализируют объявления XML и текста. Отчет a "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). Используя другие символьные последовательности чем рекомендуемые может привести к документу, который или не сериализуем или не правильно построен).
На извлечении значение по умолчанию этого атрибута является реализацией определенная последовательность конца строки по умолчанию. Реализации ДОМА должны выбрать значение по умолчанию, чтобы соответствовать обычное соглашение для текстовых файлов в используемой среде. Реализации должны выбрать последовательность по умолчанию, которая соответствует один из позволенных 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). Используя другие символьные последовательности чем рекомендуемые может привести к документу, который или не сериализуем или не правильно построен).
На извлечении значение по умолчанию этого атрибута является реализацией определенная последовательность конца строки по умолчанию. Реализации ДОМА должны выбрать значение по умолчанию, чтобы соответствовать обычное соглашение для текстовых файлов в используемой среде. Реализации должны выбрать последовательность по умолчанию, которая соответствует один из позволенных XML 1.0 или XML 1.1, в зависимости от сериализированного контента. Установка этого атрибута к null сбросит его значение к значению по умолчанию.

getFilter

LSSerializerFilter getFilter()

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

setFilter

void setFilter(LSSerializerFilter filter)

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

записать

boolean write(Node nodeArg,
            LSOutput destination)
              throws LSException

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

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

Если никакое кодирование не будет достижимо через вышеупомянутые свойства, то кодировка по умолчанию "UTF-8" будет использоваться. Если указанное кодирование не поддерживается повышается, "неподдерживаемый закодированная" фатальная ошибка.
Если никакой вывод не определяется в LSOutput, никакой вывод определенная фатальная ошибка не повышается.
Реализация ответственна за соединение соответствующего типа носителя с сериализированными данными.
При записи в URI HTTP ПОМЕЩЕННЫЙ HTTP выполняется. При записи в другие типы URI механизм для того, чтобы записать данные в URI является зависящим от реализации.

Параметры:

nodeArg - Узел, чтобы сериализировать.

destination - Место назначения для сериализированного ДОМА.

Возвраты:

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

Броски:

LSException - SERIALIZE_ERR: Повышенный, если LSSerializer было неспособно сериализировать узел. Приложения ДОМА должны присоединить a DOMErrorHandler использование параметра "обработчик ошибок", если они хотят получить детали об ошибке.

writeToURI

boolean writeToURI(Node nodeArg,
                 String uri)
                   throws LSException

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

Параметры:

nodeArg - Узел, чтобы сериализировать.

uri - URI, чтобы записать в.

Возвраты:

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

Броски:

LSException - SERIALIZE_ERR: Повышенный, если LSSerializer было неспособно сериализировать узел. Приложения ДОМА должны присоединить a DOMErrorHandler использование параметра "обработчик ошибок", если они хотят получить детали об ошибке.

writeToString

String writeToString(Node nodeArg)
                     throws DOMException,
                            LSException

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

Параметры:

nodeArg - Узел, чтобы сериализировать.

Возвраты:

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

Броски:

DOMException - DOMSTRING_SIZE_ERR: Повышенный, если получающаяся строка является слишком длинной, чтобы поместиться в a DOMString.

LSException - SERIALIZE_ERR: Повышенный, если LSSerializer было неспособно сериализировать узел. Приложения ДОМА должны присоединить a DOMErrorHandler использование параметра "обработчик ошибок", если они хотят получить детали об ошибке.