Интерфейс 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».

Информация из этого события не требуется для обычной обработки пространств имён: XML-считыватель SAX автоматически заменяет префиксы в именах элементов и атрибутов, когда функция 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-документа; каждому событию 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 могут вернуть все непрерывные символьные данные одним фрагментом или разделить их на несколько фрагментов; однако все символы в одном событии должны происходить из одной и той же внешней сущности, чтобы локатор предоставлял полезную информацию.

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

Для представления отдельных символов может потребоваться более одного значения char в Java. Есть два важных случая, когда это происходит, поскольку символы нельзя представить всего шестнадцатью битами. В одном случае символы представлены суррогатной парой с использованием двух специальных значений 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.