Интерфейс LSParser

public interface LSParser

Интерфейс объекта, способного создавать или дополнять дерево DOM из различных источников ввода.

LSParser предоставляет API для разбора XML и построения соответствующей структуры документа DOM. Экземпляр LSParser можно получить, вызвав метод DOMImplementationLS.createLSParser().

Как указано в [DOM Level 3 Core] , когда документ впервые становится доступным через LSParser:

никогда не будет двух смежных узлов типа NODE_TEXT, и никогда не будет пустых текстовых узлов.
ожидается, что атрибуты value и nodeValue узла Attr изначально возвращают нормализованное значение XML 1.0. Однако, если параметры "validate-if-schema" и "datatype-normalization" установлены в true, в зависимости от используемой нормализации атрибутов, значения атрибутов могут отличаться от значений, полученных при нормализации атрибутов XML 1.0. Если параметр "datatype-normalization" установлен в false, нормализация атрибутов XML 1.0 гарантируется, и если список атрибутов не содержит объявлений пространства имён, то атрибут attributes узла Element представляет собой свойство [attributes], определённое в [XML Information Set].

Ожидается, что асинхронные объекты LSParser также будут реализовывать интерфейс events::EventTarget, чтобы можно было регистрировать обработчики событий на асинхронных объектах LSParser.

События, поддерживаемые асинхронными объектами LSParser:

load: Загрузка документа LSParser завершена. Смотрите также определение интерфейса LSLoadEvent.
progress: Объект LSParser сигнализирует о ходе обработки, поскольку данные анализируются. В данном спецификации не делается попытка точно определить, когда должны быть отправлены события прогресса. Это намеренно оставлено на усмотрение реализации. Вот один пример того, как приложение может отправлять события прогресса: После того, как анализатор начнёт получать данные, отправляется событие прогресса, чтобы указать на начало разбора. После этого для каждого полученного и обработанного 4096 байт данных отправляется событие прогресса. Однако это всего лишь один пример, и реализации могут выбирать отправлять события прогресса в любое время во время разбора или вообще не отправлять их. Смотрите также определение интерфейса LSProgressEvent.

Примечание: Все события, определённые в этой спецификации, используют URI пространства имён "http://www.w3.org/2002/DOMLS".

Во время разбора источника ввода ошибки сообщаются приложению через обработчик ошибок (параметр "error-handler" LSParser.domConfig). Данная спецификация никоим образом не пытается определить все возможные ошибки, которые могут произойти во время разбора XML или любого другого разметки, но некоторые распространённые случаи ошибок определены. Типы (DOMError.type) ошибок и предупреждений, определённые в этой спецификации:

"check-character-normalization-failure" [error]

Возникает, если параметр "check-character-normalization" установлен в значение true, и встречается строка, которая не проходит проверку нормализации.

"doctype-not-allowed" [fatal]

Возникает, если конфигурационный параметр "disallow-doctype" установлен в true и встречается объявление типа документа.

"no-input-specified" [fatal]

Возникает при загрузке документа, если в объекте LSInput не указан ввод.

"pi-base-uri-not-preserved" [warning]

Возникает, если встречается инструкция обработки в месте, где базовый URI инструкции обработки не может быть сохранён. Один пример случая, когда будет поднято это предупреждение, — если конфигурационный параметр "entities" установлен в false и анализируется следующий XML-файл:

 <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
 <root> &e; </root>

И subdir/myentity.ent содержит:

<one> <two/> </one> <?pi 3.14159?>
 <more/>

"unbound-prefix-in-entity" [warning]

Зависимое от реализации предупреждение, которое может быть поднято, если конфигурационный параметр "namespaces" установлен в true и встречается не связанный префикс пространства имён в тексте замены сущности. Поднятие этого предупреждения не навязано, так как некоторые существующие анализаторы могут не распознавать не связанные префиксы пространства имён в тексте замены сущностей.

"unknown-character-denormalization" [fatal]

Возникает, если конфигурационный параметр "ignore-unknown-character-denormalizations" установлен в false и встречается символ, для которого процессор не может определить свойства нормализации.

"unsupported-encoding" [fatal]

Возникает, если встречается недопустимое кодирование.

"unsupported-media-type" [fatal]

Возникает, если конфигурационный параметр "supported-media-types-only" установлен в true и встречается недопустимый тип медиа.

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

