Интерфейс DocumentHandler
- Все известные реализующие классы:
-
HandlerBase,ParserAdapter
@Deprecated(since="1.5") public interface DocumentHandler
Этот интерфейс был основным интерфейсом обработки событий для SAX1; в SAX2 он заменён на ContentHandler, который обеспечивает поддержку пространства имён и отчёт о пропущенных сущностях. Этот интерфейс включён в SAX2 только для поддержки устаревших приложений SAX1.
Порядок событий в этом интерфейсе очень важен и отражает порядок информации в самом документе. Например, всё содержимое элемента (символьные данные, инструкции обработки и/или подэлементы) будет появляться в порядке следования между событием startElement и соответствующим событием endElement.
Авторы приложений, которые не хотят реализовывать весь интерфейс, могут создать класс, производный от HandlerBase, который реализует стандартную функциональность; авторы парсеров могут создать экземпляр HandlerBase для получения обработчика по умолчанию. Приложение может определить местоположение любого события документа, используя интерфейс Locator, предоставленный парсером через метод setDocumentLocator.
- С:
- 1.4, SAX 1.0
- См. также:
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
void |
characters |
Устарело. Получение уведомления о символьных данных. |
void |
endDocument() |
Устарело. Получение уведомления о завершении документа. |
void |
endElement |
Устарело. Получение уведомления о завершении элемента. |
void |
ignorableWhitespace |
Устарело. Получение уведомления о пренебрежимых пробелах в содержимом элемента. |
void |
processingInstruction |
Устарело. Получение уведомления об инструкции обработки. |
void |
setDocumentLocator |
Устарело. Получение объекта для определения источника событий SAX документа. |
void |
startDocument() |
Устарело. Получение уведомления о начале документа. |
void |
startElement |
Устарело. Получение уведомления о начале элемента. |
Подробное описание методов
setDocumentLocator
void setDocumentLocator(Locator locator)
SAX-парсерам настоятельно рекомендуется (хотя и не является обязательным) предоставлять локатор: если он это делает, он должен предоставить локатор приложению, вызвав этот метод перед вызовом любого другого метода в интерфейсе DocumentHandler.
Локатор позволяет приложению определить конечную позицию любого события, связанного с документом, даже если парсер не сообщает об ошибке. Как правило, приложение будет использовать эту информацию для сообщения об собственных ошибках (например, контент символов, не соответствующий бизнес-правилам приложения). Информация, возвращаемая локатором, вероятно, не будет достаточной для использования с поисковой системой.
Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова событий в этом интерфейсе. Приложение не должно пытаться использовать его в любое другое время.
- Параметры:
-
locator- Объект, который может вернуть расположение любого SAX-события документа. - См. также:
startDocument
void startDocument() throws SAXException
SAX-парсер вызовет этот метод только один раз, прежде чем вызывать любые другие методы в этом интерфейсе или в DTDHandler (кроме setDocumentLocator).
- Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение.
endDocument
void endDocument() throws SAXException
SAX-парсер вызовет этот метод только один раз, и это будет последний вызываемый метод во время разбора. Парсер не вызовет этот метод, пока не прекратит разбор (из-за неисправимой ошибки) или не достигнет конца входных данных.
- Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение.
startElement
void startElement(String name, AttributeList atts) throws SAXException
Парсер вызовет этот метод в начале каждого элемента в XML-документе; будет соответствующее событие endElement() для каждого события startElement() (даже когда элемент пустой). Весь контент элемента будет сообщаться по порядку перед соответствующим событием endElement().
Если имя элемента имеет префикс пространства имен, префикс по-прежнему будет присоединён. Обратите внимание, что предоставленный список атрибутов будет содержать только атрибуты с явными значениями (указанными или по умолчанию): атрибуты #IMPLIED будут опущены.
- Параметры:
-
name- Имя типа элемента. -
atts- Присоединённые к элементу атрибуты, если таковые имеются. - Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение. - См. также:
endElement
void endElement(String name) throws SAXException
SAX-парсер вызовет этот метод в конце каждого элемента в XML-документе; будет соответствующее событие startElement() для каждого события endElement() (даже когда элемент пустой).
Если имя элемента имеет префикс пространства имен, префикс по-прежнему будет присоединён к имени.
- Параметры:
-
name- Имя типа элемента - Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение.
characters
void characters(char[] ch, int start, int length) throws SAXException
Парсер вызовет этот метод, чтобы сообщить каждый фрагмент данных символов. SAX-парсеры могут возвращать все смежные данные символов в одном фрагменте, или они могут разбить их на несколько фрагментов; однако, все символы в любом отдельном событии должны поступать из одного внешнего сущности, чтобы локатор предоставлял полезную информацию.
Приложение не должно пытаться читать из массива за пределами указанного диапазона.
Обратите внимание, что некоторые парсеры будут сообщать пробелы с помощью метода ignorableWhitespace() вместо этого (валидирующие парсеры должны это делать).
- Параметры:
-
ch- Символы из XML-документа. -
start- Начальная позиция в массиве. -
length- Количество символов для чтения из массива. - Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение. - См. также:
ignorableWhitespace
void ignorableWhitespace(char[] ch, int start, int length) throws SAXException
Валидирующие парсеры должны использовать этот метод для сообщения о каждом фрагменте пренебрежимых пробелов (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие парсеры также могут использовать этот метод, если они способны анализировать и использовать модели содержимого.
SAX-парсеры могут возвращать все смежные пробелы в одном фрагменте, или они могут разбить их на несколько фрагментов; однако, все символы в любом отдельном событии должны поступать из одной внешней сущности, чтобы локатор предоставлял полезную информацию.
Приложение не должно пытаться читать из массива за пределами указанного диапазона.
- Параметры:
-
ch- Символы из XML-документа. -
start- Начальная позиция в массиве. -
length- Количество символов для чтения из массива. - Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение. - См. также:
processingInstruction
void processingInstruction(String target, String data) throws SAXException
Парсер вызовет этот метод один раз для каждой обработанной инструкции: обратите внимание, что инструкции обработки могут встречаться до или после основного элемента документа.
SAX-парсер никогда не должен сообщать об XML-декларации (XML 1.0, раздел 2.8) или декларации текста (XML 1.0, раздел 4.3.1) с помощью этого метода.
- Параметры:
-
target- Цель инструкции обработки. -
data- Данные инструкции обработки, или null, если их не было. - Исключения:
-
SAXException- Любое SAX-исключение, возможно, обертывающее другое исключение.
© 1993, 2021, 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/17/docs/api/java.xml/org/xml/sax/DocumentHandler.html
ContentHandler, который включает поддержку пространства имён.