Интерфейс XMLReader

boolean getFeature(String name) throws SAXNotRecognizedException, SAXNotSupportedException

Возвращает значение флага функции.

Имя функции — это любой URI с полным указанием. XMLReader может распознавать имя функции, но временно не иметь возможности вернуть её значение. Некоторые значения функций могут быть доступны только в определённых контекстах, например до, во время или после разбора. Кроме того, некоторые значения функций могут быть недоступны программно. (В случае адаптера для Parser 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 должны поддерживать установку значения true для http://xml.org/sax/features/namespaces и значения false для http://xml.org/sax/features/namespace-prefixes.

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).

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

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

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

void parse(String systemId) throws IOException, SAXException

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

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

parse(new InputSource(systemId));

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