java.lang.Object

java.beans.Encoder

java.beans.XMLEncoder

すべての実装されたインタフェース:: AutoCloseable

public class XMLEncoder
extends Encoder
implements AutoCloseable

XMLEncoderクラスは、ObjectOutputStreamの補足的な代替であり、ObjectOutputStreamを使ってSerializableオブジェクトのバイナリ表現を作成できるのと同じ方法でJavaBeanのテキスト表現を生成するために使用できます。たとえば、次のコードでは、提供された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とUnicode/ISO 10646文字セットのUTF-8文字エンコーディングに準拠したXML文書として表現するデフォルトの指定を提供します。 XMLEncoderクラスによって生成されるXML文書には、次のような特徴があります。

移植性とバージョンの違いに対する許容性: クラスの非公開実装には一切依存しないため、Javaソース・ファイルと同様に、一部のクラスのバージョンが異なる複数の環境間、あるいはベンダーの異なるVM間で交換可能です。
コンパクトな構造: 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構文は、次の規約に準拠しています。

個々の要素はメソッド呼出しを表す。
objectタグは、囲む要素の引数として使用される値を持つ式を表す。
voidタグは、実行されるだけで、その結果は囲むメソッドの引数として使用されない文を表す。
ほかの要素を包含する要素は、これらの要素を引数として使用する。ただし、包含されている要素にvoidタグが含まれていない場合にかぎる。
メソッド名はmethod属性によって表される。
XMLの標準属性であるidおよびidrefを使って以前の式を参照し、オブジェクト・グラフの循環を処理する。
class属性を使って静的メソッドまたはコンストラクタのターゲットを明示的に指定する。その値は完全指定のクラス名になる。
voidタグ付きの要素は、class属性によってターゲットが定義されていない場合、外部コンテキストをターゲットとして実行される。
JavaのStringクラスは、特別なものとして、<string>Hello, world</string>に書き込まれる。ここで、文字列に含まれる文字は、UTF-8文字セットによりバイトに変換される。

すべてのオブジェクト・グラフはこれら3つのタグで記述できますが、共通のデータ構造をより簡潔に表現するため、次の定義がなされています。

デフォルトのメソッド名はnew。
javaクラスへの参照は、<class>javax.swing.JButton</class>という形式で記述します。
Javaプリミティブ型のラッパー・クラスのインスタンスは、プリミティブ型の名前をタグとして記述される。たとえば、Integerクラスのインスタンスは<int>123</int>と記述できる。 XMLEncoderクラスが、Javaプリミティブ型と関連ラッパー・クラス間の変換を内部的に処理するJavaリフレクション・パッケージを使用する点に注意すること。 XMLEncoderクラスのAPI自体は、Objectだけを取り扱う。
名前の先頭の文字列がgetで始まるような引数なしのメソッドを表現する要素では、method属性はproperty属性で置き換えられる。なお、property属性の値は、get接頭辞を削除し、メソッド名の先頭の文字をアルファベットの小文字に変更することによって得られる。
名前の先頭の文字列がsetで始まるような単一のメソッドを表現する要素では、method属性はproperty属性で置き換えられる。なお、property属性の値は、set接頭辞を削除し、メソッド名の先頭の文字をアルファベットの小文字に変更することによって得られる。
getメソッドとして指定され、整数の引数を1つ取るようなメソッドを表現する要素では、method属性はindex属性で置き換えられる。なお、index属性の値は最初の引数の値と同じになる。
setメソッドとして指定され、引数を2つ取るようなメソッドを表現する要素では、method属性はindex属性で置き換えられる。なお、index属性の値は、最初の引数の値と同じになる。
配列の参照は、arrayタグによって記述される。 class属性はその配列のサブタイプ、length属性はその配列の長さを指定する。

詳細は、「The Swing Connection」の「 Using XMLEncoder」を参照してください。

導入されたバージョン:: 1.4
関連項目:: XMLDecoder, ObjectOutputStream

コンストラクタのサマリー

コンストラクタ
コンストラクタ	説明
`XMLEncoder(OutputStream out)`	XMLエンコーディングを使用してJavaBeansをストリーム`out`に書き出すための新しいXMLエンコーダを作成します。
`XMLEncoder(OutputStream out, String charset, boolean declaration, int indentation)`	指定された`charset`を使用し、指定された`indentation`から開始してJavaBeansをストリーム`out`に書き出すための新しいXMLエンコーダを作成します。

メソッドのサマリー

修飾子と型	メソッド	説明
`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)`	ストリームのフラッシュ時に実際の出力が生成されるように、文を記録します。

クラス 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に書き出すための新しいXMLエンコーダを作成します。
  
  パラメータ:
  
  out - オブジェクトのXML表現の書込み先となるストリーム
  
  例外:
  
  IllegalArgumentException - outがnullである場合
  
  関連項目:
  
  XMLDecoder(InputStream)
- XMLEncoder
  
  public XMLEncoder(OutputStream out, String charset, boolean declaration, int indentation)
  
  指定されたcharsetを使用し、指定されたindentationから開始してJavaBeansをストリームoutに書き出すための新しいXMLエンコーダを作成します。
  
  パラメータ:
  
  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 - ストリームに書き込まれるオブジェクト。
  
  関連項目:
  
  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でリソース・バンドルを使用する方法の詳細については、「国際化アプリケーションの作成」を参照してください。
  
  オーバーライド:
  
  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

クラスXMLEncoder

コンストラクタのサマリー

メソッドのサマリー

クラス java.beans.Encoderで宣言されたメソッド

クラス java.lang.Objectで宣言されたメソッド

コンストラクタの詳細

XMLEncoder

XMLEncoder

メソッドの詳細

setOwner

getOwner

writeObject

writeStatement

writeExpression

flush

close