Интерфейс ContentHandler

Все известные подинтерфейсы:: TemplatesHandler, TransformerHandler

Все известные реализующие классы:: DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter

public interface ContentHandler

Получите уведомление о логическом содержимом документа.

Этот модуль, как исходный код, так и документация, находится в общественном достоянии и не имеет ГАРАНТИЙ. См. http://www.saxproject.org для получения дополнительной информации.

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

Порядок событий в этом интерфейсе очень важен и отражает порядок информации в самом документе. Например, всё содержимое элемента (символьные данные, инструкции обработки и/или подэлементы) появится в порядке, между событием startElement и соответствующим событием endElement.

Этот интерфейс похож на теперь устаревший интерфейс DocumentHandler SAX 1.0, но он добавляет поддержку пространств имён и отчётности о пропущенных сущностях (в невалидирующих процессорах XML).

Реализаторы должны учитывать, что также существует класс ContentHandler в пакете java.net; это означает, что, вероятно, не стоит делать

import java.net.*;
 import org.xml.sax.*;

На самом деле, "import ...*" обычно является признаком небрежной программирования, поэтому пользователь должен рассматривать это как функцию, а не ошибку.

С:: 1.4, SAX 2.0
См. также:: XMLReader, DTDHandler, ErrorHandler

Методы

Модификатор и тип	Метод	Описание
`void`	`characters(char[] ch, int start, int length)`	Получите уведомление о символьных данных.
`void`	`endDocument()`	Получите уведомление о конце документа.
`void`	`endElement(String uri, String localName, String qName)`	Получите уведомление о конце элемента.
`void`	`endPrefixMapping(String prefix)`	Завершите область сопоставления префикс-URI.
`void`	`ignorableWhitespace(char[] ch, int start, int length)`	Получите уведомление о пропускаемых пробелах в содержании элемента.
`void`	`processingInstruction(String target, String data)`	Получите уведомление об инструкции обработки.
`void`	`setDocumentLocator(Locator locator)`	Получите объект для определения источника событий SAX документа.
`void`	`skippedEntity(String name)`	Получите уведомление о пропущенной сущности.
`void`	`startDocument()`	Получите уведомление о начале документа.
`void`	`startElement(String uri, String localName, String qName, Attributes atts)`	Получите уведомление о начале элемента.
`void`	`startPrefixMapping(String prefix, String uri)`	Начните область сопоставления пространства имён префикс-URI.

Методы

setDocumentLocator

void setDocumentLocator(Locator locator)

Получите объект для определения источника событий SAX документа.

SAX-парсеры настоятельно рекомендуют (хотя это и не обязательно) предоставлять локатор: если он это делает, он должен передать локатор приложению, вызвав этот метод перед вызовом любого другого метода в интерфейсе ContentHandler.

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

Обратите внимание, что локатор будет возвращать корректную информацию только во время вызова обратных вызовов событий SAX после startDocument возврата и до вызова endDocument. Приложение не должно пытаться использовать его в другое время.

Параметры:: locator - объект, который может вернуть местоположение любого события SAX документа
См. также:: Locator

startDocument

void startDocument()
            throws SAXException

Получите уведомление о начале документа.

SAX-парсер вызовет этот метод только один раз, перед любыми другими обратными вызовами (кроме setDocumentLocator).

Исключение:: SAXException - любое SAX исключение, возможно, обертывающее другое исключение
См. также:: endDocument()

endDocument

void endDocument()
          throws SAXException

Получите уведомление о конце документа.

Существует явное противоречие между документацией для этого метода и документацией для ErrorHandler.fatalError(org.xml.sax.SAXParseException). Пока эта неоднозначность не будет решена в будущей основной версии, клиенты не должны делать предположений о том, будет ли вызываться endDocument(), когда парсер сообщил о fatalError() или выбросил исключение.

SAX-парсер вызовет этот метод только один раз, и это будет последний вызванный метод во время разбора. Парсер не вызовет этот метод до тех пор, пока не бросит разбор (из-за невосстановимой ошибки) или не достигнет конца входных данных.

Исключение:: SAXException - любое SAX исключение, возможно, обертывающее другое исключение
См. также:: startDocument()

startPrefixMapping

void startPrefixMapping(String prefix,
                        String uri)
                 throws SAXException

Начать область отображения префикс-URI схемы имен.

