Интерфейс ContentHandler

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

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

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

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

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

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

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

Существует явное противоречие между документацией этого метода и документацией для ErrorHandler.fatalError(org.xml.sax.SAXParseException). До тех пор, пока эта неоднозначность не будет разрешена в будущей крупной версии, клиенты не должны делать предположений о том, будет ли вызван endDocument() или нет, когда парсер сообщил о fatalError() или бросил исключение.

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

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

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

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

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

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

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

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

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

Парсер вызовет этот метод в начале каждого элемента в 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 значения.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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