org.xml.sax

Интерфейсный ContentHandler

Все Известные Подынтерфейсы:

TemplatesHandler, TransformerHandler, UnmarshallerHandler

Все Известные Классы с реализацией:

DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter

public interface ContentHandler

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

Этот модуль, и исходный код и документация, находится в Общедоступном Домене, и прибывает без ГАРАНТИИ. См. http://www.saxproject.org для дополнительной информации.

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

Порядок событий в этом интерфейсе очень важен, и зеркально отражает порядок информации в документе непосредственно. Например, весь контент элемента (символьные данные, обрабатывая инструкции, и/или подэлементы) появится, в порядке, между startElement событием и соответствующим endElement событием.

Этот интерфейс подобен теперь осуждаемому SAX 1.0 интерфейса DocumentHandler, но это добавляет поддержку Пространств имен и создания отчетов о пропущенных объектах (в непроверке допустимости процессоров XML).

Конструкторы должны отметить, что есть также a ContentHandler класс в java.net пакет; это означает, что это - вероятно, плохая идея сделать

import java.net.*;
 import org.xml.sax.*;
 

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

С тех пор:

SAX 2.0

См. Также:

XMLReader, DTDHandler, ErrorHandler

Сводка метода

Методы

Модификатор и Тип	Метод и Описание
void	characters(char[] ch, int start, int length) Получите уведомление о символьных данных.
void	endDocument() Получите уведомление о конце документа.
void	endElement(String uri, String localName, String qName) Получите уведомление о конце элемента.
void	endPrefixMapping(String prefix) Закончите контекст отображения префиксного URI.
void	ignorableWhitespace(char[] ch, int start, int length) Получите уведомление об игнорируемом пробеле в контенте элемента.
void	processingInstruction(String target, String data) Получите уведомление об инструкции обработки.
void	setDocumentLocator(Locator locator) Получите объект для того, чтобы определить местоположение источника событий документа SAX.
void	skippedEntity(String name) Получите уведомление о пропущенном объекте.
void	startDocument() Получите уведомление о начале документа.
void	startElement(String uri, String localName, String qName, Attributes atts) Получите уведомление о начале элемента.
void	startPrefixMapping(String prefix, String uri) Начните контекст отображения Пространства имен префиксного URI.

Деталь метода

setDocumentLocator

void setDocumentLocator(Locator locator)

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

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

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

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

Параметры:

locator - объект, который может возвратить расположение любого события документа SAX

См. Также:

Locator

startDocument

void startDocument()
                   throws SAXException

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

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

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

См. Также:

endDocument()

endDocument

void endDocument()
                 throws SAXException

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

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

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

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

См. Также:

startDocument()

startPrefixMapping

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", так как он предварительно объявляется и неизменный.

Параметры:

prefix - объявляемый префикс Пространства имен. Пустая строка используется для пространства имен элемента по умолчанию, у которого нет никакого префикса.

uri - URI Пространства имен префикс отображается на

Броски:

SAXException - клиент может выдать исключение во время обработки

См. Также:

endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

void endPrefixMapping(String prefix)
                      throws SAXException

Закончите контекст отображения префиксного URI.

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

Параметры:

prefix - префикс, который отображался. Это - пустая строка, когда значение по умолчанию, отображающее контекст, заканчивается.

Броски:

SAXException - клиент может выдать исключение во время обработки

См. Также:

startPrefixMapping(java.lang.String, java.lang.String), endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

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 Пространства имен и локальное имя требуются, когда свойство пространств имен является true (значение по умолчанию), и является дополнительным, когда свойством пространств имен является false (если Вы определяетесь, оба должны быть);
• полностью определенное имя требуется, когда свойство префиксов пространства имен является true, и является дополнительным, когда свойством префиксов пространства имен является false (значение по умолчанию).

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

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

Параметры:

uri - URI Пространства имен, или пустая строка, если у элемента нет никакого URI Пространства имен или если обработка Пространства имен не выполняется

localName - локальное имя (без префикса), или пустая строка, если обработка Пространства имен не выполняется

qName - полностью определенное имя (с префиксом), или пустая строка, если полностью определенные имена не доступны

atts - атрибуты, присоединенные к элементу. Если не будет никаких атрибутов, то это должен быть пустой объект Атрибутов. Значение этого объекта после startElement возвраты неопределено

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

См. Также:

endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

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

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

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

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

Параметры:

uri - URI Пространства имен, или пустая строка, если у элемента нет никакого URI Пространства имен или если обработка Пространства имен не выполняется

localName - локальное имя (без префикса), или пустая строка, если обработка Пространства имен не выполняется

qName - квалифицированное имя XML (с префиксом), или пустая строка, если полностью определенные имена не доступны

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

символы

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

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

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

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

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

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

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

Параметры:

ch - символы из XML-документа

start - позиция запуска в массиве

length - число символов, чтобы читать из массива

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

См. Также:

ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

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

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

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

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

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

Параметры:

ch - символы из XML-документа

start - позиция запуска в массиве

length - число символов, чтобы читать из массива

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

См. Также:

characters(char[], int, int)

processingInstruction

void processingInstruction(String target,
                         String data)
                           throws SAXException

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

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

Синтаксический анализатор SAX никогда не должен сообщать об объявлении XML (XML 1.0, разделять 2.8) или текстовое объявление (XML 1.0, разделите 4.3.1), использующий этот метод.

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

Параметры:

target - цель инструкции обработки

data - данные инструкции обработки, или нуль, если ни один не был предоставлен. Данные не включают пробела, разделяющего это от цели

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение

skippedEntity

void skippedEntity(String name)
                   throws SAXException

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

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

Параметры:

name - имя пропущенного объекта. Если это будет объект параметра, то имя начнется 'с %', и если это будет внешнее подмножество DTD, то это будет строка" [дата]"

Броски:

SAXException - любое исключение SAX, возможно обертывая другое исключение