Класс XMLEncoder

public class XMLEncoder
extends Encoder
implements AutoCloseable

Класс XMLEncoder — это дополнительная альтернатива ObjectOutputStream и может использоваться для генерации текстового представления JavaBean, аналогично тому, как ObjectOutputStream используется для создания двоичного представления объектов Serializable. Например, следующий фрагмент можно использовать для создания текстового представления предоставленного JavaBean и всех его свойств:

XMLEncoder e = new XMLEncoder(
                          new BufferedOutputStream(
                              new FileOutputStream("Test.xml")));
       e.writeObject(new JButton("Hello, world"));
       e.close();

Несмотря на сходство API, класс XMLEncoder предназначен исключительно для архивирования графов JavaBean в виде текстовых представлений их публичных свойств. Как и файлы исходного кода Java, документы, написанные таким образом, обладают естественной устойчивостью к изменениям в реализации вовлечённых классов. Рекомендуется использовать ObjectOutputStream для межпроцессного взаимодействия и сериализации общего назначения.

Класс XMLEncoder предоставляет стандартное обозначение для JavaBean, в котором они представлены как XML-документы, соответствующие версии 1.0 спецификации XML и кодировке UTF-8 набора символов Unicode/ISO 10646. XML-документы, создаваемые классом XMLEncoder, обладают следующими характеристиками:

• Переносимость и устойчивость к версиям: они не зависят от частной реализации любого класса и, таким образом, как файлы исходного кода Java, могут обмениваться между средами, которые могут иметь разные версии некоторых классов, и между виртуальными машинами от разных поставщиков.
• Структурная компактность: класс XMLEncoder использует алгоритм исключения избыточности, так что значения по умолчанию свойств Bean не записываются в поток.
• Устойчивость к ошибкам: неструктурные ошибки в файле, вызванные либо повреждением файла, либо изменениями API в классах в архиве, остаются локализованными, так что читатель может сообщить об ошибке и продолжить загрузку частей документа, которые не были затронуты ошибкой.

Ниже приведен пример XML-архива, содержащего некоторые компоненты пользовательского интерфейса из набора инструментов swing:

<?xml version="1.0" encoding="UTF-8"?>
 <java version="1.0" class="java.beans.XMLDecoder">
 <object class="javax.swing.JFrame">
   <void property="name">
     <string>frame1</string>
   </void>
   <void property="bounds">
     <object class="java.awt.Rectangle">
       <int>0</int>
       <int>0</int>
       <int>200</int>
       <int>200</int>
     </object>
   </void>
   <void property="contentPane">
     <void method="add">
       <object class="javax.swing.JButton">
         <void property="label">
           <string>Hello</string>
         </void>
       </object>
     </void>
   </void>
   <void property="visible">
     <boolean>true</boolean>
   </void>
 </object>
 </java>

XML-синтаксис использует следующие соглашения:

• Каждый элемент представляет вызов метода.
• Тег "object" обозначает выражение, значение которого используется в качестве аргумента для окружающего элемента.
• Тег "void" обозначает утверждение, которое будет выполнено, но результат которого не будет использоваться в качестве аргумента окружающего метода.
• Элементы, содержащие элементы, используют эти элементы в качестве аргументов, если только у них нет тега "void".
• Имя метода обозначается атрибутом "method".
• Стандартные атрибуты XML "id" и "idref" используются для создания ссылок на предыдущие выражения — для обработки циклов в графике объектов.
• Атрибут "class" используется для явного указания целевого объекта статического метода или конструктора; его значением является полное имя класса.
• Элементы с тегом "void" выполняются с использованием внешнего контекста в качестве целевого объекта, если целевой объект не определён атрибутом "class".
• Класс Java String обрабатывается особым образом и записывается как <string>Привет, мир</string>, где символы строки преобразуются в байты с использованием кодировки UTF-8.

Хотя все графики объектов могут быть записаны только с использованием этих трёх тегов, следующие определения включены для более компактного выражения распространённых структур данных:

