Интерфейс XMLReader

boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException

Получение значения флага функции.

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

Все XMLReader обязаны распознавать имена функций 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.

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

Установка значения флага функции.

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

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

Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException

Получение значения свойства.

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

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

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

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

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

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

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

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

void setEntityResolver(EntityResolver resolver)

Разрешение приложения зарегистрировать обработчик сущностей.

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

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

EntityResolver getEntityResolver()

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

void setDTDHandler(DTDHandler handler)

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

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

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

DTDHandler getDTDHandler()

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

void setContentHandler(ContentHandler handler)

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

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

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

ContentHandler getContentHandler()

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

void setErrorHandler(ErrorHandler handler)

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

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

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

ErrorHandler getErrorHandler()

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

void parse(InputSource input) throws IOException, SAXException

Обработка XML-документа.

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

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

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

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

void parse(String systemId) throws IOException, SAXException

Обработка XML-документа из идентификатора системы (URI).

Этот метод является сокращением для распространённого случая чтения документа из идентификатора системы. Он точно эквивалентен следующему:

 parse(new InputSource(systemId));
 

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