Общие средства выполнения преобразований документов 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 не имеет.