Интерфейс 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, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.xml/org/xml/sax/DocumentHandler.html
ContentHandler, который поддерживает имена пространств.