Интерфейс DocumentHandler
- Все известные классы, реализующие интерфейс:
HandlerBase, ParserAdapter
@Deprecated(since="1.5") public interface DocumentHandler
Это был основной интерфейс обработки событий в SAX1; в SAX2 он заменён интерфейсом ContentHandler, который обеспечивает поддержку пространств имён и уведомления о пропущенных сущностях. Этот интерфейс включён в SAX2 только для поддержки устаревших приложений SAX1.
Порядок событий в этом интерфейсе очень важен и соответствует порядку информации в самом документе. Например, всё содержимое элемента (текстовые данные, инструкции по обработке и/или вложенные элементы) будет появляться по порядку между событием startElement и соответствующим событием endElement.
Разработчики приложений, которым не требуется реализовывать весь интерфейс, могут создать класс на основе HandlerBase, реализующего функциональность по умолчанию; разработчики анализаторов могут создать экземпляр HandlerBase, чтобы получить обработчик по умолчанию. Приложение может определить местоположение любого события документа с помощью интерфейса Locator, предоставленного Parser через метод 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-документа; каждому событию startElement() будет соответствовать событие endElement() (даже если элемент пуст). Всё содержимое элемента будет передано по порядку до соответствующего события endElement().
Если имя элемента содержит префикс пространства имён, этот префикс сохранится. Обратите внимание, что предоставленный список атрибутов будет содержать только атрибуты с явными значениями (заданными явно или по умолчанию): атрибуты #IMPLIED будут опущены.
- Параметры:
-
name— Имя типа элемента. -
atts— Атрибуты элемента, если они есть. - Вызывает исключения:
-
SAXException— Любое исключение SAX, возможно, оборачивающее другое исключение. - См. также:
endElement
void endElement(String name) throws SAXException
Анализатор SAX будет вызывать этот метод в конце каждого элемента XML-документа; каждому событию endElement() будет соответствовать событие startElement() (даже если элемент пуст).
Если имя элемента содержит префикс пространства имён, этот префикс сохранится в имени.
- Параметры:
-
name— Имя типа элемента - Вызывает исключения:
-
SAXException— Любое исключение SAX, возможно, оборачивающее другое исключение.
characters
void characters(char[] ch, int start, int length) throws SAXException
Анализатор будет вызывать этот метод для передачи каждого фрагмента текстовых данных. Анализаторы SAX могут передать все непрерывные текстовые данные одним фрагментом или разделить их на несколько фрагментов; однако все символы в рамках одного события должны поступать из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.
Приложение не должно пытаться читать данные из массива за пределами указанного диапазона.
Обратите внимание, что некоторые анализаторы будут сообщать о пробельных символах с помощью метода 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 могут передать все смежные пробельные символы одним фрагментом или разделить их на несколько фрагментов; однако все символы в рамках одного события должны поступать из одной и той же внешней сущности, чтобы Locator предоставлял полезную информацию.
Приложение не должно пытаться читать данные из массива за пределами указанного диапазона.
- Параметры:
-
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://docs.oracle.com/en/java/javase/25/docs/api/java.xml/org/xml/sax/DocumentHandler.html
ContentHandler, который включает поддержку пространств имён.