オブジェクト出力クラス

トピック:

• ObjectOutputStream クラス
• ObjectOutputStream.PutField クラス
• writeObject メソッド
• writeExternal メソッド
• writeReplace メソッド
• useProtocolVersion メソッド

2.1 ObjectOutputStream クラス

package java.io;

public class ObjectOutputStream
    extends OutputStream
    implements ObjectOutput, ObjectStreamConstants
{
    public ObjectOutputStream(OutputStream out)
        throws IOException;

    public final void writeObject(Object obj)
        throws IOException;

    public void writeUnshared(Object obj)
        throws IOException;

    public void defaultWriteObject()
        throws IOException, NotActiveException;

    public PutField putFields()
        throws IOException;

    public writeFields()
        throws IOException;

    public void reset() throws IOException;

    protected void annotateClass(Class cl) throws IOException;

    protected void writeClassDescriptor(ObjectStreamClass desc)
        throws IOException;

    protected Object replaceObject(Object obj) throws IOException;

    protected boolean enableReplaceObject(boolean enable)
        throws SecurityException;

    protected void writeStreamHeader() throws IOException;

    public void write(int data) throws IOException;

    public void write(byte b[]) throws IOException;

    public void write(byte b[], int off, int len) throws IOException;

    public void flush() throws IOException;

    protected void drain() throws IOException;

    public void close() throws IOException;

    public void writeBoolean(boolean data) throws IOException;

    public void writeByte(int data) throws IOException;

    public void writeShort(int data) throws IOException;

    public void writeChar(int data) throws IOException;

    public void writeInt(int data) throws IOException;

    public void writeLong(long data) throws IOException;

    public void writeFloat(float data) throws IOException;

    public void writeDouble(double data) throws IOException;

    public void writeBytes(String data) throws IOException;

    public void writeChars(String data) throws IOException;

    public void writeUTF(String data) throws IOException;

    // Inner class to provide access to serializable fields.
    abstract static public class PutField
    {
        public void put(String name, boolean value)
            throws IOException, IllegalArgumentException;

        public void put(String name, char data)
            throws IOException, IllegalArgumentException;

        public void put(String name, byte data)
            throws IOException, IllegalArgumentException;

        public void put(String name, short data)
            throws IOException, IllegalArgumentException;

        public void put(String name, int data)
            throws IOException, IllegalArgumentException;

        public void put(String name, long data)
            throws IOException, IllegalArgumentException;

        public void put(String name, float data)
            throws IOException, IllegalArgumentException;

        public void put(String name, double data)
            throws IOException, IllegalArgumentException;

        public void put(String name, Object data)
            throws IOException, IllegalArgumentException;
    }

    public void useProtocolVersion(int version) throws IOException;

    protected ObjectOutputStream()
        throws IOException;

     protected writeObjectOverride()
        throws NotActiveException, IOException;
}

writeObject メソッドは、オブジェクトをストリームに直列化するために使用します。オブジェクトは、次のように直列化されます。

例外は、トラバーサル中に発生する場合も、基になるストリーム内で発生する場合もあります。IOException のサブクラスの場合、例外プロトコルを使って例外がストリームに書き込まれ、ストリーム状態が破棄されます。最初の例外をストリームに書き込んでいる間に 2 番目の IOException がスローされた場合、ストリームは不明状態のままになり、writeObject から StreamCorruptedException がスローされます。その他の例外の場合、ストリームは中止され、不明で使用不能な状態のままになります。

• writeUnshared を使用して書き込まれたオブジェクトは、そのオブジェクトが以前に書き込まれているかどうかにかかわらず、常に新しく出現するオブジェクト (ストリームにまだ書き込まれたことがないオブジェクト) として同じ方法で直列化されます。
• writeUnshared によって以前に書き込まれたオブジェクトを書き込む際に writeObject を使用すると、以前の writeUnshared 操作は、別のオブジェクトの書き込みとして扱われます。つまり、ObjectOutputStream は、writeUnshared 呼び出しによって書き込まれたオブジェクトデータへの逆参照を生成しません。

defaultWriteObject メソッドは、現在のクラスに対するデフォルト直列化メカニズムを実装します。このメソッドの呼び出しは、クラスの writeObject メソッドからのみ可能です。このメソッドは、現在のクラスのすべての直列化可能フィールドをストリームに書き込みます。writeObject メソッドの外部からこのメソッドが呼び出されると、NotActiveException がスローされます。

putFields メソッドは、ストリーム内の直列化可能フィールドの値を設定する際に呼び出し側が使用する PutField オブジェクトを返します。フィールドは、任意の順序で設定できます。すべてのフィールドの設定が完了したら、writeFields を呼び出して、フィールド値を正規の順序でストリームに書き込む必要があります。フィールドが設定されていない場合、その型に適したデフォルト値がストリームに書き込まれます。このメソッドは、直列化可能クラスの writeObject メソッド内からしか呼び出すことができません。また、このメソッドは、1 回しか呼び出すことができず、defaultWriteObject がすでに呼び出されている場合は呼び出せません。writeFields を呼び出したあとでないと、ほかのデータをストリームに書き込むことはできません。

