Интерфейс 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 сигнализирует о прогрессе по мере разбора данных. Данная спецификация не пытается определить точное время отправки событий progress. Это намеренно оставлено зависящим от реализации. Вот один пример того, как приложение может отправлять события progress: После того, как анализатор начнёт получать данные, отправляется событие progress, чтобы указать на начало анализа. Далее, событие progress отправляется после обработки каждого 4096 байт данных. Это лишь один пример, и реализации могут выбирать отправлять события progress в любое время во время разбора или не отправлять их вообще. См. также определение интерфейса 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 и встречен тег doctype.

"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.

Since:: 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.

parse

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).
При вызове 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 используя параметр "обработчик ошибок", если необходимо получить подробную информацию об ошибке.

abort

void abort()

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

© 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/LSParser.html