Интерфейс 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, чтобы указать начало анализа. После этого для каждых 4096 байт полученных и обработанных данных отправляется событие progress. Однако это только один пример, и реализации могут выбрать отправку событий 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]

Возникает, если встречено указание обработки (processing instruction) в месте, где базовый 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 short`	`ACTION_APPEND_AS_CHILDREN`	Добавить результат операции разбора как дочерние узлы контекстного узла.
`static short`	`ACTION_INSERT_AFTER`	Вставить результат операции разбора как непосредственный следующий сосед контекстного узла.
`static short`	`ACTION_INSERT_BEFORE`	Вставить результат операции разбора как непосредственный предыдущий сосед контекстного узла.
`static short`	`ACTION_REPLACE`	Заменить контекстный узел результатом операции разбора.
`static 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.

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

abort

void abort()

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

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