XMLEncoder (Java 2 Platform SE 6)

概觀

軟體套件

類別

使用

階層樹

已過時

索引

說明

Java^TM 2 Platform
Standard Ed. 6

上一個類別 下一個類別

框架 無框架

摘要：巢狀 | 欄位 | 建構子 | 方法

詳細資訊：欄位 | 建構子 | 方法

java.beans
類別 XMLEncoder

java.lang.Object
  java.beans.Encoder
      java.beans.XMLEncoder

public class XMLEncoder
extends Encoder
extends Encoder

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 的預設指示，其中它們被表示為符合 1.0 版的 XML 規範和 Unicode/ISO 10646 字元集 UTF-8 字元編碼的 XML 文檔。由 XMLEncoder 類別產生的 XML 文檔如下：

輕便且版本靈活：它們不依賴於任何類別的私有實作，因此，與 Java 源檔案類似，可以在某些不同版本的類別之間或不同的供應商的 VM 之間交換它們。
結構緊湊：XMLEncoder 類別在內部使用刪減冗余 (redundancy elimination) 演算法，因此 Bean 屬性的預設值不會被寫入串流中。
容錯性：檔案中的非結構性錯誤（由於檔案的破壞或在歸檔檔案中對類別進行的 API 更改導致）仍然保持本地化，因此 reader 可以報告錯誤，並繼續載入不受錯誤影響的那部分文檔。

以下是一個 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" 屬性用於顯式指定靜態方法的目標或建構子；其值是類別的完全限定名。
如果沒有通過 "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。
在表示 null 方法（其名稱以 "get" 開頭）的元素中，"method" 屬性被 "property" 屬性替代，後者的值是通過移除 "get" 前綴並取消所得結果的大寫化得到的。
在表示一元方法（其名稱以 "set" 開頭）的元素中，"method" 屬性被 "property" 屬性替代，後者的值是通過移除 "set" 前綴並取消所得結果的大寫化得到的。
在表示名為 "get" 且使用一個整數參數的方法的元素中，"method" 屬性由 "index" 屬性替換，後者的值是第一個參數的值。
在表示名為 "set" 且使用兩個參數（第一個參數為整數）的方法的元素中，"method" 屬性由 "index" 屬性替換，後者的值是第一個參數的值。
陣列的參考是使用 "array" 標記來編寫的。"class" 和 "length" 屬性分別指定陣列的子型別和它的長度。

有關的更多資訊，還可以參閱 The Swing Connection 中的 Using XMLEncoder 一文。

從以下版本開始：: 1.4
另請參見：: XMLDecoder, ObjectOutputStream

建構子摘要
`XMLEncoder(OutputStream out)` 使用 XML 編碼創建一個新的輸出串流，將 JavaBeans 發送給串流 `out`。

方法摘要
`void`	`close()` 此方法調用 `flush`，寫入結束後文，然後關閉與此串流有關的輸出串流。
`void`	`flush()` 如果還沒有寫出導言，那麼此方法將寫出與 XML 編碼有關的導言，並隨後寫出從最後一次調用 `flush` 以來寫入串流中的所有值。
`Object`	`getOwner()` 獲得此編碼器的所有者。
`void`	`setOwner(Object owner)` 將此編碼器的所有者設置為 `owner`。
`void`	`writeExpression(Expression oldExp)` 記錄 Expression，以便 Encoder 在刷新串流的快取記憶體時產生實際輸出。
`void`	`writeObject(Object o)` 將指定物件的 XML 表示形式寫入輸出中。
`void`	`writeStatement(Statement oldStm)` 記錄 Statement，以便 Encoder 在刷新串流的快取記憶體時產生實際輸出。

從類別 java.beans.Encoder 繼承的方法
`get, getExceptionListener, getPersistenceDelegate, remove, setExceptionListener, setPersistenceDelegate`

從類別 java.lang.Object 繼承的方法
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

建構子詳細資訊

XMLEncoder

public XMLEncoder(OutputStream out)

使用 XML 編碼創建一個新的輸出串流，將 JavaBeans 發送給串流 out。

參數：: out - 接收物件的 XML 表示形式的串流。
另請參見：: XMLDecoder.XMLDecoder(InputStream)

方法詳細資訊

setOwner

public void setOwner(Object owner)

將此編碼器的所有者設置為 owner。

參數：: owner - 此編碼器的所有者。
另請參見：: getOwner()

getOwner

public Object getOwner()

獲得此編碼器的所有者。

返回：: 此編碼器的所有者。
另請參見：: setOwner(java.lang.Object)

writeObject

public void writeObject(Object o)

將指定物件的 XML 表示形式寫入輸出中。

覆寫：: 類別 Encoder 中的 writeObject

參數：: o - 要寫入串流中的物件。
另請參見：: XMLDecoder.readObject()

writeStatement

public void writeStatement(Statement oldStm)

記錄 Statement，以便 Encoder 在刷新串流的快取記憶體時產生實際輸出。

此方法只應在初始化持久委託的上下文中調用。

覆寫：: 類別 Encoder 中的 writeStatement

參數：: oldStm - 將寫入串流中的語句。
另請參見：: PersistenceDelegate.initialize(java.lang.Class, java.lang.Object, java.lang.Object, java.beans.Encoder)

writeExpression

public void writeExpression(Expression oldExp)

記錄 Expression，以便 Encoder 在刷新串流的快取記憶體時產生實際輸出。

此方法只應在初始化持久委託或設置編碼器從資源包中讀取資料的上下文中調用。

有關利用 XMLEncoder 使用資源套件的更多資訊，請參閱 http://java.sun.com/products/jfc/tsc/articles/persistence4/#i18n

覆寫：: 類別 Encoder 中的 writeExpression

參數：: 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，寫入結束後文，然後關閉與此串流有關的輸出串流。

概觀