Класс DocumentBuilder

Абстрактный класс DocumentBuilder определяет интерфейс прикладного программирования – API (Application Program Interface) для получения экземпляров объекта Document из документа XML.

Основными методами класса DocumentBuilder являются методы анализа документа XML:

public Document parse(File f) throws SAXException,

IOException

public abstract Document parse(InputSource is)

throws SAXException, IOException

public Document parse(InputStream is)

throws SAXException, IOException

public Document parse(InputStream is, String systemId)

throws SAXException, IOException

public Document parse(String uri) throws SAXException,

IOException

В параметре метода задается источник, в котором содержится документ, представленный как экземпляр одного из классов: File, InputSource или InputStream, либо как обращение к ресурсу URI. Параметр в systemId четвертом методе задает системный идентификатор, необходимый для разрешения относительных URI.

Получение экземпляра объекта Document для DOM-анализатора выполняется с помощью одного из методов:

public abstract Document newDocument()

public abstract DOMImplementation getDOMImplementation()

Первый метод прямо получает новый экземпляр объекта Document для построения дерева DOM. Второй метод получает объект DOMImplementation, а затем с помощью методов DOM уровня 2 создается новый объект Document.

Метод

public abstract void setErrorHandler(ErrorHandler eh)

позволяет установить обработчик ошибок для документа XML.

В интерфейсе ErrorHandler пакета org.xml.sax определены следующие методы обработки ошибок:

public void fatalError(SAXParseException exception)

throws SAXException

public void error(SAXParseException exception)

throws SAXException

public void warning(SAXParseException exception)

throws SAXException,

Эти методы обеспечивают получение уведомлений о фатальной ошибке, восстановимой ошибке и предупреждении.

Методы интерфейса ErrorHandler реализованы в классе DefaultHandler. Все эти методы просто бросают исключение SAXParseException. Если необходимо выполнить собственную обработку ошибок, методы обработки ошибок следует переписать в классе, расширяющем класс DefaultHandler.

Пример реализации собственного метода fatalError() в классе DefaultHandler документа email.xml:

public void fatalError(SAXParseException spe)

throws SAXParseException {

System.out.println(spe.getMessage() +

" в строке " + spe.getLineNumber());

System.exit(1);

}

Если в методе startElement() после оператора if для проверки элемента body вставить следующий фрагмент

else {

fatalError(new SAXParseException(

"Недопустимый дескриптор <" + qname +

">", locator)

);

}

то, при появлении в тексте документа недопустимого дескриптора, например, <Header>, будет выведено сообщение

Недопустимый дескриптор <header> в строке 11

Метод

public abstract void setEntityResolver(EntityResolver er)

позволяет установить обработчик сущностей для документа XML.

Единственный метод

public InputSource resolveEntity(String publicId,

String systemId) throws SAXException, IOException

интерфейса EntityResolver в пакете org.xml.sax позволяет предложению обрабатывать ссылки на внешние сущности. Интерфейс EntityResolver реализован в классе DefaultHandler. Метод resolveEntity(), реализованный в этом классе, всегда возвращает null. В подклассе класса DefaultHandler можно переопределить метод resolveEntity()для конкретного приложения.

Пример реализации метода resolveEntity() для разрешения внешних ссылок в документе email.xml:

public InputSource resolveEntity(String publicId,

String systemId) throws SAXException {

InputSource entitySource = null;

if (systemId.startsWith("file:"))

systemId = systemId.substring(5);

try {

entitySource =

new InputSource(new FileInputStream(systemId));

}

catch(IOException ioe) {

System.out.println("Ошибка в файле <" +

systemId + ">");

}

return entitySource;

}

С помощью методов

public abstract boolean isNamespaceAware()

public abstract boolean isValidating()

выполняется проверка, сконфигурирован ли данный DOM-анализатор для работы с пространствами имен или для проверки действительности документа XML.