Интерфейс 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) уровня 3.

С:: 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 или декларации Text (см. также раздел 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.

END_OF_DOCUMENT_MARKER

parse

Document parse(LSInput input) throws DOMException, LSException

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

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

parseURI

Document parseURI(String uri) throws DOMException, LSException

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

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

parseWithContext

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

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

Parameters:: input - LSInput, из которого будет считываться исходный документ. Исходный документ должен быть фрагментом XML, то есть всё, кроме полного XML-документа (кроме случаев, когда узел контекста типа DOCUMENT_NODE, и действие равно ACTION_REPLACE_CHILDREN), DOCTYPE (внутренний подмножество), деклараций сущности(ей), деклараций обозначения(ий), или деклараций XML или текста.; contextArg - Узел, используемый в качестве контекста для обрабатываемых данных. Этот узел должен быть узлом Document, узлом DocumentFragment или узлом, который разрешается в качестве дочернего элемента узла Element, например, он не может быть узлом Attribute.; action - Этот параметр описывает действие, которое должно быть выполнено между новым набором узлов, которые будут вставлены, и существующими дочерними элементами узла контекста. Набор возможных действий определён в ACTION_TYPES выше.
Returns:: Возвращает узел, являющийся результатом операции обработки. Если результат содержит более одного узла верхнего уровня, возвращается первый.
Throws:: 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 используя параметр "error-handler", если требуется получить подробности об ошибке.

abort

void abort()

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

© 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://download.java.net/java/early_access/jdk24/docs/api/java.xml/org/w3c/dom/ls/LSParser.html