Интерфейс 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; для каждого события 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 свойств.