Интерфейс XMLReader

Имя функции — любой полностью квалифицированный 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

 parse(new InputSource(systemId));
 

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