java.beans

Class XMLEncoder

java.lang.Object

java.beans.Encoder

java.beans.XMLEncoder

All Implemented Interfaces:

AutoCloseable

public class XMLEncoder
extends Encoder
implements AutoCloseable

XMLEncoder类是ObjectOutputStream的补充ObjectOutputStream ，可以用于生成JavaBean的文本表示，方式与使用ObjectOutputStream可以创建Serializable对象的二进制表示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文档和Unicode / ISO 10646字符集的UTF-8字符编码。 由产生的XML文档XMLEncoder类有：

• 便携式和版本弹性 ：它们不依赖于任何类的私有实现，因此，像Java源文件一样，它们可能在可能具有不同版本的某些类和不同供应商的VM之间交换。
• 结构紧凑 ： XMLEncoder类在XMLEncoder使用冗余消除算法，以使Bean的属性的默认值不会写入流。
• 容错 ：文件中的非结构性错误是由文件损坏引起的，或者对归档中的类进行的API更改导致的本地化，以便读者可以报告错误，并继续加载不是文档的部分受到错误的影响。

以下是包含swing工具包中的一些用户界面组件的XML存档示例：

  <?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语法使用以下约定：

• 每个元素表示方法调用。
• “对象”标签表示一个表达式 ，其值将用作封闭元素的参数。
• “void”标签表示将被执行的语句 ，但其结果将不会用作封闭方法的参数。
• 包含元素的元素使用这些元素作为参数，除非它们具有标签：“void”。
• 方法的名称由“method”属性表示。
• XML的标准“id”和“idref”属性用于对前面的表达式进行引用，以便处理对象图形中的循环。
• “类”属性用于明确指定静态方法或构造函数的目标; 其值是该类的完全限定名称。
• 如果没有由“class”属性定义目标，则使用“void”标签的元素将使用外部上下文作为目标来执行。
• Java的String类被特别处理，并写入<string> Hello，world </ string>，其中使用UTF-8字符编码将字符串的字符转换为字节。

虽然所有的对象图都可以使用这三个标签进行写入，但是包含以下定义可以更简明地表达共同的数据结构：

• 默认方法名称为“new”。
• 对java类的引用以<class> javax.swing.JButton </ class>的形式编写。
• Java原始类型的包装器类的实例使用原始类型的名称作为标签编写。 例如， Integer类的一个实例可以写成：<int> 123 </ int>。 请注意， XMLEncoder类使用Java的反射包，其中Java的原始类型与其关联的“包装器类”之间的转换在内部进行处理。 XMLEncoder类的API本身只涉及Object 。
• 在一个表示以“get”开头的空值方法的元素中，“method”属性被替换为“property”属性，该属性的值通过删除“get”前缀并对结果进行重新赋值。
• 在表示以“set”开头的单体方法的元素中，“method”属性被替换为“property”属性，该属性的值通过删除“set”前缀并对结果进行重新赋值来给出。
• 在一个表示一个名为“get”的方法中使用一个整数参数的元素中，“method”属性被替换为“index”属性，其值为第一个参数的值。
• 在一个表示一个名为“set”的元素的元素中，它有两个参数，其中第一个是一个整数，“method”属性被替换为“index”属性，其值是第一个参数的值。
• 使用“array”标签写入数组的引用。 “类”和“长度”属性分别指定数组的子类型及其长度。

有关更多信息，您可能还需要查看Using XMLEncoder ， “Swing连接”中的一篇文章。

从以下版本开始：

1.4

另请参见：

XMLDecoder ， ObjectOutputStream

构造方法摘要

构造方法

Constructor and Description
XMLEncoder(OutputStream out) 创建一个新的XML编码器 的JavaBeans写出到流 out使用XML编码。
XMLEncoder(OutputStream out, String charset, boolean declaration, int indentation) 创建一个新的XML编码器 的JavaBeans写出到流 out使用给定 charset从给定的起始 indentation 。

方法摘要

Modifier and Type	Method and Description
void	close() 该方法调用 flush ，写入关闭后缀，然后关闭与此流相关联的输出流。
void	flush() 如果尚未写入与XML编码相关联的前导码，则该方法会写出自上次调用 flush以来写入流的所有值。
Object	getOwner() 获取该编码器的所有者。
void	setOwner(Object owner) 将此编码器的所有者设置为 owner 。
void	writeExpression(Expression oldExp) 记录表达式，以便当流被刷新时，编码器将产生实际的输出。
void	writeObject(Object o) 将指定对象的XML表示形式写入输出。
void	writeStatement(Statement oldStm) 记录声明，以便编码器将在流被冲洗时产生实际的输出。

Methods inherited from class java.beans.Encoder

get, getExceptionListener, getPersistenceDelegate, remove, setExceptionListener, setPersistenceDelegate

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

构造方法详细信息

XMLEncoder

public XMLEncoder(OutputStream out)

创建一个新的XML编码器 的JavaBeans写出到流 out使用XML编码。

参数

out - 要写入对象的XML表示形式的流

异常

IllegalArgumentException - 如果 out是 null

另请参见：

XMLDecoder.XMLDecoder(InputStream)

XMLEncoder

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

创建一个新的XML编码器 的JavaBeans写出到流 out使用给定 charset从给定的起始 indentation 。

参数

out - 要写入对象的XML表示形式的流

charset - 请求的字符集的名称; 可能是规范名称或别名

declaration - 是否应该生成XML声明; 在将内容嵌入另一个XML文档时将其设置为false

indentation - 用于缩进整个XML文档的空格字符数

异常

IllegalArgumentException - 如果 out或 charset是 null ，或者如果 indentation小于0

IllegalCharsetNameException - 如果 charset名字是非法的

UnsupportedCharsetException - 如果在Java虚拟机的此实例中不支持命名的字符集

UnsupportedOperationException - 如果加载的字符集不支持编码

从以下版本开始：

1.7

另请参见：

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 - 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)

记录表达式，以便当流被刷新时，编码器将产生实际的输出。

该方法只能在初始化持久代理或设置编码器以从资源束读取的上下文中被调用。

有关使用资源包与XMLEncoder的更多信息，请参阅http://java.sun.com/products/jfc/tsc/articles/persistence4/#i18n

重写：

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 ，写入关闭后缀，然后关闭与此流相关联的输出流。

Specified by:

close in interface AutoCloseable