Интерфейс LSParserFilter

public interface LSParserFilter

LSParserFilter предоставляют приложениям возможность исследовать узлы по мере их построения во время разбора. При исследовании каждого узла он может быть изменён или удалён, или весь разбор может быть прерван досрочно.

В момент вызова любых методов фильтра анализатором, объекты Document и DOMImplementation владельца существуют и доступны. Элемент документа никогда не передаётся в методы LSParserFilter, т.е. отфильтровать элемент документа невозможно. Document, DocumentType, Notation, Entity, и Attr узлы никогда не передаются методу acceptNode фильтра. Дочерние узлы узла EntityReference передаются фильтру, если параметр «сущности» установлен в значение false. Обратите внимание, что, как описано в параметре «сущности», нераспакованные узлы ссылок на сущности никогда не отбрасываются и всегда передаются фильтру.

Вся проверка корректности при разборе документа выполняется на исходном документе, как он появляется в потоке ввода, а не на документе DOM, как он строится в памяти. С фильтрами документ в памяти может быть подмножеством документа в потоке, и его корректность может быть нарушена фильтром.

Все атрибуты по умолчанию должны присутствовать в элементах, когда элементы передаются методам фильтра. Весь остальной контент по умолчанию должен быть передан методам фильтра.

Приложения DOM не должны генерировать исключения в фильтре. Воздействие исключений из фильтра зависит от реализации DOM.

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

С момента:: 1.5

Поля

Модификатор и тип	Поле	Описание
`static short`	`FILTER_ACCEPT`	Принять узел.
`static short`	`FILTER_INTERRUPT`	Прервать нормальную обработку документа.
`static short`	`FILTER_REJECT`	Отклонить узел и его потомков.
`static short`	`FILTER_SKIP`	Пропустить этот единственный узел.

Методы

Модификатор и тип	Метод	Описание
`short`	`acceptNode(Node nodeArg)`	Этот метод будет вызываться анализатором по завершении разбора каждого узла.
`int`	`getWhatToShow()`	Указывает `LSParser` какие типы узлов отображать методу `LSParserFilter.acceptNode`.
`short`	`startElement(Element elementArg)`	Анализатор вызовет этот метод после сканирования каждого начального тега `Element`, но перед обработкой остальной части `Element`.

Поля

FILTER_ACCEPT

static final short FILTER_ACCEPT

Принять узел.

См. также:: Значения константных полей

FILTER_REJECT

static final short FILTER_REJECT

Отклонить узел и его потомков.

См. также:: Значения константных полей

FILTER_SKIP

static final short FILTER_SKIP

Пропустить этот единственный узел. Потомки этого узла всё ещё будут рассмотрены.

См. также:: Значения константных полей

FILTER_INTERRUPT

static final short FILTER_INTERRUPT

Прервать нормальную обработку документа.

См. также:: Значения константных полей

Методы

startElement

short startElement(Element elementArg)

Анализатор вызовет этот метод после сканирования каждого начального тега Element, но перед обработкой остальной части Element. Цель состоит в том, чтобы эффективно пропустить элемент, включая все его дочерние элементы. Обратите внимание, что только узлы элементов передаются функции startElement.
Узел элемента, переданный startElement для фильтрации, будет включать все атрибуты элемента, но ни один из дочерних узлов. Элемент может ещё не находиться в документе (у него может не быть родительского узла).
Функция фильтра startElement может получить доступ к атрибутам элемента или изменить их. Изменение объявлений пространства имён не повлияет на разрешение пространства имён анализатором.
Для эффективности узел элемента, переданный фильтру, может не совпадать с тем, который фактически помещается в дерево, если узел принят. И фактический узел (тождество объекта узла) может быть повторно использован в процессе чтения и фильтрации документа.

Параметры:

elementArg - Новый встреченный элемент. На момент вызова этого метода элемент неполный — у него есть атрибуты, но нет дочерних узлов.

Возвращает:

FILTER_ACCEPT если Element должен быть включён в документ DOM, который строится.
FILTER_REJECT если Element и все его дочерние элементы должны быть отклонены.
FILTER_SKIP если Element должен быть пропущен. Все его дочерние элементы вставляются вместо пропущенного узла Element.
FILTER_INTERRUPT если фильтр хочет остановить обработку документа. Прерывание обработки документа больше не гарантирует, что полученное дерево DOM является хорошо сформированным XML. Element отклоняется.

Возвращение других значений приведёт к неопределённому поведению.

acceptNode

short acceptNode(Node nodeArg)

Этот метод будет вызываться анализатором по завершении разбора каждого узла. Узел и все его потомки будут существовать и будут полными. Родительский узел также будет существовать, хотя он может быть неполным, т.е. у него могут быть дополнительные дочерние узлы, которые ещё не были обработаны. Узлы атрибутов никогда не передаются этой функции.
Изнутри этого метода новый узел может быть свободно изменён — могут быть добавлены или удалены дочерние узлы, изменены текстовые узлы и т.д. Состояние остальной части документа вне этого узла не определено, и влияние любых попыток перейти к нему или изменить любую другую часть документа не определено.
Для проверки анализаторов проверки выполняются на исходном документе, до любых изменений фильтром. Никакие проверки корректности не выполняются на изменениях документа, сделанных фильтром.
Если этот новый узел отклоняется, анализатор может повторно использовать новый узел и любые его потомки.

Параметры:

nodeArg - Новый построенный элемент. На момент вызова этого метода элемент завершён — у него есть все дочерние элементы (и их дочерние элементы рекурсивно) и атрибуты, и он прикреплён как дочерний к своему родителю.

Возвращает:

FILTER_ACCEPT если этот Node должен быть включён в строящийся документ DOM.
FILTER_REJECT если Node и все его дочерние элементы должны быть отклонены.
FILTER_SKIP если Node должен быть пропущен, а Node должен быть заменён всеми дочерними элементами Node.
FILTER_INTERRUPT если фильтр хочет остановить обработку документа. Прерывание обработки документа больше не гарантирует, что результирующее дерево DOM является хорошо сформированным XML. Node принят и будет последним полностью обработанным узлом.

getWhatToShow

int getWhatToShow()

Указывает LSParser какие типы узлов отображать методу LSParserFilter.acceptNode. Если узел не отображается фильтру с помощью этого атрибута, он автоматически включается в строящийся документ DOM. См. NodeFilter для определения констант. Константы SHOW_ATTRIBUTE, SHOW_DOCUMENT, SHOW_DOCUMENT_TYPE, SHOW_NOTATION, SHOW_ENTITY, и SHOW_DOCUMENT_FRAGMENT здесь бессмысленны. Эти узлы никогда не будут передаваться LSParserFilter.acceptNode.
Использованные здесь константы определены в [DOM Level 2 Traversal and Range].