Интерфейс XMLReader

Все известные подинтерфейсы:
XMLFilter
Все известные реализующие классы:
ParserAdapter, XMLFilterImpl 
public interface XMLReader

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

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

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

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

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

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

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

Доступны адаптеры для преобразования SAX1 Parser в SAX2 XMLReader и наоборот.

С:
1.4, SAX 2.0
См. также:
XMLFilter, ParserAdapter, XMLReaderAdapter

Методы

Модификатор и тип Метод Описание
ContentHandler getContentHandler()

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

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

Возвращает текущий разрешитель сущностей.
ErrorHandler getErrorHandler()

Возвращает текущий обработчик ошибок.
boolean getFeature​(String name)

Получает значение флага параметра.
Object getProperty​(String name)

Получает значение свойства.
void parse​(String systemId)

Парсит XML-документ по идентификатору системы (URI).
void parse​(InputSource input)

Парсит XML-документ.
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 нет независимого от реализации способа отобразить, выполняет ли базовый анализатор валидацию, расширяет ли внешние сущности и т. д.)

Все 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.

Параметры:
name - Имя функции, являющееся полностью квалифицированным URI.
Возвращает:
Текущее значение функции (true или false).
Исключение:
SAXNotRecognizedException - Если значение функции не может быть назначено или получено.
SAXNotSupportedException - Когда XMLReader распознает имя функции, но не может определить его значение в данный момент.
См. также:
setFeature(java.lang.String, boolean)

setFeature

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.

Параметры:
name - Имя функции, являющееся полностью квалифицированным URI.
value - Требуемое значение функции (true или false).
Исключение:
SAXNotRecognizedException - Если значение функции не может быть назначено или получено.
SAXNotSupportedException - Когда XMLReader распознает имя функции, но не может установить затребованное значение.
См. также:
getFeature(java.lang.String)

getProperty

Object getProperty(String name)
            throws SAXNotRecognizedException,
                   SAXNotSupportedException

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

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

XMLReader не обязаны распознавать какие-либо конкретные имена свойств, хотя начальный набор основных свойств описан в 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 может распознать имя свойства, но не сможет изменить текущее значение. Некоторые значения свойств могут быть неизменяемыми или изменяемыми только в определенных контекстах, например, до, во время или после разбора.

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

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

Параметры:
name - Имя свойства, являющееся полностью квалифицированным URI.
value - Затребованное значение свойства.
Исключение:
SAXNotRecognizedException - Если значение свойства не может быть назначено или получено.
SAXNotSupportedException - Когда XMLReader распознает имя свойства, но не может установить затребованное значение.

setEntityResolver

void setEntityResolver(EntityResolver resolver)

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

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

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

Параметры:
resolver - Обработчик сущностей.
См. также:
getEntityResolver()

getEntityResolver

EntityResolver getEntityResolver()

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

Возвращает:
Текущий обработчик сущностей или null, если он не зарегистрирован.
См. также:
setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

void setDTDHandler(DTDHandler handler)

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

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

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

Параметры:
handler - Обработчик DTD.
См. также:
getDTDHandler()

getDTDHandler

DTDHandler getDTDHandler()

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

Возвращает:
Текущий обработчик DTD или null, если он не зарегистрирован.
См. также:
setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

void setContentHandler(ContentHandler handler)

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

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

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

Параметры:
handler - Обработчик содержимого.
См. также:
getContentHandler()

getContentHandler

ContentHandler getContentHandler()

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

Возвращает:
Текущий обработчик содержимого или null, если он не зарегистрирован.
См. также:
setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

void setErrorHandler(ErrorHandler handler)

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

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

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

Параметры:
handler - Обработчик ошибок.
См. также:
getErrorHandler()

getErrorHandler

ErrorHandler getErrorHandler()

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

Возвращает:
Текущий обработчик ошибок или null, если он не зарегистрирован.
См. также:
setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(InputSource input)
    throws IOException,
           SAXException

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

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

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

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

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

Параметры:
input - Источник ввода для верхнего уровня XML-документа.
Исключение:
SAXException - Любое исключение SAX, возможно, обернутое другим исключением.
IOException - Исключение ввода-вывода от анализатора, возможно, из потока байтов или потока символов, предоставленных приложением.
См. также:
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)

parse

void parse(String systemId)
    throws IOException,
           SAXException

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

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

parse(new InputSource(systemId));

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

Параметры:
systemId - Идентификатор системы (URI).
Исключения:
SAXException - Любое исключение SAX, возможно, обертывающее другое исключение.
IOException - Исключение ввода-вывода от парсера, возможно, из потока байтов или потока символов, предоставленного приложением.
См. также:
parse(org.xml.sax.InputSource)

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.xml/org/xml/sax/XMLReader.html

Spec-Zone .ru
спецификации, руководства, описания, API