5.2.3.2.10. ИсключениеDomException

Многие методы пакета org.w3c.domбросают исключениеDOMException.

Объект класса DOMExceptionсоздается с помощью конструктора

public DOMException(short code, String message)

в котором задается числовой код codeошибки и сообщение message, выводимое при ошибке.

Код ошибки содержится в поле

public short code

класса DOMException. Другие поля этого класса (с модификаторамиpublic static final short) содержат целые переменные, позволяющие определить причину возникновения ошибки:

• DOMSTRING_SIZE_ERR– если заданная строка не помещается в другую строку;

• HIERARCHY_REQUEST_ERR– если узел вставляется туда, где он не может находиться;

• INDEX_SIZE_ERR– если индекс или размер являются отрицательными числами, либо превышают допустимое значение;

• INUSE_ATTRIBUTE_ERR– попытка добавления атрибута, используемого в другом месте;

• INVALID_ACCESS_ERR– если параметр и операция не поддерживаются объектом;

• INVALID_CHARACTER_ERR– если используется неверный или недопустимый символ (например, в имени);

• INVALID_MODIFICATION_ERR– если предпринята попытка изменить тип объекта;

• INVALID_STATE_ERR– если предпринята попытка использовать объект, который нельзя использовать;

• NAMESPACE_ERR– если предпринята попытка создать или изменить объект без учета пространства имен;

• NO_DATA_ALLOWED_ERR– если данные определены для узла, который их не поддерживает;

• NO_MODIFICATION_ALLOWED_ERR– если предпринята попытка модифицировать объект, который нельзя модифицировать;

• NOT_FOUND_ERR– если предпринята попытка ссылки на узел в контексте, в котором данный узел не существует;

• NOT_SUPPORTED_ERR– если реализация не поддерживает запрашиваемый тип объекта или операцию;

• SYNTAX_ERR– если определена неверная или незаконная строка;

• WRONG_DOCUMENT_ERR– если узел используется не в том документе, в котором он был создан.

5.2.3.3. Средства выполнения преобразований документовXmLв языкеJava

Общие средства выполнения преобразований документов XMLопределены в пакетеjavax.xml.transform. Реализация этих средств дляDOM-анализаторов иSAX-анализаторов описаны в пакетахjavax.xml.transform.domиjavax.xml.transform.sax. Средства преобразования для потоков ввода-вывода иURIописаны в пакетеjavax.xml.transform.stream.

5.2.3.3.1. Общие средства выполнения преобразований документовXml

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

Интерфейсы содержат по два одинаковых метода

public String getSystemId()

public void setSystemId(String systemId),

позволяющих получить или установить системный идентификатор для источника или результата.

Кроме того, интерфейс содержит два строковых поля с модификаторами public static final: полеPI_DISABLE_OUTPUT_ESCAPING, определяющее имя инструкции по обработке, посылаемую, если в результирующем дереве отключено удаление символов (обычно при сериализации отключается вывод символов "&", "<" в выходное дерево) и полеPI_ENABLE_OUTPUT_ESCAPING, определяющее имя инструкции по обработке, посылаемую, если в результирующем дереве включено удаление символов.

Интерфейс SourceLocatorсодержит методы, определяющие местоположение ошибки в источникеXMLили инструкции преобразования.

Метолы этого интерфейса

public int getLineNumber()

public int getColumnNumber()

public String getPublicId()

public String getSystemId()

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

Объект, реализующий интерфейс Templatesявляется представлением времени выполнения для обрабатываемой инструкции преобразования.

Метод

public Properties getOutputProperties()

позволяет получить статические свойства для xsl:output, а метод

public Transformer newTransformer()

throws TransformerConfigurationException

создает новый контекст преобразования для данного объекта Transformer.

Объект, реализующий интерфейс URIResolverдля преобразованияURI, используемого в документе –xsl:importилиxsl:includeв объектSource. Единственный метод этого интерфейса

public Source resolve(String href, String base)

throws TransformerException

вызывается процессором XML, когда он встречает элементы xsl:include, xsl:import или функцию.

Интерфейс ErrorListenerопределяет три метода для получения уведомления о серьезной ошибке, восстановимой ошибке и предупреждении при выполнении операций преобразования:

public void fatalError(TransformerException exception)

throws TransformerException

public void error(TransformerException exception)

throws TransformerException

public void warning(TransformerException exception)

throws TransformerException

Абстрактный класс Transformerопределяет объекты, которые могут использоваться для преобразования из исходного дерева в результирующее дерево.

Основной метод этого класса

public abstract void transform(Source xmlSource,

Result outputTarget) throws TransformerException

выполняет преобразование исходного дерева xmlSource в результирующее дерево outputTarget.

Остальные методы позволяют получить или установить отдельные свойства преобразования.

Так, методы

public abstract Object getParameter(String name)

public abstract void setParameter(String name,

Object value)

public abstract void clearParameters()

позволяют соответственно получить, установить или очистить параметры преобразования.

Методы

