Интерфейс LSParserFilter

public interface LSParserFilter

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

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

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

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

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

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

Подробное описание полей

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 Обход и диапазоны].