モジュール java.desktop
パッケージ java.beans

クラスXMLEncoder

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