org.xml.sax

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

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

XMLFilter

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

ParserAdapter, XMLFilterImpl

public interface XMLReader

Интерфейс для того, чтобы считать использование XML-документа обратные вызовы.

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

Отметьте: несмотря на его имя, этот интерфейс не расширяет стандартный Java Reader интерфейс, потому что чтение XML является существенно различным действием чем чтение символьных данных.

XMLReader является интерфейсом, который должен реализовать драйвер синтаксического анализатора XML SAX2. Этот интерфейс позволяет приложению устанавливать и запрашивать функции и свойства в синтаксическом анализаторе, регистрировать обработчики событий для обработки документов, и инициировать синтаксический анализ документа.

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

Этот интерфейс заменяет (теперь осуждаемый) SAX 1.0 Parser интерфейс. Интерфейс XMLReader содержит два важных улучшения по старому интерфейсу Синтаксического анализатора (так же как некоторые незначительные):

1. это добавляет стандартный способ запросить и установить функции и свойства; и
2. это добавляет поддержку Пространства имен, которая требуется для многих высокоуровневых стандартов XML.

Есть адаптеры, доступные, чтобы преобразовать Синтаксический анализатор SAX1 в SAX2 XMLReader и наоборот.

С тех пор:

SAX 2.0

См. Также:

XMLFilter, ParserAdapter, XMLReaderAdapter

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

Методы

Модификатор и Тип	Метод и Описание
ContentHandler	getContentHandler() Возвратите текущий обработчик содержимого.
DTDHandler	getDTDHandler() Возвратите текущий обработчик DTD.
EntityResolver	getEntityResolver() Возвратите текущий преобразователь объекта.
ErrorHandler	getErrorHandler() Возвратите текущий обработчик ошибок.
boolean	getFeature(String name) Ищите значение значения параметра.
Объект	getProperty(String name) Ищите значение свойства.
void	parse(InputSource input) Проанализируйте XML-документ.
void	parse(String systemId) Проанализируйте XML-документ от системного идентификатора (URI).
void	setContentHandler(ContentHandler handler) Позвольте приложению регистрировать обработчик событий контента.
void	setDTDHandler(DTDHandler handler) Позвольте приложению регистрировать обработчик событий DTD.
void	setEntityResolver(EntityResolver resolver) Позвольте приложению регистрировать преобразователь объекта.
void	setErrorHandler(ErrorHandler handler) Позвольте приложению регистрировать ошибочный обработчик событий.
void	setFeature(String name, boolean value) Установите значение значения параметра.
void	setProperty(String name, Object value) Установите значение свойства.

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

getFeature

boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

Ищите значение значения параметра.

Имя функции является любым полностью определенным URI. Для XMLReader возможно распознать имя функции, но временно быть неспособным возвратить его значение. Некоторые значения функции могут быть доступными только в определенных контекстах, такой как прежде, во время, или после синтаксического анализа. Кроме того, некоторые значения функции, возможно, не программно доступны. (В случае адаптера для SAX1 Parser, нет никакого независимого от реализации способа представить, выполняет ли базовый синтаксический анализатор проверку допустимости, разворачивая внешние объекты, и т.д.)

Все XMLReaders обязаны распознавать http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes имена функции.

Типичное использование - что-то вроде этого:

 XMLReader r = new MySAXDriver();

                         // try to activate validation
 try {
   r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
   System.err.println("Cannot activate validation.");
 }

                         // register event handlers
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

                         // parse the first document
 try {
   r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
   System.err.println("I/O exception reading XML document");
 } catch (SAXException e) {
   System.err.println("XML exception reading document.");
 }
 

Конструкторы свободны (и поощренный) изобрести свои собственные функции, используя имена, основанные на их собственных URI.

Параметры:

name - Имя функции, которое является полностью определенным URI.

Возвраты:

Текущая стоимость функции (истина или ложь).

Броски:

SAXNotRecognizedException - Если значение функции не может быть присвоено или получено.

SAXNotSupportedException - Когда XMLReader распознает имя функции, но не может определить его значение в это время.

См. Также:

setFeature(java.lang.String, boolean)

setFeature

