Интерфейс 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, но их порядок не гарантируется.

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

void endPrefixMapping(String prefix) throws SAXException

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

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

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

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

Анализатор вызовет этот метод в начале каждого элемента в XML-документе; будет соответствующее событие endElement для каждого события startElement (даже когда элемент пуст). Всё содержимое элемента будет сообщено в порядке, перед соответствующим событием 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-документе; будет соответствующее событие startElement для каждого события endElement (даже когда элемент пуст).

Для информации о именах, см. 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.