モジュール java.desktop
パッケージ 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エンコーダを作成します。
    • コンストラクタの詳細

      • XMLEncoder

        public XMLEncoder​(OutputStream out)
        XMLエンコーディングを使用してJavaBeansをストリームoutに書き出すための新しいXMLエンコーダを作成します。
        パラメータ:
        out - オブジェクトのXML表現の書込み先となるストリーム
        例外:
        IllegalArgumentException - outnullである場合
        関連項目:
        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またはcharsetnullの場合、あるいは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()
      • flush

        public void flush​()
        このメソッドは、XMLエンコーディングに関連付けられているプリアンブルを書き出し(まだ書き出されていない場合)、flushを最後に呼び出したときからストリームに書き込まれたすべての値を書き出します。 フラッシュ後、このストリームに書き込まれた値の内部参照はすべてクリアされます。
      • close

        public void close​()
        このメソッドは、flushを呼び出し、閉じるポストアンブルを書き込んでから、このストリームに関連付けられている出力ストリームを閉じます。
        定義:
        close、インタフェース: AutoCloseable