public abstract Properties getOutputProperties()

public abstract void

setOutputProperties(Properties oformat)

throws IllegalArgumentException

позволяют получить или установить выходные свойства как объекты класса Properties, а методы

public abstract String getOutputProperty(String name)

throws IllegalArgumentException

public abstract void setOutputProperty(String name,

String value) throws IllegalArgumentException

позволяют получить или установить одно выходное свойство как строковый объект.

Методы

public abstract URIResolver getURIResolver()

public abstract void setURIResolver(URIResolver resolver)

позволяют получить или установить объект, который будет использоваться для разрешения URI, используемых в документе.

И, наконец, методы

public abstract ErrorListener getErrorListener()

public abstract void

setErrorListener(ErrorListener listener)

throws IllegalArgumentException

позволяют получить или установить блок прослушивания событий ошибок для данного преобразования.

Абстрактный класс TransformerFactoryпозволяет создать объекты классаTransformerи интерфейсаTemplates.

Объект этого класса создается с помощью производственного метода

public static TransformerFactory newInstance()

throws TransformerFactoryConfigurationError,

Объект класса Transformerсоздается с помощью одного из методов:

public abstract Transformer newTransformer()

throws TransformerConfigurationException

public abstract Transformer newTransformer(Source source)

throws TransformerConfigurationException.

Первый метод создает объект Transformer, который преобразует копию источника в результат, а второй метод преобразует объект интерфейса Source в объект Transformer.

Объект интерфейса Templates создается с помощью метода

public abstract Templates newTemplates(Source source)

throws TransformerConfigurationException.

Метод

public abstract Source

getAssociatedStylesheet(Source source,

String media, String title, String charset)

throws TransformerConfigurationException

позволяет получить связанную с источником таблицу стилей (определенную в документе XMLс помощью инструкции по обработкеxml-stylesheet).

Метод

public abstract boolean getFeature(String name)

позволяет получить заданное свойство, задаваемое в форме абсолютного URI).

Методы

public abstract Object getAttribute(String name)

throws IllegalArgumentException

public abstract void setAttribute(String name,

Object value) throws IllegalArgumentException

позволяют пользователю получать или устанавливать значение указанного атрибута в данной реализации.

Остальные методы класса: getErrorListener(),setErrorListener(),getURIResolver()иsetURIResolver()дублируют соответствующие методы классаTransformer.

Класс OutputKeysобеспечивает строковые константы, которые используются либо для установки выходных свойств классаTransformer, либо для получения выходных свойств объектовTransformerилиTemplates.

Имена свойств задаются следующими строковыми константами класса OutputKeysс модификаторамиpublic static final:

• CDATA_SECTION_ELEMENTS – список имен секций CDATA;

• DOCTYPE_PUBLIC– общедоступный идентификатор преобразованного документа;

• DOCTYPE_SYSTEM– системный идентификатор преобразованного документа;

• ENCODING– кодировка символов преобразованного документа;

• INDENT– делать ли отступы: "yes" или "no";

• MEDIA_TYPE– MIME-тип содержимого преобразованного документа;

• METHOD– одно из значений "xml", "html" или "text"',

• OMIT_XML_DECLARATION– не включать объявление XML: "yes" или "no";

• STANDALONE— отдельный или вложенный документ: "yes" или "no";

• VERSION– номер версии.

Например, можно задать кодировку символов преобразованного документа следующим методом:

transformer.setOutputProperty(

OutputKeys.ENCODING, "Windows-1251"

);

Правда, в этом случае все символы кириллицы будут представлены как сущности – десятичные коды символов Unicode. По умолчанию используется кодировка "UTF-8".

Класс TransformerExceptionопределяет исключительную ситуацию, которая может случиться во время выполнения операции преобразования.

Основным конструктором этого класса является конструктор

public TransformerException(String message,

SourceLocator locator, Throwable e)

который создает объект-исключение с заданным текстом сообщения message, объектомlocatorинтерфейсаSourceLocatorи являющийся оболочкой для исключенияe. В остальных конструкторах задаются один или два из приведенных параметров.

Методы

public Throwable getCause()

public Throwable getException()

public String getLocationAsString()

public SourceLocator getLocator()

public String getMessageAndLocation()

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

Метод

public Throwable initCause(Throwable cause)

инициализирует причину данного исключения и приводит его к другому исключению, а метод

public void setLocator(SourceLocator location)

устанавливает объект интерфейса SourceLocator.

Методы

public void printStackTrace()

public void printStackTrace(PrintStream s)

public void printStackTrace(PrintWriter s)

переопределяют соответствующие методы класса Throwableи выводят трассировку ошибки на дисплей, в байтовый или символьный поток.

Класс TransformerConfigurationException, расширяющий классTransformerException, указывает на серьезную ошибку конфигурации. Так же, как и в классеTransformerException, основным конструктором является конструктор

public TransformerConfigurationException(String message,

SourceLocator locator, Throwable e),

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

Своих методов класс TransformerConfigurationException не имеет.