• Имя метода по умолчанию — "new".
• Ссылка на класс Java записывается в формате <class>javax.swing.JButton</class>.
• Экземпляры обёртных классов для примитивных типов Java записываются с использованием имени примитивного типа в качестве тега. Например, экземпляр класса Integer можно записать: <int>123</int>. Обратите внимание, что класс XMLEncoder использует пакет рефлексии Java, в котором преобразование между примитивными типами Java и связанными с ними "обёртками" обрабатывается внутренне. Сам API класса XMLEncoder работает только с Object.
• В элементе, представляющем метод без аргументов, имя которого начинается с "get", атрибут "method" заменяется атрибутом "property", значение которого получается путём удаления префикса "get" и приведения к нижнему регистру результата.
• В элементе, представляющем метод с одним аргументом, имя которого начинается с "set", атрибут "method" заменяется атрибутом "property", значение которого получается путём удаления префикса "set" и приведения к нижнему регистру результата.
• В элементе, представляющем метод с именем "get", принимающий один целочисленный аргумент, атрибут "method" заменяется атрибутом "index", значение которого равно значению первого аргумента.
• В элементе, представляющем метод с именем "set", принимающий два аргумента, первый из которых — целое число, атрибут "method" заменяется атрибутом "index", значение которого равно значению первого аргумента.
• Ссылка на массив записывается с использованием тега "array". Атрибуты "class" и "length" указывают подтип массива и его длину соответственно.

Дополнительную информацию можно найти в статье Использование XMLEncoder в The Swing Connection.

Конструкторы

XMLEncoder

public XMLEncoder(OutputStream out)

Создаёт новый кодировщик XML для записи JavaBeans в поток out с использованием кодировки XML.

Параметры:

out - поток, в который будет записано XML-представление объектов

Исключения:

IllegalArgumentException - если out является null

См. также:

XMLDecoder(InputStream)

XMLEncoder

public XMLEncoder(OutputStream out,
                  String charset,
                  boolean declaration,
                  int indentation)

Создаёт новый кодировщик XML для записи JavaBeans в поток out с использованием указанной charset, начиная с заданного indentation.

Параметры:

out - поток, в который будет записано XML-представление объектов

charset - имя запрошенной кодировки символов; может быть как каноническим именем, так и псевдонимом

declaration - флаг, указывающий, должна ли генерироваться декларация XML; установите в false при встраивании содержимого в другой XML-документ

indentation - количество пробельных символов для отступа всего XML-документа

Исключения:

IllegalArgumentException - если out или charset является null, или если indentation меньше 0

IllegalCharsetNameException - если имя кодировки символов является недопустимым

UnsupportedCharsetException - если поддержка указанной кодировки символов недоступна в текущей виртуальной машине Java

UnsupportedOperationException - если загруженная кодировка символов не поддерживает кодирование

См. также:

Charset.forName(String)

Методы

setOwner

public void setOwner(Object owner)

Устанавливает владельца этого кодировщика в owner.

Параметры:

owner - Владелец этого кодировщика.

См. также:

getOwner()

getOwner

public Object getOwner()

Возвращает владельца этого кодировщика.

Возвращает:

Владелец этого кодировщика.

См. также:

setOwner(java.lang.Object)

writeObject

public void writeObject(Object o)

Записывает XML-представление указанного объекта в выходной поток.

Переопределяет:

writeObject в классе Encoder

Параметры:

o - Объект, который будет записан в поток.

См. также:

XMLDecoder.readObject()

writeStatement

public void writeStatement(Statement oldStm)

Переопределяет:

writeStatement в классе Encoder

Параметры:

oldStm - Инструкция, которая будет записана в поток.

См. также:

PersistenceDelegate.initialize(java.lang.Class<?>, java.lang.Object, java.lang.Object, java.beans.Encoder)

writeExpression

public void writeExpression(Expression oldExp)

Переопределяет:

writeExpression в классе Encoder

Параметры:

oldExp - Выражение, которое будет записано в поток.

См. также:

PersistenceDelegate.initialize(java.lang.Class<?>, java.lang.Object, java.lang.Object, java.beans.Encoder)

flush

public void flush()

Этот метод записывает преамбулу, связанную с XML-кодированием, если она ещё не была записана, а затем записывает все значения, которые были записаны в поток с момента последнего вызова flush. После сброса все внутренние ссылки на значения, которые были записаны в этот поток, очищаются.

close

public void close()

Этот метод вызывает flush, записывает заключительный постскрипт и затем закрывает выходной поток, связанный с этим потоком.

Задано:

close в интерфейсе AutoCloseable