void setFeature(String name,
              boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

Установите значение значения параметра.

Имя функции является любым полностью определенным URI. Для XMLReader возможно представить значение функции, но быть неспособным изменить текущую стоимость. Некоторые значения функции могут быть неизменными или изменчивыми только в определенных контекстах, такой как прежде, во время, или после синтаксического анализа.

Все XMLReaders обязаны поддерживать установку http://xml.org/sax/features/namespaces к истине и http://xml.org/sax/features/namespace-prefixes ко лжи.

Параметры:

name - Имя функции, которое является полностью определенным URI.

value - Требуемое значение функции (истина или ложь).

Броски:

SAXNotRecognizedException - Если значение функции не может быть присвоено или получено.

SAXNotSupportedException - Когда XMLReader распознает имя функции, но не может установить требуемое значение.

См. Также:

getFeature(java.lang.String)

getProperty

Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

Ищите значение свойства.

Имя свойства является любым полностью определенным URI. Для XMLReader возможно распознать имя свойства, но временно быть неспособным возвратить его значение. Некоторые значения свойств могут быть доступными только в определенных контекстах, такой как прежде, во время, или после синтаксического анализа.

XMLReaders не обязаны распознавать любые определенные имена свойства, хотя начальный базовый набор документируется для SAX2.

Конструкторы свободны (и поощренный) изобрести свои собственные свойства, используя имена, основанные на их собственных URI.

Параметры:

name - Имя свойства, которое является полностью определенным URI.

Возвраты:

Текущая стоимость свойства.

Броски:

SAXNotRecognizedException - Если значение свойства не может быть присвоено или получено.

SAXNotSupportedException - Когда XMLReader распознает имя свойства, но не может определить его значение в это время.

См. Также:

setProperty(java.lang.String, java.lang.Object)

setProperty

void setProperty(String name,
               Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

Установите значение свойства.

Имя свойства является любым полностью определенным URI. Для XMLReader возможно распознать имя свойства, но быть неспособным изменить текущую стоимость. Некоторые значения свойств могут быть неизменными или изменчивыми только в определенных контекстах, такой как прежде, во время, или после синтаксического анализа.

XMLReaders не обязаны распознавать определение любых определенных имен свойства, хотя базовый набор определяется SAX2.

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

Параметры:

name - Имя свойства, которое является полностью определенным URI.

value - Требуемое значение для свойства.

Броски:

SAXNotRecognizedException - Если значение свойства не может быть присвоено или получено.

SAXNotSupportedException - Когда XMLReader распознает имя свойства, но не может установить требуемое значение.

setEntityResolver

void setEntityResolver(EntityResolver resolver)

Позвольте приложению регистрировать преобразователь объекта.

Если приложение не зарегистрирует преобразователь объекта, то XMLReader выполнит свое собственное разрешение по умолчанию.

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

Параметры:

resolver - Преобразователь объекта.

См. Также:

getEntityResolver()

getEntityResolver

EntityResolver getEntityResolver()

Возвратите текущий преобразователь объекта.

Возвраты:

Текущий преобразователь объекта, или нуль, если ни один не был зарегистрирован.

См. Также:

setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

void setDTDHandler(DTDHandler handler)

Позвольте приложению регистрировать обработчик событий DTD.

Если приложение не зарегистрирует обработчик DTD, то все события DTD, о которых сообщает синтаксический анализатор SAX, будут тихо проигнорированы.

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

Параметры:

handler - Обработчик DTD.

См. Также:

getDTDHandler()

getDTDHandler

DTDHandler getDTDHandler()

Возвратите текущий обработчик DTD.

Возвраты:

Текущий обработчик DTD, или нуль, если ни один не был зарегистрирован.

См. Также:

setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

void setContentHandler(ContentHandler handler)

Позвольте приложению регистрировать обработчик событий контента.

Если приложение не зарегистрирует обработчик содержимого, то все события контента, о которых сообщает синтаксический анализатор SAX, будут тихо проигнорированы.

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

Параметры:

handler - Обработчик содержимого.

См. Также:

getContentHandler()

getContentHandler

ContentHandler getContentHandler()

Возвратите текущий обработчик содержимого.

Возвраты:

Текущий обработчик содержимого, или нуль, если ни один не был зарегистрирован.

См. Также:

setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

void setErrorHandler(ErrorHandler handler)

Позвольте приложению регистрировать ошибочный обработчик событий.

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

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

Параметры:

handler - Обработчик ошибок.

См. Также:

getErrorHandler()

getErrorHandler

ErrorHandler getErrorHandler()

Возвратите текущий обработчик ошибок.

Возвраты:

Текущий обработчик ошибок, или нуль, если ни один не был зарегистрирован.

См. Также:

setErrorHandler(org.xml.sax.ErrorHandler)

синтаксический анализ

void parse(InputSource input)
           throws IOException,
                  SAXException

Проанализируйте XML-документ.

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

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

Во время синтаксического анализа XMLReader предоставит информацию о XML-документе через зарегистрированные обработчики событий.

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

Параметры:

input - Входной источник для верхнего уровня XML-документа.

Броски:

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

IOException - Исключение IO из синтаксического анализатора, возможно из потока байтов или символьного потока предоставляется приложением.

См. Также:

InputSource, parse(java.lang.String), setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setContentHandler(org.xml.sax.ContentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

синтаксический анализ

void parse(String systemId)
           throws IOException,
                  SAXException

Проанализируйте XML-документ от системного идентификатора (URI).

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

 parse(new InputSource(systemId));
 

Если системным идентификатором является URL, он должен быть полностью разрешен приложением прежде, чем его передадут к синтаксическому анализатору.

Параметры:

systemId - Системный идентификатор (URI).

Броски:

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

IOException - Исключение IO из синтаксического анализатора, возможно из потока байтов или символьного потока предоставляется приложением.

См. Также:

parse(org.xml.sax.InputSource)