Интерфейс 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 или текстовом объявлении (см. также раздел 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], для LSParser значение этого параметра по умолчанию — true.

"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.busy объекта LSParser имеет значение 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]), поведение не определено этой спецификацией; в будущих версиях спецификации оно может быть определено.

Параметры:: uri — расположение XML-документа, который требуется прочитать.
Возвращает:: Если LSParser является синхронным LSParser, возвращается вновь созданный и заполненный Document или null, если произошла ошибка. Если LSParser является асинхронным, возвращается null, поскольку объект документа может быть ещё не создан к моменту возврата этого метода.
Выбрасывает:: 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. При разборе входного потока контекстный узел (или его родительский узел — в зависимости от места вставки результата) используется для разрешения несвязанных префиксов пространств имён. Узел ownerDocument контекстного узла (или сам узел, если он имеет тип DOCUMENT_NODE) используется для разрешения атрибутов по умолчанию и ссылок на сущности.
При вставке новых данных в документ для каждого нового непосредственного дочернего или соседнего узла контекстного узла генерируется как минимум одно событие мутации.
Если контекстный узел является узлом 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 так же, как при разборе целого документа.

Параметры:: input — LSInput, из которого следует прочитать исходный документ. Исходный документ должен быть фрагментом XML, то есть чем угодно, кроме целого XML-документа (за исключением случая, когда контекстный узел имеет тип DOCUMENT_NODE, а действие — ACTION_REPLACE_CHILDREN), DOCTYPE (внутреннего подмножества), объявления сущности (объявлений сущностей), объявления нотации (объявлений нотаций) или объявления XML либо текста (объявлений 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 с помощью параметра "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://docs.oracle.com/en/java/javase/25/docs/api/java.xml/org/w3c/dom/ls/LSParser.html