Интерфейс 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 и встречен доктайп.

"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 и т. д.

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

Поля

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"

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

"well-formed"

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

getFilter

LSParserFilter getFilter()

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

setFilter

void setFilter(LSParserFilter filter)

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

getAsync

boolean getAsync()

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

getBusy

boolean getBusy()

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

parse

Document parse(LSInput input)
        throws DOMException,
               LSException

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

Параметры:

input - LSInput для чтения источника документа.

Возвращает:

Если парсер синхронный, возвращается новый созданный и заполненный Document объект. Если парсер асинхронный, возвращается null, так как объект документа может ещё не быть построен на момент возврата этого метода.

Исключения:

DOMException - INVALID_STATE_ERR: Возникает, если атрибут LSParser.busy объекта LSParser равен true.

LSException - PARSE_ERR: Возникает, если парсер не смог загрузить XML-документ. Приложения DOM должны прикрепить обработчик ошибок, используя параметр " 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 используя параметр " обработчик ошибок", если требуется получить подробную информацию об ошибке.

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 в настоящее время не занят, вызов этого метода ничего не делает.