Информация из этого события не нужна для обычной обработки схем имен: SAX XML-читатель автоматически заменит префиксы для имен элементов и атрибутов, когда функция http://xml.org/sax/features/namespaces имеет значение true (по умолчанию).

Однако существуют случаи, когда приложениям необходимо использовать префиксы в данных символов или в значениях атрибутов, где их нельзя безопасно автоматически расширять; событие start/endPrefixMapping предоставляет приложению информацию для расширения префиксов в этих контекстах самостоятельно, если это необходимо.

Обратите внимание, что события start/endPrefixMapping не гарантируют правильное вложение друг относительно друга: все события startPrefixMapping будут происходить непосредственно перед соответствующим startElement событием, а все события endPrefixMapping будут происходить непосредственно после соответствующего endElement событием, но их порядок не гарантируется иначе.

Для префикса "xml" никогда не должно быть событий start/endPrefixMapping, так как он предопределен и неизменен.

Параметры:: prefix - префикс схемы имен, который объявляется. Пустая строка используется для стандартной схемы имен элемента, у которой нет префикса.; uri - URI схемы имен, к которому отображается префикс
Исключение:: SAXException - клиент может выбросить исключение во время обработки
См. также:: endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

void endPrefixMapping(String prefix)
               throws SAXException

Завершить область отображения схемы имен префикс-URI.

См. startPrefixMapping для получения подробностей. Эти события всегда будут происходить непосредственно после соответствующего endElement события, но порядок событий endPrefixMapping не гарантируется иначе.

Параметры:: prefix - префикс, который отображался. Это пустая строка, когда завершается область отображения стандартного отображения.
Исключение:: SAXException - клиент может выбросить исключение во время обработки
См. также:: startPrefixMapping(java.lang.String, java.lang.String), endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

void startElement(String uri,
                  String localName,
                  String qName,
                  Attributes atts)
           throws SAXException

Получить уведомление о начале элемента.

Парсер вызовет этот метод в начале каждого элемента в XML-документе; для каждого события startElement будет соответствующее событие endElement (даже когда элемент пустой). Все содержимое элемента будет сообщено в порядке, перед соответствующим событием endElement.

Это событие допускает до трех компонентов имени для каждого элемента:

URI схемы имен;
локальное имя; и
полное (с префиксом) имя.

Любые или все из них могут быть предоставлены, в зависимости от значений свойств http://xml.org/sax/features/namespaces и http://xml.org/sax/features/namespace-prefixes:

URI схемы имен и локальное имя являются обязательными, когда свойство namespaces имеет значение true (по умолчанию), и необязательны, когда свойство namespaces имеет значение false (если одно указано, оба должны быть);
полное имя требуется, когда свойство namespace-prefixes имеет значение true, и является необязательным, когда свойство namespace-prefixes имеет значение false (по умолчанию).

Обратите внимание, что список атрибутов будет содержать только атрибуты с явными значениями (указанными или по умолчанию): атрибуты #IMPLIED будут опущены. Список атрибутов будет содержать атрибуты, используемые для объявлений схем имен (атрибуты xmlns*), только если свойство http://xml.org/sax/features/namespace-prefixes имеет значение true (по умолчанию оно имеет значение false, а поддержка значения true является необязательной).

Как и в characters(), значения атрибутов могут содержать символы, которым требуется более одного char значения.

Параметры:: uri - URI схемы имен или пустая строка, если у элемента нет URI схемы имен или если обработка схем имен не выполняется; localName - локальное имя (без префикса) или пустая строка, если обработка схем имен не выполняется; qName - полное имя (с префиксом) или пустая строка, если полные имена недоступны; atts - атрибуты, прикрепленные к элементу. Если атрибутов нет, это будет пустой объект Attributes. Значение этого объекта после возвращения startElement неопределено
Исключение:: SAXException - любое SAX исключение, возможно, обертывающее другое исключение
См. также:: endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

void endElement(String uri,
                String localName,
                String qName)
         throws SAXException

Получить уведомление об окончании элемента.

SAX-парсер вызовет этот метод в конце каждого элемента в XML-документе; для каждого события endElement будет соответствующее событие startElement (даже когда элемент пустой).

Для получения информации об именах см. startElement.

Параметры:: uri - URI схемы имен или пустая строка, если у элемента нет URI схемы имен или если обработка схем имен не выполняется; localName - локальное имя (без префикса) или пустая строка, если обработка схем имен не выполняется; qName - полное имя XML (с префиксом) или пустая строка, если полные имена недоступны
Исключение:: SAXException - любое SAX исключение, возможно, обертывающее другое исключение