reset メソッドは、ストリーム状態をリセットして、構築時の状態に戻します。Reset は、すでにストリームに書き込まれたオブジェクトの状態を破棄します。ストリーム内の現在位置にリセットのマークが付けられるので、対応する ObjectInputStream も同じ位置でリセットされます。以前にストリームに書き込まれたオブジェクトが、ストリームに書き込み済みのオブジェクトとして記憶されることはありません。これらのオブジェクトは、ストリームに再度書き込まれます。これは、オブジェクトの内容やオブジェクトを再送信しなければいけない場合に有用です。Reset は、オブジェクトの直列化中は呼び出されない場合もあります。不正に呼び出されると、IOException がスローされます。

Java 2 SDK, Standard Edition, v1.3 から、ObjectStreamClass の直列化が必要になると、writeClassDescriptor メソッドが呼び出されるようになりました。writeClassDescriptor は、ObjectStreamClass 表現の直列化ストリームへの書き込みを担当します。サブクラスでこのメソッドをオーバーライドすることにより、クラス記述子の直列化ストリームへの書き込み方法をカスタマイズできます。このメソッドをオーバーライドする場合は、ObjectInputStream 内の対応する readClassDescriptor メソッドもオーバーライドして、カスタムストリーム表現からクラス記述子を再構成することをお勧めします。デフォルトでは、writeClassDescriptor は、セクション 6.4「ストリーム形式の文法」で指定された形式に従ってクラス記述子を書き込みます。このメソッドは、ObjectOutputStream が古い直列化ストリーム形式を使用していない場合にのみ、呼び出し可能です (セクション 6.3「ストリームプロトコルバージョン」を参照)。この直列化ストリームが古い形式 (ObjectStreamConstants.PROTOCOL_VERSION_1) を使用している場合、クラス記述子はオーバーライドまたはカスタマイズが不可能な方法で内部的に書き込まれます。

Class の直列化中、かつクラス記述子のストリームへの書き込み後に、annotateClass メソッドが呼び出されます。サブクラスがこのメソッドを継承して、クラスに関するほかの情報をストリームに書き込むことも可能です。この情報の読み取りは、対応する ObjectInputStream サブクラスの resolveClass メソッドを使って実行する必要があります。

ObjectOutputStream サブクラスは、replaceObject メソッドを実装することにより、直列化中にオブジェクトの監視および置換を実行できます。最初の置換対象オブジェクトに対して writeObject を呼び出す前に、enableReplaceObject を呼び出して、置換を明示的に有効にする必要があります。オブジェクトの置換が有効にされたあと、オブジェクトをはじめて直列化する直前に、各オブジェクトに対して replaceObject が呼び出されます。replaceObject メソッドは、特別に処理されるクラスである Class および ObjectStreamClass のオブジェクトに対しては呼び出されません。サブクラスの実装が、元のオブジェクトではなく直列化される代替オブジェクトを返す場合があります。代替オブジェクトは、直列化可能でなければいけません。ストリームにおける元のオブジェクトへのすべての参照は、置換オブジェクトによって置き換えられます。

サブクラスはオブジェクトが置換されているときに、置換されるオブジェクトが参照を保存するすべてのフィールドと互換性が持つこと、つまり直列化復元時に補完的な置換が行われることを保証する必要があります。型がフィールドまたは配列要素の型のサブクラスでないオブジェクトは、あとで ClassCastException をスローして直列化復元を中止することになり、参照は保存されません。

enableReplaceObject メソッドは、直列化の際にあるオブジェクトを別のオブジェクトで置換するために、ObjectOutputStream の信頼できるサブクラスで呼び出すことができます。オブジェクトの置換は、enableReplaceObject が true 値で呼び出されるまでは、無効になっています。それ以降は、false に設定することで無効にできます。前の設定が返されます。enableReplaceObject メソッドは、置換を要求するストリームを信頼できるかどうかを調べます。オブジェクトの private 状態が意図せずに公開されないことを保証するために、信頼できるストリームサブクラスだけが replaceObject を使用できます。信頼されるクラスとは、Serializable 置換を有効にする権限を保持する、セキュリティー保護ドメインに属するクラスのことです。

ObjectOutputStream のサブクラスがシステムドメインの一部とはみなされない場合、SerializablePermission "enableSubstitution" をセキュリティーポリシーファイルに追加する必要があります。ObjectInputStream のサブクラスの保護ドメインに、enableReplaceObject 呼び出しによる "enableSubstitution" の権限がない場合は、AccessControlException がスローされます。セキュリティーモデルの詳細は、Java セキュリティーアーキテクチャー (JDK1.2) のドキュメントを参照してください。

