Интерфейс ContentHandler

void setDocumentLocator(Locator locator)

Получение объекта для определения источника событий SAX документа.

SAX парсеры настоятельно рекомендуют (хотя и не требуют обязательно) предоставлять локатор: если он это делает, он должен предоставить локатор приложению, вызвав этот метод до вызова других методов интерфейса ContentHandler.

Локатор позволяет приложению определить конечную позицию любого события, связанного с документом, даже если парсер не сообщает об ошибке. Как правило, приложение будет использовать эту информацию для сообщения об собственных ошибках (например, содержимое символов, которое не соответствует бизнес-правилам приложения). Информация, возвращаемая локатором, вероятно, не будет достаточной для использования с поисковой системой.

Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова обратных вызовов SAX событий после startDocument и до endDocument. Приложение не должно пытаться использовать его в любое другое время.

void startDocument() throws SAXException

Получение уведомления о начале документа.

SAX парсер вызовет этот метод только один раз, перед любыми другими обратными вызовами событий (кроме setDocumentLocator).

default void declaration(String version, String encoding, String standalone) throws SAXException

Получение уведомления об XML декларации.

void endDocument() throws SAXException

Получение уведомления о конце документа.

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

void startPrefixMapping(String prefix, String uri) throws SAXException

Начало области сопоставления префикс-URI пространства имен.

Информация из этого события не нужна для обычной обработки пространства имен: SAX XML-читатель автоматически заменит префиксы для имен элементов и атрибутов, когда свойство http://xml.org/sax/features/namespaces имеет значение true (значение по умолчанию).

Однако существуют случаи, когда приложениям нужно использовать префиксы в данных символов или значениях атрибутов, где их нельзя безопасно автоматически расширить; событие start/endPrefixMapping предоставляет приложению информацию для расширения префиксов в этих контекстах самостоятельно, если это необходимо.

Обратите внимание, что события start/endPrefixMapping не гарантируются как правильно вложенные друг относительно друга: все события startPrefixMapping будут происходить непосредственно перед соответствующим startElement событием, а все события endPrefixMapping будут происходить непосредственно после соответствующего endElement события, но их порядок не гарантируется.

Для префикса "xml" никогда не должно быть событий start/endPrefixMapping, так как он предопределён и неизменяем.

void endPrefixMapping(String prefix) throws SAXException

Окончание области сопоставления префикс-URI.

См. startPrefixMapping для подробностей. Эти события всегда будут происходить непосредственно после соответствующего endElement события, но порядок событий endPrefixMapping не гарантируется.

void startElement(String uri, String localName, String qName, Attributes atts) throws SAXException

Получение уведомления о начале элемента.

Парсер вызовет этот метод в начале каждого элемента в XML-документе; для каждого события startElement будет соответствующее endElement событие (даже когда элемент пустой). Всё содержимое элемента будет сообщено в порядке, перед соответствующим событием endElement.

Это событие позволяет до трёх компонентов имени для каждого элемента:

1. URI пространства имен;
2. локальное имя; и
3. полное (префиксное) имя.

Любые или все из них могут быть предоставлены, в зависимости от значений свойств http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes:

• URI пространства имен и локальное имя обязательны, когда свойство namespaces равно true (значение по умолчанию), и необязательны, когда свойство namespaces равно false (если одно указано, оба должны быть указаны);
• полное имя обязательно, когда свойство namespace-prefixes равно true, и необязательно, когда свойство namespace-prefixes равно false (значение по умолчанию).

Обратите внимание, что список атрибутов будет содержать только атрибуты с явными значениями (указанными или заданными по умолчанию): атрибуты #IMPLIED будут опущены. Список атрибутов будет содержать атрибуты, используемые для деклараций пространства имен (атрибуты xmlns*), только если свойство http://xml.org/sax/features/namespace-prefixes равно true (по умолчанию оно равно false, и поддержка значения true является необязательной).

Как и в characters(), значения атрибутов могут содержать символы, которым требуется более одного значения char.

void endElement(String uri, String localName, String qName) throws SAXException

Получение уведомления о конце элемента.

SAX парсер вызовет этот метод в конце каждого элемента в XML-документе; для каждого события endElement будет соответствующее startElement событие (даже когда элемент пустой).

Для информации об именах см. startElement.

void characters(char[] ch, int start, int length) throws SAXException

Получение уведомления о данных символов.

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

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

Отдельные символы могут состоять из более чем одного значения Java char . Существует два важных случая, когда это происходит, потому что символы не могут быть представлены всего лишь шестнадцатью битами. В одном случае символы представлены в паре суррогатов, используя две специальные значения Unicode. Такие символы находятся в так называемых «астрольных плоскостях», с кодовым значением выше U+FFFF. Второй случай связан с составными символами, такими как основной символ, сочетающийся с одним или несколькими символами акцента.

Ваш код не должен предполагать, что алгоритмы, использующие char-посимвольные идиомы, будут работать с единицами символов; в некоторых случаях они будут разделять символы. Это актуально везде, где XML допускает произвольные символы, такие как значения атрибутов, данные инструкций обработки и комментарии, а также данные, полученные из этого метода. Это также, как правило, актуально всякий раз, когда код Java обрабатывает интернационализированный текст; эта проблема не уникальна для XML.

Обратите внимание, что некоторые парсеры будут сообщать о пробелах в содержании элемента с помощью метода ignorableWhitespace, а не этого (валидирующие парсеры обязаны это делать).

void ignorableWhitespace(char[] ch, int start, int length) throws SAXException

Получение уведомления о пропускаемых пробелах в содержимом элемента.

Валидирующие парсеры должны использовать этот метод для сообщения о каждом блоке пробелов в содержимом элемента (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие парсеры также могут использовать этот метод, если они способны анализировать и использовать модели содержимого.

Парсеры SAX могут возвращать все непрерывные пробелы в одном блоке или разбить их на несколько блоков; однако все символы в любом отдельном событии должны быть взяты из одной и той же внешней сущности, чтобы локализатор предоставлял полезную информацию.

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

void processingInstruction(String target, String data) throws SAXException

Получение уведомления об инструкции обработки.

Парсер вызовет этот метод один раз для каждой инструкции обработки, найденной: обратите внимание, что инструкции обработки могут появляться до или после основного элемента документа.

Парсер SAX никогда не должен сообщать об XML-декларации (XML 1.0, раздел 2.8) или декларации текста (XML 1.0, раздел 4.3.1) с помощью этого метода.

Как и characters(), данные инструкции обработки могут содержать символы, требующие более одного char значения.

void skippedEntity(String name) throws SAXException

Получение уведомления о пропущенной сущности. Это не вызывается для ссылок на сущности внутри конструкций разметки, таких как открывающие теги элементов или объявления разметки. (XML-рекомендация требует сообщения о пропущенных внешних сущностях. SAX также сообщает о расширении/не-расширении внутренних сущностей, за исключением конструкций разметки.)

Парсер вызовет этот метод каждый раз, когда сущность пропускается. Невалидирующие процессоры могут пропускать сущности, если они не видели объявления (например, потому что сущность была объявлена во внешнем подмножестве DTD). Все процессоры могут пропускать внешние сущности, в зависимости от значений свойств http://xml.org/sax/features/external-general-entities и http://xml.org/sax/features/external-parameter-entities.