org.w3c.dom.ls

Интерфейсный LSParser

public interface LSParser

Интерфейс к объекту, который в состоянии создать, или увеличиться, дерево ДОМА из различных входных источников.

LSParser обеспечивает API для того, чтобы он проанализировал XML и создал соответствующую структуру документа ДОМА. A LSParser экземпляр может быть получен, вызывая DOMImplementationLS.createLSParser() метод.

Как определено в [ДОМ Левель 3 Ядра], когда документ сначала делается доступным через LSParser:

• никогда не будет двух смежных узлов типа NODE_TEXT, и никогда не будет пустых текстовых узлов.
• ожидается что value и nodeValue атрибуты Attr узел первоначально возвращает XML 1.0 нормализованное значение. Однако, если параметры "проверяют, если схема" и "нормализация типа данных" устанавливаются в true, В зависимости от используемой нормализации атрибута значения атрибута могут отличаться от тех полученных нормализацией атрибута XML 1.0. Если параметры "нормализация типа данных" устанавливаются к false, нормализация атрибута XML 1.0, как гарантируют, произойдет, и если список атрибутов не содержит объявления пространства имен, attributes атрибут на Element узел представляет свойство [атрибуты], определенные в [Набор Информации XML].

Асинхронный LSParser объекты, как ожидают, также реализуют events::EventTarget взаимодействуйте через интерфейс так, чтобы слушатели события могли быть зарегистрированы на асинхронном LSParser объекты.

События, поддерживаемые асинхронным LSParser объекты:

загрузка

LSParser концы, чтобы загрузить документ. См. также определение LSLoadEvent интерфейс.

продвижение

LSParser продвижение сигналов как данные анализируется. Эта спецификация не пытается определить точно, когда события продвижения должны быть диспетчеризированы. Это преднамеренно оставляют как зависящее от реализации. Вот один пример того, как приложение могло бы диспетчеризировать события продвижения: Как только синтаксический анализатор начинает получать данные, событие продвижения диспетчеризируется, чтобы указать, что парсинг запускается. Оттуда на, событие продвижения диспетчеризируется для каждых 4096 байтов данных, которые получаются и обрабатываются. Это - только один пример, тем не менее, и реализации могут хотеть диспетчеризировать события продвижения в любое время, анализируя, или не диспетчеризировать их вообще. См. также определение LSProgressEvent интерфейс.

Отметьте: Все события, определенные в этой спецификации, используют URI пространства имен "http://www.w3.org/2002/DOMLS".