writeStreamHeader メソッドは、マジック番号とバージョンをストリームに書き込みます。この情報は、ObjectInputStream の readStreamHeader メソッドを使って読み取る必要があります。ストリームの一意形式を識別するために、サブクラスがこのメソッドを実装することが必要な場合があります。

flush メソッドは、ストリームが保持するバッファーを空にして基になるストリームにフラッシュを転送するために、使用されます。基になるストリームのフラッシュを強制せずに ObjectOutputStream のバッファーだけを空にするために、サブクラスから drain メソッドを使用できます。

プリミティブ型用のすべての write メソッドは、DataOutputStream を使って値をエンコードして、標準ストリーム形式にします。バイトがブロックデータレコードにバッファリングされることにより、オブジェクトのエンコーディングとの区別が可能になります。このバッファリングにより、クラスのバージョン管理が必要な場合、プリミティブデータのスキップも可能になります。また、クラス固有のメソッドを呼び出すことなく、ストリームの構文解析を行うことも可能になります。

直列化の実装をオーバーライドするときは、ObjectOutputStream のサブクラスは引数なしの protected ObjectOutputStream コンストラクタを呼び出すことをお勧めします。SerializablePermission "enableSubclassImplementation" 用の引数なしコンストラクタ内では、信頼できるクラスだけがデフォルト実装のオーバーライドを許可されるようにセキュリティーチェックがあります。このコンストラクタは、ObjectOutputStream に private なデータを割り当てず、final writeObject メソッドが writeObjectOverride メソッドを呼び出してから復帰するべきことを示すフラグを設定します。ほかのすべての ObjectOutputStream メソッドは、final ではないので、サブクラスによって直接オーバーライドできます。

2.2 ObjectOutputStream.PutField クラス

クラス PutField は、あるクラスがデフォルト直列化を使わない場合に、そのクラスの直列化可能フィールドの値を設定するための API を提供します。各メソッドは、指定された名前付き値をストリームに置きます。name が、フィールドが書き込まれているクラスの直列化可能フィールドの名前と一致しない場合、または指定されたフィールドの型が、呼び出された特定の put メソッドの 2 番目のパラメータの型と一致しない場合、IllegalArgumentException がスローされます。

2.3 writeObject メソッド

    private void writeObject(ObjectOutputStream stream)
        throws IOException;

クラスの writeObject メソッドには、実装されている場合、クラスの状態を保存する責任があります。ObjectOutputStream の defaultWriteObject メソッドまたは writeFields メソッドを一度 (一度だけ) 呼び出してからでないと、対応する readObject メソッドがオブジェクトの状態を復元するために必要なオプションデータを書き込むことはできません。オプションデータを書き込まない場合でも、defaultWriteObject または writeFields を一度呼び出す必要があります。オプションデータ (ある場合) の書き込みの前に defaultWriteObject か writeFields が呼び出されなければ、ObjectInputStream がその writeObject メソッドを定義したクラスを解決できない場合に、インスタンス直列化復元の動作は未定義になります。

オプションデータの形式、構造体、バージョン管理の責任は、完全にクラスにあります。

2.4 writeExternal メソッド

    public void writeExternal(ObjectOutput stream)
        throws IOException;

JDK 1.2 で、Externalizable データを書き込むための新しいデフォルト形式が導入されました。新しい形式は、プリミティブデータが writeExternal メソッドによってブロックデータモードで書き込まれるように指定します。さらに、writeExternal メソッドから戻ったあとに、外部オブジェクトの末尾を示すタグがストリームに付加されます。この形式変更の利点については、セクション 3.6「readExternal メソッド」を参照してください。この変更により生じる互換性の問題の詳細は、セクション 2.6「useProtocolVersion メソッド」を参照してください。

2.5 writeReplace メソッド

このメソッドは、次のように定義されます。

   ANY-ACCESS-MODIFIER Object writeReplace() {
                 throws ObjectStreamException;

ObjectOutputStream がストリームにオブジェクトを書き込む準備をしているとき、writeReplace メソッドが呼び出されます。ObjectOutputStream は、クラスが writeReplace メソッドを定義しているかどうかをチェックします。このメソッドが定義されている場合は、オブジェクトがストリーム内で置換を指定することを許可するために writeReplace メソッドが呼び出されます。返されるオブジェクトは、渡されるオブジェクトと同じ型であるか、または読み込まれて解釈されたオブジェクトが、オブジェクトへのすべての参照と互換性を持つ型のオブジェクトであるべきです。そうでない場合、型の不一致が検出されたときに、ClassCastException が発生します。

2.6 useProtocolVersion メソッド

ストリームプロトコルバージョンについては、セクション 6.3「ストリームプロトコルバージョン」を参照してください。