См. также Спецификацию DOM Level 3 Load and Save.

С момента:: 1.5

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final short`	`ACTION_APPEND_AS_CHILDREN`	Добавить результат операции разбора в качестве дочерних узлов узла контекста.
`static final short`	`ACTION_INSERT_AFTER`	Вставить результат операции разбора как непосредственного следующего сиблинга узла контекста.
`static final short`	`ACTION_INSERT_BEFORE`	Вставить результат операции разбора как непосредственного предыдущего сиблинга узла контекста.
`static final short`	`ACTION_REPLACE`	Заменить узел контекста результатом операции разбора.
`static final short`	`ACTION_REPLACE_CHILDREN`	Заменить все дочерние узлы узла контекста результатом операции разбора.

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`abort()`	Прервать загрузку документа, который в настоящее время загружается `LSParser`.
`boolean`	`getAsync()`	`true` если `LSParser` асинхронный, `false` если синхронный.
`boolean`	`getBusy()`	`true` если `LSParser` в настоящее время загружает документ, в противном случае `false`.
`DOMConfiguration`	`getDomConfig()`	Объект `DOMConfiguration`, используемый при разборе источника ввода.
`LSParserFilter`	`getFilter()`	Если предоставлен фильтр, реализация вызовет фильтр при построении структуры дерева DOM.
`Document`	`parse(LSInput input)`	Разбор XML-документа из ресурса, идентифицируемого `LSInput`.
`Document`	`parseURI(String uri)`	Разбор XML-документа из местоположения, идентифицированного URI-ссылкой [IETF RFC 2396].
`Node`	`parseWithContext(LSInput input, Node contextArg, short action)`	Разбор XML-фрагмента из ресурса, идентифицируемого `LSInput`, и вставка содержимого в существующий документ в позиции, указанной аргументами `context` и `action`.
`void`	`setFilter(LSParserFilter filter)`	Если предоставлен фильтр, реализация вызовет фильтр при построении структуры дерева DOM.

Подробное описание полей

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN

Добавить результат операции парсинга в качестве дочерних узлов узла контекста. Для работы этой операции узел контекста должен быть Element или DocumentFragment.

См. также:

Значения константных полей

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN

Заменить всех дочерних узлов узла контекста результатом операции парсинга. Для работы этой операции узел контекста должен быть Element, Document, или DocumentFragment.

См. также:

Значения константных полей

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE

Вставить результат операции парсинга как непосредственно предшествующего узла-потомка узла контекста. Для работы этой операции родительский узел контекста должен быть Element или DocumentFragment.

См. также:

Значения константных полей

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER

Вставить результат операции парсинга как непосредственно последующего узла-потомка узла контекста. Для работы этой операции родительский узел контекста должен быть Element или DocumentFragment.

См. также:

Значения константных полей

ACTION_REPLACE

static final short ACTION_REPLACE

Заменить узел контекста результатом операции парсинга. Для работы этой операции узел контекста должен иметь родителя, а родитель должен быть Element или DocumentFragment.

См. также:

Значения константных полей

Подробное описание методов

getDomConfig

DOMConfiguration getDomConfig()

Объект DOMConfiguration , используемый при парсинге входного источника. Этот DOMConfiguration специфичен для операции парсинга. Значения параметров из этого DOMConfiguration объекта не передаются автоматически объекту DOMConfiguration в Document , созданном или используемом операцией парсинга. Приложение DOM отвечает за передачу необходимых значений параметров из этого объекта DOMConfiguration объекту DOMConfiguration , на который ссылается объект Document.
Кроме параметров, распознаваемых в интерфейсе DOMConfiguration, определенном в [DOM Level 3 Core], объекты DOMConfiguration для LSParser добавляют или изменяют следующие параметры:

"charset-overrides-xml-encoding"

true: [необязательно] (по умолчанию) Если протокол более высокого уровня, такой как HTTP [IETF RFC 2616], предоставляет указание кодировки символов входного потока, обрабатываемого, это переопределит любую кодировку, указанную в объявлении XML или в объявлении текста (см. также раздел 4.3.3, "Кодировка символов в сущностях", в [XML 1.0]). Явное указание кодировки в LSInput переопределяет любую кодировку из протокола.
false: [обязательно] Парсер игнорирует любые данные кодировки набора символов из протоколов более высокого уровня.

"disallow-doctype"

true: [необязательно] Вызвать ошибку "doctype-not-allowed", если при парсинге документа найден узел doctype. Это полезно при работе с такими вещами, как конверты SOAP, где узлы doctype не допускаются.
false: [обязательно] (по умолчанию) Разрешить узлы doctype в документе.

"ignore-unknown-character-denormalizations"

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

"infoset"

См. определение DOMConfiguration для описания этого параметра. В отличие от [DOM Level 3 Core], этот параметр по умолчанию будет true для LSParser.

"namespaces"

true: [обязательно] (по умолчанию) Выполнить обработку пространства имен, как определено в [XML Namespaces] и [XML Namespaces 1.1].
false: [необязательно] Не выполнять обработку пространства имен.

"resource-resolver"

[обязательно] Ссылка на объект LSResourceResolver или null. Если значение этого параметра не null, когда встречается внешний ресурс (например, внешняя XML-сущность или расположение XML-схемы), реализация запросит, чтобы LSResourceResolver , на который ссылается этот параметр, разрешил ресурс.

"supported-media-types-only"

true: [необязательно] Проверить, является ли тип носителя проанализированного ресурса поддерживаемым типом носителя. Если встречается неподдерживаемый тип носителя, будет вызвана фатальная ошибка типа "unsupported-media-type". Типы носителей, определенные в [IETF RFC 3023], всегда должны приниматься.
false: [обязательно] (по умолчанию) Принимать любой тип носителя.

"validate"

См. определение DOMConfiguration для описания этого параметра. В отличие от [DOM Level 3 Core], обработка внутреннего подмножества всегда выполняется, даже если этот параметр установлен в false.

"validate-if-schema"

"well-formed"

См. определение DOMConfiguration для описания этого параметра. В отличие от [DOM Level 3 Core], этот параметр не может быть установлен в false.

getFilter

LSParserFilter getFilter()

При предоставлении фильтра, реализация обращается к фильтру при построении структуры дерева DOM. Фильтр может выбрать удаление элементов из создаваемого документа или преждевременное завершение парсинга.
Фильтр вызывается после применения операций, запрошенных параметрами DOMConfiguration. Например, если "validate" установлен в true, валидация выполняется до вызова фильтра.

setFilter

void setFilter(LSParserFilter filter)

getAsync

boolean getAsync()

true если LSParser асинхронный, false если синхронный.

getBusy

boolean getBusy()

true если LSParser в настоящее время загружает документ, в противном случае false.

Разбор

Document parse(LSInput input) throws DOMException, LSException

Разбор XML-документа из ресурса, идентифицированного LSInput.

Параметры:: input - LSInput для чтения источника документа.
Возвращает:: Если LSParser является синхронным LSParser, возвращается новый созданный и заполненный Document. Если LSParser является асинхронным, возвращается null, так как объект документа может ещё не быть сформирован на момент возвращения метода.
Выбрасывает:: DOMException - INVALID_STATE_ERR: Выбрасывается, если атрибут LSParser LSParser.busy имеет значение true.; LSException - PARSE_ERR: Выбрасывается, если LSParser не смог загрузить XML-документ. Приложения DOM должны прикрепить DOMErrorHandler с помощью параметра "обработчик ошибок», если они хотят получить подробную информацию об ошибке.

parseURI

Document parseURI(String uri) throws DOMException, LSException

Разбор XML-документа из местоположения, указанного URI-ссылкой [IETF RFC 2396]. Если URI содержит идентификатор фрагмента (см. раздел 4.1 в [IETF RFC 2396]), поведение не определено этой спецификацией; будущие версии этой спецификации могут определить поведение.

Параметры:: uri - Местоположение XML-документа для чтения.
Возвращает:: Если LSParser является синхронным LSParser, возвращается новый созданный и заполненный Document, или null при возникновении ошибки. Если LSParser является асинхронным, возвращается null, так как объект документа может ещё не быть сформирован на момент возвращения метода.
Выбрасывает:: DOMException - INVALID_STATE_ERR: Выбрасывается, если атрибут LSParser.busy имеет значение true.; LSException - PARSE_ERR: Выбрасывается, если LSParser не смог загрузить XML-документ. Приложения DOM должны прикрепить DOMErrorHandler с помощью параметра "обработчик ошибок», если они хотят получить подробную информацию об ошибке.

parseWithContext

Node parseWithContext(LSInput input, Node contextArg, short action) throws DOMException, LSException

Разбор XML-фрагмента из ресурса, идентифицированного LSInput, и вставка содержимого в существующий документ в позиции, заданной аргументами context и action. При разборе входного потока узле контекста (или его родительском узле, в зависимости от места вставки результата) используется для разрешения не связанных префиксов пространств имён. Узел контекста ownerDocument (или сам узел, если узел типа DOCUMENT_NODE) используется для разрешения атрибутов по умолчанию и ссылок на сущности.
При вставке новых данных в документ, по крайней мере, одно событие изменения генерируется для каждого нового непосредственного дочернего или соседнего узла узла контекста.
Если узел контекста является узлом Document и действие равно ACTION_REPLACE_CHILDREN, тогда документ, переданный в качестве узла контекста, будет изменён таким образом, что его атрибуты xmlEncoding, documentURI, xmlVersion, inputEncoding, xmlStandalone и все остальные подобные атрибуты будут установлены так, как они были бы установлены, если бы исходный источник был проанализирован с помощью LSParser.parse().
Этот метод всегда синхронный, даже если LSParser является асинхронным (LSParser.async является true).
Если при разборе возникла ошибка, вызывающий метод уведомляется через экземпляр ErrorHandler связанный с параметром "обработчика ошибок" в DOMConfiguration.
При вызове parseWithContext, значения следующих параметров конфигурации будут игнорироваться и будут использоваться их значения по умолчанию: "validate", "validate-if-schema" и "element-content-whitespace". Другие параметры будут обработаны обычно, и ожидается, что анализатор вызовет LSParserFilter так, как если бы был проанализирован весь документ.

Параметры:: input - LSInput для чтения источника документа. Источник документа должен быть XML-фрагментом, т.е. чем-либо, кроме полного XML-документа (за исключением случаев, когда узел контекста типа DOCUMENT_NODE, а действие равно ACTION_REPLACE_CHILDREN) - DOCTYPE (внутреннее подмножество), объявление(я) сущности, объявление(я) обозначения или XML- или текстовое объявление(я).; contextArg - Узел, используемый в качестве контекста для данных, которые анализируются. Этот узел должен быть узлом Document, узлом DocumentFragment или узлом типа, разрешенного как дочерний узел узла Element, например, это не может быть узел Attribute.; action - Этот параметр описывает действие, которое должно быть выполнено между новым набором узлов, которые вставляются, и существующими дочерними узлами узла контекста. Набор возможных действий определён в ACTION_TYPES выше.
Возвращает:: Возвращает узел, являющийся результатом операции разбора. Если результат включает более одного узла верхнего уровня, возвращается первый.
Выбрасывает:: DOMException - HIERARCHY_REQUEST_ERR: Выбрасывается, если содержимое не может заменить, быть вставлено до, после или как дочерний узел узла контекста (см. также Node.insertBefore или Node.replaceChild в [DOM Level 3 Core] ).
NOT_SUPPORTED_ERR: Выбрасывается, если LSParser не поддерживает этот метод, или если узел контекста имеет тип Document и реализация DOM не поддерживает замену DocumentType или Element дочернего узла.
NO_MODIFICATION_ALLOWED_ERR: Выбрасывается, если узел контекста является узлом только для чтения, и содержимое добавляется к его списку дочерних узлов, или если родительский узел узла контекста является узлом только для чтения, и содержимое вставляется в его список дочерних узлов.
INVALID_STATE_ERR: Выбрасывается, если атрибут LSParser.busy имеет значение true.; LSException - PARSE_ERR: Выбрасывается, если LSParser не смог загрузить XML-фрагмент. Приложения DOM должны прикрепить DOMErrorHandler с помощью параметра "обработчик ошибок», если они хотят получить подробную информацию об ошибке.

Прервать

void abort()

Прервать загрузку документа, который в данный момент загружается LSParser. Если LSParser в данный момент не занят, вызов этого метода ничего не делает.

© 1993, 2021, 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/17/docs/api/java.xml/org/w3c/dom/ls/LSParser.html