Анализируя входной источник, об ошибках сообщают приложению через обработчик ошибок (LSParser.domConfig's параметр "обработчика ошибок"). Эта спецификация никоим образом не пытается определить все возможные ошибки, которые могут произойти, анализируя XML, или любая другая разметка, но некоторые случаи распространенной ошибки определяется. Типы (DOMError.type) из ошибок и предупреждений, определенных этой спецификацией:

"check-character-normalization-failure" [error]

Повышенный, если параметры "нормализация контрольного символа" устанавливаются к истине и строке, встречается что проверка нормализации сбоев.

"doctype-not-allowed" [fatal]

Повышенный, если параметр конфигурации "отвергает-doctype", устанавливается в true и с doctype встречаются.

"no-input-specified" [fatal]

Повышенный, загружая документ и никакой ввод определяется в LSInput объект.

"pi-base-uri-not-preserved" [warning]

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

Зависящее от реализации предупреждение, которое может быть повышено, если параметр конфигурации "пространства имен" устанавливается в true и с несвязанным префиксом пространства имен встречаются в заменяющем тексте объекта. Повышение этого предупреждения не осуществляется, так как некоторые существующие синтаксические анализаторы, возможно, не распознают несвязанные префиксы пространства имен в заменяющем тексте объектов.

"unknown-character-denormalization" [fatal]

Повышенный, если параметр конфигурации "ignore-unknown-character-denormalizations" устанавливается в false и с символом встречаются, для которого процессор не может определить свойства нормализации.

"unsupported-encoding" [fatal]

Повышенный, если с неподдерживаемым кодированием встречаются.

"unsupported-media-type" [fatal]

Повышенный, если параметр конфигурации "поддерживаемые типы носителя только" устанавливается в true и с неподдерживаемым типом носителя встречаются.

В дополнение к повышению определенных ошибок и предупреждений, реализации, как ожидают, повысят реализацию определенные ошибки и предупреждения для любой другой ошибки и предупреждение случаев, таких как ошибки IO (файл, не найденный, отрицаемое разрешение...), ошибки отмеченности XML, и так далее.

См. также Объектную модель документа (ДОМ) Загрузка Уровня 3 и Сохраните Спецификацию.

Полевая Сводка

Поля

Модификатор и Тип	Поле и Описание
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() Когда фильтр будет обеспечен, реализация обратится к фильтру, поскольку это создает древовидную структуру ДОМА.
Документ	parse(LSInput input) Проанализируйте XML-документ от ресурса, идентифицированного a LSInput.
Документ	parseURI(String uri) Проанализируйте XML-документ от расположения, идентифицированного ссылкой URI [IETF RFC 2396].
Узел	parseWithContext(LSInput input, Node contextArg, short action) Проанализируйте фрагмент XML от ресурса, идентифицированного a LSInput и вставьте контент в существующий документ в позиции, определенной с context и action параметры.
void	setFilter(LSParserFilter filter) Когда фильтр будет обеспечен, реализация обратится к фильтру, поскольку это создает древовидную структуру ДОМА.

Полевая Деталь

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN

Добавьте результат работы синтаксического анализа как дочерние элементы узла контекста. Для этого действия, чтобы работать, узел контекста должен быть Element или a DocumentFragment.

См. Также:

Постоянные Значения полей

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN

Замените все дочерние элементы узла контекста с результатом работы синтаксического анализа. Для этого действия, чтобы работать, узел контекста должен быть Element, a Document, или a DocumentFragment.

См. Также:

Постоянные Значения полей

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE

Вставьте результат работы синтаксического анализа как сразу предыдущий одноуровневый элемент узла контекста. Для этого действия, чтобы работать родитель узла контекста должен быть Element или a DocumentFragment.

См. Также:

Постоянные Значения полей

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER

Вставьте результат работы синтаксического анализа как сразу после одноуровневого элемента узла контекста. Для этого действия, чтобы работать родитель узла контекста должен быть Element или a DocumentFragment.

См. Также:

Постоянные Значения полей

ACTION_REPLACE

static final short ACTION_REPLACE

Замените узел контекста результатом работы синтаксического анализа. Для этого действия, чтобы работать, у узла контекста должен быть родитель, и родитель должен быть Element или a DocumentFragment.

См. Также:

Постоянные Значения полей

Деталь метода

getDomConfig

DOMConfiguration getDomConfig()

DOMConfiguration объект, используемый, анализируя входной источник. Это DOMConfiguration является определенным для работы синтаксического анализа. Никакой параметр не оценивает от этого DOMConfiguration объект передают автоматически к DOMConfiguration объект на Document это создается, или используется работой синтаксического анализа. Приложение ДОМА ответственно за передачу любых необходимых значений параметра от этого DOMConfiguration возразите против DOMConfiguration объект, на который ссылаются Document объект.
В дополнение к параметрам, распознанным в в интерфейсе DOMConfiguration, определенном в [ДОМ Левель 3 Ядра], 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

[дополнительный] Отчет фатальная ошибка "неизвестной символьной денормализации", если с символом встречаются, для которого процессор не может определить свойства нормализации.

"infoset"

См. определение DOMConfiguration для описания этого параметра. В отличие от этого в [ДОМ Левель 3 Ядра], этот параметр примет значение по умолчанию к true для LSParser.

"namespaces"

true

[необходимый] (значение по умолчанию) Выполняют пространство имен, обрабатывающее как определено в [XML Пространства имен] и [XML Пространства имен 1.1].

false

[дополнительный] не выполняют обработку пространства имен.

"resource-resolver"

[требуемый] ссылка на a LSResourceResolver объект, или нуль. Если значение этого параметра не будет нулем, когда с внешним ресурсом (таким как внешний объект XML или расположение XML-схемы) встретятся, то реализация запросит что LSResourceResolver ссылаемый в этом параметре разрешает ресурс.

"supported-media-types-only"

true

[дополнительная] Проверка, что тип носителя проанализированного ресурса является поддерживаемым типом носителя. Если с неподдерживаемым типом носителя встретятся, то фатальная ошибка типа "неподдерживаемый тип носителя" будет повышена. Типы носителя, определенные в [IETF RFC 3023], должны всегда приниматься.

false

[необходимый] (значение по умолчанию) Принимают любой тип носителя.

"validate"

См. определение DOMConfiguration для описания этого параметра. В отличие от этого в [ДОМ Левель 3 Ядра], обработка внутреннего подмножества всегда выполняется, даже если эти параметры устанавливаются к false.

"validate-if-schema"

См. определение DOMConfiguration для описания этого параметра. В отличие от этого в [ДОМ Левель 3 Ядра], обработка внутреннего подмножества всегда выполняется, даже если эти параметры устанавливаются к false.

"well-formed"

См. определение DOMConfiguration для описания этого параметра. В отличие от этого в [ДОМ Левель 3 Ядра], эти параметры не могут быть установлены к false.

getFilter

LSParserFilter getFilter()

Когда фильтр будет обеспечен, реализация обратится к фильтру, поскольку это создает древовидную структуру ДОМА. Фильтр может хотеть удалять элементы из документа, создаваемого, или завершать парсинг рано.
Фильтр вызывается после операций, которые требуют DOMConfiguration параметры были применены. Например, если "проверяют", устанавливается в true, проверка допустимости делается прежде, чем вызвать фильтр.

setFilter

void setFilter(LSParserFilter filter)

Когда фильтр будет обеспечен, реализация обратится к фильтру, поскольку это создает древовидную структуру ДОМА. Фильтр может хотеть удалять элементы из документа, создаваемого, или завершать парсинг рано.
Фильтр вызывается после операций, которые требуют DOMConfiguration параметры были применены. Например, если "проверяют", устанавливается в true, проверка допустимости делается прежде, чем вызвать фильтр.

getAsync

boolean getAsync()

true если LSParser является асинхронным, false если это синхронно.

getBusy

boolean getBusy()

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

синтаксический анализ

Document parse(LSInput input)
               throws DOMException,
                      LSException

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

Параметры:

input - LSInput из которого должен быть считан источник документа.

Возвраты:

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

Броски:

DOMException - INVALID_STATE_ERR: Повышенный, если LSParser's LSParser.busy атрибут true.

LSException - PARSE_ERR: Повышенный, если LSParser было неспособно загрузить XML-документ. Приложения ДОМА должны присоединить a 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-документ. Приложения ДОМА должны присоединить a DOMErrorHandler использование параметра "обработчик ошибок", если они хотят получить детали об ошибке.

parseWithContext

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

Проанализируйте фрагмент XML от ресурса, идентифицированного a LSInput и вставьте контент в существующий документ в позиции, определенной с context и action параметры. Анализируя входной поток, узел контекста (или его родитель, в зависимости от того, где результат будет вставлен) используется для того, чтобы разрешить несвязанные префиксы пространства имен. Узел контекста ownerDocument узел (или узел непосредственно, если узел типа DOCUMENT_NODE) используется, чтобы разрешить атрибуты по умолчанию и ссылки на сущность.
Поскольку новые данные вставляются в документ, по крайней мере одно событие мутации запускается на новый непосредственный дочерний элемент или одноуровневый элемент узла контекста.
Если узел контекста является a Document узел и действие ACTION_REPLACE_CHILDREN, тогда документ, который передают как узел контекста, будет изменен так, что xmlEncoding, documentURI, xmlVersion, inputEncoding, xmlStandalone, и все другие такие атрибуты устанавливаются в то, что они были бы установлены в то, если бы входной источник был проанализирован, используя LSParser.parse().
Этот метод всегда синхронен, даже если LSParser является асинхронным (LSParser.async true).
Если ошибка происходит, анализируя, вызывающая сторона уведомляется через ErrorHandler экземпляр, связанный с параметром "обработчика ошибок" DOMConfiguration.
Вызывая parseWithContext, значения следующих параметров конфигурации будут проигнорированы, и их значения по умолчанию будут всегда использоваться вместо этого: "проверьте", "проверьте если схема", и "пробел контента элемента". Другие параметры будут обычно обрабатываться, и синтаксический анализатор, как ожидают, вызовет LSParserFilter так же, как если бы был проанализирован целый документ.

Параметры:

input - LSInput из которого должен быть считан исходный документ. Исходный документ должен быть фрагментом XML, то есть чем-либо кроме полного XML-документа (кроме в случае, где узел контекста типа DOCUMENT_NODE, и действие ACTION_REPLACE_CHILDREN), DOCTYPE (внутреннее подмножество), объявление (я) объекта, объявление (я) нотации, или объявление (я) XML или текста.

contextArg - Узел, который используется в качестве контекста для данных, которые анализируются. Этот узел должен быть a Document узел, a DocumentFragment узел, или узел типа, который позволяется как дочерний элемент Element узел, например, это не может быть Attribute узел.

action - Этот параметр описывает, какие меры должны быть предприняты между новым набором вставляемых узлов и существующими дочерними элементами узла контекста. Набор возможных действий определяется в ACTION_TYPES выше.

Возвраты:

Возвратите узел, который является результатом работы синтаксического анализа. Если результатом является больше чем один высокоуровневый узел, первый возвращается.

Броски:

DOMException - HIERARCHY_REQUEST_ERR: Повышенный, если контент не может заменить, быть вставленным прежде, после, или как дочерний элемент узла контекста (см. также Node.insertBefore или Node.replaceChild в [ДОМ Левель 3 Ядра]).
NOT_SUPPORTED_ERR: Повышенный, если LSParser не поддерживает этот метод, или если узел контекста имеет тип Document и реализация ДОМА не поддерживает замену DocumentType дочерний элемент или Element дочерний элемент.
NO_MODIFICATION_ALLOWED_ERR: Повышенный, если узел контекста является узлом только для чтения и контентом, добавляется к его дочернему списку, или если родительский узел узла контекста является узлом только для чтения, и контент вставляется в его дочерний список.
INVALID_STATE_ERR: Повышенный, если LSParser.busy атрибут true.

LSException - PARSE_ERR: Повышенный, если LSParser было неспособно загрузить фрагмент XML. Приложения ДОМА должны присоединить a DOMErrorHandler использование параметра "обработчик ошибок", если они хотят получить детали об ошибке.

аварийное прекращение работы

void abort()

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