characters

void characters(char[] ch,
                int start,
                int length)
         throws SAXException

Получить уведомление о данных символов.

Парсер вызовет этот метод, чтобы сообщить о каждом фрагменте данных символов. Парсеры SAX могут возвращать все смежные данные символов в одном фрагменте или разделить их на несколько фрагментов; однако все символы в любом отдельном событии должны поступать из одного и того же внешнего сущности, чтобы локатор предоставлял полезную информацию.

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

Отдельные символы могут состоять более чем из одного значения Java char. Есть два важных случая, когда это происходит, потому что символы не могут быть представлены только шестнадцатью битами. В одном случае символы представляются в паре суррогатов, используя два специальных значения Unicode. Такие символы находятся в так называемых "астрольных плоскостях", с кодовым значением выше U+FFFF. Второй случай касается составных символов, таких как базовый символ, комбинирующийся с одним или несколькими символами акцента.

Ваш код не должен предполагать, что алгоритмы, использующие идиомы char-в-размер, будут работать с единицами символов; в некоторых случаях они будут разделять символы. Это актуально везде, где XML допускает произвольные символы, такие как значения атрибутов, данные инструкций обработки и комментарии, а также данные, полученные из этого метода. Это также обычно актуально всякий раз, когда код Java обрабатывает интернационализированный текст; эта проблема не уникальна для XML.

Обратите внимание, что некоторые парсеры будут сообщать о пробелах в содержимом элемента, используя метод ignorableWhitespace, а не этот (валидирующие парсеры должны это делать).

Параметры:: ch - символы из документа XML; start - начальная позиция в массиве; length - количество символов для чтения из массива
Исключения:: SAXException - любое исключение SAX, возможно, обертывающее другое исключение
См. также:: ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

void ignorableWhitespace(char[] ch,
                         int start,
                         int length)
                  throws SAXException

Получить уведомление о пробелах, игнорируемых в содержимом элемента.

Валидирующие парсеры должны использовать этот метод для сообщения о каждом фрагменте пробелов в содержимом элемента (см. рекомендацию W3C XML 1.0, раздел 2.10): невалидирующие парсеры также могут использовать этот метод, если они способны парсить и использовать модели содержимого.

Парсеры SAX могут возвращать все смежные пробелы в одном фрагменте или разделить их на несколько фрагментов; однако все символы в любом отдельном событии должны поступать из одной и той же внешней сущности, чтобы локатор предоставлял полезную информацию.

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

Параметры:: ch - символы из документа XML; start - начальная позиция в массиве; length - количество символов для чтения из массива
Исключения:: SAXException - любое исключение SAX, возможно, обертывающее другое исключение
См. также:: characters(char[], int, int)

processingInstruction

void processingInstruction(String target,
                           String data)
                    throws SAXException

Получить уведомление об инструкции обработки.

Парсер вызовет этот метод один раз для каждой инструкции обработки, найденной: обратите внимание, что инструкции обработки могут появляться до или после основного элемента документа.

Парсер SAX никогда не должен сообщать об объявлении XML (XML 1.0, раздел 2.8) или объявлении текста (XML 1.0, раздел 4.3.1) с помощью этого метода.

Подобно characters(), данные инструкции обработки могут содержать символы, которым требуется более одного значения char.

Параметры:: target - целевой элемент инструкции обработки; data - данные инструкции обработки или null, если они не были предоставлены. Данные не включают пробелы, разделяющие их с целевым элементом
Исключения:: SAXException - любое исключение SAX, возможно, обертывающее другое исключение

skippedEntity

void skippedEntity(String name)
            throws SAXException

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

Парсер вызовет этот метод каждый раз, когда сущность будет пропущена. Невалидирующие процессоры могут пропускать сущности, если они не видели объявлений (например, потому что сущность была объявлена во внешнем подмножестве DTD). Все процессоры могут пропускать внешние сущности, в зависимости от значений свойств http://xml.org/sax/features/external-general-entities и http://xml.org/sax/features/external-parameter-entities.

Параметры:: name - имя пропущенной сущности. Если это параметр сущности, имя начнется с '%', а если это внешнее подмножество DTD, то это будет строка "[dtd]"
Исключения:: SAXException - любое исключение SAX, возможно, обертывающее другое исключение

© 1993, 2020, 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/11/docs/api/java.xml/org/xml/sax/ContentHandler.html